Async IO API

Asynchronous Linux Based Communications API allows for the creation of asynchronous communications channels that allow for passive IO through the use of callbacks. More...

Macros
#define	MQ_MAXMSG   256
#define	MQ_MSGSIZE   256

Typedefs
typedef void *	aIO_handle_t
	Handle used to reference and opened asyncronour communications channel. More...
typedef void(*	aIO_callback_t) (size_t recv_size, char *buffer, void *args)
	Callback for an asynchronous IO connection. More...

Enumerations
enum	aIO_socket_e { UDP , TCP }
	Socket protocols supported. More...

Functions
void	aIODeinit (void)
	Function that closes all open connections. More...
void	aIOCloseConn (aIO_handle_t conn)
	Closes a connection and frees all resources used by that connection. More...
int	aIOMessageQueuePut (const char *mq_name, char *buffer)
	Sends the data stored in buffer to the message queue with the provided name. More...
int	aIOSocketPut (aIO_socket_e protocol, char *s_addr, in_port_t port, char *buffer, size_t buffer_size)
	Send the data stored in buffer to the socket described by s_addr and port. More...
aIO_handle_t	aIOOpenMessageQueue (const char *name, long max_msg_num, long max_msg_size, aIO_callback_t callback, void *args)
	Open a POSIX message queue. More...
aIO_handle_t	aIOOpenUDPSocket (char *s_addr, in_port_t port, size_t buffer_size, aIO_callback_t callback, void *args)
	Opens a socket enpoint. More...
aIO_handle_t	aIOOpenTCPSocket (char *s_addr, in_port_t port, size_t buffer_size, aIO_callback_t callback, void *args)
	Opens a socket enpoint. More...

Detailed Description

Asynchronous Linux Based Communications API allows for the creation of asynchronous communications channels that allow for passive IO through the use of callbacks.

Focusing on sockets (UDP and TCP) and POSIX message queues, this API allows for the creation of the particular IO stream, registering a callback to the stream that is automatically called when a communication event is triggered on the stream. For example a UDP packet is send to the port that is bound to the socket associated to the IO stream, passing the received packet buffer to the user-defined callback.

Macro Definition Documentation

MQ_MAXMSG

#define MQ_MAXMSG   256

MQ_MSGSIZE

#define MQ_MSGSIZE   256

Typedef Documentation

aIO_callback_t

typedef void(* aIO_callback_t) (size_t recv_size, char *buffer, void *args)

Callback for an asynchronous IO connection.

Parameters

recv_size	The number of bytes received
buffer	Buffer containing the received data
args	Args passed in during the creation of the connection

aIO_handle_t

typedef void* aIO_handle_t

Handle used to reference and opened asyncronour communications channel.

Enumeration Type Documentation

aIO_socket_e

enum aIO_socket_e

Socket protocols supported.

Enumerator
UDP
TCP

Function Documentation

aIOCloseConn()

void aIOCloseConn

(

aIO_handle_t

conn

)

Closes a connection and frees all resources used by that connection.

Parameters

conn	Handle to the connection that is to be closed

aIODeinit()

void aIODeinit

(

void

)

Function that closes all open connections.

Calling this function will close all connection and free all allocated reources used by those connections. Use in conjunction with atexit to automatically free all resources when exiting the program via normal methods (eg. SIGINT).

aIOMessageQueuePut()

int aIOMessageQueuePut	(	const char *	mq_name,
		char *	buffer
	)

Sends the data stored in buffer to the message queue with the provided name.

Parameters

mq_name	Name of the message queue to which the data is to be sent, note that the message queue name does not require the preceeding '/' as this is handled automatically
buffer	A reference to the buffer storing the data to be send to the message queue

Returns

returns 0 on success; on error, -1 is returned.

aIOOpenMessageQueue()

aIO_handle_t aIOOpenMessageQueue	(	const char *	name,
		long	max_msg_num,
		long	max_msg_size,
		aIO_callback_t	callback,
		void *	args
	)

Open a POSIX message queue.

Opens a POSIX message queue as described in MQ_OVERVIEW(7)

Parameters

name	The name of the POSIX message queue, note that the message queue name does not require the preceeding '/' as this is handled automatically
max_msg_num	The max. # of messages that can be in the queue. See mq_open(3). A global limit is set using MQ_MAXMSG.
max_msg_size	The max. length of a single message. A global limit is set using MQ_MSGSIZE.
callback	A callback function that is called and passed the received data.
args	Args to be passed to the connection's callback function args Args to be passed to the connection's callback function

Returns

Handle to the created connection, or NULL

aIOOpenTCPSocket()

aIO_handle_t aIOOpenTCPSocket	(	char *	s_addr,
		in_port_t	port,
		size_t	buffer_size,
		aIO_callback_t	callback,
		void *	args
	)

Opens a socket enpoint.

Parameters

s_addr	IP address of target client in IPv4 numbers-and-dots notation. eg. 127.0.0.1. NULL for localhost/loopback.
port	Port to open the socket on
buffer_size	Number of bytes to be reserved as a buffer for the connection
callback	Callback triggered each time trffic is received
args	Args passed to the specified callback

Returns

Handle to the created connection, or NULL

aIOOpenUDPSocket()

aIO_handle_t aIOOpenUDPSocket	(	char *	s_addr,
		in_port_t	port,
		size_t	buffer_size,
		aIO_callback_t	callback,
		void *	args
	)

Opens a socket enpoint.

Parameters

s_addr	IP address of target client in IPv4 numbers-and-dots notation. eg. 127.0.0.1. NULL for localhost/loopback.
port	Port to open the socket on
buffer_size	Number of bytes to be reserved as a buffer for the connection
callback	Callback triggered each time trffic is received
args	Args passed to the specified callback

Returns

Handle to the created connection, or NULL

aIOSocketPut()

int aIOSocketPut	(	aIO_socket_e	protocol,
		char *	s_addr,
		in_port_t	port,
		char *	buffer,
		size_t	buffer_size
	)

Send the data stored in buffer to the socket described by s_addr and port.

The data to be sent is copied dynamically and then sent to the socket. As such, both static and dynamic buffers can be sent via aIOSocketPut.

Parameters

protocol

Either UDP or TCP,

See also

aIO_socket_e

Parameters

s_addr	IP address of target client in IPv4 numbers-and-dots notation. eg. 127.0.0.1. NULL for localhost/loopback.
port	Port
buffer	Reference to data to be sent
buffer_size	Length of the data to be send in bytes

Returns

returns 0 on success; on error, -1 is returned.