BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJLIB Reference

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

This opaque structure describes the active socket.


Function Documentation

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

 


PJLIB Open Source, high performance, small footprint, and very very portable framework
Copyright (C) 2006-2009 Teluu Inc.