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.766 * @warning DO NOT SEND DIRECTORY FILE DESCRIPTORS. That can be exploited to break out of chroot()788 * That would reduce the amount of code required in the common case. However, we chose to require789 * that the client release the message explicitly in all cases, because the consequences of using825 //--------------------------------------------------------------------------------------------------829 //--------------------------------------------------------------------------------------------------832 //--------------------------------------------------------------------------------------------------836 //--------------------------------------------------------------------------------------------------839 //--------------------------------------------------------------------------------------------------843 //--------------------------------------------------------------------------------------------------846 //--------------------------------------------------------------------------------------------------850 //--------------------------------------------------------------------------------------------------853 //--------------------------------------------------------------------------------------------------857 //--------------------------------------------------------------------------------------------------860 //--------------------------------------------------------------------------------------------------864 //--------------------------------------------------------------------------------------------------867 //--------------------------------------------------------------------------------------------------872 //--------------------------------------------------------------------------------------------------875 //--------------------------------------------------------------------------------------------------886 //--------------------------------------------------------------------------------------------------888 (894 //--------------------------------------------------------------------------------------------------905 //--------------------------------------------------------------------------------------------------907 (913 //--------------------------------------------------------------------------------------------------925 //--------------------------------------------------------------------------------------------------927 (937 //--------------------------------------------------------------------------------------------------943 //--------------------------------------------------------------------------------------------------951 //--------------------------------------------------------------------------------------------------957 //--------------------------------------------------------------------------------------------------964 //--------------------------------------------------------------------------------------------------970 //--------------------------------------------------------------------------------------------------981 //--------------------------------------------------------------------------------------------------992 //--------------------------------------------------------------------------------------------------1000 //--------------------------------------------------------------------------------------------------1002 * Sets an opaque context value (void pointer) that can be retrieved from that session later using1005 //--------------------------------------------------------------------------------------------------1014 //--------------------------------------------------------------------------------------------------1022 //--------------------------------------------------------------------------------------------------1029 //--------------------------------------------------------------------------------------------------1038 //--------------------------------------------------------------------------------------------------1045 //--------------------------------------------------------------------------------------------------1056 //--------------------------------------------------------------------------------------------------1065 //--------------------------------------------------------------------------------------------------1077 * - This is a client-only function. Servers are expected to use le_msg_AddServiceCloseHandler()1080 //--------------------------------------------------------------------------------------------------1089 //--------------------------------------------------------------------------------------------------1100 //--------------------------------------------------------------------------------------------------1110 //--------------------------------------------------------------------------------------------------1122 //--------------------------------------------------------------------------------------------------1129 //--------------------------------------------------------------------------------------------------1131 * Synchronously open a session with a service. Does not wait for the session to become available1144 * - LE_NOT_FOUND if the server is not currently offering the service to which the client is bound.1145 * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).1154 //--------------------------------------------------------------------------------------------------1161 //--------------------------------------------------------------------------------------------------1165 //--------------------------------------------------------------------------------------------------1172 //--------------------------------------------------------------------------------------------------1178 //--------------------------------------------------------------------------------------------------1185 //--------------------------------------------------------------------------------------------------1191 //--------------------------------------------------------------------------------------------------1197 //--------------------------------------------------------------------------------------------------1206 //--------------------------------------------------------------------------------------------------1213 //--------------------------------------------------------------------------------------------------1222 //--------------------------------------------------------------------------------------------------1229 //--------------------------------------------------------------------------------------------------1238 //--------------------------------------------------------------------------------------------------1252 //--------------------------------------------------------------------------------------------------1263 //--------------------------------------------------------------------------------------------------1270 //--------------------------------------------------------------------------------------------------1274 //--------------------------------------------------------------------------------------------------1281 //--------------------------------------------------------------------------------------------------1283 * Releases a message object, decrementing its reference count. If the reference count has reached1286 //--------------------------------------------------------------------------------------------------1293 //--------------------------------------------------------------------------------------------------1304 //--------------------------------------------------------------------------------------------------1311 //--------------------------------------------------------------------------------------------------1319 //--------------------------------------------------------------------------------------------------1326 //--------------------------------------------------------------------------------------------------1332 //--------------------------------------------------------------------------------------------------1339 //--------------------------------------------------------------------------------------------------1348 //--------------------------------------------------------------------------------------------------1356 //--------------------------------------------------------------------------------------------------1360 * @return The file descriptor, or -1 if no file descriptor was sent with this message or if the1363 //--------------------------------------------------------------------------------------------------1370 //--------------------------------------------------------------------------------------------------1374 //--------------------------------------------------------------------------------------------------1381 //--------------------------------------------------------------------------------------------------1387 //--------------------------------------------------------------------------------------------------1394 //--------------------------------------------------------------------------------------------------1407 //--------------------------------------------------------------------------------------------------1416 //--------------------------------------------------------------------------------------------------1443 //--------------------------------------------------------------------------------------------------1450 //--------------------------------------------------------------------------------------------------1462 //--------------------------------------------------------------------------------------------------1473 //--------------------------------------------------------------------------------------------------1479 //--------------------------------------------------------------------------------------------------1487 //--------------------------------------------------------------------------------------------------1493 //--------------------------------------------------------------------------------------------------1499 //--------------------------------------------------------------------------------------------------1505 //--------------------------------------------------------------------------------------------------1513 //--------------------------------------------------------------------------------------------------1520 //--------------------------------------------------------------------------------------------------1528 //--------------------------------------------------------------------------------------------------1535 //--------------------------------------------------------------------------------------------------1542 //--------------------------------------------------------------------------------------------------1549 //--------------------------------------------------------------------------------------------------1558 //--------------------------------------------------------------------------------------------------1565 //--------------------------------------------------------------------------------------------------1575 //--------------------------------------------------------------------------------------------------1585 //--------------------------------------------------------------------------------------------------1592 //--------------------------------------------------------------------------------------------------1598 //--------------------------------------------------------------------------------------------------1605 //--------------------------------------------------------------------------------------------------1612 //--------------------------------------------------------------------------------------------------1619 //--------------------------------------------------------------------------------------------------1627 //--------------------------------------------------------------------------------------------------1634 //--------------------------------------------------------------------------------------------------1640 //--------------------------------------------------------------------------------------------------1647 //--------------------------------------------------------------------------------------------------1652 * @return Reference to the message being handled, or NULL if no Service message receive handler1655 //--------------------------------------------------------------------------------------------------1662 //--------------------------------------------------------------------------------------------------1667 * - if the caller is not running a server-side IPC function, kills the caller (doesn't return).1669 //--------------------------------------------------------------------------------------------------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:888le_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:851size_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:907void 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:873le_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:927le_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)