Macros
#define	M_IO_LAYER_FIND_FIRST_ID SIZE_MAX

Typedefs
typedef enum M_io_type	M_io_type_t

typedef struct M_io	M_io_t

typedef struct M_io_meta	M_io_meta_t

typedef enum M_io_error	M_io_error_t

typedef enum M_io_state	M_io_state_t

Enumerations
enum	M_io_type { M_IO_TYPE_STREAM = 1 , M_IO_TYPE_WRITER = 2 , M_IO_TYPE_READER = 3 , M_IO_TYPE_LISTENER = 4 , M_IO_TYPE_EVENT = 5 }

enum	M_io_error { M_IO_ERROR_SUCCESS = 0 , M_IO_ERROR_WOULDBLOCK = 1 , M_IO_ERROR_DISCONNECT = 2 , M_IO_ERROR_ERROR = 3 , M_IO_ERROR_NOTCONNECTED = 4 , M_IO_ERROR_NOTPERM = 5 , M_IO_ERROR_CONNRESET = 6 , M_IO_ERROR_CONNABORTED = 7 , M_IO_ERROR_ADDRINUSE = 8 , M_IO_ERROR_PROTONOTSUPPORTED = 9 , M_IO_ERROR_CONNREFUSED = 10 , M_IO_ERROR_NETUNREACHABLE = 11 , M_IO_ERROR_TIMEDOUT = 12 , M_IO_ERROR_NOSYSRESOURCES = 13 , M_IO_ERROR_INVALID = 14 , M_IO_ERROR_NOTIMPL = 15 , M_IO_ERROR_NOTFOUND = 16 , M_IO_ERROR_BADCERTIFICATE = 17 , M_IO_ERROR_INTERRUPTED = 99 }

enum	M_io_state { M_IO_STATE_INIT = 0 , M_IO_STATE_LISTENING = 1 , M_IO_STATE_CONNECTING = 2 , M_IO_STATE_CONNECTED = 3 , M_IO_STATE_DISCONNECTING = 4 , M_IO_STATE_DISCONNECTED = 5 , M_IO_STATE_ERROR = 6 }

Functions
const char *	M_io_error_string (M_io_error_t error)

M_io_meta_t *	M_io_meta_create (void)

void	M_io_meta_destroy (M_io_meta_t *meta)

M_io_error_t	M_io_read (M_io_t comm, unsigned char buf, size_t buf_len, size_t *len_read)

M_io_error_t	M_io_read_into_buf (M_io_t comm, M_buf_t buf)

M_io_error_t	M_io_read_into_parser (M_io_t comm, M_parser_t parser)

M_io_error_t	M_io_read_meta (M_io_t comm, unsigned char buf, size_t buf_len, size_t len_read, M_io_meta_t meta)

M_io_error_t	M_io_read_into_buf_meta (M_io_t comm, M_buf_t buf, M_io_meta_t *meta)

M_io_error_t	M_io_read_into_parser_meta (M_io_t comm, M_parser_t parser, M_io_meta_t *meta)

M_io_error_t	M_io_read_clear (M_io_t *io)

M_io_error_t	M_io_write (M_io_t comm, const unsigned char buf, size_t buf_len, size_t *len_written)

M_io_error_t	M_io_write_from_buf (M_io_t comm, M_buf_t buf)

M_io_error_t	M_io_write_meta (M_io_t comm, const unsigned char buf, size_t buf_len, size_t len_written, M_io_meta_t meta)

M_io_error_t	M_io_write_from_buf_meta (M_io_t comm, M_buf_t buf, M_io_meta_t *meta)

M_io_error_t	M_io_accept (M_io_t *io_out, M_io_t server_io)

M_io_state_t	M_io_get_state (M_io_t *io)

M_io_state_t	M_io_get_layer_state (M_io_t *io, size_t id)

size_t	M_io_layer_count (M_io_t *io)

const char *	M_io_layer_name (M_io_t *io, size_t idx)

M_io_error_t	M_io_get_error (M_io_t *io)

void	M_io_get_error_string (M_io_t io, char error, size_t err_len)

M_bool	M_io_reconnect (M_io_t *io)

void	M_io_disconnect (M_io_t *comm)

M_bool	M_io_close (M_io_t *comm)

M_bool	M_io_is_user_initiated_disconnect (M_io_t *io)

void	M_io_destroy (M_io_t *comm)

Detailed Description

Common IO functions

Macro Definition Documentation

◆ M_IO_LAYER_FIND_FIRST_ID

#define M_IO_LAYER_FIND_FIRST_ID SIZE_MAX

Passed to M_io_layer_acquire() to search for matching layer by name

Typedef Documentation

◆ M_io_type_t

typedef enum M_io_type M_io_type_t

◆ M_io_t

typedef struct M_io M_io_t

◆ M_io_meta_t

typedef struct M_io_meta M_io_meta_t

◆ M_io_error_t

typedef enum M_io_error M_io_error_t

◆ M_io_state_t

typedef enum M_io_state M_io_state_t

Enumeration Type Documentation

◆ M_io_type

enum M_io_type

io type

Enumerator
M_IO_TYPE_STREAM	Object is a stream handle, can read and write
M_IO_TYPE_WRITER	Object is write only, such as a one-way pipe
M_IO_TYPE_READER	Object is read only, such as a one-way pipe
M_IO_TYPE_LISTENER	Object is a listener for acceptance of new connections
M_IO_TYPE_EVENT	Object just handles events, cannot connect, read or write

◆ M_io_error

enum M_io_error

io error.

Enumerator
M_IO_ERROR_SUCCESS	Success. No Error
M_IO_ERROR_WOULDBLOCK	Operation would block
M_IO_ERROR_DISCONNECT	Connection disconnected during operation
M_IO_ERROR_ERROR	Generic Undefined error occurred
M_IO_ERROR_NOTCONNECTED	Connection is not established, invalid operation
M_IO_ERROR_NOTPERM	Not a permitted action for this io object
M_IO_ERROR_CONNRESET	Connection was reset by peer
M_IO_ERROR_CONNABORTED	Connection aborted
M_IO_ERROR_ADDRINUSE	Address or Port already in use
M_IO_ERROR_PROTONOTSUPPORTED	Protocol not supported by OS
M_IO_ERROR_CONNREFUSED	Connection refused
M_IO_ERROR_NETUNREACHABLE	Network requested is unreachable
M_IO_ERROR_TIMEDOUT	Operation timed out at the OS level
M_IO_ERROR_NOSYSRESOURCES	System reported not enough resources
M_IO_ERROR_INVALID	Invalid use or order of operation
M_IO_ERROR_NOTIMPL	OS Does not implement the command or parameters
M_IO_ERROR_NOTFOUND	Host/File/Path not found
M_IO_ERROR_BADCERTIFICATE	Bad Peer Certificate (TLS)
M_IO_ERROR_INTERRUPTED	Should never be returned to a user

◆ M_io_state

enum M_io_state

io state.

Enumerator
M_IO_STATE_INIT	Initializing, not yet prompted to start connecting
M_IO_STATE_LISTENING	Listening for a client connection
M_IO_STATE_CONNECTING	Attempting to establish a connection
M_IO_STATE_CONNECTED	Connected
M_IO_STATE_DISCONNECTING	In-progress graceful disconnect
M_IO_STATE_DISCONNECTED	Connection Closed/Disconnected
M_IO_STATE_ERROR	Connection in error state (not connected)

Function Documentation

◆ M_io_error_string()

const char * M_io_error_string ( M_io_error_t error )

Convert an error code to a string.

Parameters

[in] error Error code.

Returns: String description.

◆ M_io_meta_create()

M_io_meta_t * M_io_meta_create ( void )

Create an io meta data object.

Returns: io meta data object.

◆ M_io_meta_destroy()

void M_io_meta_destroy ( M_io_meta_t * meta )

Destory an io meta data object.

Parameters

[in] meta meta data object.

◆ M_io_read()

M_io_error_t M_io_read	(	M_io_t *	comm,
		unsigned char *	buf,
		size_t	buf_len,
		size_t *	len_read
	)

Read from an io object.

Parameters

[in]	comm	io object.
[out]	buf	Buffer to store data read from io object.
[in]	buf_len	Lenght of provided buffer.
[out]	len_read	Number of bytes fread from the io object.

Returns: Result.

See also: M_io_read_meta

◆ M_io_read_into_buf()

M_io_error_t M_io_read_into_buf	(	M_io_t *	comm,
		M_buf_t *	buf
	)

Read from an io object into an M_buf_t.

This will read all available data into the buffer.

Parameters

[in]	comm	io object.
[out]	buf	Buffer to store data read from io object.

Returns: Result.

See also: M_io_read_into_buf_meta

◆ M_io_read_into_parser()

M_io_error_t M_io_read_into_parser	(	M_io_t *	comm,
		M_parser_t *	parser
	)

Read from an io object into an M_parser_t.

This will read all available data into the buffer.

Parameters

[in]	comm	io object.
[out]	parser	Parser to store data read from io object.

Returns: Result.

See also: M_io_read_into_parser_meta

◆ M_io_read_meta()

M_io_error_t M_io_read_meta	(	M_io_t *	comm,
		unsigned char *	buf,
		size_t	buf_len,
		size_t *	len_read,
		M_io_meta_t *	meta
	)

Read from an io object with a meta data object.

Parameters

[in]	comm	io object.
[out]	buf	Buffer to store data read from io object.
[in]	buf_len	Lenght of provided buffer.
[out]	len_read	Number of bytes fread from the io object.
[in]	meta	Meta data object.

Returns: Result.

See also: M_io_read

◆ M_io_read_into_buf_meta()

M_io_error_t M_io_read_into_buf_meta	(	M_io_t *	comm,
		M_buf_t *	buf,
		M_io_meta_t *	meta
	)

Read from an io object into an M_buf_t with a meta data object.

This will read all available data into the buffer.

Parameters

[in]	comm	io object.
[out]	buf	Buffer to store data read from io object.
[in]	meta	Meta data object.

Returns: Result.

See also: M_io_read_into_buf

◆ M_io_read_into_parser_meta()

M_io_error_t M_io_read_into_parser_meta	(	M_io_t *	comm,
		M_parser_t *	parser,
		M_io_meta_t *	meta
	)

Read from an io object into an M_parser_t with a meta data object.

This will read all available data into the buffer.

Parameters

[in]	comm	io object.
[out]	parser	Parser to store data read from io object.
[in]	meta	Meta data object.

Returns: Result.

See also: M_io_read_into_parser

◆ M_io_read_clear()

M_io_error_t M_io_read_clear ( M_io_t * io )

Clear/Flush the read buffer to consume all data and dispose of it.

Parameters

[in] io io object

Returns: M_IO_ERROR_SUCCESS if data was flushed and the connection is still active. M_IO_ERROR_WOULDBLOCK if no data to flush, otherwise one of the additional errors if the connection failed.

◆ M_io_write()

M_io_error_t M_io_write	(	M_io_t *	comm,
		const unsigned char *	buf,
		size_t	buf_len,
		size_t *	len_written
	)

Write data to an io object.

This function will attempt to write as much data as possible. If not all data is written the application should wait until the next write event and then try writing more data.

Parameters

[in]	comm	io object.
[in]	buf	Buffer to write from.
[in]	buf_len	Number of bytes in buffer to write.
[out]	len_written	Number of bytes from the buffer written.

Returns: Result.

See also: M_io_write_meta

◆ M_io_write_from_buf()

M_io_error_t M_io_write_from_buf	(	M_io_t *	comm,
		M_buf_t *	buf
	)

Write data to an io object from an M_buf_t.

This function will attempt to write as much data as possible. If not all data is written the application should wait until the next write event and then try writing more data.

Parameters

[in]	comm	io object.
[in]	buf	Buffer to write from.

Returns: Result.

See also: M_io_write_from_buf_meta

◆ M_io_write_meta()

M_io_error_t M_io_write_meta	(	M_io_t *	comm,
		const unsigned char *	buf,
		size_t	buf_len,
		size_t *	len_written,
		M_io_meta_t *	meta
	)

Write data to an io object with a meta data object.

This function will attempt to write as much data as possible. If not all data is written the application should wait until the next write event and then try writing more data.

Parameters

[in]	comm	io object.
[in]	buf	Buffer to write from.
[in]	buf_len	Number of bytes in buffer to write.
[out]	len_written	Number of bytes from the buffer written.
[in]	meta	Meta data object.

Returns: Result.

See also: M_io_write

◆ M_io_write_from_buf_meta()

M_io_error_t M_io_write_from_buf_meta	(	M_io_t *	comm,
		M_buf_t *	buf,
		M_io_meta_t *	meta
	)

Write data to an io object from an M_buf_t with a meta data object.

This function will attempt to write as much data as possible. If not all data is written the application should wait until the next write event and then try writing more data.

Parameters

[in]	comm	io object.
[in]	buf	Buffer to write from.
[in]	meta	Meta data object.

Returns: Result.

See also: M_io_write_from_buf

◆ M_io_accept()

M_io_error_t M_io_accept	(	M_io_t **	io_out,
		M_io_t *	server_io
	)

Accept an io connection.

Typically used with network io when a connection is setup as a listening socket. The io object will remain valid and a new io object for the connection will be created.

A return of M_IO_ERROR_WOULDBLOCK should not be treated as an error. It means either there is more data that needs to be received and the event will trigger again. Or there is no more outstanding connections waiting to be accepted.

Example:

void ipserver_listen_callback(M_event_t *el, M_event_type_t type, M_io_t *io, void *thunk)
{
    M_io_t       *io_out   = NULL;
    M_io_error_t  ioerr;

    (void)thunk;

    if (type != M_EVENT_TYPE_ACCEPT)
        return;

    ioerr = M_io_accept(&io_out, io);
    if (ioerr != M_IO_ERROR_SUCCESS || io_out == NULL) {
        if (ioerr != M_IO_ERROR_WOULDBLOCK) {
            // Connection error
        }
        return;
    }

    M_event_add(el, io_out, ipserver_connection_callback, NULL);
}

Parameters

[out]	io_out	io object created from the accept.
[in]	server_io	io object which was listening.

Returns: Result.

◆ M_io_get_state()

M_io_state_t M_io_get_state ( M_io_t * io )

Current state of an io object

Parameters

[in] io io object;

Returns: State.

◆ M_io_get_layer_state()

M_io_state_t M_io_get_layer_state	(	M_io_t *	io,
		size_t	id
	)

Current state of a layer within an io object

Parameters

[in]	io	io object
[in]	id	id of a layer to query (0 for base layer)

Returns: State.

◆ M_io_layer_count()

size_t M_io_layer_count ( M_io_t * io )

Retrieve the number of layers from an io object

Parameters

[in] io io object

Returns: count of layers in object

◆ M_io_layer_name()

const char * M_io_layer_name	(	M_io_t *	io,
		size_t	idx
	)

Retrieve the name of the layer at the specified index.

Parameters

[in]	io	io object
[in]	idx	index of layer (0 - M_io_layer_count())

Returns: internal name of layer in string form

◆ M_io_get_error()

M_io_error_t M_io_get_error ( M_io_t * io )

Get the last error associated with the io object.

Parameters

[in] io io object.

Returns: an M_io_error_t error

◆ M_io_get_error_string()

void M_io_get_error_string	(	M_io_t *	io,
		char *	error,
		size_t	err_len
	)

Get a textual error message associated with the io object.

This message is populated by the layer that reported the error. The message could come from an external library such as an TLS library. It is meant to be a human readable description and should not be used programmatically.

Parameters

[in]	io	io object.
[out]	error	Error buffer.
[in]	err_len	Size of error buffer.

◆ M_io_reconnect()

M_bool M_io_reconnect ( M_io_t * io )

Request system to tear down existing connection and reconnect using the same configuration and layers as are currently in use. Will preserve existing event handle and callbacks.

Parameters

[in] io io object.

Returns: M_TRUE if object can be reconnected, M_FALSE if cannot be. This returning M_TRUE does NOT mean the reconnect itself was successful, must still wait for CONNECT or ERROR event.

◆ M_io_disconnect()

void M_io_disconnect ( M_io_t * comm )

Gracefully issue a disconnect to the communications object, a DISCONNECTED (or ERROR) event will be triggered when complete.

Parameters

[in] comm io object.

◆ M_io_close()

M_bool M_io_close ( M_io_t * comm )

Forcibly close the io object without destroying the entire object. If the connection is still active, this will perform a dirty disconnect (not recommended).

This is primarily used after receiving a disconnect or error event with the anticipation of performing a reconnect at some point in the future, but not immediately.

This will detach from the event subsystem and clean up the OS handles.

Parameters

[in] comm io object.

Returns: M_FALSE on error, M_TRUE on success.

◆ M_io_is_user_initiated_disconnect()

M_bool M_io_is_user_initiated_disconnect ( M_io_t * io )

Query if disconnect/error might have been generated by a call to M_io_disconnect() rather than triggered by a system-level event.

This might be useful for things like HTTP connections where we can M_io_reconnect() after a remote disconnect.

Parameters

[in] io io object.

Returns: M_TRUE if disconnect/error was triggered by M_io_disconnecT(), M_FALSE otherwise.

◆ M_io_destroy()

void M_io_destroy ( M_io_t * comm )

Destroy any communications object.

This can be called from a different thread than the thread the event loop the io object is running on. When this happens the destroy is queued and will happen once the event loop the io object is associated with has finished processing all queued events.

Parameters

[in] comm io object.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ M_IO_LAYER_FIND_FIRST_ID

Typedef Documentation

◆ M_io_type_t

◆ M_io_t

◆ M_io_meta_t

◆ M_io_error_t

◆ M_io_state_t

Enumeration Type Documentation

◆ M_io_type

◆ M_io_error

◆ M_io_state

Function Documentation

◆ M_io_error_string()

◆ M_io_meta_create()

◆ M_io_meta_destroy()

◆ M_io_read()

◆ M_io_read_into_buf()

◆ M_io_read_into_parser()

◆ M_io_read_meta()

◆ M_io_read_into_buf_meta()

◆ M_io_read_into_parser_meta()

◆ M_io_read_clear()

◆ M_io_write()

◆ M_io_write_from_buf()

◆ M_io_write_meta()

◆ M_io_write_from_buf_meta()

◆ M_io_accept()

◆ M_io_get_state()

◆ M_io_get_layer_state()

◆ M_io_layer_count()

◆ M_io_layer_name()

◆ M_io_get_error()

◆ M_io_get_error_string()

◆ M_io_reconnect()

◆ M_io_disconnect()

◆ M_io_close()

◆ M_io_is_user_initiated_disconnect()

◆ M_io_destroy()