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
cfgThe 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
asockThe 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
poolPool to allocate memory from.
sockThe socket handle.
sock_typeSpecify socket type, either pj_SOCK_DGRAM() or pj_SOCK_STREAM(). The active socket needs this information to handle connection closure for connection oriented sockets.
ioqueueThe ioqueue to use.
optOptional settings. When this setting is not specifed, the default values will be used.
cbPointer to structure containing application callbacks.
user_dataArbitrary user data to be associated with this active socket.
p_asockPointer 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
poolPool to allocate memory from.
addrSpecifies 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.
optOptional settings. When this setting is not specifed, the default values will be used.
cbPointer to structure containing application callbacks.
user_dataArbitrary user data to be associated with this active socket.
p_asockPointer to receive the active socket instance.
bound_addrIf 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
asockThe 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
asockThe active socket.
send_keyThe 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.
dataThe data to be sent. This data must remain valid until the data has been sent.
sizeThe size of the data.
flagsFlags 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
asockThe active socket.
send_keyThe 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.
dataThe data to be sent. This data must remain valid until the data has been sent.
sizeThe size of the data.
flagsFlags to be given to pj_ioqueue_send().
addrThe destination address.
addr_lenThe 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
asockThe active socket.
user_dataThe 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
asockThe active socket.
poolPool 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
asockThe active socket.
poolThe pool to allocate some internal data for the operation.
remaddrRemote address.
addr_lenLength 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
asockThe active socket.
poolPool used to allocate buffers for incoming data.
buff_sizeThe size of each buffer, in bytes.
flagsFlags 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
asockThe active socket.
poolPool used to allocate buffers for incoming data.
buff_sizeThe size of each buffer, in bytes.
readbufArray of packet buffers, each has buff_size size.
flagsFlags 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
asockThe active socket.
poolPool used to allocate buffers for incoming data.
buff_sizeThe size of each buffer, in bytes.
flagsFlags 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
asockThe active socket.
poolPool used to allocate buffers for incoming data.
buff_sizeThe size of each buffer, in bytes.
readbufArray of packet buffers, each has buff_size size.
flagsFlags 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.