le_messaging.h File Reference

Go to the source code of this file.

Macros
#define	LE_KILL_CLIENT(formatString,...)

Typedefs
typedef struct le_msg_Protocol *	le_msg_ProtocolRef_t
typedef struct le_msg_Service *	le_msg_ServiceRef_t
typedef struct le_msg_Session *	le_msg_SessionRef_t
typedef struct le_msg_Message *	le_msg_MessageRef_t
typedef void(*	le_msg_SessionEventHandler_t )(le_msg_SessionRef_t sessionRef, void *contextPtr)
typedef void(*	le_msg_ReceiveHandler_t )(le_msg_MessageRef_t msgRef, void *contextPtr)
typedef void(*	le_msg_ResponseCallback_t )(le_msg_MessageRef_t msgRef, void *contextPtr)

Functions
le_msg_ProtocolRef_t	le_msg_GetProtocolRef (const char *protocolId, size_t largestMsgSize)
const char *	le_msg_GetProtocolIdStr (le_msg_ProtocolRef_t protocolRef)
size_t	le_msg_GetProtocolMaxMsgSize (le_msg_ProtocolRef_t protocolRef)
le_msg_SessionRef_t	le_msg_CreateSession (le_msg_ProtocolRef_t protocolRef, const char *serviceName)
void	le_msg_SetSessionContextPtr (le_msg_SessionRef_t sessionRef, void *contextPtr)
void *	le_msg_GetSessionContextPtr (le_msg_SessionRef_t sessionRef)
void	le_msg_DeleteSession (le_msg_SessionRef_t sessionRef)
void	le_msg_SetSessionRecvHandler (le_msg_SessionRef_t sessionRef, le_msg_ReceiveHandler_t handlerFunc, void *contextPtr)
void	le_msg_SetSessionCloseHandler (le_msg_SessionRef_t sessionRef, le_msg_SessionEventHandler_t handlerFunc, void *contextPtr)
void	le_msg_OpenSession (le_msg_SessionRef_t sessionRef, le_msg_SessionEventHandler_t callbackFunc, void *contextPtr)
void	le_msg_OpenSessionSync (le_msg_SessionRef_t sessionRef)
void	le_msg_CloseSession (le_msg_SessionRef_t sessionRef)
le_msg_ProtocolRef_t	le_msg_GetSessionProtocol (le_msg_SessionRef_t sessionRef)
le_msg_ServiceRef_t	le_msg_GetSessionService (le_msg_SessionRef_t sessionRef)
le_result_t	le_msg_GetClientUserId (le_msg_SessionRef_t sessionRef, uid_t *userIdPtr)
le_result_t	le_msg_GetClientProcessId (le_msg_SessionRef_t sessionRef, pid_t *processIdPtr)
le_result_t	le_msg_GetClientUserCreds (le_msg_SessionRef_t sessionRef, uid_t *userIdPtr, pid_t *processIdPtr)
le_msg_MessageRef_t	le_msg_CreateMsg (le_msg_SessionRef_t sessionRef)
void	le_msg_AddRef (le_msg_MessageRef_t msgRef)
void	le_msg_ReleaseMsg (le_msg_MessageRef_t msgRef)
bool	le_msg_NeedsResponse (le_msg_MessageRef_t msgRef)
void *	le_msg_GetPayloadPtr (le_msg_MessageRef_t msgRef)
size_t	le_msg_GetMaxPayloadSize (le_msg_MessageRef_t msgRef)
void	le_msg_SetFd (le_msg_MessageRef_t msgRef, int fd)
int	le_msg_GetFd (le_msg_MessageRef_t msgRef)
void	le_msg_Send (le_msg_MessageRef_t msgRef)
le_msg_SessionRef_t	le_msg_GetSession (le_msg_MessageRef_t msgRef)
void	le_msg_RequestResponse (le_msg_MessageRef_t msgRef, le_msg_ResponseCallback_t handlerFunc, void *contextPtr)
le_msg_MessageRef_t	le_msg_RequestSyncResponse (le_msg_MessageRef_t msgRef)
void	le_msg_Respond (le_msg_MessageRef_t msgRef)
le_msg_ServiceRef_t	le_msg_CreateService (le_msg_ProtocolRef_t protocolRef, const char *serviceName)
void	le_msg_DeleteService (le_msg_ServiceRef_t serviceRef)
void	le_msg_SetServiceOpenHandler (le_msg_ServiceRef_t serviceRef, le_msg_SessionEventHandler_t handlerFunc, void *contextPtr)
void	le_msg_GetServiceOpenHandler (le_msg_ServiceRef_t serviceRef, le_msg_SessionEventHandler_t *handlerFunc, void **contextPtr)
void	le_msg_SetServiceCloseHandler (le_msg_ServiceRef_t serviceRef, le_msg_SessionEventHandler_t handlerFunc, void *contextPtr)
void	le_msg_GetServiceCloseHandler (le_msg_ServiceRef_t serviceRef, le_msg_SessionEventHandler_t *handlerFunc, void **contextPtr)
void	le_msg_SetServiceRecvHandler (le_msg_ServiceRef_t serviceRef, le_msg_ReceiveHandler_t handlerFunc, void *contextPtr)
void	le_msg_SetServiceContextPtr (le_msg_ServiceRef_t serviceRef, void *contextPtr)
void *	le_msg_GetServiceContextPtr (le_msg_ServiceRef_t serviceRef)
void	le_msg_AdvertiseService (le_msg_ServiceRef_t serviceRef)
void	le_msg_HideService (le_msg_ServiceRef_t serviceRef)
const char *	le_msg_GetServiceName (le_msg_ServiceRef_t serviceRef)
le_msg_ProtocolRef_t	le_msg_GetServiceProtocol (le_msg_ServiceRef_t serviceRef)
le_msg_MessageRef_t	le_msg_GetServiceRxMsg (void)

Detailed Description

Legato Low-Level Messaging API include file.

Copyright (C) Sierra Wireless, Inc. 2013-2014. Use of this work is subject to license.

Macro Definition Documentation

#define LE_KILL_CLIENT	(		formatString,
			...
	)

Value:

{ \
    le_msg_MessageRef_t msgRef = le_msg_GetServiceRxMsg(); \
    LE_FATAL_IF(msgRef == NULL, formatString, ##__VA_ARGS__); \
    LE_EMERG(formatString, ##__VA_ARGS__); \
    le_msg_CloseSession(le_msg_GetSession(msgRef)); \
}

Logs an error message (at EMERGENCY level) and:

• if the caller is running a server-side IPC function, kills the connection to the client and returns.
• if the caller is not running a server-side IPC function, kills the caller (doesn't return).

Typedef Documentation

typedef struct le_msg_Message* le_msg_MessageRef_t

Reference to a message.

typedef struct le_msg_Protocol* le_msg_ProtocolRef_t

Reference to a protocol.

typedef void(* le_msg_ReceiveHandler_t)(le_msg_MessageRef_t msgRef, void *contextPtr)

Receive handler function prototype.

See le_msg_SetSessionRecvHandler() and le_msg_SetServiceRecvHandler().

Parameters

msgRef	[in] Reference to the received message. Don't forget to release this using le_msg_ReleaseMsg() when you are finished with it.
contextPtr	[in] Opaque contextPtr value provided when the handler was registered.

typedef void(* le_msg_ResponseCallback_t)(le_msg_MessageRef_t msgRef, void *contextPtr)

Asynchronous response callback function prototype.

See le_msg_RequestResponse().

Parameters

msgRef	[in] Reference to the received response message, or NULL if the transaction failed and no response was received. If not NULL, don't forget to release it by calling le_msg_ReleaseMsg() when you are finished with it.
contextPtr	[in] Opaque contextPtr value passed to le_msg_RequestResponse().

typedef struct le_msg_Service* le_msg_ServiceRef_t

Reference to a server's service instance.

typedef void(* le_msg_SessionEventHandler_t)(le_msg_SessionRef_t sessionRef, void *contextPtr)

Handler function prototype for handlers that take session references as their arguments.

See le_msg_SetSessionCloseHandler(), le_msg_SetServiceOpenHandler(), and le_msg_SetServiceCloseHandler().

Parameters

sessionRef	[in] Reference to the session that experienced the event.
contextPtr	[in] Opaque contextPtr value provided when the handler was registered.

typedef struct le_msg_Session* le_msg_SessionRef_t

Reference to a client-server session.

Function Documentation

void le_msg_AddRef

(

le_msg_MessageRef_t

msgRef

)

Adds to the reference count on a message object.

Parameters

[in]

msgRef

Reference to the message.

void le_msg_AdvertiseService

(

le_msg_ServiceRef_t

serviceRef

)

Makes a given service available for clients to find.

Note

Server-only function.

Parameters

[in]

serviceRef

Reference to the service.

void le_msg_CloseSession

(

le_msg_SessionRef_t

sessionRef

)

Terminates a session.

Parameters

[in]

sessionRef

Reference to the session.

le_msg_MessageRef_t le_msg_CreateMsg

(

le_msg_SessionRef_t

sessionRef

)

Creates a message to be sent over a given session.

Returns

Message reference.

Note

• Function never returns on failure, there's no need to check the return code.
• If you see warnings on message pools expanding, then you may be forgetting to release the messages you have received.

Parameters

[in]

sessionRef

Reference to the session.

le_msg_ServiceRef_t le_msg_CreateService	(	le_msg_ProtocolRef_t	protocolRef,
		const char *	serviceName
	)

Creates a service that is accessible using a protocol.

Returns

Service reference.

Parameters

[in]	protocolRef	Reference to the protocol to be used.
[in]	serviceName	Service instance name.

le_msg_SessionRef_t le_msg_CreateSession	(	le_msg_ProtocolRef_t	protocolRef,
		const char *	serviceName
	)

Creates a session that will make use of a protocol to talk to a given service.

Note

This does not actually attempt to open the session. It just creates the session object, allowing the client the opportunity to register handlers for the session before attempting to open it using le_msg_OpenSession().

Returns

Session reference.

Parameters

[in]	protocolRef	Reference to the protocol to be used.
[in]	serviceName	Name of the service instance.

void le_msg_DeleteService

(

le_msg_ServiceRef_t

serviceRef

)

Deletes a service. Any open sessions will be terminated.

Note

Server-only function.

Parameters

[in]

serviceRef

Reference to the service.

void le_msg_DeleteSession

(

le_msg_SessionRef_t

sessionRef

)

Deletes a session. This will end the session and free up any resources associated with it. Any pending request-response transactions in this sesssion will be terminated. If the far end has registered a session close handler callback, it will be called.

Note

Function is only used by clients. On the server side, sessions are automatically deleted when they close.

Parameters

[in]

sessionRef

Reference to the session.

le_result_t le_msg_GetClientProcessId	(	le_msg_SessionRef_t	sessionRef,
		pid_t *	processIdPtr
	)

Fetches the user PID of the client at the far end of a given IPC session.

Warning

This function can only be called for the server-side of a session.

Returns

LE_OK if successful. LE_CLOSED if the session has closed.

Parameters

[in]	sessionRef	Reference to the session.
[out]	processIdPtr	Ptr to where the result is to be stored on success.

le_result_t le_msg_GetClientUserCreds	(	le_msg_SessionRef_t	sessionRef,
		uid_t *	userIdPtr,
		pid_t *	processIdPtr
	)

Fetches the user creds of the client at the far end of a given IPC session.

Warning

This function can only be called for the server-side of a session.

Returns

LE_OK if successful. LE_CLOSED if the session has closed.

Parameters

[in]	sessionRef	Reference to the session.
[out]	userIdPtr	Ptr to where the uid is to be stored on success.
[out]	processIdPtr	Ptr to where the pid is to be stored on success.

le_result_t le_msg_GetClientUserId	(	le_msg_SessionRef_t	sessionRef,
		uid_t *	userIdPtr
	)

Fetches the user ID of the client at the far end of a given IPC session.

Warning

This function can only be called for the server-side of a session.

Returns

LE_OK if successful. LE_CLOSED if the session has closed.

Parameters

[in]	sessionRef	Reference to the session.
[out]	userIdPtr	Ptr to where the result is to be stored on success.

int le_msg_GetFd

(

le_msg_MessageRef_t

msgRef

)

Fetches a received file descriptor from the message.

Returns

The file descriptor, or -1 if no file descriptor was sent with this message or if the fd was already fetched from the message.

Parameters

[in]

msgRef

Reference to the message.

size_t le_msg_GetMaxPayloadSize

(

le_msg_MessageRef_t

msgRef

)

Gets the size, in bytes, of the message payload memory buffer.

Returns

The size, in bytes.

Parameters

[in]

msgRef

Reference to the message.

void* le_msg_GetPayloadPtr

(

le_msg_MessageRef_t

msgRef

)

Gets a pointer to the message payload memory buffer.

Returns

Pointer to the payload buffer.

Warning

Be careful not to overflow this buffer.

Parameters

[in]

msgRef

Reference to the message.

const char* le_msg_GetProtocolIdStr

(

le_msg_ProtocolRef_t

protocolRef

)

Gets the unique identifier string of the protocol.

Returns

Pointer to the protocol identifier (null-terminated, UTF-8 string).

Parameters

[in]

protocolRef

Reference to the protocol.

size_t le_msg_GetProtocolMaxMsgSize

(

le_msg_ProtocolRef_t

protocolRef

)

Gets the protocol's maximum message size.

Returns

The size, in bytes.

Parameters

[in]

protocolRef

Reference to the protocol.

le_msg_ProtocolRef_t le_msg_GetProtocolRef	(	const char *	protocolId,
		size_t	largestMsgSize
	)

Gets a reference to refer to a particular version of a particular protocol.

Used to help match clients with services that use the same protocol.

Returns

Protocol reference.

Parameters

[in]	protocolId	String uniquely identifying the the protocol and version.
[in]	largestMsgSize	Size (in bytes) of the largest message in the protocol.

void le_msg_GetServiceCloseHandler	(	le_msg_ServiceRef_t	serviceRef,
		le_msg_SessionEventHandler_t *	handlerFunc,
		void **	contextPtr
	)

Gets the currently registered service close handler and it's context pointer, or NULL if none are currently registered.

Parameters

[in]	serviceRef	Reference to the service.
[out]	handlerFunc	Handler function.
[out]	contextPtr	Opaque pointer value to pass to handler.

void* le_msg_GetServiceContextPtr

(

le_msg_ServiceRef_t

serviceRef

)

Fetches the opaque context value (void pointer) associated with a specified service using le_msg_SetServiceContextPtr().

Returns

Context pointer value, or NULL if le_msg_SetServiceContextPtr() was never called for this service.

Note

Server-only function.

Parameters

[in]

serviceRef

Reference to the service.

const char* le_msg_GetServiceName

(

le_msg_ServiceRef_t

serviceRef

)

Fetches a pointer to the name of a service.

Returns

Pointer to a null-terminated string.

Warning

Pointer returned will only remain valid until the service is deleted.

Parameters

[in]

serviceRef

Reference to the service.

void le_msg_GetServiceOpenHandler	(	le_msg_ServiceRef_t	serviceRef,
		le_msg_SessionEventHandler_t *	handlerFunc,
		void **	contextPtr
	)

Gets the currently registered service open handler and it's context pointer, or NULL if none are currently registered.

Parameters

[in]	serviceRef	Reference to the service.
[out]	handlerFunc	Handler function.
[out]	contextPtr	Opaque pointer value to pass to handler.

le_msg_ProtocolRef_t le_msg_GetServiceProtocol

(

le_msg_ServiceRef_t

serviceRef

)

Fetches a reference to the protocol supported by a specified Service.

Returns

Protocol reference.

Parameters

[in]

serviceRef

Reference to the service.

le_msg_MessageRef_t le_msg_GetServiceRxMsg

(

void

)

Check if the calling thread is currently running a Service's message receive handler; if so, return a reference to the message object being handled.

Returns

Reference to the message being handled, or NULL if no Service message receive handler is currently running.

le_msg_SessionRef_t le_msg_GetSession

(

le_msg_MessageRef_t

msgRef

)

Gets a reference to the session to which a given message belongs.

Returns

Session reference.

Parameters

[in]

msgRef

Reference to the message.

void* le_msg_GetSessionContextPtr

(

le_msg_SessionRef_t

sessionRef

)

Fetches the opaque context value (void pointer) that was set earlier using le_msg_SetSessionContextPtr().

Returns

Context Ptr value passed into le_msg_SetSessionContextPtr(), or NULL if le_msg_SetSessionContextPtr() has not been called for this session yet.

Parameters

[in]

sessionRef

Reference to the session.

le_msg_ProtocolRef_t le_msg_GetSessionProtocol

(

le_msg_SessionRef_t

sessionRef

)

Fetches a reference to the protocol that is being used for a given session.

Returns

Reference to the protocol.

Parameters

[in]

sessionRef

Reference to the session.

le_msg_ServiceRef_t le_msg_GetSessionService

(

le_msg_SessionRef_t

sessionRef

)

Fetches a reference to the service that is associated with a given session.

Returns

Reference to the service.

Parameters

[in]

sessionRef

Reference to the session.

void le_msg_HideService

(

le_msg_ServiceRef_t

serviceRef

)

Makes a specified service unavailable for clients to find without terminating any ongoing sessions.

Note

Server-only function.

Parameters

[in]

serviceRef

Reference to the service.

bool le_msg_NeedsResponse

(

le_msg_MessageRef_t

msgRef

)

Checks whether a message requires a response or not.

Note

This is intended for use on the server side only.

Returns

• TRUE if the message needs to be responded to using le_msg_Respond().
• FALSE if the message does not need to be responded to, and should be disposed of using le_msg_ReleaseMsg() when it is no longer needed.

Parameters

[in]

msgRef

Reference to the message.

void le_msg_OpenSession	(	le_msg_SessionRef_t	sessionRef,
		le_msg_SessionEventHandler_t	callbackFunc,
		void *	contextPtr
	)

Opens a session with a service, providing a function to be called-back when the session is open.

Note

Only clients open sessions. Servers must patiently wait for clients to open sessions with them.

Warning

If the client and server don't agree on the maximum message size for the protocol, an attempt to open a session between that client and server will result in a fatal error being logged and the client process being killed.

Parameters

[in]	sessionRef	Reference to the session.
[in]	callbackFunc	Function to be called when open. NULL if no notification is needed.
[in]	contextPtr	Opaque value to pass to the callback.

void le_msg_OpenSessionSync

(

le_msg_SessionRef_t

sessionRef

)

Synchronously open a session with a service. Blocks until the session is open or the attempt is rejected.

This function logs a fatal error and terminates the calling process if unsuccessful.

Note

Only clients open sessions. Servers' must patiently wait for clients to open sessions with them.

Warning

If the client and server do not agree on the maximum message size for the protocol, then an attempt to open a session between that client and server will result in a fatal error being logged and the client process being killed.

Parameters

[in]

sessionRef

Reference to the session.

void le_msg_ReleaseMsg

(

le_msg_MessageRef_t

msgRef

)

Releases a message object, decrementing its reference count. If the reference count has reached zero, the message object is deleted.

Parameters

[in]

msgRef

Reference to the message.

void le_msg_RequestResponse	(	le_msg_MessageRef_t	msgRef,
		le_msg_ResponseCallback_t	handlerFunc,
		void *	contextPtr
	)

Requests a response from a server by sending it a request. Doesn't block. Instead, provides a callback function to be called when the response arrives or the transaction terminates without a response (due to the session terminating or the server deleting the request without responding).

Note

• The thread attached to the session (i.e., thread created by the session) will trigger the callback from its main event loop. This means if that thread doesn't run its main event loop, it won't trigger the callback.
• Function can only be used on the client side of a session.

Parameters

[in]	msgRef	Reference to the request message.
[in]	handlerFunc	Function to be called when transaction done.
[in]	contextPtr	Opaque value to be passed to handler function.

le_msg_MessageRef_t le_msg_RequestSyncResponse

(

le_msg_MessageRef_t

msgRef

)

Requests a response from a server by sending it a request. Blocks until the response arrives or until the transaction terminates without a response (i.e., if the session terminates or the server deletes the request without responding).

Returns

Reference to the response message, or NULL if the transaction terminated without a response.

Note

• To prevent deadlocks, this function can only be used on the client side of a session. Servers can't use this function.
• To prevent race conditions, only the client thread attached to the session (the thread that created the session) is allowed to perform a synchronous request-response transaction.

Warning

• The calling (client) thread will be blocked until the server responds, so no other event handling will happen in that client thread until the response is received (or the server dies). This function should only be used when the server is certain to respond quickly enough to ensure that it will not cause any event response time deadlines to be missed by the client. Consider using le_msg_RequestResponse() instead.
• If this function is used when the client and server are in the same thread, then the message will be discarded and NULL will be returned. This is a deadlock prevention measure.

Parameters

[in]

msgRef

Reference to the request message.

void le_msg_Respond

(

le_msg_MessageRef_t

msgRef

)

Sends a response back to the client that send the request message.

Takes a reference to the request message. Copy the response payload (if any) into the same payload buffer that held the request payload, then call le_msg_Respond().

The messaging system will delete the message automatically when it's finished sending the response.

Note

Function can only be used on the server side of a session.

Parameters

[in]

msgRef

Reference to the request message.

void le_msg_Send

(

le_msg_MessageRef_t

msgRef

)

Sends a message. No response expected.

Parameters

[in]

msgRef

Reference to the message.

void le_msg_SetFd	(	le_msg_MessageRef_t	msgRef,
		int	fd
	)

Sets the file descriptor to be sent with this message.

This file descriptor will be closed when the message is sent (or when it is deleted without being sent).

At most one file descriptor is allowed to be sent per message.

Parameters

[in]	msgRef	Reference to the message.
[in]	fd	File descriptor.

void le_msg_SetServiceCloseHandler	(	le_msg_ServiceRef_t	serviceRef,
		le_msg_SessionEventHandler_t	handlerFunc,
		void *	contextPtr
	)

Registers a function to be called whenever one of this service's sessions is closed by the client.

Note

Server-only function.

Parameters

[in]	serviceRef	Reference to the service.
[in]	handlerFunc	Handler function.
[in]	contextPtr	Opaque pointer value to pass to handler.

void le_msg_SetServiceContextPtr	(	le_msg_ServiceRef_t	serviceRef,
		void *	contextPtr
	)

Associates an opaque context value (void pointer) with a given service that can be retrieved later using le_msg_GetServiceContextPtr().

Note

Server-only function.

Parameters

[in]	serviceRef	Reference to the service.
[in]	contextPtr	Opaque value to be returned by le_msg_GetServiceContextPtr().

void le_msg_SetServiceOpenHandler	(	le_msg_ServiceRef_t	serviceRef,
		le_msg_SessionEventHandler_t	handlerFunc,
		void *	contextPtr
	)

Registers a function to be called when clients open sessions with this service.

Note

Server-only function.

Parameters

[in]	serviceRef	Reference to the service.
[in]	handlerFunc	Handler function.
[in]	contextPtr	Opaque pointer value to pass to handler.

void le_msg_SetServiceRecvHandler	(	le_msg_ServiceRef_t	serviceRef,
		le_msg_ReceiveHandler_t	handlerFunc,
		void *	contextPtr
	)

Registers a function to be called when messages are received from clients via sessions that they have open with this service.

Note

Server-only function.

Parameters

[in]	serviceRef	Reference to the service.
[in]	handlerFunc	Handler function.
[in]	contextPtr	Opaque pointer value to pass to the handler.

void le_msg_SetSessionCloseHandler	(	le_msg_SessionRef_t	sessionRef,
		le_msg_SessionEventHandler_t	handlerFunc,
		void *	contextPtr
	)

Sets the handler callback function to be called when the session is closed from the other end. A local termination of the session will not trigger this callback.

The handler function will be called by the Legato event loop of the thread that created the session.

Note

• If this isn't set on the client side, the framework assumes the client is not designed to recover from the server terminating the session, and the client process will terminate if the session is terminated by the server.
• This is a client-only function. Servers are expected to use le_msg_SetServiceCloseHandler() instead.

Parameters

[in]	sessionRef	Reference to the session.
[in]	handlerFunc	Handler function.
[in]	contextPtr	Opaque pointer value to pass to handler.

void le_msg_SetSessionContextPtr	(	le_msg_SessionRef_t	sessionRef,
		void *	contextPtr
	)

Sets an opaque context value (void pointer) that can be retrieved from that session later using le_msg_GetSessionContextPtr().

Parameters

[in]	sessionRef	Reference to the session.
[in]	contextPtr	Opaque value to be returned by le_msg_GetSessionContextPtr().

void le_msg_SetSessionRecvHandler	(	le_msg_SessionRef_t	sessionRef,
		le_msg_ReceiveHandler_t	handlerFunc,
		void *	contextPtr
	)

Sets the receive handler callback function to be called when a non-response message arrives on this session.

The handler function will be called by the Legato event loop of the thread that created the session.

Note

This is a client-only function. Servers are expected to use le_msg_SetServiceRecvHandler() instead.

Parameters

[in]	sessionRef	Reference to the session.
[in]	handlerFunc	Handler function.
[in]	contextPtr	Opaque pointer value to pass to the handler.