All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
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_FATAL_IF(msgRef == NULL, formatString, ##__VA_ARGS__); \
LE_EMERG(formatString, ##__VA_ARGS__); \
}
le_msg_MessageRef_t le_msg_GetServiceRxMsg(void)
le_msg_SessionRef_t le_msg_GetSession(le_msg_MessageRef_t msgRef)
void le_msg_CloseSession(le_msg_SessionRef_t sessionRef)
#define LE_EMERG(formatString,...)
Emergency. A fatal error has occurred. A process is being terminated.
Definition: le_log.h:445
#define LE_FATAL_IF(condition, formatString,...)
Definition: le_log.h:501
struct le_msg_Message * le_msg_MessageRef_t
Definition: le_messaging.h:841

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]msgRefReference 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]serviceRefReference to the service.
void le_msg_CloseSession ( le_msg_SessionRef_t  sessionRef)

Terminates a session.

Parameters
[in]sessionRefReference 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]sessionRefReference 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]protocolRefReference to the protocol to be used.
[in]serviceNameService 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]protocolRefReference to the protocol to be used.
[in]serviceNameName 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]serviceRefReference 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]sessionRefReference 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]sessionRefReference to the session.
[out]processIdPtrPtr 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]sessionRefReference to the session.
[out]userIdPtrPtr to where the uid is to be stored on success.
[out]processIdPtrPtr 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]sessionRefReference to the session.
[out]userIdPtrPtr 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]msgRefReference 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]msgRefReference 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]msgRefReference 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]protocolRefReference 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]protocolRefReference 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]protocolIdString uniquely identifying the the protocol and version.
[in]largestMsgSizeSize (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]serviceRefReference to the service.
[out]handlerFuncHandler function.
[out]contextPtrOpaque 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]serviceRefReference 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]serviceRefReference 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]serviceRefReference to the service.
[out]handlerFuncHandler function.
[out]contextPtrOpaque 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]serviceRefReference 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]msgRefReference 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]sessionRefReference 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]sessionRefReference 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]sessionRefReference 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]serviceRefReference 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]msgRefReference 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]sessionRefReference to the session.
[in]callbackFuncFunction to be called when open. NULL if no notification is needed.
[in]contextPtrOpaque 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]sessionRefReference 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]msgRefReference 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]msgRefReference to the request message.
[in]handlerFuncFunction to be called when transaction done.
[in]contextPtrOpaque 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]msgRefReference 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]msgRefReference to the request message.
void le_msg_Send ( le_msg_MessageRef_t  msgRef)

Sends a message. No response expected.

Parameters
[in]msgRefReference 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]msgRefReference to the message.
[in]fdFile 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]serviceRefReference to the service.
[in]handlerFuncHandler function.
[in]contextPtrOpaque 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]serviceRefReference to the service.
[in]contextPtrOpaque 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]serviceRefReference to the service.
[in]handlerFuncHandler function.
[in]contextPtrOpaque 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]serviceRefReference to the service.
[in]handlerFuncHandler function.
[in]contextPtrOpaque 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]sessionRefReference to the session.
[in]handlerFuncHandler function.
[in]contextPtrOpaque 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]sessionRefReference to the session.
[in]contextPtrOpaque 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]sessionRefReference to the session.
[in]handlerFuncHandler function.
[in]contextPtrOpaque pointer value to pass to the handler.