Purpose

This document describes the design and structure of a mouse
manager.  The purpose of this manager is to open channels to
mouse servers and collect and distribute events to registered
tasks.  This type of task is needed because opens to mouse
servers are stacked, i.e, the second open masks the first from
receiving events.  Having a central mouse manager prevents
this problem by making one task open all the channels to the
mouse servers.

Using the mouse manager, programs could be written to accept
mouse events from multiple users.  In the future, I hope to be
able to write applications (games!) in which two or more users
could work in the same program simultaneously, by distributing
their mouse (later keyboard) events (multi-user applications).

The Client Task

A client task will register itself with the mouse manager
indicating that it wishes to receive events from all other
registered client tasks. Also, all registered client tasks
will be notified of the new client.  Calling the
multi_mouse_open library routine will register the client task
with the mouse manager.


The Mouse Manager

The mouse manager (MultiMouse) task accepts a _MOUSEMAN_OPEN
message from a client task wishing to register.  A client task
simply sends a proxy that it wishes to be triggered when new
mouse events are available, plus its node number.  The mouse
manager replies with a handle used for later identifying the
client. Next, the mouse manager adds a _NEWCLIENT event for
every client process that is currently registered.  Then, the
mouse manager notifies all currently registered process of the
new client by trigger their event proxy. Finally, the mouse
manager opens up a channel to the mouse server on the client
task's node.  

Any events generated by the mouse server will be added to
each registered client's event list.  Each client will then
be notified by triggering its event proxy.

The mouse manager also accepts a _MOUSEMAN_READ message from
a client task.  The client sends its handle assigned by the
mouse manager. The mouse manager replies with any available
events.

The Mouse Monitor

The mouse monitor (MultiMouse.mon) task shows a list of the
clients currently registered with the mouse manager. 
Information is updated 10 times a second.

Mouse Manager Test

A simple test program (MultiMouse.test) receives mouse events
from any client registered with the mouse manager and shows
which type of event it is.


Future

The mouse manager could be modified to collect other types of
events from devices (like the keyboard).


multi_mouse_open

Synopsis:
	#include "mm_msg.h"

	int multi_mouse_open(char *name, pid_t *eproxy);

    The multi_mouse_open function opens a channel to the
    mouse manager for all client events.

    The event proxy is triggered for the following reasons:

    1) a client task has generated a mouse event,
    2) a new client has registered with the mouse manager.
       Subsequent events may include those of the newly
       registered client.
    3) a client task previously registered with the client
       task has died or closed its channel with the mouse
       manager.

    The argument 'name' is an alternate name assigned to the
    mouse manager.  

    The returned argment 'eproxy' will be triggered when
    events become availble.  

Returns:

    Zero is returned if successfull, otherwise (-1) is
    returned and 'errno' is set.


multi_mouse_read

Synopsis:
    #include "mm_msg.h"

	int multi_mouse_read(MMEvent **buffer, int *empty);

    The multi_mouse_read function is used to read pending
    events after receiving the event proxy. 

    The return argument 'buffer' pointers to a list of up to
    25 events.

    The return argument 'empty' is set to true if event list
    in the mouse manager is empty (there are currently no
    more events to read).

Returns:

    The number of events read. If an error occurs (-1) is
    returned and 'errno' is set.



multi_mouse_close

Synopsis:
    #include "mm_msg.h"

	int multi_mouse_close(void);

    The multi_mouse_open function closes a previously opened
    channel to the mouse manager.

Returns:

    Zero is returned if successfull, otherwise (-1) is
    returned and 'errno' is set.


