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

Public Members

pj_bool_t (*on_data_read)(pj_activesock_t *asock, void *data, pj_size_t size, pj_status_t status, pj_size_t *remainder)

This callback is called when a data arrives as the result of pj_activesock_start_read().

Param asock:: The active socket.
Param data:: The buffer containing the new data, if any. If the status argument is non-PJ_SUCCESS, this argument may be NULL.
Param size:: The length of data in the buffer.
Param status:: The status of the read operation. This may contain non-PJ_SUCCESS for example when the TCP connection has been closed. In this case, the buffer may contain left over data from previous callback which the application may want to process.
Param remainder:: If application wishes to leave some data in the buffer (common for TCP applications), it should move the remainder data to the front part of the buffer and set the remainder length here. The value of this parameter will be ignored for datagram sockets.
Return:: PJ_TRUE if further read is desired, and PJ_FALSE when application no longer wants to receive data. Application may destroy the active socket in the callback and return PJ_FALSE here.

pj_bool_t (*on_data_recvfrom)(pj_activesock_t *asock, void *data, pj_size_t size, const pj_sockaddr_t *src_addr, int addr_len, pj_status_t status)

This callback is called when a packet arrives as the result of pj_activesock_start_recvfrom().

Param asock:: The active socket.
Param data:: The buffer containing the packet, if any. If the status argument is non-PJ_SUCCESS, this argument will be set to NULL.
Param size:: The length of packet in the buffer. If the status argument is non-PJ_SUCCESS, this argument will be set to zero.
Param src_addr:: Source address of the packet.
Param addr_len:: Length of the source address.
Param status:: This contains
Return:: PJ_TRUE if further read is desired, and PJ_FALSE when application no longer wants to receive data. Application may destroy the active socket in the callback and return PJ_FALSE here.

pj_bool_t (*on_data_sent)(pj_activesock_t *asock, pj_ioqueue_op_key_t *send_key, pj_ssize_t sent)

This callback is called when data has been sent.

Param asock:: The active socket.
Param send_key:: Key associated with the send operation.
Param sent:: If value is positive non-zero it indicates the number of data sent. When the value is negative, it contains the error code which can be retrieved by negating the value (i.e. status=-sent).
Return:: Application may destroy the active socket in the callback and return PJ_FALSE here.

pj_bool_t (*on_accept_complete)(pj_activesock_t *asock, pj_sock_t newsock, const pj_sockaddr_t *src_addr, int src_addr_len)

This callback is called when new connection arrives as the result of pj_activesock_start_accept(). If the status of accept operation is needed use on_accept_complete2 instead of this callback.

Param asock:: The active socket.
Param newsock:: The new incoming socket.
Param src_addr:: The source address of the connection.
Param addr_len:: Length of the source address.
Return:: PJ_TRUE if further accept() is desired, and PJ_FALSE when application no longer wants to accept incoming connection. Application may destroy the active socket in the callback and return PJ_FALSE here.

pj_bool_t (*on_accept_complete2)(pj_activesock_t *asock, pj_sock_t newsock, const pj_sockaddr_t *src_addr, int src_addr_len, pj_status_t status)

This callback is called when new connection arrives as the result of pj_activesock_start_accept().

Param asock:: The active socket.
Param newsock:: The new incoming socket.
Param src_addr:: The source address of the connection.
Param addr_len:: Length of the source address.
Param status:: The status of the accept operation. This may contain non-PJ_SUCCESS for example when the TCP listener is in bad state for example on iOS platform after the application waking up from background.
Return:: PJ_TRUE if further accept() is desired, and PJ_FALSE when application no longer wants to accept incoming connection. Application may destroy the active socket in the callback and return PJ_FALSE here.

pj_bool_t (*on_connect_complete)(pj_activesock_t *asock, pj_status_t status)

This callback is called when pending connect operation has been completed.

Param asock:: The active socket.
Param status:: The connection result. If connection has been successfully established, the status will contain PJ_SUCCESS.
Return:: Application may destroy the active socket in the callback and return PJ_FALSE here.

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().

Public Members

pj_grp_lock_t *grp_lock: Optional group lock to be assigned to the ioqueue key.

unsigned async_cnt

Number of concurrent asynchronous operations that is to be supported by the active socket. This value only affects socket receive and accept operations — the active socket will issue one or more asynchronous read and accept operations based on the value of this field. Setting this field to more than one will allow more than one incoming data or incoming connections to be processed simultaneously on multiprocessor systems, when the ioqueue is polled by more than one threads.

The default value is 1.

int concurrency

The ioqueue concurrency to be forced on the socket when it is registered to the ioqueue. See pj_ioqueue_set_concurrency() for more info about ioqueue concurrency.

When this value is -1, the concurrency setting will not be forced for this socket, and the socket will inherit the concurrency setting of the ioqueue. When this value is zero, the active socket will disable concurrency for the socket. When this value is +1, the active socket will enable concurrency for the socket.

The default value is -1.

pj_bool_t whole_data

If this option is specified, the active socket will make sure that asynchronous send operation with stream oriented socket will only call the callback after all data has been sent. This means that the active socket will automatically resend the remaining data until all data has been sent.

Please note that when this option is specified, it is possible that error is reported after partial data has been sent. Also setting this will disable the ioqueue concurrency for the socket.

Default value is PJ_TRUE.

pj_bool_t sock_cloexec

If this option is specified, set close-on-exec flag for socket. This option is only used by pj_activesock_create_udp()

Default value is PJ_TRUE.