Nexus for incoming and outgoing calls. More...

Macros

#define LWMSG_DISPATCH_BLOCK(tag, func)
 Define blocking message handler. More...
 
#define LWMSG_DISPATCH_NONBLOCK(tag, func)
 Define non-blocking message handler. More...
 
#define LWMSG_DISPATCH_END
 Terminate dispatch table. More...
 

Typedefs

typedef struct
LWMsgDispatchSpec const 
LWMsgDispatchSpec
 Dispatch specification. More...
 
typedef struct LWMsgPeer LWMsgPeer
 Peer structure. More...
 
typedef LWMsgStatus(* LWMsgPeerCallFunction )(LWMsgCall *call, const LWMsgParams *in, LWMsgParams *out, void *data)
 Call handler function. More...
 
typedef void(* LWMsgPeerExceptionFunction )(LWMsgPeer *peer, LWMsgStatus status, void *data)
 Exception handler function. More...
 
typedef void(* LWMsgPeerTraceFunction )(LWMsgCall *call, const LWMsgParams *params, LWMsgStatus status, void *data)
 Call trace function. More...
 

Functions

LWMsgStatus lwmsg_peer_new (const LWMsgContext *context, LWMsgProtocol *protocol, LWMsgPeer **peer)
 Create a new peer object. More...
 
void lwmsg_peer_delete (LWMsgPeer *peer)
 Delete a peer object. More...
 
LWMsgStatus lwmsg_peer_set_timeout (LWMsgPeer *peer, LWMsgTimeout type, LWMsgTime *value)
 Set timeout. More...
 
LWMsgStatus lwmsg_peer_set_max_listen_clients (LWMsgPeer *peer, unsigned int max_clients)
 Set maximum number of simultaneous incoming associations. More...
 
LWMsgStatus lwmsg_peer_set_max_listen_backlog (LWMsgPeer *peer, unsigned int max_backlog)
 Set maximum number of backlogged associations. More...
 
LWMsgStatus lwmsg_peer_add_dispatch_spec (LWMsgPeer *peer, LWMsgDispatchSpec *spec)
 Add a message dispatch specification. More...
 
LWMsgStatus lwmsg_peer_add_listen_fd (LWMsgPeer *peer, LWMsgEndpointType type, int fd)
 Add listen socket. More...
 
LWMsgStatus lwmsg_peer_add_listen_endpoint (LWMsgPeer *peer, LWMsgEndpointType type, const char *endpoint, mode_t permissions)
 Add listening endpoint. More...
 
LWMsgStatus lwmsg_peer_set_listen_session_functions (LWMsgPeer *peer, LWMsgSessionConstructFunction construct, LWMsgSessionDestructFunction destruct, void *data)
 Set session construct and destruct functions for incoming clients. More...
 
LWMsgStatus lwmsg_peer_set_dispatch_data (LWMsgPeer *peer, void *data)
 Set dispatch data pointer. More...
 
void * lwmsg_peer_get_dispatch_data (LWMsgPeer *peer)
 Get dispatch data pointer. More...
 
LWMsgStatus lwmsg_peer_start_listen (LWMsgPeer *peer)
 Start listening for incoming associations. More...
 
LWMsgStatus lwmsg_peer_stop_listen (LWMsgPeer *peer)
 Stop listening for incoming assocations. More...
 
LWMsgStatus lwmsg_peer_set_exception_function (LWMsgPeer *peer, LWMsgPeerExceptionFunction except, void *except_data)
 Set exception handler. More...
 
LWMsgStatus lwmsg_peer_set_trace_functions (LWMsgPeer *peer, LWMsgPeerTraceFunction begin, LWMsgPeerTraceFunction end, void *data)
 Set trace functions. More...
 
LWMsgStatus lwmsg_peer_add_connect_endpoint (LWMsgPeer *peer, LWMsgEndpointType type, const char *endpoint)
 Add connection endpoint. More...
 
LWMsgStatus lwmsg_peer_connect (LWMsgPeer *peer, LWMsgSession **session)
 Create outgoing session. More...
 
LWMsgStatus lwmsg_peer_disconnect (LWMsgPeer *peer)
 Close outgoing session. More...
 
LWMsgStatus lwmsg_peer_connect_fd (LWMsgPeer *peer, LWMsgEndpointType type, int fd, LWMsgSession **session)
 Establish session on existing fd. More...
 
LWMsgStatus lwmsg_peer_accept_fd (LWMsgPeer *peer, LWMsgEndpointType type, int fd)
 Accept session on existing fd. More...
 
LWMsgStatus lwmsg_peer_acquire_call (LWMsgPeer *peer, LWMsgCall **call)
 Acquire outgoing call handle [DEPRECATED]. More...
 

Detailed Description

An LWMsgPeer struct acts as a nexus for both incoming and outgoing calls, combining client and server functionality into a single abstraction. A peer speaks a single protocol (LWMsgProtocol) and may do any or all of the following simultaneously.

To use an LWMsgPeer as a call server:

  1. Create and set up an LWMsgProtocol and optionally an LWMsgContext to customize memory management and logging.
  2. Create a peer with lwmsg_peer_new().
  3. Register one or more tables of dispatch functions to handle incoming calls with lwmsg_peer_add_dispatch_spec().
  4. Register one or more listening endpoints with lwmsg_peer_add_listen_endpoint().
  5. Start listening for incoming requests with lwmsg_peer_start_listen().

To use an LWMsgPeer as a call client:

  1. Create and set up an LWMsgProtocol and optionally an LWMsgContext to customize memory management and logging.
  2. Create a peer with lwmsg_peer_new().
  3. If the protocol makes use of callbacks, register one or more tables of dispatch functions to handle incoming callbacks with lwmsg_peer_add_dispatch_spec().
  4. Register one or more endpoints to connect to with lwmsg_peer_add_connect_endpoint(). The first one which can be succefully connected to is the one which will be used.
  5. Connect with lwmsg_peer_connect() to get an LWMsgSession.
  6. Acquire a call handle with lwmsg_session_acquire_call() and call with lwmsg_call_dispatch().

Macro Definition Documentation

#define LWMSG_DISPATCH_BLOCK (   tag,
  func 
)

Defines a message handler function for the given message tag within a dispatch specification. The provided callback function may block indefinitely in the process of servicing the request. It may also opt to complete the request asynchronously with lwmsg_call_pend() and lwmsg_call_complete().

Parameters
tagthe message tag
funcan LWMsgPeerCallFunction
#define LWMSG_DISPATCH_NONBLOCK (   tag,
  func 
)

Defines a message handler function for the given message tag within a dispatch specification. The provided callback function must not block indefinitely in the process of servicing the request. If the request cannot be completed immediately, it must complete it asynchronously.

Parameters
tagthe message tag
funcan LWMsgPeerCallFunction
#define LWMSG_DISPATCH_END

This macro is used in dispatch table construction to mark the end of the table

Typedef Documentation

typedef struct LWMsgDispatchSpec const LWMsgDispatchSpec

This structure defines a table of dispatch functions to handle incoming messages in a peer. It should be constructed as a statically-initialized array using #LWMSG_DISPATCH() and LWMSG_DISPATCH_END macros.

typedef struct LWMsgPeer LWMsgPeer

An opaque structure from which calls can be answered or dispatched.

typedef LWMsgStatus(* LWMsgPeerCallFunction)(LWMsgCall *call, const LWMsgParams *in, LWMsgParams *out, void *data)

A callback function which handles an incoming call request. The function may complete the call immediately by filling in the out params structure and returning LWMSG_STATUS_SUCCESS, or asynchronously by invoking lwmsg_call_pend() on the call handle, returning LWMSG_STATUS_PENDING, and completing the call later with lwmsg_call_complete(). Returning any other status code will cause the client call to fail with the same status.

The contents of the in params structure is defined only for the duration of the function call and must not be referenced after the function returns or modified during the course of the call. The call handle is also only valid while the call is in progress and should not be referenced after completion.

Data inserted into the out params structure must be allocated with the same memory manager as the LWMsgPeer which dispatched the call. By default, this is plain malloc(). The caller assumes ownership of all such memory and the responsibility of freeing it.

Parameters
[in,out]callthe call handle
[in]inthe input parameters
[out]outthe output parameters
[in]datathe data pointer set by lwmsg_peer_set_dispatch_data()
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_PENDINGthe request will be completed asynchronously
...call-specific failure
See Also
lwmsg_context_set_memory_functions() and lwmsg_peer_new() for customizing the Peers's memory manager.
typedef void(* LWMsgPeerExceptionFunction)(LWMsgPeer *peer, LWMsgStatus status, void *data)

A callback function which is invoked when an unexpected error occurs in the process of handling incoming calls.

Parameters
[in]peerthe peer handle
[in]statusthe status code of the error
[in]dataa user data pointer
typedef void(* LWMsgPeerTraceFunction)(LWMsgCall *call, const LWMsgParams *params, LWMsgStatus status, void *data)

A callback function which allows tracing when a call begins or ends.

Parameters
[in]callthe call handle
[in]paramsthe input or output parameters of the call
[in]dataa user data pointer

Function Documentation

LWMsgStatus lwmsg_peer_new ( const LWMsgContext context,
LWMsgProtocol protocol,
LWMsgPeer **  peer 
)

Creates a new peer object

Parameters
[in]contextan optional context
[in]protocola protocol object which describes the protocol spoken by the peer
[out]peerthe created peer object
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMSG_STATUS_INVALID_PARAMETERprotocol was NULL
void lwmsg_peer_delete ( LWMsgPeer peer)

Deletes a peer object.

Warning
Attempting to delete a peer which has outstanding outgoing calls has undefined behavior. Attempting to delete a peer which is listening for incoming calls will block until all outstanding incoming calls can be cancelled.
Parameters
[in,out]peerthe peer object to delete
LWMsgStatus lwmsg_peer_set_timeout ( LWMsgPeer peer,
LWMsgTimeout  type,
LWMsgTime *  value 
)

Sets the specified timeout to the specified value. See lwmsg_assoc_set_timeout() for more information.

Parameters
[in,out]peerthe peer object
[in]typethe type of timeout to set
[in]valuethe value, or NULL for no timeout
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_UNSUPPORTEDthe specified timeout type is not supported
LWMSG_STATUS_INVALID_PARAMETERthe timeout was invalid
LWMsgStatus lwmsg_peer_set_max_listen_clients ( LWMsgPeer peer,
unsigned int  max_clients 
)

Sets the maximum numbers of incoming associations which the peer will track simultaneously. Associations beyond this will wait until a slot becomes available.

Parameters
[in,out]peerthe peer object
[in]max_clientsthe maximum number of simultaneous associations to support
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_STATEthe peer is already listening
LWMsgStatus lwmsg_peer_set_max_listen_backlog ( LWMsgPeer peer,
unsigned int  max_backlog 
)

Sets the maximum numbers of pending associations which the peer will keep waiting until a client slot becomes available. Pending associations beyond this value will be rejected outright.

Parameters
[in,out]peerthe peer object
[in]max_backlogthe maximum number of clients to queue
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_STATEthe peer is already active
LWMsgStatus lwmsg_peer_add_dispatch_spec ( LWMsgPeer peer,
LWMsgDispatchSpec spec 
)

Adds a set of message dispatch functions to the specified peer object.

Parameters
[in,out]peerthe peer object
[in]specthe dispatch specification
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMsgStatus lwmsg_peer_add_listen_fd ( LWMsgPeer peer,
LWMsgEndpointType  type,
int  fd 
)

Adds a socket on which the peer will accept incoming associations. This function must be passed a valid socket descriptor that matches the specified mode and is already listening (has had listen() called on it). The peer will assume ownership of this fd.

Parameters
[in,out]peerthe peer object
[in]typethe endpoint type
[in]fdthe socket on which to listen
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_STATEthe peer is already active
LWMSG_STATUS_INVALID_PARAMETERthe file descriptor was invalid
LWMsgStatus lwmsg_peer_add_listen_endpoint ( LWMsgPeer peer,
LWMsgEndpointType  type,
const char *  endpoint,
mode_t  permissions 
)

Adds an endpoint on which the peer will listen for connections.

Parameters
[in,out]peerthe peer object
[in]typethe type of endpoint
[in]endpointthe endpoint path on which to listen
[in]permissionspermissions for the endpoint (only applicable to local endpoints)
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_STATEthe peer is already active
LWMSG_STATUS_INVALID_PARAMETERthe endpoint was invalid
LWMsgStatus lwmsg_peer_set_listen_session_functions ( LWMsgPeer peer,
LWMsgSessionConstructFunction  construct,
LWMsgSessionDestructFunction  destruct,
void *  data 
)

Sets functions which will be called when a client is accepted into a session for the first time. The constructor function may set up a session context which the destructor function should clean up when the session is terminated.

Parameters
[in,out]peerthe peer handle
[in]constructa session constructor function
[in]destructa session destructor function
[in]dataa user data pointer to be passed to both functions
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_STATEthe peer is already active
LWMsgStatus lwmsg_peer_set_dispatch_data ( LWMsgPeer peer,
void *  data 
)

Sets the user data pointer which is passed to dispatch functions. This function may only be used while the peer is inactive.

Parameters
[in,out]peerthe peer object
[in]datathe data pointer
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_STATEthe peer is already active
void* lwmsg_peer_get_dispatch_data ( LWMsgPeer peer)

Gets the user data pointer which is passed to dispatch functions. If no pointer was explicitly set, the value defaults to NULL.

Parameters
[in]peerthe peer object
Returns
the data pointer
LWMsgStatus lwmsg_peer_start_listen ( LWMsgPeer peer)

Starts listening for incoming associations from other peers on all endpoints registered with lwmsg_peer_add_listen_endpoint(). This function returns once all endpoints are ready to accept incoming associations.

Parameters
[in,out]peerthe peer object
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMsgStatus lwmsg_peer_stop_listen ( LWMsgPeer peer)

Stops the specified peer accepting new associations and aggressively terminates any existing associations, including cancelling all outstanding incoming calls. This function returns once all incoming associations have been terminated.

Parameters
[in,out]peerthe peer object
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMsgStatus lwmsg_peer_set_exception_function ( LWMsgPeer peer,
LWMsgPeerExceptionFunction  except,
void *  except_data 
)

Sets a callback function which will be invoked when an error occurs during the course of servicing incoming or outgoing calls. The function may take appropriate action depending on the error, such as logging a warning or instructing the main application thread to shut down.

Warning
Do not call lwmsg_peer_stop_listen() from an exception handler
Parameters
[in,out]peerthe peer handle
[in]exceptthe handler function
[in]except_dataa user data pointer to pass to the handler function
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMsgStatus lwmsg_peer_set_trace_functions ( LWMsgPeer peer,
LWMsgPeerTraceFunction  begin,
LWMsgPeerTraceFunction  end,
void *  data 
)

Sets functions which will be invoked whenever a call begins or ends. To determine the direction of a call, use lwmsg_call_get_direction(). To store extra data on the call handle, use lwmsg_call_set_user_data(). This mechanism can be use for logging, statistics gathering, etc.

Parameters
[in,out]peerthe peer handle
[in]begintrace begin function
[in]endtrace end function
[in]datauser data pointer to pass to trace functions
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_STATEthe peer is already active
LWMsgStatus lwmsg_peer_add_connect_endpoint ( LWMsgPeer peer,
LWMsgEndpointType  type,
const char *  endpoint 
)

Adds an endpoint which will be used when establishing an outgoing association with lwmsg_peer_connect().

Parameters
[in,out]peerthe peer handle
[in]typethe type of endpoint
[in]endpointthe endpoint path
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMsgStatus lwmsg_peer_connect ( LWMsgPeer peer,
LWMsgSession **  session 
)

Creates a session suitable for making calls to one of the endpoints registered with lwmsg_peer_add_connect_endpoint(). Establishing a connection to an endpoint will not occur until a call is made, at which point the endpoints will be tried in order until one succeeds.

Parameters
[in,out]peerthe peer handle
[out]sessionthe created session
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMsgStatus lwmsg_peer_disconnect ( LWMsgPeer peer)

Closes the session established by lwmsg_peer_connect(). All outstanding outgoing calls will be canceled and all open handles will be rendered invalid. The session handle may no longer be used after calling this function.

Parameters
[in,out]peerthe peer handle
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMsgStatus lwmsg_peer_connect_fd ( LWMsgPeer peer,
LWMsgEndpointType  type,
int  fd,
LWMsgSession **  session 
)

Establishes a session with a peer like lwmsg_peer_connect(), but uses the provided pre-connected file descriptor.

Parameters
[in,out]peerthe peer handle
[in]typethe endpoint type
[in]fdthe fd
[out]sessionset to the created session
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMsgStatus lwmsg_peer_accept_fd ( LWMsgPeer peer,
LWMsgEndpointType  type,
int  fd 
)

Accepts a session on an fd that is already connected.

Parameters
[in,out]peerthe peer handle
[in]typethe endpoint type
[in]fdthe fd
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMsgStatus lwmsg_peer_acquire_call ( LWMsgPeer peer,
LWMsgCall **  call 
)

Acquire a call handle which can be used to make an outgoing call. Peer call handles fully support asynchronous calls. The handle may be reused after each call completes. If the peer has not been connected with lwmsg_peer_connect(), this function will do so implicitly. The acquired call handle should be released with lwmsg_call_release() when no longer needed.

Parameters
[in,out]peerthe peer handle
[out]callthe acquired call handle
Return values
LWMSG_STATUS_SUCCESSsuccess
Deprecated:
Use lwmsg_session_acquire_call() on the LWMsgSession returned by lwmsg_peer_connect() instead.