Call discipline

Abstract call mechanism with asynchronous support. More...

Data Structures

struct  LWMsgParams
 Call parameters. More...
 

Macros

#define LWMSG_PARAMS_INITIALIZER
 Static initializer for LWMsgParams. More...
 

Typedefs

typedef struct LWMsgCall LWMsgCall
 Call handle. More...
 
typedef void(* LWMsgCompleteFunction )(LWMsgCall *call, LWMsgStatus status, void *data)
 Call completion callback. More...
 
typedef void(* LWMsgCancelFunction )(LWMsgCall *call, void *data)
 Call cancellation function. More...
 

Enumerations

enum  LWMsgCallDirection
 Call direction. More...
 

Functions

LWMsgStatus lwmsg_call_destroy_params (LWMsgCall *call, LWMsgParams *params)
 Destroy parameters. More...
 
LWMsgStatus lwmsg_call_dispatch (LWMsgCall *call, const LWMsgParams *input, LWMsgParams *output, LWMsgCompleteFunction complete, void *data)
 Dispatch call. More...
 
void lwmsg_call_pend (LWMsgCall *call, LWMsgCancelFunction cancel, void *data)
 Mark call as pending. More...
 
void lwmsg_call_complete (LWMsgCall *call, LWMsgStatus status)
 Complete a pending call. More...
 
void lwmsg_call_cancel (LWMsgCall *call)
 Cancel a pending call. More...
 
LWMsgStatus lwmsg_call_wait (LWMsgCall *call)
 Wait for pending call. More...
 
void lwmsg_call_release (LWMsgCall *call)
 Release call handle. More...
 
LWMsgSessionlwmsg_call_get_session (LWMsgCall *call)
 Get session for call. More...
 
LWMsgCallDirection lwmsg_call_get_direction (LWMsgCall *call)
 Get call direction. More...
 
void lwmsg_call_set_user_data (LWMsgCall *call, void *data)
 Set user data. More...
 
void * lwmsg_call_get_user_data (LWMsgCall *call)
 Get user data. More...
 

Detailed Description

Macro Definition Documentation

#define LWMSG_PARAMS_INITIALIZER

A constant which may be used to initialize automatic variables of LWMsgParams to sane default values

Typedef Documentation

typedef struct LWMsgCall LWMsgCall

Tracks a call through its life cycle.

typedef void(* LWMsgCompleteFunction)(LWMsgCall *call, LWMsgStatus status, void *data)

A caller-supplied function which is invoked when an asynchronous call is completed by the callee. A completion function must not block.

Parameters
[in]callthe call handle
[in]statusthe status code the call completed with
[in]dataa user data pointer
typedef void(* LWMsgCancelFunction)(LWMsgCall *call, void *data)

A callee-supplied function which is invoked when an asynchronous operation is cancelled by the caller. A cancellation function must not block.

Parameters
[in]callthe call handle
[in]dataa user data pointer

Enumeration Type Documentation

The direction of a call.

Function Documentation

LWMsgStatus lwmsg_call_destroy_params ( LWMsgCall call,
LWMsgParams params 
)

Destroys the contents of a parameters structure that was previously filled in by the given call handle. If the parameters structure contains no data (e.g. tag is LWMSG_TAG_INVALID), this function will take no action and return LWMSG_STATUS_SUCCESS. Therefore, you may always safely use this function on a LWMsgParams structure that has been correctly initialized (e.g. with LWMSG_PARAMS_INITIALIZER) to free any data it might contain.

Parameters
[in]callthe call handle
[in,out]paramsthe parameters structure
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MALFORMEDthe parameter data was not well-formed and could not be fully destroyed
LWMsgStatus lwmsg_call_dispatch ( LWMsgCall call,
const LWMsgParams input,
LWMsgParams output,
LWMsgCompleteFunction  complete,
void *  data 
)

Dispatches a call. If complete is provided, the callee may opt to complete the call asynchronously, in which case it will be invoked at completion time in an arbitrary thread.

Parameters
[in,out]callthe call handle
[in]inputthe input parameters
[out]outputthe output parameters
[in]completean optional completion callback
[in]dataa user data pointer to be passed to the completion callback
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_PENDINGthe call will be completed asynchronously by invoking the provided completion function
...call-specific error
void lwmsg_call_pend ( LWMsgCall call,
LWMsgCancelFunction  cancel,
void *  data 
)

Marks the given call as pending asychronous completion. This function must only be used by callees. It signifies the callee's intent to complete the call asynchronously with lwmsg_call_complete(). The callee must also cause LWMSG_STATUS_PENDING to be returned from lwmsg_call_dispatch().

Parameters
[in,out]callthe call handle
[in]cancela mandatory call cancellation function
[in]dataa data pointer to pass to the cancellation function
void lwmsg_call_complete ( LWMsgCall call,
LWMsgStatus  status 
)

Completes the given call with the provided status code. This function must only be used by callees, and only after marking the call as pending with lwmsg_call_pend().

Parameters
[in,out]callthe call handle
[in]statusthe call return status
void lwmsg_call_cancel ( LWMsgCall call)

Cancels the given call. The function must only be used by callers, and only after lwmsg_call_dispatch() has returned LWMSG_STATUS_PENDING for the call. When successfully cancelled, the completion function passed to lwmsg_call_dispatch() will be invoked with a status of LWMSG_STATUS_CANCELLED.

Parameters
[in,out]callthe call handle
LWMsgStatus lwmsg_call_wait ( LWMsgCall call)

Waits for the given pending call to complete and returns the status it completed with.

Parameters
[in]callthe call handle
Returns
the status the call completed with
void lwmsg_call_release ( LWMsgCall call)

Releases the given call handle. This function should be used by the caller after it is finished with the call. A pending call may be released before it completes.

Parameters
[in,out]callthe call handle
LWMsgSession* lwmsg_call_get_session ( LWMsgCall call)

Returns the LWMsgSession associated with the given call. This function may be used by both callers and callees.

Parameters
[in]callthe call handle
Returns
the session for the call
LWMsgCallDirection lwmsg_call_get_direction ( LWMsgCall call)

Returns whether a call is incoming or outgoing.

Parameters
[in]callthe call handle
Returns
the call type
void lwmsg_call_set_user_data ( LWMsgCall call,
void *  data 
)

Sets an arbitrary user data pointer on a call handle, which may be used for any purpose.

Parameters
[in,out]callthe call handle
[in]datathe data pointer
void* lwmsg_call_get_user_data ( LWMsgCall call)

Gets the user data pointer previously set with lwmsg_call_set_user_data().

Parameters
[in]callthe call handle
Returns
the user data pointer