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... | |
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:
To use an LWMsgPeer as a call client:
#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().
tag | the message tag |
func | an 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.
tag | the message tag |
func | an LWMsgPeerCallFunction |
#define LWMSG_DISPATCH_END |
This macro is used in dispatch table construction to mark the end of the table
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.
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.
[in,out] | call | the call handle |
[in] | in | the input parameters |
[out] | out | the output parameters |
[in] | data | the data pointer set by lwmsg_peer_set_dispatch_data() |
LWMSG_STATUS_SUCCESS | success |
LWMSG_STATUS_PENDING | the request will be completed asynchronously |
... | call-specific failure |
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.
[in] | peer | the peer handle |
[in] | status | the status code of the error |
[in] | data | a 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.
[in] | call | the call handle |
[in] | params | the input or output parameters of the call |
[in] | data | a user data pointer |
LWMsgStatus lwmsg_peer_new | ( | const LWMsgContext * | context, |
LWMsgProtocol * | protocol, | ||
LWMsgPeer ** | peer | ||
) |
Creates a new peer object
[in] | context | an optional context |
[in] | protocol | a protocol object which describes the protocol spoken by the peer |
[out] | peer | the created peer object |
LWMSG_STATUS_SUCCESS | success |
LWMSG_STATUS_MEMORY | out of memory |
LWMSG_STATUS_INVALID_PARAMETER | protocol was NULL |
void lwmsg_peer_delete | ( | LWMsgPeer * | peer | ) |
Deletes a peer object.
[in,out] | peer | the 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.
[in,out] | peer | the peer object |
[in] | type | the type of timeout to set |
[in] | value | the value, or NULL for no timeout |
LWMSG_STATUS_SUCCESS | success |
LWMSG_STATUS_UNSUPPORTED | the specified timeout type is not supported |
LWMSG_STATUS_INVALID_PARAMETER | the 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.
[in,out] | peer | the peer object |
[in] | max_clients | the maximum number of simultaneous associations to support |
LWMSG_STATUS_SUCCESS | success |
LWMSG_STATUS_INVALID_STATE | the 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.
[in,out] | peer | the peer object |
[in] | max_backlog | the maximum number of clients to queue |
LWMSG_STATUS_SUCCESS | success |
LWMSG_STATUS_INVALID_STATE | the 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.
[in,out] | peer | the peer object |
[in] | spec | the dispatch specification |
LWMSG_STATUS_SUCCESS | success |
LWMSG_STATUS_MEMORY | out 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.
[in,out] | peer | the peer object |
[in] | type | the endpoint type |
[in] | fd | the socket on which to listen |
LWMSG_STATUS_SUCCESS | success |
LWMSG_STATUS_INVALID_STATE | the peer is already active |
LWMSG_STATUS_INVALID_PARAMETER | the 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.
[in,out] | peer | the peer object |
[in] | type | the type of endpoint |
[in] | endpoint | the endpoint path on which to listen |
[in] | permissions | permissions for the endpoint (only applicable to local endpoints) |
LWMSG_STATUS_SUCCESS | success |
LWMSG_STATUS_INVALID_STATE | the peer is already active |
LWMSG_STATUS_INVALID_PARAMETER | the 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.
[in,out] | peer | the peer handle |
[in] | construct | a session constructor function |
[in] | destruct | a session destructor function |
[in] | data | a user data pointer to be passed to both functions |
LWMSG_STATUS_SUCCESS | success |
LWMSG_STATUS_INVALID_STATE | the 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.
[in,out] | peer | the peer object |
[in] | data | the data pointer |
LWMSG_STATUS_SUCCESS | success |
LWMSG_STATUS_INVALID_STATE | the 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.
[in] | peer | the peer object |
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.
[in,out] | peer | the peer object |
LWMSG_STATUS_SUCCESS | success |
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.
[in,out] | peer | the peer object |
LWMSG_STATUS_SUCCESS | success |
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.
[in,out] | peer | the peer handle |
[in] | except | the handler function |
[in] | except_data | a user data pointer to pass to the handler function |
LWMSG_STATUS_SUCCESS | success |
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.
[in,out] | peer | the peer handle |
[in] | begin | trace begin function |
[in] | end | trace end function |
[in] | data | user data pointer to pass to trace functions |
LWMSG_STATUS_SUCCESS | success |
LWMSG_STATUS_INVALID_STATE | the 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().
[in,out] | peer | the peer handle |
[in] | type | the type of endpoint |
[in] | endpoint | the endpoint path |
LWMSG_STATUS_SUCCESS | success |
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.
[in,out] | peer | the peer handle |
[out] | session | the created session |
LWMSG_STATUS_SUCCESS | success |
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.
[in,out] | peer | the peer handle |
LWMSG_STATUS_SUCCESS | success |
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.
[in,out] | peer | the peer handle |
[in] | type | the endpoint type |
[in] | fd | the fd |
[out] | session | set to the created session |
LWMSG_STATUS_SUCCESS | success |
LWMsgStatus lwmsg_peer_accept_fd | ( | LWMsgPeer * | peer, |
LWMsgEndpointType | type, | ||
int | fd | ||
) |
Accepts a session on an fd that is already connected.
[in,out] | peer | the peer handle |
[in] | type | the endpoint type |
[in] | fd | the fd |
LWMSG_STATUS_SUCCESS | success |
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.
[in,out] | peer | the peer handle |
[out] | call | the acquired call handle |
LWMSG_STATUS_SUCCESS | success |
Likewise Message Library, part of the Likewise platform
Copyright © 2016 Likewise Software. All rights reserved.