src/connection.h File Reference

Typedefs
typedef struct con_connection_tag	con_connection_s
typedef struct con_handler_tag	con_handler_s
typedef enum con_close_reason_tag	con_close_reason_e
typedef enum con_connect_reason_tag	con_connect_reason_e
typedef enum con_upstream_action_tag	con_upstream_action_e
Enumerations
enum	con_close_reason_tag { CON_CLOSE_ERROR = 0, CON_CLOSE_EOF, CON_CLOSE_TIMEOUT }
enum	con_connect_reason_tag { CON_CONNECT_OKAY = 0, CON_CONNECT_DNS_FAILURE, CON_CONNECT_ERROR, CON_CONNECT_TIMEOUT }
enum	con_upstream_action_tag { CON_UPSTREAM_CONTINUE = 0, CON_UPSTREAM_CLOSE }
Functions
bool	con_module_init (void)
	Initialise the connection module.
void	con_module_close (void)
	Close the connection module.
con_handler_s *	con_handler_register (const char *name, const unsigned short int port, const unsigned long int maxClients, const int backlog, con_upstream_action_e(*readCb)(con_connection_s *), bool(*acceptCb)(con_connection_s *), void(*closeCb)(con_connection_s *, con_close_reason_e))
	Register a new connection handler to listen for.
bool	con_listen (con_handler_s *handler)
	Start listening on the given connection handler.
void	con_event_loop (void)
	Start the event loop.
void	con_close_event_loop (void)
	Close the event loop.
void	con_set_userdata (con_connection_s *connection, void *data)
	Set the user data of a connection.
void *	con_get_userdata (con_connection_s *connection)
	Get the user data of a connection.
con_handler_s *	con_get_handler (con_connection_s *connection)
	Get the connection handler for the given connection.
bool	con_is_connector (const con_connection_s *connection)
	Returns true if we made this connection.
net_recv_result_e	con_read_data (con_connection_s *connection, void *buffer, const size_t len, size_t *bytesRead)
	Read data from a connection data structure.
net_send_result_e	con_send_data (con_connection_s *connection, const void *data, const size_t len, size_t *bytesSent)
	Send data.
size_t	con_send_data_fully (con_connection_s *connection, const void *data, const size_t len)
bool	con_connector_register (const char *hostname, const unsigned short int port, const int timeout, con_handler_s *handler, void(*connectCb)(con_connection_s *, con_connect_reason_e), void *userData)
	Register a new connector.
void	con_close_connection (con_connection_s *connection, con_close_reason_e reason)
	Called when we want to close/free a connection.

---

Typedef Documentation

typedef enum con_close_reason_tag con_close_reason_e

typedef enum con_connect_reason_tag con_connect_reason_e

typedef struct con_connection_tag con_connection_s

typedef struct con_handler_tag con_handler_s

typedef enum con_upstream_action_tag con_upstream_action_e

---

Enumeration Type Documentation

enum con_close_reason_tag

Enumerator:

CON_CLOSE_ERROR
CON_CLOSE_EOF
CON_CLOSE_TIMEOUT

enum con_connect_reason_tag

Enumerator:

CON_CONNECT_OKAY
CON_CONNECT_DNS_FAILURE
CON_CONNECT_ERROR
CON_CONNECT_TIMEOUT

enum con_upstream_action_tag

Enumerator:

CON_UPSTREAM_CONTINUE
CON_UPSTREAM_CLOSE	continue processing close the connection upstream

---

Function Documentation

void con_close_connection	(	con_connection_s *	connection,
		con_close_reason_e	reason
	)

Called when we want to close/free a connection.

The registered close callback will be called.

Parameters:

	connection	The connection to close.
	reason	The reason for the close.

void con_close_event_loop

(

void

)

Close the event loop.

See also:

con_event_loop()

bool con_connector_register	(	const char *	hostname,
		const unsigned short int	port,
		const int	timeout,
		con_handler_s *	handler,
		void(*)(con_connection_s *, con_connect_reason_e)	connectCb,
		void *	userData
	)

Register a new connector.

Once the connection is made, the callback will be called.

Parameters:

	hostname	The IPv4, IPv6 or hostname of the server.
	port	The port to connect on.
	timeout	How long to try to connect before timing out.
	handler	The connection handler to use, once the socket is connected.
	connectCb	The callback to call on error, or successful connect.
	userData	The user-defined data to give the connection (get with con_get_userdata())

Returns:

true if the connector was registered. On error, false is returned.

void con_event_loop

(

void

)

Start the event loop.

Previously listening handlers will begin to accept connections.

See also:

con_listen()

con_handler_s* con_get_handler

(

con_connection_s *

connection

)

Get the connection handler for the given connection.

Parameters:

connection

The connection to set the data of.

Returns:

The connection handler for the connection.

void* con_get_userdata

(

con_connection_s *

connection

)

Get the user data of a connection.

See also:

con_set_userdata()

Parameters:

connection

The connection to set the data of.

Returns:

The previously set userdata. If there is none, NULL is returned.

con_handler_s* con_handler_register	(	const char *	name,
		const unsigned short int	port,
		const unsigned long int	maxClients,
		const int	backlog,
		con_upstream_action_e(*)(con_connection_s *)	readCb,
		bool(*)(con_connection_s *)	acceptCb,
		void(*)(con_connection_s *, con_close_reason_e)	closeCb
	)

Register a new connection handler to listen for.

See also:

con_listen()

con_event_loop()

Warning:

Don't register more than one connection handler on the same port.

Parameters:

	name	The name of the connection handler.
	port	The port to listen on.
	maxClients	The max number of clients to have at any one time.
	backlog	How many clients to backlog before accepting them.
	readCb	The callback to call when data can be read.
	acceptCb	The callback to call when a client connects. If returned false, the client is rejected. Use this callback to set userdata.
	closeCb	The callback to call when the connection is closed.

Returns:

A handle to a connection handler. On error, NULL is returned

bool con_is_connector

(

const con_connection_s *

connection

)

Returns true if we made this connection.

Parameters:

connection

The connection to check.

Returns:

true if the connection was made by us.

bool con_listen

(

con_handler_s *

handler

)

Start listening on the given connection handler.

See also:

con_handler_register()

con_event_loop()

Parameters:

handler

The handler to bind to and start listening on.

Returns:

true on success. On error, false is returned.

void con_module_close

(

void

)

Close the connection module.

Any unclosed handlers are closed.

See also:

con_close_handler()

bool con_module_init

(

void

)

Initialise the connection module.

This should be called before any other functions.

See also:

con_module_close()

Note:

On success, con_module_close() must be called.

Returns:

true on success. On error, false is returned

net_recv_result_e con_read_data	(	con_connection_s *	connection,
		void *	buffer,
		const size_t	len,
		size_t *	bytesRead
	)

Read data from a connection data structure.

See also:

con_send_data()

Parameters:

	connection	The connection.
	buffer	Where to put the data.
	len	The number of bytes to read.
	bytesRead	Where to record how many bytes were read.

Returns:

A net_recv_result_e value

net_send_result_e con_send_data	(	con_connection_s *	connection,
		const void *	data,
		const size_t	len,
		size_t *	bytesSent
	)

Send data.

See also:

con_read_data()

Parameters:

	connection	The connection to send on.
	data	The data to send.
	len	The length of the data.
	bytesSent	Where to record how many bytes were sent.

Returns:

true on success. On error, false is returned.

size_t con_send_data_fully	(	con_connection_s *	connection,
		const void *	data,
		const size_t	len
	)

void con_set_userdata	(	con_connection_s *	connection,
		void *	data
	)

Set the user data of a connection.

See also:

con_get_userdata()

Parameters:

	connection	The connection to set the data of.
	data	The userdata to set.