pconn.h File Reference

PIC/Peer connection functions. More...

Data Structures
struct	pconn_peer_info_s
	Data structure defining the peer information. More...
struct	pconn_client_params_s
	Data structure defining the client parameters. More...
struct	pconn_server_params_s
	Data structure defining the server parameters. More...
Defines
#define	PCONN_OK   0
	Operation succeeded.
#define	PCONN_INVALID_OP   -100
	Invalid operation.
#define	PCONN_INVAL_PARAM   -101
	Invalid parameters.
#define	PCONN_LIB_ERR   -102
	Generic error, refer to errno for more details.
#define	PCONN_RETRY_MIN   2
	Minimum connect retries.
#define	PCONN_RETRY_MAX   10
	Maximum connect retries.
#define	PCONN_RETRY_DEF   PCONN_RETRY_MIN
	Default connect retries.
#define	PCONN_TIMEOUT_MIN   0
	No timeout.
#define	PCONN_TIMEOUT_DEF   (5 * 60)
	The length, in seconds, before the timeout starts.
#define	PCONN_SLOT_ID_UNSPEC   0xFFFFFFFF
	Invalid FPC slot index.
#define	PCONN_HOSTNAME_RE   "RE"
	pconn Routing Engine host name.
#define	PCONN_MSG_TYPE_END   0xFFFF
	ipc_msg_t message type end.
#define	PCONN_MAX_CONN   128
	Maximum number of concurrent pconn client connections.
Typedefs
typedef pconn_client_s	pconn_client_t
	Client structure.
typedef void(*	pconn_client_event_handler_t )(pconn_client_t *clnt, pconn_event_t event, void *cookie)
	Client event handler function prototype.
typedef status_t(*	pconn_client_msg_handler_t )(pconn_client_t *clnt, ipc_msg_t *msg, void *cookie)
	Client event handler function prototype.
typedef pconn_server_s	pconn_server_t
	Server structure.
typedef pconn_session_s	pconn_session_t
	Server session structure.
typedef void(*	pconn_server_session_event_handler_t )(pconn_session_t *session, pconn_event_t event, void *cookie)
	Server event handler function prototype.
typedef status_t(*	pconn_server_msg_handler_t )(pconn_session_t *session, ipc_msg_t *msg, void *cookie)
	Server event handler function prototype.
typedef pconn_peer_info_s	pconn_peer_info_t
	Data structure defining the peer information.
typedef pconn_client_params_s	pconn_client_params_t
	Data structure defining the client parameters.
typedef pconn_server_params_s	pconn_server_params_t
	Data structure defining the server parameters.
Enumerations
enum	pconn_event_t { PCONN_EVENT_ESTABLISHED, PCONN_EVENT_SHUTDOWN, PCONN_EVENT_FAILED }
	Enum values of all the pconn events. More...
enum	pconn_peer_type_t { PCONN_PEER_TYPE_RE = 1, PCONN_PEER_TYPE_PIC }
	Enum values of all the pconn peer types. More...
Functions
pconn_client_t *	pconn_client_connect_async (pconn_client_params_t *params, evContext ev_context, pconn_client_msg_handler_t msg_handler, void *cookie)
	Opens an asynchronous connection to the remote server.
pconn_client_t *	pconn_client_connect (pconn_client_params_t *params)
	Opens a TCP connection to the remote server.
int	pconn_client_send (pconn_client_t *clnt, int type, void *msg, int length)
	Sends a message to the remote server.
void *	pconn_client_recv (pconn_client_t *clnt)
	Receives a message from a remote server.
void	pconn_client_close (pconn_client_t *clnt)
	Closes the connection.
pconn_server_t *	pconn_server_create (pconn_server_params_t *params, evContext ev_context, pconn_server_msg_handler_t msg_handler, void *cookie)
	Starts a server instance.
int	pconn_server_send (pconn_session_t *session, int type, void *msg, int len)
	Sends a message to the client.
void	pconn_server_shutdown (pconn_server_t *server)
	Shuts down the specified server.
int	pconn_server_set_session_cookie (pconn_session_t *session, void *cookie)
	Sets the session-specific cookie on the server.
int	pconn_session_get_peer_address (pconn_session_t *session, u_int32_t *peer_address)
	Returns the address of the peer.
int	pconn_session_get_peer_info (pconn_session_t *session, pconn_peer_info_t *peer_info)
	Gets the peer information for the client connecting to the server.
int	pconn_get_peer_address (pconn_peer_info_t *peer_info, u_int32_t *peer_address)
	Returns the peer address.
void	pconn_session_close (pconn_session_t *session)
	Closes the peer connection for a server session with the client.
void *	pconn_server_get_server_cookie (pconn_server_t *pconn_server)
	Return the application cookie.

---

Detailed Description

PIC/Peer connection functions.

---

Enumeration Type Documentation

enum pconn_event_t

Enum values of all the pconn events. Enumerator: PCONN_EVENT_ESTABLISHED  Connection successful event. PCONN_EVENT_SHUTDOWN  Session shutdown event. PCONN_EVENT_FAILED  Connection fail event.

enum pconn_peer_type_t

Enum values of all the pconn peer types. Enumerator: PCONN_PEER_TYPE_RE  Indicates RE peer type. PCONN_PEER_TYPE_PIC  Indicates non-RE peer type.

---

Function Documentation

void pconn_client_close (  pconn_client_t *  clnt  )

Closes the connection. Closes the connection to the remote server running on the RE or the PIC. Cleans up the resources associated with the connection. Parameters: [in]  clnt  Pointer to the client structure. Returns: None

pconn_client_t* pconn_client_connect (  pconn_client_params_t *  params  )

Opens a TCP connection to the remote server. Opens a TCP connection to the remote server running on the RE or on the PIC. It is up to the calling application to receive data from the socket and handle the messages accordingly. The caller, after it is done, needs to close this connection to free up the resources. This is a synchronous function. Parameters: [in]  params  Connection parameters, e.g., address, port, etc. Returns: Pointer to client struct if successful; otherwise NULL.

pconn_client_t* pconn_client_connect_async (  pconn_client_params_t *  params, evContext  ev_context, pconn_client_msg_handler_t  msg_handler, void *  cookie )

Opens an asynchronous connection to the remote server. This function opens an asynchronous TCP connection to the remote server running on the RE or on the PIC. It creates the client structure and attaches event context, connection event handler, and message handler. This function uses event library functions to connect and for asynchronous handling of incoming data over the socket. The caller, after it is done, needs to close this connection to free up the resources. Parameters: [in]  params  Connection parameters. [in]  ev_context  Event context for attaching it to the event loop. [in]  msg_handler  Message handler. [in]  cookie  Caller's context information. Returns: Pointer to client struct if successful; otherwise NULL.

void* pconn_client_recv (  pconn_client_t *  clnt  )

Receives a message from a remote server. Receives a message from the remote server running on the RE or the PIC. This is a synchronous function and can only be used along with pconn_client_connect(). Parameters: [in]  clnt  Pointer to the client structure. Returns: Pointer to the message if successful; otherwise NULL.

int pconn_client_send (  pconn_client_t *  clnt, int  type, void *  msg, int  length )

Sends a message to the remote server. Sends a message to the remote server running on RE or the PIC. It returns 0 on success and -1 on error. If the error number is EAGAIN, it is left up to the caller of this function to retry sending the message again. Parameters: [in]  clnt  Pointer to the client structure. [in]  type  Message type. [in]  msg  Pointer to the message. [in]  length  Message length. Returns: PCONN_OK on success; otherwise PCONN_LIB_ERR.

int pconn_get_peer_address (  pconn_peer_info_t *  peer_info, u_int32_t *  peer_address )

Returns the peer address. The address is returned in IRI-2 format. Parameters: [in]  peer_info  Pointer to peer information structure. [out]  peer_address  Pointer to the return peer address. Returns: PCONN_OK on success; otherwise PCONN_INVAL_PARAM.

pconn_server_t* pconn_server_create (  pconn_server_params_t *  params, evContext  ev_context, pconn_server_msg_handler_t  msg_handler, void *  cookie )

Starts a server instance. Starts a server using the values specified in the server params structure. Registers the session handler function to be called for the incoming connections. pconn_max_connections of the params structure should be set to a value less than or equal to PCONN_MAX_CONN. If a '0' is specified, then pconn_max_connections defaults to PCONN_MAX_CONN. Parameters: [in]  params  Parameters to create server instance. [in]  ev_context  Event context. [in]  msg_handler  Session message handler. [in]  cookie  Pointer to caller's cookie. Returns: Pointer to server struct if successful; otherwise NULL.

void* pconn_server_get_server_cookie (  pconn_server_t *  pconn_server  )

Return the application cookie. Parameters: [in]  pconn_server  pointer to pconn server information. Returns: void Pointer to session-specific cookie. NULL if no server or cookie.

int pconn_server_send (  pconn_session_t *  session, int  type, void *  msg, int  len )

Sends a message to the client. Sends a message to the client running on the RE or PFE. This is a non-blocking function. The message size is limited by the IPC pipe size. It returns 0 on success and -1 on error. If the error number is EAGAIN, it is left up to the caller of this function to retry sending the message again. Parameters: [in]  session  Pointer to the session structure. [in]  type  Message type. [in]  msg  Pointer to the message. [in]  len  Message length. Returns: PCONN_OK on success; otherwise PCONN_LIB_ERR.

int pconn_server_set_session_cookie (  pconn_session_t *  session, void *  cookie )

Sets the session-specific cookie on the server. This function is used to set the session-specific cookie at the server end. Any time the server accepts a connection from the client and calls the registered event handler, this function can be called to set the session-specific cookie. When the server receives the message over this session, this cookie will be passed as a parameter to the session message/event handler. Note: If a session-specific cookie is not set, the server context will be passed as a parameter to the session message/event handler. Parameters: [in]  session  Pointer to the session structure. [in]  cookie  Pointer to session-specific cookie. Returns: 0 for success; otherwise -1.

void pconn_server_shutdown (  pconn_server_t *  server  )

Shuts down the specified server. Parameters: server  Pointer to the server structure. Returns: None

void pconn_session_close (  pconn_session_t *  session  )

Closes the peer connection for a server session with the client. Parameters: [in]  session  Pointer to session information structure.

int pconn_session_get_peer_address (  pconn_session_t *  session, u_int32_t *  peer_address )

Returns the address of the peer. Gets the address of the peer (client) connecting to the server. It takes a pointer to the session structure as one of the arguments. This function returns the peer address in the argument provided by the calling function. Parameters: [in]  session  Pointer to the session structure. [out]  peer_address  Pointer to return peer address. Returns: PCONN_OK on success; otherwise PCONN_INVAL_PARAM or PCONN_LIB_ERR.

int pconn_session_get_peer_info (  pconn_session_t *  session, pconn_peer_info_t *  peer_info )

Gets the peer information for the client connecting to the server. This function takes a pointer to the session structure as one of the arguments and returns the peer information in the argument provided by the caller. This function then returns the address of the FPC and PIC slot when the peer is a PIC. Parameters: [in]  session  Pointer to the session structure. [out]  peer_info  Pointer to return peer information. Returns: PCONN_OK on success; otherwise PCONN_INVAL_PARAM or PCONN_LIB_ERR.

---