Galaxy Communicator Documentation:

I/O Library

License / Documentation home / Help and feedback

This documentation briefly describes functions in the directory src/libGalaxy/io which are present but probably will not be used by the developer. The signatures of these functions may change from release to release.

Brokering functions
Comm structure functions
Server structure functions
Flow of control functions
Socket queue functions

Brokering functions

GAL_SOCKET GalIO_GetBrokerSocket(GalIO_BrokerStruct *b)
Returns the socket that the broker connection is using to transmit or receive broker data.

GAL_SOCKET GalIO_GetBrokerListenSocket(GalIO_BrokerStruct *b)
Returns the socket that the outgoing broker connection is using to listen for connections on.

int GalIO_BrokerDataOutHandler(GalIO_BrokerStruct *b)
Once you've set up the outgoing broker connection, call this function to poll it. It returns 1 if the the connection is done, 0 if it is not done, -1 if there is an error. If the result is not 0, you should stop polling and call GalIO_DestroyBrokerStruct to clean up.

int GalIO_BrokerDataInHandler(GalIO_BrokerStruct *b)
Once you've set up the incoming broker connection, call this function to poll it. It returns 1 if the the connection is done, 0 if it is not done, -1 if there is an error. If the result is not 0, you should stop polling and call GalIO_DestroyBrokerStruct to clean up.

void GalIO_DestroyBrokerStruct(GalIO_BrokerStruct *b)
Destroys the broker structure and terminates the connection.

Comm structure functions

void GalIO_DestroyCommStruct(GalIO_CommStruct *gcomm)

GAL_SOCKET GalIO_GetCommSocket(GalIO_CommStruct *gcomm)

void GalIO_CloseCommSocket(GalIO_CommStruct *gcomm)

char *GalIO_GetCommHost(GalIO_CommStruct *gcomm)

void GalIO_SetCommDone(GalIO_CommStruct *gcomm)

void GalIO_CommFlushOutQueue(GalIO_CommStruct *gcomm)

int GalIO_QueueProcessOut(GalIO_CommStruct *gcomm, int do_block)

int GalIO_CommReadFrame(GalIO_CommStruct *gcomm, Gal_Frame *frame, int do_block)

Gal_Frame GalIO_CommDispatchFrame(GalIO_CommStruct *gcomm, Gal_Frame dispatch, GalIO_MsgType *msg_type_ptr, const char *reply_key)
This function implements a module-to-module subdialogue with the Hub. It sends the dispatch and waits for a reply. This function corresponds to GalSS_DispatchViaHub, which implements this functionality for the default "container". This function requires the reply_key which will notify the Hub that this a reply is expected; use :hub_reply_requested. The msg_type_ptr is a pointer to one of the GalIO_MsgType values which describe the content of the response.

int GalIO_CommWriteMessage(GalIO_CommStruct *gcomm, Gal_Frame frame, GalIO_MsgType msg_type, int do_block)
See the discussion on message types.

int GalIO_CommReadMessage(GalIO_CommStruct *gcomm, Nframe *frame, GalIO_MsgType *msg_type_ptr, int do_block)
See the discussion on message types.

void GalIO_AddCommDispatchFunctionEntry(GalIO_CommStruct *gcomm, const char *name, Gal_FrameDataFnPtr fn_with_data, Gal_DispatchFnSignatureKeyEntry *in_key_array, int allow_other_in_keys, int reply_provided, Gal_DispatchFnSignatureKeyEntry *out_key_array, int allow_other_out_keys)

Gal_DispatchFnPkg *GalIO_GetCommDispatchFnPkg(GalIO_CommStruct *gcomm)

void GalIO_SetCommDispatchFnPkg(GalIO_CommStruct *gcomm, Gal_DispatchFnPkg *pkg)

void _GalIO_SetCommDispatchFnAccess(GalIO_CommStruct *gcomm, Gal_DispatchFunctionSelector s, Gal_DispatchFnSignatureLister l, Gal_DispatchFunctionInvoker i, void *invocation_client_data)

Gal_FrameGalIO_CreateErrorFrame(int errnum, const char *error)
Used by GalSS_EnvError and other functions to create a well-formed error frame.

GalIO_ServerStruct *GalIO_CommServer(GalIO_CommStruct *gcomm)

char *GalIO_MsgTypeToName(GalIO_MsgType mt)

int GalIO_ConnectionPoll(GalIO_CommStruct *gcomm)
This function handles an established connection. It returns 0 if normal processing occurred (either it had no input or it processed the input it had), 1 if the connection is finished and was terminated, and -1 when the connection encountered an error and was terminated. The connection object will have been freed by the time the error is reported, so if you need to recover any data from the object (such as the socket so that you can shut off a poll), you should do it before you call GalIO_ConnectionPoll.

It's also possible to set up a server which is polled at intervals instead of being activated by file descriptor input. It also uses these two handlers, but its structure is much simpler. The main loop example also contains an example of this. This alternative example polls both server and all its connections, using GalIO_ServerPoll.

void GalIO_SetDisconnectCallback(GalIO_CommStruct *gcomm, void (*disconnect_callback)(GalIO_CommStruct *server_data))
Associates with the connection gcomm a function disconnect_callback which is called when the connection is shut down. The callback is called with the connection to be shut down as its sole argument. This function should no longer be used; it has been superseded by the event-driven programming model.

Server structure functions

int GalIO_ResetCommSockets(GalIO_ServerStruct *scomm)

GAL_SOCKET GalIO_GetServerListenSocket(GalIO_ServerStruct *scomm)

void GalIO_CloseServerListenSocket(GalIO_ServerStruct *scomm)

void GalIO_AddServerDispatchFunctionEntry(GalIO_ServerStruct *scomm, const char *name, Gal_FrameDataFnPtr fn_with_data, Gal_DispatchFnSignatureKeyEntry *in_key_array, int allow_other_in_keys, int reply_provided, Gal_DispatchFnSignatureKeyEntry *out_key_array, int allow_other_out_keys)

void _GalIO_SetServerDispatchFnAccess(GalIO_ServerStruct *server, Gal_DispatchFunctionSelector s, Gal_DispatchFnSignatureLister l, Gal_DispatchFunctionInvoker i, void *invocation_client_data)

Gal_DispatchFnPkg *GalIO_GetServerDispatchFnPkg(GalIO_ServerStruct *scomm)

void GalIO_SetServerDispatchFnPkg(GalIO_ServerStruct *scomm, Gal_DispatchFnPkg *pkg)

GalIO_CommStruct *GalIO_AcceptUniqueConnection(GalIO_ServerStruct *scomm)

void GalIO_SetServerListenStatus(GalIO_ServerStruct *scomm, int server_listen_status, const char *client_pair_string, const char *session_id)
Sets the listener status and a variety of other information relevant to the listener status. The client_pair_string has the same format as the -contact_hub command line argument, and the session ID is the name of the session the connection(s) should be locked to.

int GalIO_ServerHandler(GalIO_ServerStruct *scomm, GalIO_CommStruct **new_conn_ptr)
This function listens for connections on the socket initialized by GalSS_InitializeServerToplevel. It returns 1 if a connection has been established, 0 if not, -1 if error. Once the connection has been established, GalIO_ConnectionPoll should be used for further handling. On error, the server should be marked as done and shut down.

void GalIO_SetServerDone(GalIO_ServerStruct *scomm)
Marks the server as done. GalIO_DestroyServerStruct will not actually destroy the server until it's marked as done.

void GalIO_DestroyServerStruct(GalIO_ServerStruct *scomm)
Destroys a server as soon as it's marked as done.

int GalIO_ServerPoll(GalIO_ServerStruct *scomm)
Polls the server and all connections associated with it. The status returned is the one associated with the server.

int GalIO_ServerIsClient(GalIO_ServerStruct *scomm)
Returns 1 if the server will contact a Hub listener to set up connections, 0 otherwise.

int GalIO_ServerIsListener(GalIO_ServerStruct *scomm)
Returns 1 if the server has its own listener which the Hub will contact to set up connections, 0 otherwise.

int GalIO_ServerListensForConnections(GalIO_ServerStruct *s)
Returns 1 if the server has its own listener and that listener is listening for "regular" connections (that is, connections which will fire dispatch functions), 0 otherwise.

int GalIO_ServerListensForBrokers(GalIO_ServerStruct *s)
Returns 1 if the server has its own listener and that listener is listening for broker connections, 0 otherwise.

Flow of control functions

GalIO_ServerStruct *GalIO_ServerInit(unsigned short port, int require_port, GalIO_FrameHandler fnptr, void *server_data, int poll_ms, int max_connections)
This function creates a structure which contains the appropriate information for interacting with the Hub: the file descriptors, ports, appropriate buffers, and information for callbacks. The port is the port the server should start on. If require_port is 0, the function will start the server on the first port number which is available, starting from port; otherwise, the function will return NULL if the port is unavailable. The fnptr is always GalSS_FrameHandler.

The poll_ms indicate how often the state of the server should be checked. If the number is 0 or greater, this function will set up a timed task to check the state of the server. If the number is 0, the system uses the default (100 ms, currently); positive values are taken to be poll intervals in milliseconds. If the number is less than 0, no timed task is set up, and the developer is responsible for polling the system.

Finally, the server_data defines the information which can be retrieved using GalIO_GetCommServerData and GalIO_GetServerData.

GalIO_ServerStruct *GalIO_ServerCreate(unsigned short port, int require_port, GalIO_FrameHandler fnptr, void *server_data, int poll_ms, int max_connections)

GalIO_ServerStruct *GalIO_ServerStart(GalIO_ServerStruct *scomm)

int GalIO_StartListener(GalIO_ServerStruct *scomm, int additional_flags)
Ensures that a listener is started. Used internally by the outgoing broker setup.

int GalIO_StartClient(GalIO_ServerStruct *scomm)

GalIO_CommStruct *GalIO_ClientInit(const char *host, unsigned short port, GalIO_FrameHandler fnptr, int poll_ms)

intGalIO_OutHandler(GalIO_CommStruct *gcomm)

int GalIO_InHandler(GalIO_CommStruct *gcomm)

GalIO_ServerStruct *GalIO_ListenerCreate(unsigned short port, int require_port, GalIO_FrameHandler foo_ptr, void *server_data, int poll_ms, int max_connections)

void GalIO_SetServerDisconnectCallback(GalIO_ServerStruct *scomm, void (*disconnect_callback)(GalIO_CommStruct *server_data))

int GalIO_VerificationHandler(GalIO_CommStruct *gcomm)

GalIO_ServerLocation *GalIO_AddServerLocation(GalIO_ServerStruct *scomm, const char *host, unsigned short port, int client_poll_flags)

void GalIO_FreeServerLocations(GalIO_ServerLocation *loc)

Socket queue functions

GalIO_SockQueueStruct *GalIO_CreateSockQueue(GAL_SOCKET sockfd, int in_size, int out_size)

void GalIO_DestroySockQueue(GalIO_SockQueueStruct *q)

void GalIO_SetSockQueueComment(GalIO_SockQueueStruct *q, char *comment)

int GalIO_GetSockQueueError(GalIO_SockQueueStruct *q)

int GalIO_SockQueueProcessSend(GalIO_SockQueueStruct *q)

int GalIO_SockQueueProcessReceive(GalIO_SockQueueStruct *q)

int GalIO_SockQueueWrite(GalIO_SockQueueStruct *q, void *data, long len)

int GalIO_SockQueueRead(GalIO_SockQueueStruct *q, char *data, int max_data_len, int *data_len)

int GalIO_SockQueueReadAtom(GalIO_SockQueueStruct *q, char *data, int data_len)