cl_com_messages_in_send_queue() -- Returns the number of messages in the
send queue of the communication library
unsigned long cl_com_messages_in_send_queue(cl_com_handle_t *handle)
Returns the number of messages in the send queue of the commlib
library, i.e. the messages that were placed into the send queue
using the cl_commlib_send_message() function but were not
immediately sent.
cl_com_handle_t *handle - Handle of the commlib instance.
unsigned long - Number of messages in send queue.
MT-NOTE: cl_com_messages_in_send_queue() is MT safe
cl_com_setup_commlib_complete() -- check whether commlib setup was called
bool cl_com_setup_commlib_complete(void)
This function returns true when cl_com_setup_commlib() was called
at least one time.
bool - true: cl_com_setup_commlib() was done
false: There was no commlib setup till now
MT-NOTE: cl_com_setup_commlib_complete() is MT safe
cl_com_close_connection() -- cleanup a connection
int cl_com_close_connection(cl_com_connection_t* connection)
This wrapper function will call the correct cl_com_xxx_close_connection()
function for the selected framework. The called function must free
the memory for the connection->com_private pointer.
cl_com_connection_t* connection - pointer to a cl_com_connection_t
structure
int - CL_RETVAL_XXXX error or CL_RETVAL_OK on success
cl_com_connection_request_handler() -- Get new incomming connections
int cl_com_connection_request_handler(cl_com_connection_t* connection,
cl_com_connection_t** new_connection, int timeout_val_sec, int
timeout_val_usec)
This wrapper function will call the correct
cl_com_xxx_connection_request_handler() function for the selected
framework.
It will create a new connection pointer and sets new_connection to the
new connection when connection requests are queueing. new_connection
must point to NULL when calling this function.
The new connection must be handled (and erased) by the caller of this
function.
cl_com_connection_t* connection - pointer to service connection
struct. (Created with a call to
cl_com_connection_request_handler_setup())
cl_com_connection_t** new_connection - pointer to an address of a cl_com_connection_t
struct. (will be set to a new
connection)
int timeout_val_sec - timeout in sec
int timeout_val_usec - timeout in usec
int - CL_RETVAL_XXXX error or CL_RETVAL_OK on success
cl_com_connection_request_handler_cleanup() -- cleanup service
int cl_com_connection_request_handler_cleanup(cl_com_connection_t*
connection)
This wrapper function calls the correct
cl_com_xxx_connection_request_handler_cleanup() function to shutdown a
server connection.
cl_com_connection_t* connection - open service connection struct
int - CL_RETVAL_XXXX error or CL_RETVAL_OK on success
cl_com_connection_request_handler_setup() -- Setup service
int cl_com_connection_request_handler_setup(cl_com_connection_t*
connection)
This function is used to setup a connection service handler. All service
specific setup is done here. When the setup was done the connection can
be used to call cl_com_connection_request_handler(). To shutdown the
service a call to cl_com_connection_request_handler_cleanup() must be done.
This function is only a wrapper for the correct
cl_com_xxx_connection_request_handler_setup() function of the selected
framework.
cl_com_connection_t* connection - pointer to a inizialized connection
int - CL_RETVAL_XXXX error or CL_RETVAL_OK on success
cl_com_open_connection() -- open a connection to a service handler
int cl_com_open_connection(cl_com_connection_t* connection, const char*
comp_host, const char* comp_name, int comp_id, int timeout)
This function is called to setup a connection to a service handler. The
connection object (cl_com_connection_t) must be initalized with a call
to cl_com_setup_xxx_connection (e.g. cl_com_setup_tcp_connection() for
a CL_CT_TCP connection which is using tcp/ip for transport)
cl_com_connection_t* connection - pointer to a connection object
const char* comp_host - host of service
const char* comp_name - component name of service
int comp_id - component id of service
int timeout - timeout for connection establishment
int - CL_COMM_XXXX error value or CL_RETVAL_OK for no errors
cl_com_open_connection_request_handler() -- Check for incomming data
int cl_com_open_connection_request_handler(int framework_type,
cl_raw_list_t* connection_list, int timeout)
This function is a wrapper for the correct
cl_com_xxx_open_connection_request_handler() function of the selected
framework.
This function will set the connection data_read_flag if there is any
data to read from this connection.
int framework_type - framework type of connection list
cl_raw_list_t* connection_list - list of connections to check
int timeout - timeout
int - CL_RETVAL_XXXX error or CL_RETVAL_OK on success
cl_com_tcp_setup_connection() -- setup a connection type
int cl_com_tcp_setup_connection(cl_com_connection_t* connection, int
server_port, int connect_port)
This function is used to setup the connection type. It will malloc
a cl_com_tcp_private_t structure and set the pointer
connection->com_private to this structure.
When the connection structure is used to provide a service the server_port
must be specified. If the connection is used to be a client to a service
the connect_port must be specified.
The memory obtained by the malloc() call for the cl_com_tcp_private_t structure
is released by a call to cl_com_tcp_close_connection()
cl_com_connection_t* connection - empty connection structure
int server_port - port to provide a tcp service
int connect_port - port to connect to
int data_flow_type - CL_COM_STREAM or CL_COM_MESSAGE
int - CL_COMM_XXXX error value or CL_RETVAL_OK for no errors
cl_com_tcp_close_connection() -- close and shutdown a tcp connection
int cl_com_tcp_close_connection(cl_com_connection_t* connection)
This function will shutdown and close the connection (if open) and free
the connection->com_private pointer for a tcp connection.
cl_com_connection_t* connection - connection pointer
int - CL_RETVAL_XXXX error or CL_RETVAL_OK on success
cl_com_tcp_connection_request_handler() -- Check for connection requests
int cl_com_tcp_connection_request_handler(cl_com_connection_t*
connection, cl_com_connection_t** new_connection, int timeout_val_sec,
int timeout_val_usec)
This function will do a select call for the service connection file de-
scriptor. If the select returns with no error the connection is accepted
(via accept()) and a new connection structure ( cl_com_connection_t )
is malloced. The new connection will get all default settings from the
service connection struct.
This function has to fill all struct information for the new connection
( cl_com_connection_t type)
cl_com_connection_t* connection - pointer to service connection
cl_com_connection_t** new_connection - NULL
int timeout_val_sec - timeout value in sec (for select)
int timeout_val_usec - timeout value in usec (for select)
int - CL_RETVAL_XXXX error or CL_RETVAL_OK on success
an address to a new connection in new_connection parameter
cl_com_tcp_connection_request_handler_cleanup() -- shutdown service
int cl_com_tcp_connection_request_handler_cleanup(cl_com_connection_t*
connection)
This function will shutdown a service connection, created with the
cl_com_tcp_connection_request_handler_setup() function. Free the connection
with cl_tcp_close_connection() has to be done by caller.
cl_com_connection_t* connection - Connection to shutdown
int - CL_RETVAL_XXXX error or CL_RETVAL_OK on success
cl_com_tcp_connection_request_handler_setup() -- bind tcp/ip socket
int cl_com_tcp_connection_request_handler_setup(cl_com_connection_t*
connection)
This function creates a new stream socket and sets SO_REUSEADDR socket
option. After that the socket is bind to the server_port. A final listen
enables connection requests on that socket.
cl_com_connection_t* connection - pointer to connection
int - CL_RETVAL_XXXX error or CL_RETVAL_OK on success
cl_com_tcp_free_com_private() -- free private struct of a tcp connection
int cl_com_tcp_free_com_private(cl_com_connection_t* connection)
This function will free the com_private struct pointer of a tcp connection
struct
cl_com_connection_t* connection - pointer to tcp/ip connection
int - CL_RETVAL_XXXX error or CL_RETVAL_OK on success
cl_com_tcp_get_private() -- get cl_com_tcp_private_t struct of a connection
static cl_com_tcp_private_t* cl_com_tcp_get_private(cl_com_connection_t*
connection)
This function returns the com_private pointer of the connection and does
a type cast.
cl_com_connection_t* connection - tcp connection to get private struct
static cl_com_tcp_private_t* - pointer to private tcp data of tcp connection
cl_com_tcp_open_connection() -- open a tcp/ip connection
int cl_com_tcp_open_connection(cl_com_connection_t* connection, const
char* comp_host, const char* comp_name, int comp_id, int timeout)
This function will create a new socket file descriptor and set the
SO_REUSEADDR socket option and the O_NONBLOCK file descriptor flag.
After that the socket will try to connect the service handler on the
given connect_port (set with cl_com_tcp_setup_connection()) on the
host specified with comp_host. After a successful connect the
TCP_NODELAY socket option is set.
cl_com_connection_t* connection - pointer to a connection struct
const char* comp_host - host where a service is available
const char* comp_name - component name of service
int comp_id - component id of service
int timeout - timeout for connect
int - CL_COMM_XXXX error value or CL_RETVAL_OK for no errors
cl_com_tcp_open_connection_request_handler() -- ???
int cl_com_tcp_open_connection_request_handler(cl_raw_list_t*
connection_list, int timeout_val)
First action of this function is do set the data_read_flag of each
connection in the list to CL_COM_DATA_NOT_READY.
After that this function will do a select on all file descriptors in
the list for reading. If the select returns that there is data for a
connection the data_read_flag of the connection
( struct cl_com_connection_t ) is set.
cl_raw_list_t* connection_list - connection list
int timeout_val - timeout for select
int - CL_RETVAL_XXXX error or CL_RETVAL_OK on success
cl_com_transformString2XML() -- convert special chars to escape sequences
int cl_com_transformString2XML(const char* input, char** output)
This function will parse the input char string and replace characters
by escape sequences in the output string where necessary. The user has
to sge_free() the output string.
const char* input - input string without xml escape sequences
char** output - pointer to empty string pointer. The function will
malloc() memory for the output string and return
the input string with xml escape sequences.
Character XML escape sequence name
'\n' "
" carriage return
'\r' "
" linefeed
'\t' "	" tab
'&' "&" amp
'<' "<" lower than
'>' ">" greater than
'"' """ quote
'\'' "'" apostrophe
int - CL_RETVAL_OK - no errors
CL_RETVAL_PARAMS - input or output are not correctly initialized
CL_RETVAL_MALLOC - can't malloc() memory for output string
MT-NOTE: cl_com_transformString2XML() is MT safe
cl_com_transformXML2String() -- convert XML escape sequences to string
int cl_com_transformXML2String(const char* input, char** output)
Converts an XML string into standard string without XML escape sequences.
Character XML escape sequence name
'\n' "
" carriage return
'\r' "
" linefeed
'\t' "	" tab
'&' "&" amp
'<' "<" lower than
'>' ">" greater than
'"' """ quote
'\'' "'" apostrophe
const char* input - xml sequence string
char** output - pointer to empty string pointer. The function will
malloc() memory for the output string and return
the input string with xml escape sequences converted to
standard string characters.
int - CL_RETVAL_OK - no errors
CL_RETVAL_PARAMS - input or output are not correctly initialized
CL_RETVAL_MALLOC - can't malloc() memory for output string
MT-NOTE: cl_com_transformXML2String() is MT safe
cl_com_close_connection: cl_communication cl_com_close_connectioncl_com_connection_request_handler: cl_communication cl_com_connection_request_handlercl_com_connection_request_handler_cleanup: cl_communication cl_com_connection_request_handler_cleanupcl_com_connection_request_handler_setup: cl_communication cl_com_connection_request_handler_setupcl_com_messages_in_send_queue: cl_commlib cl_com_messages_in_send_queuecl_com_open_connection: cl_communication cl_com_open_connectioncl_com_open_connection_request_handler: cl_communication cl_com_open_connection_request_handlercl_com_setup_commlib_complete: cl_commlib cl_com_setup_commlib_completecl_com_tcp_close_connection: cl_tcp_framework cl_com_tcp_close_connectioncl_com_tcp_connection_request_handler: cl_tcp_framework cl_com_tcp_connection_request_handlercl_com_tcp_connection_request_handler_cleanup: cl_tcp_framework cl_com_tcp_connection_request_handler_cleanupcl_com_tcp_connection_request_handler_setup: cl_tcp_framework cl_com_tcp_connection_request_handler_setupcl_com_tcp_free_com_private: cl_tcp_framework cl_com_tcp_free_com_privatecl_com_tcp_get_private: cl_tcp_framework cl_com_tcp_get_privatecl_com_tcp_open_connection: cl_tcp_framework cl_com_tcp_open_connectioncl_com_tcp_open_connection_request_handler: cl_tcp_framework cl_com_tcp_open_connection_request_handlercl_com_tcp_setup_connection: cl_communication cl_com_tcp_setup_connectioncl_com_transformString2XML: commlib cl_xml_parsing cl_com_transformString2XMLcl_com_transformXML2String: commlib cl_xml_parsing cl_com_transformXML2String