# 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

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

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

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

This function takes no 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:

This function takes no 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:

This function takes no 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:

This function takes no 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, 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:

- connection : The connection object.
- info : The arbitrary connection information pointer.
- channel : The channel that was remotely closed, causing the connection to be closed. This may be NULL, indicating that the connection was closed locally.

Returns: Nothing.
Multithreading Level: Unsafe

void conn_PROTO_quiescent_func ()

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

Parameters:

This function takes no parameters

Returns: Nothing.
Multithreading Level: Unsafe

Back to Karma Home Page