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_initialise	Initialise the package.
conn_register_server_protocol	Register server protocol support.
conn_register_client_protocol	Register client protocol support.
conn_get_channel	Extract the channel object associated with a connection.
conn_get_datagram_channel	Extract the datagram channel associated with a connection.
conn_attempt_connection	Attempt connection.
conn_close	Close connection.
conn_become_server	Become a Karma server.
conn_get_num_serv_connections	Get number of server connections.
conn_get_num_client_connections	Get number of client connections.
conn_get_serv_connection	Get a numbered server connection.
conn_get_client_connection	Get a numbered client connection.
conn_get_connection_info	Get the arbitrary information for a connection.
conn_controlled_by_cm_tool	Check if controlled by CM tool.
conn_get_connection_module_name	Get the name of the module at the other end of a connection.
conn_get_connection_remote_addr	Get the address of the machine at the other end of a connection.
conn_register_cm_quiescent_func	Register callback for quiescence.
conn_extract_protocols	Get supported protocols.
conn_show_connections	Show all connections.

Prototype Functions

exit_schedule_func	Exit schedule function.
conn_PROTO_client_validate_func	Client connection validate event callback.
conn_PROTO_open_func	Connection open event callback.
conn_PROTO_read_func	Connection read event callback.
conn_PROTO_close_func	Connection close event callback.
conn_PROTO_quiescent_func	Quiescence callback.

Functions

EXPERIMENTAL FUNCTION: subject to change without notice

void conn_initialise ( void (*exit_schedule_func) () )

Initialise the package.

Parameters:

exit_shedule_func : The routine which should be called when a clean exit is to be scheduled. The prototype function is conn_PROTO_exit_schedule_func. If this is NULL, then exit(3) is called instead.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

This routine MUST be called prior to the conn_become_server routine.

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:

protocol_name : The name of the new protocol to support. Note that this is only for incoming connections.
version : The version number for the protocol. When any changes to the protocol are made, this should be increased.
max_connections : The maximum number of incoming connections to this server If this is 0, an unlimited number of connections is permitted.
open_func : The routine which is called when a new connection is opened. The prototype function is conn_PROTO_open_func.
read_func : The function which will be called when data is ready to be read data from the connection. The prototype function is conn_PROTO_read_func.
close_func : The function which will be called prior to closure of a connection. The prototype function is conn_PROTO_close_func.

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:

protocol_name : The name of the new protocol to support. Note that this is only for outgoing connections.
version : The version number for the protocol. When any changes to the protocol are made, this should be increased.
max_connections : The maximum number of outgoing connections from this client. If this is 0, an unlimited number of connections is permitted.
validate_func : The function which will validate the opening of a new connection (prior to any attempts to connect to the server). The prototype function is conn_PROTO_client_validate_func.
open_func : The routine which is called when a new connection is opened. The prototype function is conn_PROTO_open_func.
read_func : The function which will be called when data is ready to be read data from the connection. The prototype function is conn_PROTO_read_func.
close_func : The function which will be called prior to closure of a connection. The prototype function is conn_PROTO_close_func.

Returns: Nothing.
Multithreading Level: Unsafe

Channel conn_get_channel (Connection connection)

Extract the channel object associated with a connection.

Parameters:

connection : The connection object.

Returns: The channel object.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

Channel conn_get_datagram_channel (Connection connection)

Extract the datagram channel associated with a connection.

Parameters:

connection : The connection object.

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

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:

hostname : The hostname of the machine on which the server is running.
port_number : The Karma port number to connect to.
protocol_name : The protocol to connect with.

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

The appropriate callback functions registered with conn_register_client_protocol will be called.

flag conn_close (Connection connection)

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

Parameters:

connection : The connection object.

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:

port_number : The port number to allocate. The routine will write the actual port number allocated to this address. This must point to an address which lies on an int boundary.
retries : The number of succsessive port numbers to attempt to allocate before giving up. If this is 0, then the routine will give up immediately if the specified port number is in use.

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:

protocol_name : The protocol name.

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:

protocol_name : The protocol name.

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:

protocol_name : The protocol name.
number : The number of the connection to get.

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:

protocol_name : The protocol name.
number : The number of the connection to get.

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:

connection : The connection object. The routine aborts the process if the connection is not valid.

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:

connection : The connection object. The routine aborts the process if the connection is not valid.

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:

connection : The connection object. The routine aborts the process if the connection is not valid.

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:

quiescent_func : The routine which will be called when the Connection Management tool or shell is quiescent. The prototype function is conn_PROTO_quiescent_func.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

Only one callback may be registered.

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 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:

info : A pointer to the arbitrary information pointer. This may be modified

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

Even if this routine is called and returns TRUE, there is no guarantee that the connection will be subsequently opened.

flag conn_PROTO_open_func (Connection connection, void **info)

This routine is called when a connection opens.

Parameters:

connection : The connection object.
info : A pointer to the arbitrary information pointer. This may be modified

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

The close_func will not be called if this routine returns FALSE.

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:

connection : The connection object.
info : A pointer to the arbitrary information pointer. This may be modified
channel : The channel object on which the read event occurred. This may be the normal or datagram channel.

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

The close_func will be called if this routine returns FALSE.

void conn_PROTO_close_func (Connection connection, void *info)

This routine is called when a connection 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:

connection : The connection object.
info : The arbitrary connection information pointer.

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