Group PJ_ACTIVESOCK¶

group PJ_ACTIVESOCK

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.

Typedefs

typedef struct pj_activesock_t pj_activesock_t¶: This opaque structure describes the active socket.

Functions

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

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

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

struct pj_activesock_cb¶: #include <activesock.h>
This structure contains the callbacks to be called by the active socket.

struct pj_activesock_cfg¶: #include <activesock.h>
Settings that can be given during active socket creation. Application must initialize this structure with pj_activesock_cfg_default().