vlcallbacks(3dm)

NAME
     vlRegisterHandler, vlRemoveHandler, vlAddCallback, vlRemoveCallback,
     vlRemoveAllCallbacks, vlCallCallbacks, vlMainLoop - IRIS VL event
     handling routines

SYNOPSIS
     #include <dmedia/vl.h>

     int vlRegisterHandler(VLServer svr, int fd, VLEventHandler handler,
                    VLPendingFunc pendingFunc, void *clientData);
     int vlRemoveHandler(VLServer svr, int fd);
     int vlAddCallback(VLServer svr, VLPath path, VLEventMask events,
                 VLCallbackProc callback, void *clientData);
     int vlRemoveCallback(VLServer svr, VLPath path, VLEventMask events,
                    VLCallbackProc callback, void *clientData);
     int vlRemoveAllCallbacks(VLServer svr, VLPath path, VLEventMask events);
     int vlCallCallbacks(VLServer svr, VLEvent *ev);
     void vlMainLoop();

PARAMETERS
     svr           Specifies the video server.

     fd            a file descriptor that can be used with select(2).

     handler       Pointer to a function to handle data valid on the file
                   descriptor.

     pendingFunc   Pointer to a function that will tell whether there is data
                   that has been read from the file descriptor, but not passed
                   to a handler function. If this is null, no data will be
                   checked for before entering select(2).

     clientData    Data for the use of the client callback.

     path          The path for which a callback will be invoked, of VL_ANY
                   for all paths.

     events        Event mask for which add or remove a handler.

     callback      The callback function to be invoked or removed.

     ev            A pointer to an event for which you wish event callbacks to
                   be invoked.

DESCRIPTION
     vlRegisterHandler is intended to provide a mechanism for receiving events
     from servers other than the VL, e.g., the X server or the GL. After
     vlMainLoop is given control, the handler function will be called with the
     file descriptor and the client data specified when select(2) returns the
     fd as readable.
     This function should not be called with the VL file descriptor.

     vlRemoveHandler removes the corresponding handler from the file
     descriptor. There can only be one handler per file descriptor at a time.
     Registering a handler on a file descriptor that already has a handler
     registered will remove the previous handler.  After vlRemoveHandler is
     called, vlMainLoop will no longer wait on the file descriptor using
     select (2)

     vlAddCallback will add a callback with the specified client data to the
     event mask given. If the callback and the client data match a previous
     callback added on the same server and path, the event masks will be or'ed
     together and the callback will only be called once. If any of the
     parameters differs, all callbacks for a given event will be called, but
     not in a guaranteed sequence. If VL_ANY is given as the path, the
     callback will be called when the events occur on any path. These
     callbacks will be called only if control is given to vlMainLoop, or
     vlCallCallbacks is called.

     vlRemoveCallback will remove the given callback from the events in the
     event mask. A callback is only removed if the server, path, and client
     data match exactly. Note that VL_ANY given as a path, will only remove a
     callback that has been registered on VL_ANY.

     vlRemoveAllCallbacks will remove all callbacks on a given path for a set
     of events. Note again that VL_ANY will not match any path.

     vlCallCallbacks will call all the callbacks registered for the server and
     event. The path field in the event must be set properly. This function
     will aid in creating your own main loop, or using one other than
     vlMainLoop.

     vlMainLoop is a select loop that will infinitely loop waiting for events
     to come in on all of the file descriptors registered. If the select(2)
     call is interrupted, it will try to re-enter select and continue. This
     function will not return.

RETURN VALUE
     If successful, those routines that return a value will return zero.  A
     value of -1 indicates an error.

SEE ALSO
     vlSelectEvents(3dm), vlNextEvent(3dm), vlConnectionNumber(3dm)