Listening on Endpoints

It's almost an afterthought with a phone, but to receive calls you have to listen for the phone to ring or whatever annoying bleeps you have the thing programmed to tourtue you, and those around you, with. But for GAT this is not an afterthought.

Before a process can be contacted by a second process using a GATEndpoint instance, it has to explicitly listen for such connections. This is done using one of two methods.

The first method used to listen for ``incoming calls'' is to invoke the function

GATResult GATEndpoint_Listen( GATEndpoint_const endpoint, GATPipe *peep)

This is a blocking function that waits until an ``incoming call'' has been received. It takes as its first argument a GATEndpoint instance created by the calling process. It's next argument is a pointer to a GATPipe, a class which we will cover below. It is through this pointer that this function returns a GATPipe instance which the process can use to converse with ``incoming caller.'' Finally, this function returns a GATResult, covered in Appendix , which indicates this function's completion status.

The second method used to listen for ``incoming calls'' is to invoke the function

GATResult GATEndpoint_AddGATPipeListener( GATEndpoint_const endpoint, 
                                          GATPipeListener peepListener, 
                                          void *listenerData)

This is a non-blocking function that does not wait until an ``inccoming call'' has been received. Again its first argument is a GATEndpoint instance created by the calling process. The second argument is a GATPipeListener and the final argument is simply a void * to untyped data.

A GATPipeListener is a function pointer with the following definition

typedef GATResult (*GATPipeListener)(void *, GATPipe);

It is used for call-backs. Whenever an ``incoming call'' is placed on the above endpoint, a call is made to the GATPipeListener passed to the above function. This GATPipeListener is passed a GATPipe instance along with the void * untyped data registered with the GATPipeListener. Finally, the function GATEndpoint_AddGATPipeListener returns a GATResult, a type covered in Appendix , which indicates the function's completion status.