le_messaging.h File Reference

#include "le_semaphore.h"

Go to the source code of this file.

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

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_MessageRef_t le_msg_GetServiceRxMsg(void)
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]msgRefReference 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]serviceRefReference to the service.
[in]handlerFuncHandler function.
[in]contextPtrOpaque 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]serviceRefReference to the service.
[in]handlerFuncHandler function.
[in]contextPtrOpaque 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]serviceRefReference to the service.

◆ le_msg_CloseSession()

void le_msg_CloseSession ( le_msg_SessionRef_t  sessionRef)

Terminates a session.

Parameters
[in]sessionRefReference 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]sessionRefReference 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]servicePtrReference 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]sessionRefReference 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]protocolRefReference to the protocol to be used.
[in]interfaceNameServer-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]protocolRefReference to the protocol to be used.
[in]interfaceNameName 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]serviceRefReference 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]sessionRefReference 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]sessionRefReference to the session.
[out]processIdPtrPtr 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]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_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]sessionRefReference to the session.
[out]userIdPtrPtr 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]msgRefReference 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]interfaceRefReference 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]interfaceRefReference 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]msgRefReference 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]msgRefReference 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]protocolRefReference 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]protocolRefReference 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]protocolIdString uniquely identifying the the protocol and version.
[in]largestMsgSizeSize (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]serviceRefReference 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]msgRefReference 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]sessionRefReference to the session.
[out]handlerFuncHandler function.
[out]contextPtrOpaque pointer value to pass to the handler.

◆ le_msg_GetSessionContextPtr()

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_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]sessionRefReference 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]sessionRefReference 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]serviceRefReference 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]msgRefReference 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]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.

◆ 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]sessionRefReference 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]msgRefReference 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]handlerRefReference 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]msgRefReference to the request message.
[in]handlerFuncFunction to be called when transaction done.
[in]contextPtrOpaque 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]msgRefReference 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]msgRefReference to the request message.

◆ le_msg_Send()

void le_msg_Send ( le_msg_MessageRef_t  msgRef)

Sends a message. No response expected.

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

◆ le_msg_SetSessionContextPtr()

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

◆ 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]sessionRefReference to the session.
[in]handlerFuncHandler function.
[in]contextPtrOpaque 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]sessionRefReference to the session.