le_messaging.h
Go to the documentation of this file.
46 * a server to deny service to other clients. Also, if a client started a blocking request-response53 * client-side and server-side interfaces are identified by name, but the names don't have to match118 * When the session opens, the Event Loop will call the "session open handler" call-back function133 * Before sending a message, the client must first allocate the message from the session's message145 * At this point, the client has handed off the message to the messaging system, and the messaging161 * If the client expects an immediate response from the server, and the client wants to block until164 * block all event handlers that share that thread. That's why le_msg_RequestSyncResponse() should187 * When a server sends a message to the client that is not a response to a request from the client,195 * The payload of a received message can be accessed using le_msg_GetPayloadPtr(), and the client231 * When the client is done using a service, it can close the session using le_msg_CloseSession().247 * automatically closed and deleted by the Legato framework, so there's no need to register process251 * notified when a session gets closed by the server. Servers often keep state on behalf of their252 * clients, and if the server closes the session (or if the system closes the session because the266 * @note If the client closes the session, the client-side session close handler will not be called,274 * (i.e., the thread that called le_msg_CreateSession()). That thread will then call any callbacks279 * To work around this, move the session creation to another thread that that uses the Legato event372 * -# Create a Service object using le_msg_CreateService(), passing in the protocol reference and374 * -# Call le_msg_SetServiceRecvHandler() to register a function to handle messages received from418 * the thread that registered those handlers (which must also be the same thread that created the445 * to that message by calling le_msg_Respond() on that message. le_msg_Respond() sends the message469 * Alternatively, the request payload structure and the response payload structure could be placed494 * @warning Of course, once you've started writing the response payload into the buffer, the request payload501 * through which the client sent it. A reference to the session can be retrieved from the message,503 * server's internal data structures that need to be cleaned up when the client closes the session556 * to ask to be notified when clients close sessions with a given service. This allows the server558 * (or when the system closes the session because the client died). The close handler is passed a590 * To work around this, you could move the service to another thread that that runs the Legato event644 * solve the age-old problem of coordinating the start-up sequence of processes that interact with645 * each other. Far too often, the start-up sequence of multiple interacting processes is addressed647 * waste a lot of CPU cycles and battery power, slow down start-up, and (in the case of arbitrary650 * In Legato, a messaging client can attempt to open a session before the server process has even654 * In this way, clients are guaranteed to wait for the servers they use, without the inefficiency657 * a session with the server, the client is allowed to do that work in parallel with the start-up663 * Message buffer memory is allocated and controlled behind the scenes, inside the Messaging API.687 * server-side interface (service). The binding thereby provides configuration of both routing and690 * Neither the client-side nor the server-side IPC sockets are named. Therefore, no process other692 * connections to the appropriate server based on the binding configuration of the client's interface.762 * @warning DO NOT SEND DIRECTORY FILE DESCRIPTORS. They can be exploited and used to break out of784 * That would reduce the amount of code required in the common case. However, we chose to require785 * that the client release the message explicitly in all cases, because the consequences of using821 //--------------------------------------------------------------------------------------------------825 //--------------------------------------------------------------------------------------------------828 //--------------------------------------------------------------------------------------------------832 //--------------------------------------------------------------------------------------------------835 //--------------------------------------------------------------------------------------------------839 //--------------------------------------------------------------------------------------------------842 //--------------------------------------------------------------------------------------------------846 //--------------------------------------------------------------------------------------------------849 //--------------------------------------------------------------------------------------------------853 //--------------------------------------------------------------------------------------------------856 //--------------------------------------------------------------------------------------------------860 //--------------------------------------------------------------------------------------------------863 //--------------------------------------------------------------------------------------------------868 //--------------------------------------------------------------------------------------------------871 //--------------------------------------------------------------------------------------------------882 //--------------------------------------------------------------------------------------------------884 (890 //--------------------------------------------------------------------------------------------------901 //--------------------------------------------------------------------------------------------------903 (909 //--------------------------------------------------------------------------------------------------921 //--------------------------------------------------------------------------------------------------923 (933 //--------------------------------------------------------------------------------------------------939 //--------------------------------------------------------------------------------------------------947 //--------------------------------------------------------------------------------------------------953 //--------------------------------------------------------------------------------------------------960 //--------------------------------------------------------------------------------------------------966 //--------------------------------------------------------------------------------------------------977 //--------------------------------------------------------------------------------------------------988 //--------------------------------------------------------------------------------------------------996 //--------------------------------------------------------------------------------------------------998 * Sets an opaque context value (void pointer) that can be retrieved from that session later using1001 //--------------------------------------------------------------------------------------------------1010 //--------------------------------------------------------------------------------------------------1018 //--------------------------------------------------------------------------------------------------1025 //--------------------------------------------------------------------------------------------------1034 //--------------------------------------------------------------------------------------------------1041 //--------------------------------------------------------------------------------------------------1052 //--------------------------------------------------------------------------------------------------1061 //--------------------------------------------------------------------------------------------------1073 * - This is a client-only function. Servers are expected to use le_msg_AddServiceCloseHandler()1076 //--------------------------------------------------------------------------------------------------1085 //--------------------------------------------------------------------------------------------------1096 //--------------------------------------------------------------------------------------------------1106 //--------------------------------------------------------------------------------------------------1118 //--------------------------------------------------------------------------------------------------1125 //--------------------------------------------------------------------------------------------------1127 * Synchronously open a session with a service. Does not wait for the session to become available1140 * - LE_NOT_FOUND if the server is not currently offering the service to which the client is bound.1141 * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).1150 //--------------------------------------------------------------------------------------------------1157 //--------------------------------------------------------------------------------------------------1161 //--------------------------------------------------------------------------------------------------1168 //--------------------------------------------------------------------------------------------------1174 //--------------------------------------------------------------------------------------------------1181 //--------------------------------------------------------------------------------------------------1187 //--------------------------------------------------------------------------------------------------1193 //--------------------------------------------------------------------------------------------------1202 //--------------------------------------------------------------------------------------------------1209 //--------------------------------------------------------------------------------------------------1218 //--------------------------------------------------------------------------------------------------1225 //--------------------------------------------------------------------------------------------------1234 //--------------------------------------------------------------------------------------------------1248 //--------------------------------------------------------------------------------------------------1259 //--------------------------------------------------------------------------------------------------1266 //--------------------------------------------------------------------------------------------------1270 //--------------------------------------------------------------------------------------------------1277 //--------------------------------------------------------------------------------------------------1279 * Releases a message object, decrementing its reference count. If the reference count has reached1282 //--------------------------------------------------------------------------------------------------1289 //--------------------------------------------------------------------------------------------------1300 //--------------------------------------------------------------------------------------------------1307 //--------------------------------------------------------------------------------------------------1315 //--------------------------------------------------------------------------------------------------1322 //--------------------------------------------------------------------------------------------------1328 //--------------------------------------------------------------------------------------------------1335 //--------------------------------------------------------------------------------------------------1344 //--------------------------------------------------------------------------------------------------1352 //--------------------------------------------------------------------------------------------------1356 * @return The file descriptor, or -1 if no file descriptor was sent with this message or if the1359 //--------------------------------------------------------------------------------------------------1366 //--------------------------------------------------------------------------------------------------1370 //--------------------------------------------------------------------------------------------------1377 //--------------------------------------------------------------------------------------------------1383 //--------------------------------------------------------------------------------------------------1390 //--------------------------------------------------------------------------------------------------1403 //--------------------------------------------------------------------------------------------------1412 //--------------------------------------------------------------------------------------------------1439 //--------------------------------------------------------------------------------------------------1446 //--------------------------------------------------------------------------------------------------1458 //--------------------------------------------------------------------------------------------------1469 //--------------------------------------------------------------------------------------------------1475 //--------------------------------------------------------------------------------------------------1483 //--------------------------------------------------------------------------------------------------1489 //--------------------------------------------------------------------------------------------------1495 //--------------------------------------------------------------------------------------------------1501 //--------------------------------------------------------------------------------------------------1509 //--------------------------------------------------------------------------------------------------1516 //--------------------------------------------------------------------------------------------------1524 //--------------------------------------------------------------------------------------------------1531 //--------------------------------------------------------------------------------------------------1538 //--------------------------------------------------------------------------------------------------1545 //--------------------------------------------------------------------------------------------------1554 //--------------------------------------------------------------------------------------------------1561 //--------------------------------------------------------------------------------------------------1571 //--------------------------------------------------------------------------------------------------1581 //--------------------------------------------------------------------------------------------------1588 //--------------------------------------------------------------------------------------------------1594 //--------------------------------------------------------------------------------------------------1601 //--------------------------------------------------------------------------------------------------1608 //--------------------------------------------------------------------------------------------------1615 //--------------------------------------------------------------------------------------------------1623 //--------------------------------------------------------------------------------------------------1630 //--------------------------------------------------------------------------------------------------1636 //--------------------------------------------------------------------------------------------------1643 //--------------------------------------------------------------------------------------------------1648 * @return Reference to the message being handled, or NULL if no Service message receive handler1651 //--------------------------------------------------------------------------------------------------1658 //--------------------------------------------------------------------------------------------------1663 * - if the caller is not running a server-side IPC function, kills the caller (doesn't return).1665 //--------------------------------------------------------------------------------------------------le_msg_MessageRef_t le_msg_GetServiceRxMsg(void)void le_msg_AddRef(le_msg_MessageRef_t msgRef)le_msg_ProtocolRef_t le_msg_GetProtocolRef(const char *protocolId, size_t largestMsgSize)bool le_msg_NeedsResponse(le_msg_MessageRef_t msgRef)size_t le_msg_GetProtocolMaxMsgSize(le_msg_ProtocolRef_t protocolRef)void le_msg_ReleaseMsg(le_msg_MessageRef_t msgRef)le_result_t le_msg_GetClientUserCreds(le_msg_SessionRef_t sessionRef, uid_t *userIdPtr, pid_t *processIdPtr)void * le_msg_GetServiceContextPtr(le_msg_ServiceRef_t serviceRef)void le_msg_SetServiceRecvHandler(le_msg_ServiceRef_t serviceRef, le_msg_ReceiveHandler_t handlerFunc, void *contextPtr)void * le_msg_GetSessionContextPtr(le_msg_SessionRef_t sessionRef)void(* le_msg_SessionEventHandler_t)(le_msg_SessionRef_t sessionRef, void *contextPtr)Definition: le_messaging.h:884le_result_t le_msg_TryOpenSessionSync(le_msg_SessionRef_t sessionRef)void le_msg_AdvertiseService(le_msg_ServiceRef_t serviceRef)void le_msg_DeleteSession(le_msg_SessionRef_t sessionRef)const char * le_msg_GetProtocolIdStr(le_msg_ProtocolRef_t protocolRef)void le_msg_SetSessionRecvHandler(le_msg_SessionRef_t sessionRef, le_msg_ReceiveHandler_t handlerFunc, void *contextPtr)void * le_msg_GetPayloadPtr(le_msg_MessageRef_t msgRef)const char * le_msg_GetInterfaceName(le_msg_InterfaceRef_t interfaceRef)struct le_msg_ClientInterface * le_msg_ClientInterfaceRef_tDefinition: le_messaging.h:847size_t le_msg_GetMaxPayloadSize(le_msg_MessageRef_t msgRef)le_msg_SessionRef_t le_msg_GetSession(le_msg_MessageRef_t msgRef)void le_msg_SetFd(le_msg_MessageRef_t msgRef, int fd)void(* le_msg_ReceiveHandler_t)(le_msg_MessageRef_t msgRef, void *contextPtr)Definition: le_messaging.h:903void le_msg_Send(le_msg_MessageRef_t msgRef)le_msg_ProtocolRef_t le_msg_GetInterfaceProtocol(le_msg_InterfaceRef_t interfaceRef)struct le_msg_SessionEventHandler * le_msg_SessionEventHandlerRef_tDefinition: le_messaging.h:869le_msg_SessionRef_t le_msg_CreateSession(le_msg_ProtocolRef_t protocolRef, const char *interfaceName)void le_msg_CloseSession(le_msg_SessionRef_t sessionRef)void le_msg_DeleteService(le_msg_ServiceRef_t serviceRef)le_msg_ServiceRef_t le_msg_CreateService(le_msg_ProtocolRef_t protocolRef, const char *interfaceName)le_msg_InterfaceRef_t le_msg_GetSessionInterface(le_msg_SessionRef_t sessionRef)le_msg_MessageRef_t le_msg_CreateMsg(le_msg_SessionRef_t sessionRef)le_msg_SessionEventHandlerRef_t le_msg_AddServiceOpenHandler(le_msg_ServiceRef_t serviceRef, le_msg_SessionEventHandler_t handlerFunc, void *contextPtr)int le_msg_GetFd(le_msg_MessageRef_t msgRef)void le_msg_RequestResponse(le_msg_MessageRef_t msgRef, le_msg_ResponseCallback_t handlerFunc, void *contextPtr)void le_msg_RemoveServiceHandler(le_msg_SessionEventHandlerRef_t handlerRef)void le_msg_HideService(le_msg_ServiceRef_t serviceRef)void le_msg_SetSessionContextPtr(le_msg_SessionRef_t sessionRef, void *contextPtr)le_result_t le_msg_GetClientProcessId(le_msg_SessionRef_t sessionRef, pid_t *processIdPtr)void le_msg_OpenSession(le_msg_SessionRef_t sessionRef, le_msg_SessionEventHandler_t callbackFunc, void *contextPtr)void le_msg_SetServiceContextPtr(le_msg_ServiceRef_t serviceRef, void *contextPtr)le_msg_ProtocolRef_t le_msg_GetSessionProtocol(le_msg_SessionRef_t sessionRef)void le_msg_Respond(le_msg_MessageRef_t msgRef)void(* le_msg_ResponseCallback_t)(le_msg_MessageRef_t msgRef, void *contextPtr)Definition: le_messaging.h:923le_result_t le_msg_GetClientUserId(le_msg_SessionRef_t sessionRef, uid_t *userIdPtr)le_msg_MessageRef_t le_msg_RequestSyncResponse(le_msg_MessageRef_t msgRef)void le_msg_OpenSessionSync(le_msg_SessionRef_t sessionRef)le_msg_SessionEventHandlerRef_t le_msg_AddServiceCloseHandler(le_msg_ServiceRef_t serviceRef, le_msg_SessionEventHandler_t handlerFunc, void *contextPtr)void le_msg_SetSessionCloseHandler(le_msg_SessionRef_t sessionRef, le_msg_SessionEventHandler_t handlerFunc, void *contextPtr)