le_messaging.h

Go to the documentation of this file.

#ifndef LE_MESSAGING_H_INCLUDE_GUARD
#define LE_MESSAGING_H_INCLUDE_GUARD

#include "le_semaphore.h"

// =======================================
//  DATA TYPES
// =======================================

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
typedef struct le_msg_Protocol* le_msg_ProtocolRef_t;

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
typedef struct le_msg_Interface* le_msg_InterfaceRef_t;

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
typedef struct le_msg_Service* le_msg_ServiceRef_t;

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
typedef struct le_msg_ClientInterface* le_msg_ClientInterfaceRef_t;

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
typedef struct le_msg_Session* le_msg_SessionRef_t;

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
typedef struct le_msg_Message* le_msg_MessageRef_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
);




//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
struct le_msg_Service
{
    enum
    {
        LE_MSG_SERVICE_UNIX_SOCKET,
        LE_MSG_SERVICE_LOCAL
    } type;
};


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
struct le_msg_Message
{
    le_msg_SessionRef_t sessionRef;   
};


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
typedef struct
{
    le_thread_Ref_t thread;           
    le_msg_ReceiveHandler_t handler;  
    void* contextPtr;                 
} le_msg_LocalReceiver_t;


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
typedef struct
{
    struct le_msg_Service service;          
#if LE_CONFIG_CUSTOM_OS && defined(LE_MSG_SERVICE_READY_FLAG)
    LE_MSG_SERVICE_READY_FLAG;       
#else
    bool serviceReady;               
#endif
    le_msg_LocalReceiver_t receiver; 
    le_mem_PoolRef_t messagePool;    
} le_msg_LocalService_t;


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
typedef struct le_msg_LocalMessage
{
    struct le_msg_Message message;          
    int fd;                                 
    le_sem_Ref_t responseReady;             
    bool needsResponse;                     
    le_msg_ResponseCallback_t completionCallback; 
    void* contextPtr;                       
    uint8_t data[] __attribute__((aligned));   
} le_msg_LocalMessage_t;


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
#define LE_MSG_LOCAL_HEADER_SIZE      sizeof(le_msg_LocalMessage_t)


// =======================================
//  PROTOCOL 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    
);


// =======================================
//  SESSION FUNCTIONS
// =======================================

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
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  
);



// =======================================
//  MESSAGE FUNCTIONS
// =======================================

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
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      
);


// =======================================
//  INTERFACE FUNCTIONS
// =======================================

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
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
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
#define LE_KILL_CLIENT(formatString, ...)  \
{ \
    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)); \
}

#endif // LEGATO_MESSAGING_INCLUDE_GUARD