FreeRTOS Tetris
Macros | Typedefs | Enumerations | Functions
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...

Collaboration diagram for Async IO API:

Macros

#define MQ_MAXMSG   256
 
#define MQ_MSGSIZE   256
 

Typedefs

typedef void * aIO_handle_t
 Handle used to reference and opened asyncronour communications channel.
 
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.
 

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 (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 (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.

Typedef Documentation

◆ aIO_callback_t

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

#include <AsyncIO.h>

Callback for an asynchronous IO connection.

Parameters
recv_sizeThe number of bytes received
bufferBuffer containing the received data
argsArgs passed in during the creation of the connection

Function Documentation

◆ aIOCloseConn()

void aIOCloseConn ( aIO_handle_t  conn)

#include <AsyncIO.h>

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

Parameters
connHandle to the connection that is to be closed

◆ aIODeinit()

void aIODeinit ( void  )

#include <AsyncIO.h>

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 ( char *  mq_name,
char *  buffer 
)

#include <AsyncIO.h>

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

Parameters
mq_nameName 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
bufferA 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 ( char *  name,
long  max_msg_num,
long  max_msg_size,
aIO_callback_t  callback,
void *  args 
)

#include <AsyncIO.h>

Open a POSIX message queue.

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

Parameters
nameThe name of the POSIX message queue, note that the message queue name does not require the preceeding '/' as this is handled automatically
max_msg_numThe max. # of messages that can be in the queue. See mq_open(3). A global limit is set using MQ_MAXMSG.
max_msg_sizeThe max. length of a single message. A global limit is set using MQ_MSGSIZE.
callbackA callback function that is called and passed the received data.
argsArgs 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 
)

#include <AsyncIO.h>

Opens a socket enpoint.

Parameters
s_addrIP address of target client in IPv4 numbers-and-dots notation. eg. 127.0.0.1. NULL for localhost/loopback.
portPort to open the socket on
buffer_sizeNumber of bytes to be reserved as a buffer for the connection
callbackCallback triggered each time trffic is received
argsArgs 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 
)

#include <AsyncIO.h>

Opens a socket enpoint.

Parameters
s_addrIP address of target client in IPv4 numbers-and-dots notation. eg. 127.0.0.1. NULL for localhost/loopback.
portPort to open the socket on
buffer_sizeNumber of bytes to be reserved as a buffer for the connection
callbackCallback triggered each time trffic is received
argsArgs 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 
)

#include <AsyncIO.h>

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

Parameters
protocolEither UDP or TCP,
See also
aIO_socket_e
Parameters
s_addrIP address of target client in IPv4 numbers-and-dots notation. eg. 127.0.0.1. NULL for localhost/loopback.
portPort
bufferReference to data to be sent
buffer_sizeLength of the data to be send in bytes
Returns
returns 0 on success; on error, -1 is returned.