Active socket I/O

Active socket performs active operations on socket. More...

Data Structures
struct	pj_activesock_cb
struct	pj_activesock_cfg

Typedefs
typedef struct pj_activesock_t	pj_activesock_t

Functions
void	pj_activesock_cfg_default (pj_activesock_cfg *cfg)
pj_status_t	pj_activesock_create (pj_pool_t *pool, pj_sock_t sock, int sock_type, const pj_activesock_cfg *opt, pj_ioqueue_t *ioqueue, const pj_activesock_cb *cb, void *user_data, pj_activesock_t **p_asock)
pj_status_t	pj_activesock_create_udp (pj_pool_t *pool, const pj_sockaddr *addr, const pj_activesock_cfg *opt, pj_ioqueue_t *ioqueue, const pj_activesock_cb *cb, void *user_data, pj_activesock_t **p_asock, pj_sockaddr *bound_addr)
pj_status_t	pj_activesock_close (pj_activesock_t *asock)
pj_status_t	pj_activesock_set_user_data (pj_activesock_t *asock, void *user_data)
void *	pj_activesock_get_user_data (pj_activesock_t *asock)
pj_status_t	pj_activesock_start_read (pj_activesock_t *asock, pj_pool_t *pool, unsigned buff_size, pj_uint32_t flags)
pj_status_t	pj_activesock_start_read2 (pj_activesock_t *asock, pj_pool_t *pool, unsigned buff_size, void *readbuf[], pj_uint32_t flags)
pj_status_t	pj_activesock_start_recvfrom (pj_activesock_t *asock, pj_pool_t *pool, unsigned buff_size, pj_uint32_t flags)
pj_status_t	pj_activesock_start_recvfrom2 (pj_activesock_t *asock, pj_pool_t *pool, unsigned buff_size, void *readbuf[], pj_uint32_t flags)
pj_status_t	pj_activesock_send (pj_activesock_t *asock, pj_ioqueue_op_key_t *send_key, const void *data, pj_ssize_t *size, unsigned flags)
pj_status_t	pj_activesock_sendto (pj_activesock_t *asock, pj_ioqueue_op_key_t *send_key, const void *data, pj_ssize_t *size, unsigned flags, const pj_sockaddr_t *addr, int addr_len)
pj_status_t	pj_activesock_start_accept (pj_activesock_t *asock, pj_pool_t *pool)
pj_status_t	pj_activesock_start_connect (pj_activesock_t *asock, pj_pool_t *pool, const pj_sockaddr_t *remaddr, int addr_len)

Detailed Description

Active socket performs active operations on socket.

Active socket is a higher level abstraction to the ioqueue. It provides automation to socket operations which otherwise would have to be done manually by the applications. For example with socket recv(), recvfrom(), and accept() operations, application only needs to invoke these operation once, and it will be notified whenever data or incoming TCP connection (in the case of accept()) arrives.

Typedef Documentation

pj_activesock_t

typedef struct pj_activesock_t pj_activesock_t

This opaque structure describes the active socket.

Function Documentation

pj_activesock_cfg_default()

void pj_activesock_cfg_default

(

pj_activesock_cfg *

cfg

)

Initialize the active socket configuration with the default values.

Parameters

cfg	The configuration to be initialized.

pj_activesock_close()

pj_status_t pj_activesock_close

(

pj_activesock_t *

asock

)

Close the active socket. This will unregister the socket from the ioqueue and ultimately close the socket.

Parameters

asock

The active socket.

Returns

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_activesock_create()

pj_status_t pj_activesock_create	(	pj_pool_t *	pool,
		pj_sock_t	sock,
		int	sock_type,
		const pj_activesock_cfg *	opt,
		pj_ioqueue_t *	ioqueue,
		const pj_activesock_cb *	cb,
		void *	user_data,
		pj_activesock_t **	p_asock
	)

Create the active socket for the specified socket. This will register the socket to the specified ioqueue.

Parameters

pool	Pool to allocate memory from.
sock	The socket handle.
sock_type	Specify socket type, either pj_SOCK_DGRAM() or pj_SOCK_STREAM(). The active socket needs this information to handle connection closure for connection oriented sockets.
ioqueue	The ioqueue to use.
opt	Optional settings. When this setting is not specifed, the default values will be used.
cb	Pointer to structure containing application callbacks.
user_data	Arbitrary user data to be associated with this active socket.
p_asock	Pointer to receive the active socket instance.

Returns

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_activesock_create_udp()

pj_status_t pj_activesock_create_udp	(	pj_pool_t *	pool,
		const pj_sockaddr *	addr,
		const pj_activesock_cfg *	opt,
		pj_ioqueue_t *	ioqueue,
		const pj_activesock_cb *	cb,
		void *	user_data,
		pj_activesock_t **	p_asock,
		pj_sockaddr *	bound_addr
	)

Create UDP socket descriptor, bind it to the specified address, and create the active socket for the socket descriptor.

Parameters

pool	Pool to allocate memory from.
addr	Specifies the address family of the socket and the address where the socket should be bound to. If this argument is NULL, then AF_INET is assumed and the socket will be bound to any addresses and port.
ioqueue	The ioqueue.
opt	Optional settings. When this setting is not specifed, the default values will be used.
cb	Pointer to structure containing application callbacks.
user_data	Arbitrary user data to be associated with this active socket.
p_asock	Pointer to receive the active socket instance.
bound_addr	If this argument is specified, it will be filled with the bound address on return.

Returns

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_activesock_get_user_data()

void * pj_activesock_get_user_data

(

pj_activesock_t *

asock

)

Retrieve the user data previously associated with this active socket.

Parameters

asock

The active socket.

Returns

The user data.

pj_activesock_send()

pj_status_t pj_activesock_send	(	pj_activesock_t *	asock,
		pj_ioqueue_op_key_t *	send_key,
		const void *	data,
		pj_ssize_t *	size,
		unsigned	flags
	)

Send data using the socket.

Parameters

asock	The active socket.
send_key	The operation key to send the data, which is useful if application wants to submit multiple pending send operations and want to track which exact data has been sent in the on_data_sent() callback.
data	The data to be sent. This data must remain valid until the data has been sent.
size	The size of the data.
flags	Flags to be given to pj_ioqueue_send().

Returns

PJ_SUCCESS if data has been sent immediately, or PJ_EPENDING if data cannot be sent immediately. In this case the on_data_sent() callback will be called when data is actually sent. Any other return value indicates error condition.

pj_activesock_sendto()

pj_status_t pj_activesock_sendto	(	pj_activesock_t *	asock,
		pj_ioqueue_op_key_t *	send_key,
		const void *	data,
		pj_ssize_t *	size,
		unsigned	flags,
		const pj_sockaddr_t *	addr,
		int	addr_len
	)

Send datagram using the socket.

Parameters

asock	The active socket.
send_key	The operation key to send the data, which is useful if application wants to submit multiple pending send operations and want to track which exact data has been sent in the on_data_sent() callback.
data	The data to be sent. This data must remain valid until the data has been sent.
size	The size of the data.
flags	Flags to be given to pj_ioqueue_send().
addr	The destination address.
addr_len	The length of the address.

Returns

PJ_SUCCESS if data has been sent immediately, or PJ_EPENDING if data cannot be sent immediately. In this case the on_data_sent() callback will be called when data is actually sent. Any other return value indicates error condition.

pj_activesock_set_user_data()

pj_status_t pj_activesock_set_user_data	(	pj_activesock_t *	asock,
		void *	user_data
	)

Associate arbitrary data with the active socket. Application may inspect this data in the callbacks and associate it with higher level processing.

Parameters

asock	The active socket.
user_data	The user data to be associated with the active socket.

Returns

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_activesock_start_accept()

pj_status_t pj_activesock_start_accept	(	pj_activesock_t *	asock,
		pj_pool_t *	pool
	)

Starts asynchronous socket accept() operations on this active socket. Application must bind the socket before calling this function. This function will issue async_cnt number of asynchronous accept() operations to the socket and returns back to caller. Incoming connection on the socket will be reported back to application via the on_accept_complete() callback.

Application only needs to call this function once to initiate accept() operations. Further accept() operations will be done automatically by the active socket when on_accept_complete() callback returns non-zero.

Parameters

asock	The active socket.
pool	Pool used to allocate some internal data for the operation.

Returns

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_activesock_start_connect()

pj_status_t pj_activesock_start_connect	(	pj_activesock_t *	asock,
		pj_pool_t *	pool,
		const pj_sockaddr_t *	remaddr,
		int	addr_len
	)

Starts asynchronous socket connect() operation for this socket. Once the connection is done (either successfully or not), the on_connect_complete() callback will be called.

Parameters

asock	The active socket.
pool	The pool to allocate some internal data for the operation.
remaddr	Remote address.
addr_len	Length of the remote address.

Returns

PJ_SUCCESS if connection can be established immediately, or PJ_EPENDING if connection cannot be established immediately. In this case the on_connect_complete() callback will be called when connection is complete. Any other return value indicates error condition.

pj_activesock_start_read()

pj_status_t pj_activesock_start_read	(	pj_activesock_t *	asock,
		pj_pool_t *	pool,
		unsigned	buff_size,
		pj_uint32_t	flags
	)

Starts read operation on this active socket. This function will create async_cnt number of buffers (the async_cnt parameter was given in pj_activesock_create() function) where each buffer is buff_size long. The buffers are allocated from the specified pool. Once the buffers are created, it then issues async_cnt number of asynchronous recv() operations to the socket and returns back to caller. Incoming data on the socket will be reported back to application via the on_data_read() callback.

Application only needs to call this function once to initiate read operations. Further read operations will be done automatically by the active socket when on_data_read() callback returns non-zero.

Parameters

asock	The active socket.
pool	Pool used to allocate buffers for incoming data.
buff_size	The size of each buffer, in bytes.
flags	Flags to be given to pj_ioqueue_recv().

Returns

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_activesock_start_read2()

pj_status_t pj_activesock_start_read2	(	pj_activesock_t *	asock,
		pj_pool_t *	pool,
		unsigned	buff_size,
		void *	readbuf[],
		pj_uint32_t	flags
	)

Same as pj_activesock_start_read(), except that the application supplies the buffers for the read operation so that the acive socket does not have to allocate the buffers.

Parameters

asock	The active socket.
pool	Pool used to allocate buffers for incoming data.
buff_size	The size of each buffer, in bytes.
readbuf	Array of packet buffers, each has buff_size size.
flags	Flags to be given to pj_ioqueue_recv().

Returns

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_activesock_start_recvfrom()

pj_status_t pj_activesock_start_recvfrom	(	pj_activesock_t *	asock,
		pj_pool_t *	pool,
		unsigned	buff_size,
		pj_uint32_t	flags
	)

Same as pj_activesock_start_read(), except that this function is used only for datagram sockets, and it will trigger on_data_recvfrom() callback instead.

Parameters

asock	The active socket.
pool	Pool used to allocate buffers for incoming data.
buff_size	The size of each buffer, in bytes.
flags	Flags to be given to pj_ioqueue_recvfrom().

Returns

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.

pj_activesock_start_recvfrom2()

pj_status_t pj_activesock_start_recvfrom2	(	pj_activesock_t *	asock,
		pj_pool_t *	pool,
		unsigned	buff_size,
		void *	readbuf[],
		pj_uint32_t	flags
	)

Same as pj_activesock_start_recvfrom() except that the recvfrom() operation takes the buffer from the argument rather than creating new ones.

Parameters

asock	The active socket.
pool	Pool used to allocate buffers for incoming data.
buff_size	The size of each buffer, in bytes.
readbuf	Array of packet buffers, each has buff_size size.
flags	Flags to be given to pj_ioqueue_recvfrom().

Returns

PJ_SUCCESS if the operation has been successful, or the appropriate error code on failure.