le_comm.h

    1 /**
    2  * @file le_comm.h
    3  *
    4  * This file contains the prototypes of Legato RPC Communication API,
    5  * used to provide network communication between two or more remote-host
    6  * systems.
    7  *
    8  * Copyright (C) Sierra Wireless Inc.
    9  */
   10 #ifndef LE_COMM_H_INCLUDE_GUARD
   11 #define LE_COMM_H_INCLUDE_GUARD
   12 
   13 //--------------------------------------------------------------------------------------------------
   14 /**
   15  * Definition to enable the RPC Proxy to be built to use local-service messaging
   16  */
   17 //--------------------------------------------------------------------------------------------------
   18 #ifdef LE_CONFIG_RPC
   19 #if defined (LE_CONFIG_RTOS) || defined(LE_CONFIG_RPC_PROXY_LIBRARY)
   20 // Enable RPC Proxy to use local-service messaging
   21 #define RPC_PROXY_LOCAL_SERVICE      1
   22 #endif
   23 #endif
   24 
   25 
   26 //--------------------------------------------------------------------------------------------------
   27 /**
   28  * Legato RPC Communication Types
   29  */
   30 //--------------------------------------------------------------------------------------------------
   31 typedef void (*le_comm_CallbackHandlerFunc_t) (void* handle, short events);
   32 
   33 
   34 //--------------------------------------------------------------------------------------------------
   35 /**
   36  * Function for Creating a RPC Communication Channel
   37  *
   38  * Return Code
   39  *      - LE_OK if successfully,
   40  *      - otherwise failure
   41  *
   42  * @return
   43  *      Opaque handle to the Communication Channel.
   44  */
   45 //--------------------------------------------------------------------------------------------------
   46 __attribute__((weak))
   47 LE_SHARED void* le_comm_Create
   48 (
   49     const int argc,         ///< [IN] Number of strings pointed to by argv.
   50     const char *argv[],     ///< [IN] Pointer to an array of character strings.
   51     le_result_t* resultPtr  ///< [OUT] Return Code
   52 );
   53 
   54 //--------------------------------------------------------------------------------------------------
   55 /**
   56  * Function for Registering a Callback Handler function to monitor events on the specific handle
   57  *
   58  * @return
   59  *      - LE_OK if successfully.
   60  */
   61 //--------------------------------------------------------------------------------------------------
   62 __attribute__((weak))
   63 LE_SHARED le_result_t le_comm_RegisterHandleMonitor
   64 (
   65     void* handle,                               ///< [IN] Communication channel handle.
   66     le_comm_CallbackHandlerFunc_t handlerFunc,  ///< [IN] Callback Handler Function.
   67     short events                                ///< [IN] Events to be monitored.
   68 );
   69 
   70 //--------------------------------------------------------------------------------------------------
   71 /**
   72  * Function for Deleting a RPC Communicaiton Channel
   73  *
   74  * @return
   75  *      - LE_OK if successfully.
   76  */
   77 //--------------------------------------------------------------------------------------------------
   78 __attribute__((weak))
   79 LE_SHARED le_result_t le_comm_Delete
   80 (
   81     void* handle        ///< [IN] Communication channel.
   82 );
   83 
   84 //--------------------------------------------------------------------------------------------------
   85 /**
   86  * Function for Connecting a RPC Communication Channel
   87  *
   88  * @return
   89  *      - LE_OK if successfully,
   90  *      - LE_IN_PROGRESS if pending on asynchronous connection,
   91  *      - otherwise failure.
   92  */
   93 //--------------------------------------------------------------------------------------------------
   94 __attribute__((weak))
   95 LE_SHARED le_result_t le_comm_Connect
   96 (
   97     void* handle        ///< [IN] Communication channel.
   98 );
   99 
  100 //--------------------------------------------------------------------------------------------------
  101 /**
  102  * Function for Disconnecting a RPC Communication Channel
  103  *
  104  * @return
  105  *      - LE_OK if successfully.
  106  */
  107 //--------------------------------------------------------------------------------------------------
  108 __attribute__((weak))
  109 LE_SHARED le_result_t le_comm_Disconnect
  110 (
  111     void* handle        ///< [IN] Communication channel.
  112 );
  113 
  114 //--------------------------------------------------------------------------------------------------
  115 /**
  116  * Function for Sending Data over a RPC Communication Channel
  117  *
  118  * @return
  119  *      - LE_OK if successfully.
  120  */
  121 //--------------------------------------------------------------------------------------------------
  122 __attribute__((weak))
  123 LE_SHARED le_result_t le_comm_Send
  124 (
  125     void* handle,       ///< [IN] Communication channel.
  126     const void* buf,    ///< [IN] Pointer to buffer of data to be sent.
  127     size_t len          ///< [IN] Size of data to be sent.
  128 );
  129 
  130 //--------------------------------------------------------------------------------------------------
  131 /**
  132  * Function for Receiving Data over a RPC Communication Channel
  133  *
  134  * @return
  135  *      - LE_OK if successfully.
  136  */
  137 //--------------------------------------------------------------------------------------------------
  138 __attribute__((weak))
  139 LE_SHARED le_result_t le_comm_Receive
  140 (
  141     void* handle,       ///< [IN] Communication channel.
  142     void* buf,          ///< [IN] Pointer to buffer to hold received data.
  143     size_t* len         ///< [IN] Size of data received.
  144 );
  145 
  146 
  147 //--------------------------------------------------------------------------------------------------
  148 /**
  149  * Get Support Functions
  150  */
  151 //--------------------------------------------------------------------------------------------------
  152 //--------------------------------------------------------------------------------------------------
  153 /**
  154  * Function to retrieve an ID for the specified handle.
  155  * NOTE:  For logging or display purposes only.
  156  *
  157  * @return
  158  *      - Non-zero integer, if successful.
  159  *      - Negative one (-1), otherwise.
  160  */
  161 //--------------------------------------------------------------------------------------------------
  162 __attribute__((weak))
  163 LE_SHARED int le_comm_GetId
  164 (
  165     void* handle
  166 );
  167 
  168 //--------------------------------------------------------------------------------------------------
  169 /**
  170  * Function to retrieve the Parent Handle.
  171  * NOTE:  For asynchronous connections only.
  172  *
  173  * @return
  174  *      - Parent (Listening) handle, if successfully.
  175  *      - NULL, otherwise.
  176  */
  177 //--------------------------------------------------------------------------------------------------
  178 __attribute__((weak))
  179 LE_SHARED void* le_comm_GetParentHandle
  180 (
  181     void* handle
  182 );
  183 
  184 #endif /* LE_COMM_H_INCLUDE_GUARD */
le_comm_Send
LE_SHARED le_result_t le_comm_Send(void *handle, const void *buf, size_t len)
LE_SHARED
#define LE_SHARED
Definition: le_basics.h:287
le_comm_RegisterHandleMonitor
LE_SHARED le_result_t le_comm_RegisterHandleMonitor(void *handle, le_comm_CallbackHandlerFunc_t handlerFunc, short events)
le_result_t
le_result_t
Definition: le_basics.h:46
le_comm_GetParentHandle
LE_SHARED void * le_comm_GetParentHandle(void *handle)
le_comm_Disconnect
LE_SHARED le_result_t le_comm_Disconnect(void *handle)
le_comm_Create
LE_SHARED void * le_comm_Create(const int argc, const char *argv[], le_result_t *resultPtr)
le_comm_GetId
LE_SHARED int le_comm_GetId(void *handle)
le_comm_CallbackHandlerFunc_t
void(* le_comm_CallbackHandlerFunc_t)(void *handle, short events)
Definition: le_comm.h:31
le_comm_Receive
LE_SHARED le_result_t le_comm_Receive(void *handle, void *buf, size_t *len)
le_comm_Delete
LE_SHARED le_result_t le_comm_Delete(void *handle)
le_comm_Connect
LE_SHARED le_result_t le_comm_Connect(void *handle)