#include "le_semaphore.h"

Data Structures
struct	le_msg_ServiceRef_t

struct	le_msg_MessageRef_t

struct	le_msg_LocalReceiver_t

struct	le_msg_LocalService_t

struct	le_msg_LocalMessage_t

Macros
#define	LE_MSG_LOCAL_HEADER_SIZE sizeof(le_msg_LocalMessage_t)

#define	LE_KILL_CLIENT(formatString, ...)

Typedefs
typedef struct le_msg_Protocol *	le_msg_ProtocolRef_t

typedef struct le_msg_Interface *	le_msg_InterfaceRef_t

typedef struct le_msg_ClientInterface *	le_msg_ClientInterfaceRef_t

typedef struct le_msg_Session *	le_msg_SessionRef_t

typedef struct le_msg_SessionEventHandler *	le_msg_SessionEventHandlerRef_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_FULL_API le_msg_ProtocolRef_t	le_msg_GetProtocolRef (const char *protocolId, size_t largestMsgSize)

LE_FULL_API const char *	le_msg_GetProtocolIdStr (le_msg_ProtocolRef_t protocolRef)

LE_FULL_API size_t	le_msg_GetProtocolMaxMsgSize (le_msg_ProtocolRef_t protocolRef)

LE_FULL_API le_msg_SessionRef_t	le_msg_CreateSession (le_msg_ProtocolRef_t protocolRef, const char *interfaceName)

le_msg_SessionRef_t	le_msg_CreateLocalSession (le_msg_LocalService_t *servicePtr)

LE_FULL_API void	le_msg_SetSessionContextPtr (le_msg_SessionRef_t sessionRef, void *contextPtr)

LE_FULL_API 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)

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

void	le_msg_GetSessionCloseHandler (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)

le_result_t	le_msg_TryOpenSessionSync (le_msg_SessionRef_t sessionRef)

void	le_msg_CloseSession (le_msg_SessionRef_t sessionRef)

void	le_msg_CloseSessionLocked (le_msg_SessionRef_t sessionRef)

LE_FULL_API le_msg_ProtocolRef_t	le_msg_GetSessionProtocol (le_msg_SessionRef_t sessionRef)

LE_FULL_API le_msg_InterfaceRef_t	le_msg_GetSessionInterface (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_FULL_API le_msg_ServiceRef_t	le_msg_CreateService (le_msg_ProtocolRef_t protocolRef, const char *interfaceName)

le_msg_ServiceRef_t	le_msg_InitLocalService (le_msg_LocalService_t servicePtr, const char serviceNameStr, le_mem_PoolRef_t messagingPoolRef)

LE_FULL_API void	le_msg_DeleteService (le_msg_ServiceRef_t serviceRef)

LE_FULL_API le_msg_SessionEventHandlerRef_t	le_msg_AddServiceOpenHandler (le_msg_ServiceRef_t serviceRef, le_msg_SessionEventHandler_t handlerFunc, void *contextPtr)

le_msg_SessionEventHandlerRef_t	le_msg_AddServiceCloseHandler (le_msg_ServiceRef_t serviceRef, le_msg_SessionEventHandler_t handlerFunc, void *contextPtr)

LE_FULL_API void	le_msg_RemoveServiceHandler (le_msg_SessionEventHandlerRef_t handlerRef)

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

LE_FULL_API void	le_msg_SetServiceContextPtr (le_msg_ServiceRef_t serviceRef, void *contextPtr)

LE_FULL_API void *	le_msg_GetServiceContextPtr (le_msg_ServiceRef_t serviceRef)

void	le_msg_AdvertiseService (le_msg_ServiceRef_t serviceRef)

LE_FULL_API void	le_msg_HideService (le_msg_ServiceRef_t serviceRef)

LE_FULL_API const char *	le_msg_GetInterfaceName (le_msg_InterfaceRef_t interfaceRef)

LE_FULL_API le_msg_ProtocolRef_t	le_msg_GetInterfaceProtocol (le_msg_InterfaceRef_t interfaceRef)

le_msg_MessageRef_t	le_msg_GetServiceRxMsg (void)

Detailed Description

Legato Low-level Messaging API include file.

Copyright (C) Sierra Wireless Inc.

Macro Definition Documentation

◆ LE_KILL_CLIENT

#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)); \
}
le_msg_GetServiceRxMsg
le_msg_MessageRef_t le_msg_GetServiceRxMsg(void)
le_msg_GetSession
le_msg_SessionRef_t le_msg_GetSession(le_msg_MessageRef_t 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).

◆ LE_MSG_LOCAL_HEADER_SIZE

#define LE_MSG_LOCAL_HEADER_SIZE sizeof(le_msg_LocalMessage_t)

Size of local message header (needs to be added to size of message in local message pools).

Typedef Documentation

◆ le_msg_ClientInterfaceRef_t

typedef struct le_msg_ClientInterface* le_msg_ClientInterfaceRef_t

Reference to a client's service instance.

◆ le_msg_InterfaceRef_t

typedef struct le_msg_Interface* le_msg_InterfaceRef_t

Reference to an interface's service instance.

◆ le_msg_ProtocolRef_t

typedef struct le_msg_Protocol* le_msg_ProtocolRef_t

Reference to a protocol.

◆ le_msg_ReceiveHandler_t

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're finished with it.
contextPtr	[in] Opaque contextPtr value provided when the handler was registered.

◆ le_msg_ResponseCallback_t

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're finished with it.
contextPtr	[in] Opaque contextPtr value passed to le_msg_RequestResponse().

◆ le_msg_SessionEventHandler_t

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_AddServiceOpenHandler(), and le_msg_AddServiceCloseHandler().

Parameters

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

◆ le_msg_SessionEventHandlerRef_t

typedef struct le_msg_SessionEventHandler* le_msg_SessionEventHandlerRef_t

Reference to a handler (call-back) function for events that can occur on a service (such as opening and closing of sessions and receipt of messages).

◆ le_msg_SessionRef_t

typedef struct le_msg_Session* le_msg_SessionRef_t

Reference to a client-server session.

Function Documentation

◆ le_msg_AddRef()

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.

◆ le_msg_AddServiceCloseHandler()

le_msg_SessionEventHandlerRef_t le_msg_AddServiceCloseHandler	(	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.

◆ le_msg_AddServiceOpenHandler()

LE_FULL_API le_msg_SessionEventHandlerRef_t le_msg_AddServiceOpenHandler	(	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.

◆ le_msg_AdvertiseService()

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.

◆ le_msg_CloseSession()

void le_msg_CloseSession ( le_msg_SessionRef_t sessionRef )

Terminates a session.

Parameters

[in] sessionRef Reference to the session.

◆ le_msg_CloseSessionLocked()

void le_msg_CloseSessionLocked ( le_msg_SessionRef_t sessionRef )

Terminates a session, already having acquired the Mutex lock.

Parameters

[in] sessionRef Reference to the session.

◆ le_msg_CreateLocalSession()

le_msg_SessionRef_t le_msg_CreateLocalSession ( le_msg_LocalService_t * servicePtr )

Create a session that will always use message boxes to talk to a service in the same process space.

Returns: Session reference.

Parameters

[in] servicePtr Reference to the service.

◆ le_msg_CreateMsg()

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.
In full API this can be called by either client or server, otherwise it can only be called by the client.

Parameters

[in] sessionRef Reference to the session.

◆ le_msg_CreateService()

LE_FULL_API le_msg_ServiceRef_t le_msg_CreateService	(	le_msg_ProtocolRef_t	protocolRef,
		const char *	interfaceName
	)

Creates a service that is accessible using a protocol.

Mailbox services should be created statically.

Returns: Service reference.

Parameters

[in]	protocolRef	Reference to the protocol to be used.
[in]	interfaceName	Server-side interface name.

◆ le_msg_CreateSession()

LE_FULL_API le_msg_SessionRef_t le_msg_CreateSession	(	le_msg_ProtocolRef_t	protocolRef,
		const char *	interfaceName
	)

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

Note: This doesn't 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]	interfaceName	Name of the client-side interface.

◆ le_msg_DeleteService()

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

◆ le_msg_DeleteSession()

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 session 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_msg_GetClientProcessId()

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_msg_GetClientUserCreds()

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

Fetches the user credentials 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_msg_GetClientUserId()

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.

◆ le_msg_GetFd()

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.

◆ le_msg_GetInterfaceName()

LE_FULL_API const char* le_msg_GetInterfaceName ( le_msg_InterfaceRef_t interfaceRef )

Fetches a pointer to the name of an interface.

Returns: Pointer to a null-terminated string.

Warning: Pointer returned will remain valid only until the interface is deleted.

Parameters

[in] interfaceRef Reference to the interface.

◆ le_msg_GetInterfaceProtocol()

LE_FULL_API le_msg_ProtocolRef_t le_msg_GetInterfaceProtocol ( le_msg_InterfaceRef_t interfaceRef )

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

Returns: Protocol reference.

Parameters

[in] interfaceRef Reference to the interface.

◆ le_msg_GetMaxPayloadSize()

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.

◆ le_msg_GetPayloadPtr()

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.

◆ le_msg_GetProtocolIdStr()

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

◆ le_msg_GetProtocolMaxMsgSize()

LE_FULL_API 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_GetProtocolRef()

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

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.

◆ le_msg_GetServiceContextPtr()

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

◆ le_msg_GetServiceRxMsg()

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_GetSession()

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.

◆ le_msg_GetSessionCloseHandler()

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

Gets the handler callback function to be called when the session is closed from the other end.

Parameters

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

◆ le_msg_GetSessionContextPtr()

LE_FULL_API 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_GetSessionInterface()

LE_FULL_API le_msg_InterfaceRef_t le_msg_GetSessionInterface ( le_msg_SessionRef_t sessionRef )

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

Returns: Reference to the interface.

Parameters

[in] sessionRef Reference to the session.

◆ le_msg_GetSessionProtocol()

LE_FULL_API 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_HideService()

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

◆ le_msg_InitLocalService()

le_msg_ServiceRef_t le_msg_InitLocalService	(	le_msg_LocalService_t *	servicePtr,
		const char *	serviceNameStr,
		le_mem_PoolRef_t	messagingPoolRef
	)

Initialize a mailbox service.

This must be called before any client can connect to the service, for example in COMPONENT_INIT before any other threads are created.

◆ le_msg_NeedsResponse()

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 doesn't need to be responded to, and should be disposed of using le_msg_ReleaseMsg() when it's no longer needed.

Parameters

[in] msgRef Reference to the message.

◆ le_msg_OpenSession()

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.

Asynchronous sessions are not supported by mailbox sessions.

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, a fatal error will be logged and the client process will be 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_msg_OpenSessionSync()

void le_msg_OpenSessionSync ( le_msg_SessionRef_t sessionRef )

Synchronously open a session with a service. Blocks until the session is open.

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, a fatal error will be logged and the client process will be killed.

Parameters

[in] sessionRef Reference to the session.

◆ le_msg_ReleaseMsg()

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.

◆ le_msg_RemoveServiceHandler()

LE_FULL_API void le_msg_RemoveServiceHandler ( le_msg_SessionEventHandlerRef_t handlerRef )

Remove a function previously registered by le_msg_AddServiceOpenHandler or le_msg_AddServiceCloseHandler.

Note: This is a server-only function.

Parameters

[in] handlerRef Reference to a previously call of le_msg_AddServiceCloseHandler()

◆ le_msg_RequestResponse()

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

Async response not supported with mailbox API

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_RequestSyncResponse()

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.

◆ le_msg_Respond()

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.

◆ le_msg_Send()

void le_msg_Send ( le_msg_MessageRef_t msgRef )

Sends a message. No response expected.

Parameters

[in] msgRef Reference to the message.

◆ le_msg_SetFd()

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's 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.

◆ le_msg_SetServiceContextPtr()

LE_FULL_API 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().

◆ le_msg_SetServiceRecvHandler()

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.

◆ le_msg_SetSessionCloseHandler()

LE_FULL_API 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_AddServiceCloseHandler() instead.

Parameters

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

◆ le_msg_SetSessionContextPtr()

LE_FULL_API 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().

◆ le_msg_SetSessionRecvHandler()

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.

◆ le_msg_TryOpenSessionSync()

le_result_t le_msg_TryOpenSessionSync ( le_msg_SessionRef_t sessionRef )

Synchronously open a session with a service. Does not wait for the session to become available if not available..

le_msg_TryOpenSessionSync() differs from le_msg_OpenSessionSync() in that le_msg_TryOpenSessionSync() will not wait for a server session to become available if it's not already available at the time of the call. That is, if the client's interface is not bound to any service, or if the service that it's bound to is not currently advertised by the server, then le_msg_TryOpenSessionSync() will return an error code, while le_msg_OpenSessionSync() will wait until the binding is created or the server advertises the service (or both).

Returns

LE_OK if the session was successfully opened.
LE_NOT_FOUND if the server is not currently offering the service to which the client is bound.
LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
LE_COMM_ERROR if the Service Directory cannot be reached.

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, a fatal error will be logged and the client process will be killed.

Parameters

[in] sessionRef Reference to the session.

le_messaging.h File Reference

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ LE_KILL_CLIENT

◆ LE_MSG_LOCAL_HEADER_SIZE

Typedef Documentation

◆ le_msg_ClientInterfaceRef_t

◆ le_msg_InterfaceRef_t

◆ le_msg_ProtocolRef_t

◆ le_msg_ReceiveHandler_t

◆ le_msg_ResponseCallback_t

◆ le_msg_SessionEventHandler_t

◆ le_msg_SessionEventHandlerRef_t

◆ le_msg_SessionRef_t

Function Documentation

◆ le_msg_AddRef()

◆ le_msg_AddServiceCloseHandler()

◆ le_msg_AddServiceOpenHandler()

◆ le_msg_AdvertiseService()

◆ le_msg_CloseSession()

◆ le_msg_CloseSessionLocked()

◆ le_msg_CreateLocalSession()

◆ le_msg_CreateMsg()

◆ le_msg_CreateService()

◆ le_msg_CreateSession()

◆ le_msg_DeleteService()

◆ le_msg_DeleteSession()

◆ le_msg_GetClientProcessId()

◆ le_msg_GetClientUserCreds()

◆ le_msg_GetClientUserId()

◆ le_msg_GetFd()

◆ le_msg_GetInterfaceName()

◆ le_msg_GetInterfaceProtocol()

◆ le_msg_GetMaxPayloadSize()

◆ le_msg_GetPayloadPtr()

◆ le_msg_GetProtocolIdStr()

◆ le_msg_GetProtocolMaxMsgSize()

◆ le_msg_GetProtocolRef()

◆ le_msg_GetServiceContextPtr()

◆ le_msg_GetServiceRxMsg()

◆ le_msg_GetSession()

◆ le_msg_GetSessionCloseHandler()

◆ le_msg_GetSessionContextPtr()

◆ le_msg_GetSessionInterface()

◆ le_msg_GetSessionProtocol()

◆ le_msg_HideService()

◆ le_msg_InitLocalService()

◆ le_msg_NeedsResponse()

◆ le_msg_OpenSession()

◆ le_msg_OpenSessionSync()

◆ le_msg_ReleaseMsg()

◆ le_msg_RemoveServiceHandler()

◆ le_msg_RequestResponse()

◆ le_msg_RequestSyncResponse()

◆ le_msg_Respond()

◆ le_msg_Send()

◆ le_msg_SetFd()

◆ le_msg_SetServiceContextPtr()

◆ le_msg_SetServiceRecvHandler()

◆ le_msg_SetSessionCloseHandler()

◆ le_msg_SetSessionContextPtr()

◆ le_msg_SetSessionRecvHandler()

◆ le_msg_TryOpenSessionSync()