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.
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.
GAL_SOCKET GalIO_GetCommSocket(GalIO_CommStruct *gcomm)
void GalIO_CloseCommSocket(GalIO_CommStruct *gcomm)
char *GalIO_GetCommHost(GalIO_CommStruct *gcomm)
Gal_Frame GalIO_GetCommFrame(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,
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, char *name, Gal_FrameFnPtr fn, 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,
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.
GAL_SOCKET GalIO_GetServerListenSocket(GalIO_ServerStruct *scomm)
void GalIO_CloseServerListenSocket(GalIO_ServerStruct *scomm)
void GalIO_AddServerDispatchFunctionEntry(GalIO_ServerStruct *scomm, char *name, Gal_FrameFnPtr fn, 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, char *client_pair_string,
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.
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(char *host, unsigned short port, Gal_Frame frame, GalIO_FrameHandler fnptr, int poll_ms)
intGalIO_OutHandler(GalIO_CommStruct *gcomm)
int GalIO_InHandler(GalIO_CommStruct *gcomm)
int GalIO_HubHandler(GalIO_CommStruct *gcomm, int silent, Gal_Frame *reply)
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, char *host, unsigned short port, int client_poll_flags)
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)
Please send comments and suggestions to:bugs-darpacomm@linus.mitre.org
Last updated October 4, 2001.
Copyright (c) 1998 - 2001
The MITRE
Corporation
ALL RIGHTS RESERVED