le_dcs_common.h

Go to the documentation of this file.
    1 
    2 /*
    3  * ====================== WARNING ======================
    4  *
    5  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    6  * DO NOT MODIFY IN ANY WAY.
    7  *
    8  * ====================== WARNING ======================
    9  */
   10 /**
   11  * @file le_dcs_common.h
   12  *
   13  * Type definitions for le_dcs.
   14  *
   15  */
   16 #ifndef LE_DCS_COMMON_H_INCLUDE_GUARD
   17 #define LE_DCS_COMMON_H_INCLUDE_GUARD
   18 
   19 
   20 #include "legato.h"
   21 
   22 #define IFGEN_LE_DCS_PROTOCOL_ID "bc64c0ae1d3e02a79c05b7e92b1cd802"
   23 #define IFGEN_LE_DCS_MSG_SIZE 3856
   24 /** @addtogroup le_dcs
   25  *  @{ **/
   26 
   27 
   28 //--------------------------------------------------------------------------------------------------
   29 /**
   30  * Interface name string length.
   31  */
   32 //--------------------------------------------------------------------------------------------------
   33 #define LE_DCS_INTERFACE_NAME_MAX_LEN 100
   34 
   35 //--------------------------------------------------------------------------------------------------
   36 /**
   37  * Channel name string length.
   38  */
   39 //--------------------------------------------------------------------------------------------------
   40 #define LE_DCS_CHANNEL_NAME_MAX_LEN 32
   41 
   42 //--------------------------------------------------------------------------------------------------
   43 /**
   44  * IP addr string's max length
   45  */
   46 //--------------------------------------------------------------------------------------------------
   47 #define LE_DCS_IPADDR_MAX_LEN 46
   48 
   49 //--------------------------------------------------------------------------------------------------
   50 /**
   51  * Max # of channel list entries for a query: CHANNEL_LIST_QUERY_MAX is for per-technology, while
   52  * CHANNEL_LIST_ENTRY_MAX is for all channels of all supported technologies. Currently, the former
   53  * one's value is set to the max value supported by cellular. The latter is set to 2 times of that
   54  * to support wifi. The extra 8 is for ethernet. When more technologies are supported, this value
   55  * needs to be raised accordingly.
   56  */
   57 //--------------------------------------------------------------------------------------------------
   58 #define LE_DCS_CHANNEL_LIST_QUERY_MAX 36
   59 
   60 //--------------------------------------------------------------------------------------------------
   61 /**
   62  */
   63 //--------------------------------------------------------------------------------------------------
   64 #define LE_DCS_CHANNEL_LIST_ENTRY_MAX 80
   65 
   66 //--------------------------------------------------------------------------------------------------
   67 /**
   68  * Reference returned by Request function and used by Release function
   69  */
   70 //--------------------------------------------------------------------------------------------------
   71 typedef struct le_dcs_ReqObj* le_dcs_ReqObjRef_t;
   72 
   73 
   74 //--------------------------------------------------------------------------------------------------
   75 /**
   76  * Reference to a data channel
   77  */
   78 //--------------------------------------------------------------------------------------------------
   79 typedef struct le_dcs_Channel* le_dcs_ChannelRef_t;
   80 
   81 
   82 //--------------------------------------------------------------------------------------------------
   83 /**
   84  * Technologies.
   85  */
   86 //--------------------------------------------------------------------------------------------------
   87 typedef enum
   88 {
   89     LE_DCS_TECH_UNKNOWN = 0,
   90         ///<
   91     LE_DCS_TECH_WIFI = 1,
   92         ///< Wi-Fi
   93     LE_DCS_TECH_CELLULAR = 2,
   94         ///< Cellular
   95     LE_DCS_TECH_ETHERNET = 3,
   96         ///< Ethernet
   97     LE_DCS_TECH_MAX = 4
   98         ///< Unknown state.
   99 }
  100 le_dcs_Technology_t;
  101 
  102 
  103 //--------------------------------------------------------------------------------------------------
  104 /**
  105  * Channel states.
  106  */
  107 //--------------------------------------------------------------------------------------------------
  108 typedef enum
  109 {
  110     LE_DCS_STATE_DOWN = 0,
  111         ///<
  112     LE_DCS_STATE_UP = 1
  113         ///<
  114 }
  115 le_dcs_State_t;
  116 
  117 
  118 //--------------------------------------------------------------------------------------------------
  119 /**
  120  * Channel events: These are the data channel events in DCS' northbound towards client apps.
  121  *
  122  * The LE_DCS_EVENT_UP event for a given data channel means that it has been brought up and become
  123  * usable.
  124  *
  125  * The LE_DCS_EVENT_DOWN event means that the given data channel has gone down, been disassociated
  126  * from all the client apps which have called le_dcs_Start() to start it, and its technology has
  127  * stopped to retry reconnecting it back further.
  128  *
  129  * The LE_DCS_EVEN_TEMP_DOWN event means, on the other hand, that the given data channel has
  130  * temporarily gone down, but remains associated with those client apps which have called
  131  * le_dcs_Start() to start but not yet le_dcs_Stop() to stop it, and its technology will
  132  * continue to retry reconnecting it back after some backoff.
  133  *
  134  */
  135 //--------------------------------------------------------------------------------------------------
  136 typedef enum
  137 {
  138     LE_DCS_EVENT_DOWN = 0,
  139         ///<
  140     LE_DCS_EVENT_UP = 1,
  141         ///<
  142     LE_DCS_EVENT_TEMP_DOWN = 2
  143         ///<
  144 }
  145 le_dcs_Event_t;
  146 
  147 
  148 //--------------------------------------------------------------------------------------------------
  149 /**
  150  * Reference type used by Add/Remove functions for EVENT 'le_dcs_Event'
  151  */
  152 //--------------------------------------------------------------------------------------------------
  153 typedef struct le_dcs_EventHandler* le_dcs_EventHandlerRef_t;
  154 
  155 
  156 //--------------------------------------------------------------------------------------------------
  157 /**
  158  * This is the structure with info about each available channel
  159  */
  160 //--------------------------------------------------------------------------------------------------
  161 typedef struct
  162 {
  163     le_dcs_ChannelRef_t ref;
  164     char name[32 + 1];
  165     le_dcs_Technology_t technology;
  166     le_dcs_State_t state;
  167 }
  168 le_dcs_ChannelInfo_t;
  169 
  170 
  171 //--------------------------------------------------------------------------------------------------
  172 /**
  173  * Handler for channel state changes
  174  */
  175 //--------------------------------------------------------------------------------------------------
  176 typedef void (*le_dcs_EventHandlerFunc_t)
  177 (
  178         le_dcs_ChannelRef_t channelRef,
  179         ///< The channel for which the event is
  180         le_dcs_Event_t event,
  181         ///< Event up or down
  182         int32_t code,
  183         ///< Additional event code, like error code
  184         void* contextPtr
  185         ///<
  186 );
  187 
  188 //--------------------------------------------------------------------------------------------------
  189 /**
  190  * Handler for the receiving the results of a channel list query
  191  */
  192 //--------------------------------------------------------------------------------------------------
  193 typedef void (*le_dcs_GetChannelsHandlerFunc_t)
  194 (
  195         le_result_t result,
  196         ///< Result of the channel list query
  197         const le_dcs_ChannelInfo_t* channelListPtr,
  198         ///< List of channels returned
  199         size_t channelListSize,
  200         ///<
  201         void* contextPtr
  202         ///<
  203 );
  204 
  205 
  206 //--------------------------------------------------------------------------------------------------
  207 /**
  208  * Get if this client bound locally.
  209  */
  210 //--------------------------------------------------------------------------------------------------
  211 LE_SHARED bool ifgen_le_dcs_HasLocalBinding
  212 (
  213     void
  214 );
  215 
  216 
  217 //--------------------------------------------------------------------------------------------------
  218 /**
  219  * Init data that is common across all threads
  220  */
  221 //--------------------------------------------------------------------------------------------------
  222 LE_SHARED void ifgen_le_dcs_InitCommonData
  223 (
  224     void
  225 );
  226 
  227 
  228 //--------------------------------------------------------------------------------------------------
  229 /**
  230  * Perform common initialization and open a session
  231  */
  232 //--------------------------------------------------------------------------------------------------
  233 LE_SHARED le_result_t ifgen_le_dcs_OpenSession
  234 (
  235     le_msg_SessionRef_t _ifgen_sessionRef,
  236     bool isBlocking
  237 );
  238 
  239 //--------------------------------------------------------------------------------------------------
  240 /**
  241  * Add handler function for EVENT 'le_dcs_Event'
  242  *
  243  * This event provides information on channel events
  244  */
  245 //--------------------------------------------------------------------------------------------------
  246 LE_SHARED le_dcs_EventHandlerRef_t ifgen_le_dcs_AddEventHandler
  247 (
  248     le_msg_SessionRef_t _ifgen_sessionRef,
  249         le_dcs_ChannelRef_t channelRef,
  250         ///< [IN] The channel for which the event is
  251         le_dcs_EventHandlerFunc_t handlerPtr,
  252         ///< [IN]
  253         void* contextPtr
  254         ///< [IN]
  255 );
  256 
  257 //--------------------------------------------------------------------------------------------------
  258 /**
  259  * Remove handler function for EVENT 'le_dcs_Event'
  260  */
  261 //--------------------------------------------------------------------------------------------------
  262 LE_SHARED void ifgen_le_dcs_RemoveEventHandler
  263 (
  264     le_msg_SessionRef_t _ifgen_sessionRef,
  265         le_dcs_EventHandlerRef_t handlerRef
  266         ///< [IN]
  267 );
  268 
  269 //--------------------------------------------------------------------------------------------------
  270 /**
  271  * Query for a channel's technology type
  272  *
  273  * @return
  274  *      - The given channel's technology type as an enumberator from @ref le_dcs_Technology_t
  275  */
  276 //--------------------------------------------------------------------------------------------------
  277 LE_SHARED le_dcs_Technology_t ifgen_le_dcs_GetTechnology
  278 (
  279     le_msg_SessionRef_t _ifgen_sessionRef,
  280         le_dcs_ChannelRef_t channelRef
  281         ///< [IN] channel which technology type is to be queried
  282 );
  283 
  284 //--------------------------------------------------------------------------------------------------
  285 /**
  286  * Query for a channel's administrative state
  287  *
  288  * @return
  289  *      - The given channel's state in the 2nd argument and associated network interface
  290  *        in 'name'
  291  */
  292 //--------------------------------------------------------------------------------------------------
  293 LE_SHARED le_result_t ifgen_le_dcs_GetState
  294 (
  295     le_msg_SessionRef_t _ifgen_sessionRef,
  296         le_dcs_ChannelRef_t channelRef,
  297         ///< [IN] channel which status is to be queried
  298         le_dcs_State_t* statePtr,
  299         ///< [OUT] channel state returned as output
  300         char* interfaceName,
  301         ///< [OUT] channel's network interface name
  302         size_t interfaceNameSize
  303         ///< [IN]
  304 );
  305 
  306 //--------------------------------------------------------------------------------------------------
  307 /**
  308  * Request by an app to start a data channel
  309  *
  310  * @return
  311  *      - Object reference to the request (to be used later for releasing the channel)
  312  *      - NULL if it has failed to process the request
  313  */
  314 //--------------------------------------------------------------------------------------------------
  315 LE_SHARED le_dcs_ReqObjRef_t ifgen_le_dcs_Start
  316 (
  317     le_msg_SessionRef_t _ifgen_sessionRef,
  318         le_dcs_ChannelRef_t channelRef
  319         ///< [IN] channel requested to be started
  320 );
  321 
  322 //--------------------------------------------------------------------------------------------------
  323 /**
  324  * Stop for an app its previously started data channel
  325  */
  326 //--------------------------------------------------------------------------------------------------
  327 LE_SHARED le_result_t ifgen_le_dcs_Stop
  328 (
  329     le_msg_SessionRef_t _ifgen_sessionRef,
  330         le_dcs_ReqObjRef_t reqRef
  331         ///< [IN] the start request's reference earlier returned
  332 );
  333 
  334 //--------------------------------------------------------------------------------------------------
  335 /**
  336  * Get the object reference of the channel given by the name and its technology type in the first
  337  * and second arguments as input
  338  *
  339  * @return
  340  *     - The retrieved channel reference is returned in the function's return value upon success.
  341  *     - Upon failure, 0 is returned back
  342  */
  343 //--------------------------------------------------------------------------------------------------
  344 LE_SHARED le_dcs_ChannelRef_t ifgen_le_dcs_GetReference
  345 (
  346     le_msg_SessionRef_t _ifgen_sessionRef,
  347         const char* LE_NONNULL name,
  348         ///< [IN] name of channel which reference is to be retrieved
  349         le_dcs_Technology_t technology
  350         ///< [IN] technology of the channel given by its name above
  351 );
  352 
  353 //--------------------------------------------------------------------------------------------------
  354 /**
  355  * Trigger a query for the list of all available data channels that will be returned asynchronously
  356  * via the ChannelQueryHandler callback notification
  357  */
  358 //--------------------------------------------------------------------------------------------------
  359 LE_SHARED void ifgen_le_dcs_GetChannels
  360 (
  361     le_msg_SessionRef_t _ifgen_sessionRef,
  362         le_dcs_GetChannelsHandlerFunc_t handlerPtr,
  363         ///< [IN] requester's handler for receiving results
  364         void* contextPtr
  365         ///< [IN]
  366 );
  367 /** @} **/
  368 #endif // LE_DCS_COMMON_H_INCLUDE_GUARD
LE_DCS_TECH_MAX
Unknown state. 
Definition: le_dcs_common.h:97


le_dcs_EventHandlerFunc_t
void(* le_dcs_EventHandlerFunc_t)(le_dcs_ChannelRef_t channelRef, le_dcs_Event_t event, int32_t code, void *contextPtr)
Definition: le_dcs_common.h:177


le_dcs_Event_t
le_dcs_Event_t
Definition: le_dcs_common.h:136


LE_SHARED
#define LE_SHARED
Definition: le_basics.h:300


le_result_t
le_result_t
Definition: le_basics.h:46


le_dcs_ReqObjRef_t
struct le_dcs_ReqObj * le_dcs_ReqObjRef_t
Definition: le_dcs_common.h:71


le_dcs_EventHandlerRef_t
struct le_dcs_EventHandler * le_dcs_EventHandlerRef_t
Definition: le_dcs_common.h:153


le_dcs_GetChannelsHandlerFunc_t
void(* le_dcs_GetChannelsHandlerFunc_t)(le_result_t result, const le_dcs_ChannelInfo_t *channelListPtr, size_t channelListSize, void *contextPtr)
Definition: le_dcs_common.h:194


LE_DCS_TECH_ETHERNET
Ethernet. 
Definition: le_dcs_common.h:95


le_dcs_Technology_t
le_dcs_Technology_t
Definition: le_dcs_common.h:87


le_dcs_ChannelInfo_t
Definition: le_dcs_common.h:161


LE_DCS_TECH_CELLULAR
Cellular. 
Definition: le_dcs_common.h:93


le_dcs_ChannelRef_t
struct le_dcs_Channel * le_dcs_ChannelRef_t
Definition: le_dcs_common.h:79


le_msg_SessionRef_t
struct le_msg_Session * le_msg_SessionRef_t
Definition: le_messaging.h:860


LE_DCS_TECH_WIFI
Wi-Fi. 
Definition: le_dcs_common.h:91


le_dcs_State_t
le_dcs_State_t
Definition: le_dcs_common.h:108