---

Nano-X events API.
[Nano-X public API]

The Nano-X event mechanism. More...

Functions
void	GrRegisterInput (int fd)
	Register an extra file descriptor to monitor in the main select() call.
void	GrUnregisterInput (int fd)
	Stop monitoring a file descriptor previously registered with GrRegisterInput().
void	GrPrepareSelect (int *maxfd, void *rfdset)
	Prepare for the client to call select().
void	GrServiceSelect (void *rfdset, GR_FNCALLBACKEVENT fncb)
	Handles events after the client has done a select() call.
void	GrMainLoop (GR_FNCALLBACKEVENT fncb)
	An infinite loop that dispatches events.
void	GrGetNextEvent (GR_EVENT *ep)
	Gets the next event from the event queue.
void	GrGetNextEventTimeout (GR_EVENT *ep, GR_TIMEOUT timeout)
	Gets the next event from the event queue, with a time limit.
int	GrPeekEvent (GR_EVENT *ep)
	Gets a copy of the next event on the queue, without actually removing it from the queue.
void	GrPeekWaitEvent (GR_EVENT *ep)
	Wait until an event is available for a client, and then peek at it.
void	GrCheckNextEvent (GR_EVENT *ep)
	Gets the next event from the event queue if there is one.
int	GrGetTypedEvent (GR_WINDOW_ID wid, GR_EVENT_MASK mask, GR_UPDATE_TYPE update, GR_EVENT *ep, GR_BOOL block)
	Fills in the specified event structure with a copy of the next event on the queue that matches the type parameters passed and removes it from the queue.
int	GrGetTypedEventPred (GR_WINDOW_ID wid, GR_EVENT_MASK mask, GR_UPDATE_TYPE update, GR_EVENT *ep, GR_BOOL block, GR_TYPED_EVENT_CALLBACK matchfn, void *arg)
	The specified callback function is called with the passed event type parameters for each event on the queue, until the callback function CheckFunction returns GR_TRUE.
void	GrSelectEvents (GR_WINDOW_ID wid, GR_EVENT_MASK eventmask)
	Select the event types which should be returned for the specified window.
int	GrQueueLength (void)
	Returns the current length of the client side queue.

---

Detailed Description

The Nano-X event mechanism.

---

Function Documentation

void GrCheckNextEvent (  GR_EVENT *  ep  )

Gets the next event from the event queue if there is one. Returns immediately with an event type of GR_EVENT_TYPE_NONE if the queue is empty. Parameters: ep  Pointer to the GR_EVENT structure to return the event in.

void GrGetNextEvent (  GR_EVENT *  ep  )

Gets the next event from the event queue. If the queue is currently empty, sleeps until the next event arrives from the server or input is read on a file descriptor previously specified by GrRegisterInput(). Parameters: ep  Pointer to the GR_EVENT structure to return the event in.

void GrGetNextEventTimeout (  GR_EVENT *  ep, GR_TIMEOUT  timeout )

Gets the next event from the event queue, with a time limit. If the queue is currently empty, we sleep until the next event arrives from the server, input is read on a file descriptor previously specified by GrRegisterInput(), or a timeout occurs. Note that a value of 0 for the timeout parameter doesn't mean "timeout after 0 milliseconds" but is in fact a magic number meaning "never time out". Parameters: ep  Pointer to the GR_EVENT structure to return the event in. timeout  The number of milliseconds to wait before timing out, or 0 for forever.

int GrGetTypedEvent (  GR_WINDOW_ID  wid, GR_EVENT_MASK  mask, GR_UPDATE_TYPE  update, GR_EVENT *  ep, GR_BOOL  block )

Fills in the specified event structure with a copy of the next event on the queue that matches the type parameters passed and removes it from the queue. If block is GR_TRUE, the call will block until a matching event is found. Otherwise, only the local queue is searched, and an event type of GR_EVENT_TYPE_NONE is returned if the a match is not found. Parameters: wid  Window id for which to check events. 0 means no window. mask  Event mask of events for which to check. 0 means no check for mask. update  Update event subtype when event mask is GR_EVENT_MASK_UPDATE. ep  Pointer to the GR_EVENT structure to return the event in. block  Specifies whether or not to block, GR_TRUE blocks, GR_FALSE does not. Returns: GR_EVENT_TYPE if an event was returned, or GR_EVENT_TYPE_NONE if no events match.

int GrGetTypedEventPred (  GR_WINDOW_ID  wid, GR_EVENT_MASK  mask, GR_UPDATE_TYPE  update, GR_EVENT *  ep, GR_BOOL  block, GR_TYPED_EVENT_CALLBACK  matchfn, void *  arg )

The specified callback function is called with the passed event type parameters for each event on the queue, until the callback function CheckFunction returns GR_TRUE. The event is then removed from the queue and returned. If block is GR_TRUE, the call will block until a matching event is found. Otherwise, only the local queue is searched, and an event type of GR_EVENT_TYPE_NONE is returned if the a match is not found. Parameters: wid  Window id for which to check events. 0 means no window. mask  Event mask of events for which to check. 0 means no check for mask. update  Update event subtype when event mask is GR_EVENT_MASK_UPDATE. ep  Pointer to the GR_EVENT structure to return the event in. block  Specifies whether or not to block, GR_TRUE blocks, GR_FALSE does not. matchfn  Specifies the callback function called for matching. arg  A programmer-specified argument passed to the callback function. Returns: GR_EVENT_TYPE if an event was returned, or GR_EVENT_TYPE_NONE if no events match.

void GrMainLoop (  GR_FNCALLBACKEVENT  fncb  )

An infinite loop that dispatches events. Calls the specified callback function whenever an event arrives or there is data to be read on a file descriptor registered with GrRegisterInput(). Never returns. Parameters: fncb  Pointer to the function to call when an event needs handling.

int GrPeekEvent (  GR_EVENT *  ep  )

Gets a copy of the next event on the queue, without actually removing it from the queue. Does not block - an event type of GR_EVENT_TYPE_NONE is given if the queue is empty. Parameters: ep  Pointer to the GR_EVENT structure to return the event in. Returns: 1 if an event was returned, or 0 if the queue was empty.

void GrPeekWaitEvent (  GR_EVENT *  ep  )

Wait until an event is available for a client, and then peek at it. Parameters: ep  Pointer to the GR_EVENT structure to return the event in.

void GrPrepareSelect (  int *  maxfd, void *  rfdset )

Prepare for the client to call select(). Asks the server to send the next event but does not wait around for it to arrive. Initializes the specified fd_set structure with the client/server socket descriptor and any previously registered external file descriptors. Also compares the current contents of maxfd, the client/server socket descriptor, and the previously registered external file descriptors, and returns the highest of them in maxfd. Usually used in conjunction with GrServiceSelect(). Note that in a multithreaded client, the application must ensure that no Nano-X calls are made between the calls to GrPrepareSelect() and GrServiceSelect(), else there will be race conditions. Parameters: maxfd  Pointer to a variable which the highest in use fd will be written to. Must contain a valid value on input - will only be overwritten if the new value is higher than the old value. rfdset  Pointer to the file descriptor set structure to use. Must be valid on input - file descriptors will be added to this set without clearing the previous contents.

int GrQueueLength (  void   )

Returns the current length of the client side queue. Returns: The current length of the client side queue.

void GrRegisterInput (  int  fd  )

Register an extra file descriptor to monitor in the main select() call. An event will be returned when the fd has data waiting to be read if that event has been selected for. Parameters: fd  The file descriptor to monitor.

void GrSelectEvents (  GR_WINDOW_ID  wid, GR_EVENT_MASK  eventmask )

Select the event types which should be returned for the specified window. Parameters: wid  The ID of the window to set the event mask of. eventmask  A bit field specifying the desired event mask.

void GrServiceSelect (  void *  rfdset, GR_FNCALLBACKEVENT  fncb )

Handles events after the client has done a select() call. Calls the specified callback function is an event has arrived, or if there is data waiting on an external fd specified by GrRegisterInput(). Used by GrMainLoop(). Parameters: rfdset  Pointer to the file descriptor set containing those file descriptors that are ready for reading. fncb  Pointer to the function to call when an event needs handling.

void GrUnregisterInput (  int  fd  )

Stop monitoring a file descriptor previously registered with GrRegisterInput(). Parameters: fd  The file descriptor to stop monitoring.

---