Defines
#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)
le_result_t	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_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_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_SetServiceCloseHandler (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.

Define 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_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.

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_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.

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.

le_result_t 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.

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, 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.

Returns:: LE_OK if successful. LE_NOT_PERMITTED if permission to access the service has been denied. LE_COMM_ERROR if failed to communicate with the Service Directory.

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_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.

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation