Sockets, datagrams and the HTTP and REST clients.

Data Structures
struct	CMUTIL_Socket
	Socket object. More...
struct	CMUTIL_ServerSocket
	Server socket object. More...
struct	CMUTIL_DGramSocket
	Datagram socket object. More...
struct	CMUTIL_HttpClient
	An HTTP/HTTPS client built on the socket layer. More...
struct	CMUTIL_RestClient
	A JSON layer over CMUTIL_HttpClient. More...

Macros
#define	CMUTIL_REST_DEFAULT_TIMEOUT   30000L

Typedefs
typedef struct sockaddr_storage	CMUTIL_SocketAddr
	Socket address object.

Enumerations
enum	CMSocketResult {   CMSocketOk = 0 , CMSocketTimeout , CMSocketPollFailed , CMSocketReceiveFailed ,   CMSocketSendFailed , CMSocketUnsupported , CMSocketNotConnected , CMSocketConnectFailed ,   CMSocketBindFailed , CMSocketUnknownError = 0x7FFFFFFF }
	Socket operation result codes. More...

Functions
CMSocketResult	CMUTIL_SocketAddrGet (const CMUTIL_SocketAddr *saddr, char *hostbuf, int *port)
	Get the host and port from a socket address.
CMSocketResult	CMUTIL_SocketAddrSet (CMUTIL_SocketAddr *saddr, const char *host, int port)
	Set the host and port in a socket address.
CMUTIL_Socket *	CMUTIL_SocketConnect (const char *host, int port, long timeout)
	Create a new socket which connected to the given endpoint.
CMUTIL_Socket *	CMUTIL_SocketConnectWithAddr (const CMUTIL_SocketAddr *saddr, long timeout)
	Create a new socket which connected to the given socket address.
CMUTIL_Socket *	CMUTIL_SocketConnectIPC (const char *ipc_path, long timeout)
	Create a new socket which connected to the given ipc path.
CMUTIL_Socket *	CMUTIL_SSLSocketConnect (const char *cert, const char *key, const char *ca, const char *servername, const char *host, int port, long timeout)
	Create a new SSL socket which connected to the given endpoint.
CMUTIL_Socket *	CMUTIL_SSLSocketConnectWithAddr (const char *cert, const char *key, const char *ca, const char *servername, const CMUTIL_SocketAddr *saddr, long timeout)
	Create a new SSL socket which connected to the given socket address.
CMUTIL_ServerSocket *	CMUTIL_ServerSocketCreate (const char *host, int port, int qcnt, CMBool silent)
	Create a new server socket which listens on the given host and port.
CMUTIL_ServerSocket *	CMUTIL_ServerSocketCreateIPC (const char *ipc_path, int qcnt, CMBool silent)
	Create a new server socket which listens on the given ipc path.
CMUTIL_ServerSocket *	CMUTIL_SSLServerSocketCreate (const char *cert, const char *key, const char *ca, const char *host, int port, int qcnt)
	Create a new SSL server socket which listens on the given host and port.
CMBool	CMUTIL_SocketPair (CMUTIL_Socket **s1, CMUTIL_Socket **s2)
	Create a pair of connected sockets.
CMUTIL_DGramSocket *	CMUTIL_DGramSocketCreate (void)
	Create a new datagram socket.
CMUTIL_DGramSocket *	CMUTIL_DGramSocketCreateBind (CMUTIL_SocketAddr *addr)
	Create a new datagram socket and bind it to the given address.
CMUTIL_HttpClient *	CMUTIL_HttpClientCreate (const char *urlprefix)
	Create an HTTP client for the given URL prefix.
CMUTIL_RestClient *	CMUTIL_RestClientCreate (const char *urlprefix)
	Create a REST client for the given URL prefix.

Detailed Description

Macro Definition Documentation

CMUTIL_REST_DEFAULT_TIMEOUT

#define CMUTIL_REST_DEFAULT_TIMEOUT   30000L

The timeout a REST client starts with, in milliseconds.

Enumeration Type Documentation

CMSocketResult

enum CMSocketResult

Socket operation result codes.

Enumerator
CMSocketOk	Operation succeeded.
CMSocketTimeout	Operation timed out.
CMSocketPollFailed	Polling the socket failed.
CMSocketReceiveFailed	Receiving data from the socket failed.
CMSocketSendFailed	Sending data to the socket failed.
CMSocketUnsupported	The socket operation is unsupported.
CMSocketNotConnected	The socket is not connected.
CMSocketConnectFailed	Connecting the socket failed.
CMSocketBindFailed	Binding the socket failed.
CMSocketUnknownError	Unknown error occurred.

Function Documentation

CMUTIL_SocketAddrGet()

CMSocketResult CMUTIL_SocketAddrGet	(	const CMUTIL_SocketAddr *	saddr,
		char *	hostbuf,
		int *	port
	)

Get the host and port from a socket address.

If saddr is inet address, hostbuf and port are filled. If saddr is ipc address, hostbuf is filled with ipc path, port is set to -1.

Parameters

saddr	Socket address object.
hostbuf	Buffer to store the host string. If NULL, host is not retrieved.
port	Pointer to store the port number. If NULL, port is not retrieved.

Returns

CMSocketResult indicating success or failure.

CMUTIL_SocketAddrSet()

CMSocketResult CMUTIL_SocketAddrSet	(	CMUTIL_SocketAddr *	saddr,
		const char *	host,
		int	port
	)

Set the host and port in a socket address.

Parameters

saddr	Socket address object to be set.
host	Host string to set.
port	Port number to set, if negative, make ipc address.

Returns

CMSocketResult indicating success or failure.

CMUTIL_SocketConnect()

CMUTIL_Socket * CMUTIL_SocketConnect	(	const char *	host,
		int	port,
		long	timeout
	)

Create a new socket which connected to the given endpoint.

Parameters

host	host where connect to.
port	port where connect to.
timeout	connect timeout in milliseconds.

Returns

A connected socket if succeeded it must be closed after use. NULL if connect failed.

CMUTIL_SocketConnectWithAddr()

CMUTIL_Socket * CMUTIL_SocketConnectWithAddr	(	const CMUTIL_SocketAddr *	saddr,
		long	timeout
	)

Create a new socket which connected to the given socket address.

Parameters

saddr	socket address where connect to.
timeout	connect timeout in milliseconds.

Returns

A connected socket if succeeded it must be closed after use. NULL if connect failed.

CMUTIL_SocketConnectIPC()

CMUTIL_Socket * CMUTIL_SocketConnectIPC	(	const char *	ipc_path,
		long	timeout
	)

Create a new socket which connected to the given ipc path.

In windows ipc_path must be a string representation of port number. In xnix systems ipc_path must be a valid unix domain socket path.

Parameters

ipc_path	unix domain socket path(xnix) or port number(windows) where connect to.
timeout	connect timeout in milliseconds.

Returns

A connected socket if succeeded it must be closed after use. NULL if connect failed.

CMUTIL_SSLSocketConnect()

CMUTIL_Socket * CMUTIL_SSLSocketConnect	(	const char *	cert,
		const char *	key,
		const char *	ca,
		const char *	servername,
		const char *	host,
		int	port,
		long	timeout
	)

Create a new SSL socket which connected to the given endpoint.

Parameters

cert	SSL certificate file path.
key	SSL private key file path.
ca	CA certificate file path.
servername	Server name for SNI.
host	host where connect to.
port	port where connect to.
timeout	connect timeout in milliseconds.

Returns

A connected SSL socket if succeeded it must be closed after use. NULL if connect failed.

CMUTIL_SSLSocketConnectWithAddr()

CMUTIL_Socket * CMUTIL_SSLSocketConnectWithAddr	(	const char *	cert,
		const char *	key,
		const char *	ca,
		const char *	servername,
		const CMUTIL_SocketAddr *	saddr,
		long	timeout
	)

Create a new SSL socket which connected to the given socket address.

Parameters

cert	SSL certificate file path.
key	SSL private key file path.
ca	CA certificate file path.
servername	Server name for SNI.
saddr	socket address where connect to.
timeout	connect timeout in milliseconds.

Returns

A connected SSL socket if succeeded it must be closed after use. NULL if connect failed.

CMUTIL_ServerSocketCreate()

CMUTIL_ServerSocket * CMUTIL_ServerSocketCreate	(	const char *	host,
		int	port,
		int	qcnt,
		CMBool	silent
	)

Create a new server socket which listens on the given host and port.

Parameters

host	Host address to listen on.(0.0.0.0 for any address)
port	Port number to listen on.
qcnt	The maximum length of the queue of pending connections.
silent	CMTrue to suppress this library's own error logging for this listener, as CMUTIL_ServerSocket::SetSilent does.

Returns

A server socket if succeeded it must be closed after use. NULL if failed.

CMUTIL_ServerSocketCreateIPC()

CMUTIL_ServerSocket * CMUTIL_ServerSocketCreateIPC	(	const char *	ipc_path,
		int	qcnt,
		CMBool	silent
	)

Create a new server socket which listens on the given ipc path.

In windows ipc_path must be a string representation of port number. In xnix systems ipc_path must be a valid unix domain socket path.

Parameters

ipc_path	unix domain socket path(xnix) or port number(windows) to listen on.
qcnt	The maximum length of the queue of pending connections.
silent	CMTrue to suppress this library's own error logging for this listener, as CMUTIL_ServerSocket::SetSilent does.

Returns

A server socket if succeeded it must be closed after use. NULL if failed.

CMUTIL_SSLServerSocketCreate()

CMUTIL_ServerSocket * CMUTIL_SSLServerSocketCreate	(	const char *	cert,
		const char *	key,
		const char *	ca,
		const char *	host,
		int	port,
		int	qcnt
	)

Create a new SSL server socket which listens on the given host and port.

Parameters

cert	SSL certificate file path.
key	SSL private key file path.
ca	CA certificate file path.
host	Host address to listen on.(0.0.0.0 for any address)
port	Port number to listen on.
qcnt	The maximum length of the queue of pending connections.

Returns

AN SSL server socket if succeeded, it must be closed after use. NULL if failed.

CMUTIL_SocketPair()

CMBool CMUTIL_SocketPair	(	CMUTIL_Socket **	s1,
		CMUTIL_Socket **	s2
	)

Create a pair of connected sockets.

Parameters

s1	Socket pointer to store the first socket.
s2	Socket pointer to store the second socket.

Returns

CMTrue if succeeded, CMFalse if failed.

CMUTIL_DGramSocketCreate()

CMUTIL_DGramSocket * CMUTIL_DGramSocketCreate

(

void

)

Create a new datagram socket.

Returns

A datagram socket if succeeded it must be closed after use.

CMUTIL_DGramSocketCreateBind()

CMUTIL_DGramSocket * CMUTIL_DGramSocketCreateBind

(

CMUTIL_SocketAddr *

addr

)

Create a new datagram socket and bind it to the given address.

Parameters

addr	Socket address to bind the datagram socket to.

Returns

A bound datagram socket if succeeded it must be closed after use.

CMUTIL_HttpClientCreate()

CMUTIL_HttpClient * CMUTIL_HttpClientCreate

(

const char *

urlprefix

)

Create an HTTP client for the given URL prefix.

Parameters

urlprefix

Scheme, host and optional port, like "https://example.com:8443". The port defaults to 80 for http and 443 for https.

Returns

A new HTTP client, or NULL if the prefix could not be parsed. Destroy it with its Destroy method.

CMUTIL_RestClientCreate()

CMUTIL_RestClient * CMUTIL_RestClientCreate

(

const char *

urlprefix

)

Create a REST client for the given URL prefix.

Parameters

urlprefix

Scheme, host and optional port, like "https://api.example.com:8443".

Returns

A new REST client, or NULL if the prefix could not be parsed. Destroy it with CMCall(&client->base, Destroy).