The "conn" Package

These routines are meant to provide a high level mechanism to create and accept connections, complete with protocols, callback functions and security mechanisms.

Library: karma
Link With: -lkarma

Functions

conn_initialiseInitialise the package.
conn_register_server_protocolRegister server protocol support.
conn_register_client_protocolRegister client protocol support.
conn_get_channelExtract the channel object associated with a connection.
conn_get_datagram_channelExtract the datagram channel associated with a connection.
conn_attempt_connectionAttempt connection.
conn_closeClose connection.
conn_become_serverBecome a Karma server.
conn_get_num_serv_connectionsGet number of server connections.
conn_get_num_client_connectionsGet number of client connections.
conn_get_serv_connectionGet a numbered server connection.
conn_get_client_connectionGet a numbered client connection.
conn_get_connection_infoGet the arbitrary information for a connection.
conn_controlled_by_cm_toolCheck if controlled by CM tool.
conn_get_connection_module_nameGet the name of the module at the other end of a connection.
conn_get_connection_remote_addrGet the address of the machine at the other end of a connection.
conn_register_cm_quiescent_funcRegister callback for quiescence.
conn_extract_protocolsGet supported protocols.
conn_show_connectionsShow all connections.

Prototype Functions

conn_PROTO_exit_schedule_funcExit schedule function.
conn_PROTO_client_validate_funcClient connection validate event callback.
conn_PROTO_open_funcConnection open event callback.
conn_PROTO_read_funcConnection read event callback.
conn_PROTO_close_funcConnection close event callback.
conn_PROTO_quiescent_funcQuiescence callback.


Functions


EXPERIMENTAL FUNCTION: subject to change without notice

void conn_initialise ( void (*exit_schedule_func) () )

Initialise the package.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe
Note:


void conn_register_server_protocol ( CONST char *protocol_name, unsigned int version, unsigned int max_connections, flag (*open_func) (), flag (*read_func) (), void (*close_func) () )

This routine will register the support of a new Karma protocol for the Karma ports which are being managed by the various routines in the conn package. This routine may be called at any time.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe


void conn_register_client_protocol ( CONST char *protocol_name, unsigned int version, unsigned int max_connections, flag (*validate_func) (), flag (*open_func) (), flag (*read_func) (), void (*close_func) () )

This routine will register the support of a new Karma protocol for outgoing (client) connections. This routine may be called at any time.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe


Channel conn_get_channel (Connection connection)

Extract the channel object associated with a connection.

Parameters:

Returns: The channel object.
Multithreading Level: Unsafe
See Also: conn_get_datagram_channel.


EXPERIMENTAL FUNCTION: subject to change without notice

Channel conn_get_datagram_channel (Connection connection)

Extract the datagram channel associated with a connection.

Parameters:

Returns: The datagram channel object. This may be NULL if the connection is a normal stream (i.e. no extra unreliable datagram channel).
Multithreading Level: Unsafe
See Also: conn_get_channel.


Connection conn_attempt_connection (CONST char *hostname, unsigned int port_number, CONST char *protocol_name)

This routine will attempt to make a connection to a server. The routine always makes a connection using the most efficient transport layer available.

Parameters:

Returns: The connection object on success, else NULL.
Multithreading Level: Unsafe
Note:


flag conn_close (Connection connection)

This routine will close a connection. This will cause the closure callback routine registered to be executed.

Parameters:

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe


flag conn_become_server (unsigned int *port_number, unsigned int retries)

This routine will allocate a Karma port for the module so that it can operate as a server (able to receive network connections).

Parameters:

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe


unsigned int conn_get_num_serv_connections (CONST char *protocol_name)

This routine will get the number of connections to this server with a specified protocol.

Parameters:

Returns: The number of current connections. A return value of 0 indicates that the protocol is not supported or there are no current connections.
Multithreading Level: Unsafe


unsigned int conn_get_num_client_connections (CONST char *protocol_name)

This routine will get the number of connections from this client with a specified protocol.

Parameters:

Returns: The number of current connections. A return value of 0 indicates that the protocol is not supported or there are no current connections.
Multithreading Level: Unsafe


Connection conn_get_serv_connection (CONST char *protocol_name, unsigned int number)

This routine will get Nth connection to this server with a specified protocol. The first connection is numbered 0.

Parameters:

Returns: The connection object on success, else NULL.
Multithreading Level: Unsafe


Connection conn_get_client_connection (CONST char *protocol_name, unsigned int number)

This routine will get Nth connection from this client with a specified protocol. The first connection is numbered 0.

Parameters:

Returns: The connection object on success, else NULL.
Multithreading Level: Unsafe


void * conn_get_connection_info (Connection connection)

Get the arbitrary information for a connection.

Parameters:

Returns: A pointer to the arbitrary information. This may be NULL.
Multithreading Level: Unsafe


flag conn_controlled_by_cm_tool ()

This routine will determine if the module is being controlled by the Connection Management tool.

Parameters:

Returns: TRUE if the module is controlled, else FALSE
Multithreading Level: Unsafe


char * conn_get_connection_module_name (Connection connection)

Get the name of the module at the other end of a connection.

Parameters:

Returns: A pointer to the module name.
Multithreading Level: Unsafe


EXPERIMENTAL FUNCTION: subject to change without notice

unsigned long conn_get_connection_remote_addr (Connection connection)

Get the address of the machine at the other end of a connection.

Parameters:

Returns: The IP address.
Multithreading Level: Unsafe


void conn_register_cm_quiescent_func ( void (*func) () )

This routine will register a callback function to be called when the Connection Management tool or shell is quiescent (ie. all modules have started and all initial connections made). The function is ONLY called if the module is running under the Connection Management tool or shell.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe
Note:


char ** conn_extract_protocols ()

This routine will extract all the supported protocols and produces a dynamically allocated array of strings which may be later displayed.

Parameters:

Returns: A pointer to a dynamically allocated array of dynamically allocated strings on success, else NULL. The end of the array is marked with a NULL string pointer.
Multithreading Level: Unsafe


EXPERIMENTAL FUNCTION: subject to change without notice

void conn_show_connections ()

Show all connections.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe


Prototype Functions


void conn_PROTO_exit_schedule_func ()

This routine is called when the conn package wishes to schedule a clean exit from the module. This routine may return (ie. it need not exit).

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe


flag conn_PROTO_client_validate_func (void **info)

This routine is called to validate whether it is appropriate to open a connection.

Parameters:

Returns: TRUE if the connection should be attempted, else FALSE indicating the connection should be aborted.
Multithreading Level: Unsafe
Note:


flag conn_PROTO_open_func (Connection connection, void **info)

This routine is called when a connection opens.

Parameters:

Returns: TRUE on successful registration, else FALSE (indicating the connection should be closed).
Multithreading Level: Unsafe
Note:


flag conn_PROTO_read_func (Connection connection, void **info, Channel channel)

This routine is called when data is ready to be read from a connection.

Parameters:

Returns: TRUE on successful reading, else FALSE (indicating the connection should be closed).
Multithreading Level: Unsafe
Note:


void conn_PROTO_close_func (Connection connection, void *info, Channel channel)

This routine is called when a connection is closed. When this routine is called, this is the last chance to read any buffered data from the channel associated with the connection object.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe


void conn_PROTO_quiescent_func ()

This routine is called when the Connection Management tool or shell is quiescent.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe


Back to Karma Home Page
Contact: Richard Gooch
Web Development: Ariel Internet Services