le_data_common.h

    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_data_common.h
   12  *
   13  * Type definitions for le_data.
   14  *
   15  */
   16 #ifndef LE_DATA_COMMON_H_INCLUDE_GUARD
   17 #define LE_DATA_COMMON_H_INCLUDE_GUARD
   18 
   19 
   20 #include "legato.h"
   21 
   22 // Interface specific includes
   23 #include "le_mdc_common.h"
   24 #include "le_dcs_common.h"
   25 #include "le_clkSync_common.h"
   26 
   27 #define IFGEN_LE_DATA_PROTOCOL_ID "aa2cce84d8273a4beb7e1ba7ca6a1121"
   28 #define IFGEN_LE_DATA_MSG_SIZE 113
   29 /** @addtogroup le_data
   30  *  @{ **/
   31 
   32 
   33 //--------------------------------------------------------------------------------------------------
   34 /**
   35  * Interface name string length.
   36  */
   37 //--------------------------------------------------------------------------------------------------
   38 #define LE_DATA_INTERFACE_NAME_MAX_LEN 100
   39 
   40 //--------------------------------------------------------------------------------------------------
   41 /**
   42  * Interface name string length. One extra byte is added for the null character.
   43  */
   44 //--------------------------------------------------------------------------------------------------
   45 #define LE_DATA_INTERFACE_NAME_MAX_BYTES 101
   46 
   47 //--------------------------------------------------------------------------------------------------
   48 /**
   49  * Reference returned by Request function and used by Release function
   50  */
   51 //--------------------------------------------------------------------------------------------------
   52 typedef struct le_data_RequestObj* le_data_RequestObjRef_t;
   53 
   54 
   55 //--------------------------------------------------------------------------------------------------
   56 /**
   57  * Technologies.
   58  */
   59 //--------------------------------------------------------------------------------------------------
   60 typedef enum
   61 {
   62     LE_DATA_WIFI = 0,
   63         ///< Wi-Fi
   64     LE_DATA_CELLULAR = 1,
   65         ///< Cellular
   66     LE_DATA_MAX = 2
   67         ///< Unknown state.
   68 }
   69 le_data_Technology_t;
   70 
   71 
   72 //--------------------------------------------------------------------------------------------------
   73 /**
   74  * Time protocols.
   75  */
   76 //--------------------------------------------------------------------------------------------------
   77 typedef enum
   78 {
   79     LE_DATA_TP = 0,
   80         ///< Time Protocol, defined in RFC 868
   81     LE_DATA_NTP = 1
   82         ///< Network Time Protocol, defined in RFC 5905
   83 }
   84 le_data_TimeProtocol_t;
   85 
   86 
   87 //--------------------------------------------------------------------------------------------------
   88 /**
   89  * Reference type used by Add/Remove functions for EVENT 'le_data_ConnectionState'
   90  */
   91 //--------------------------------------------------------------------------------------------------
   92 typedef struct le_data_ConnectionStateHandler* le_data_ConnectionStateHandlerRef_t;
   93 
   94 
   95 //--------------------------------------------------------------------------------------------------
   96 /**
   97  * Handler for connection state changes
   98  */
   99 //--------------------------------------------------------------------------------------------------
  100 typedef void (*le_data_ConnectionStateHandlerFunc_t)
  101 (
  102         const char* LE_NONNULL intfName,
  103         ///< Interface name for the data connection
  104         bool isConnected,
  105         ///< State: connected or disconnected
  106         void* contextPtr
  107         ///<
  108 );
  109 
  110 
  111 //--------------------------------------------------------------------------------------------------
  112 /**
  113  * Get if this client bound locally.
  114  */
  115 //--------------------------------------------------------------------------------------------------
  116 LE_SHARED bool ifgen_le_data_HasLocalBinding
  117 (
  118     void
  119 );
  120 
  121 
  122 //--------------------------------------------------------------------------------------------------
  123 /**
  124  * Init data that is common across all threads
  125  */
  126 //--------------------------------------------------------------------------------------------------
  127 LE_SHARED void ifgen_le_data_InitCommonData
  128 (
  129     void
  130 );
  131 
  132 
  133 //--------------------------------------------------------------------------------------------------
  134 /**
  135  * Perform common initialization and open a session
  136  */
  137 //--------------------------------------------------------------------------------------------------
  138 LE_SHARED le_result_t ifgen_le_data_OpenSession
  139 (
  140     le_msg_SessionRef_t _ifgen_sessionRef,
  141     bool isBlocking
  142 );
  143 
  144 //--------------------------------------------------------------------------------------------------
  145 /**
  146  * Add handler function for EVENT 'le_data_ConnectionState'
  147  *
  148  * This event provides information on connection state changes
  149  */
  150 //--------------------------------------------------------------------------------------------------
  151 LE_SHARED le_data_ConnectionStateHandlerRef_t ifgen_le_data_AddConnectionStateHandler
  152 (
  153     le_msg_SessionRef_t _ifgen_sessionRef,
  154         le_data_ConnectionStateHandlerFunc_t handlerPtr,
  155         ///< [IN]
  156         void* contextPtr
  157         ///< [IN]
  158 );
  159 
  160 //--------------------------------------------------------------------------------------------------
  161 /**
  162  * Remove handler function for EVENT 'le_data_ConnectionState'
  163  */
  164 //--------------------------------------------------------------------------------------------------
  165 LE_SHARED void ifgen_le_data_RemoveConnectionStateHandler
  166 (
  167     le_msg_SessionRef_t _ifgen_sessionRef,
  168         le_data_ConnectionStateHandlerRef_t handlerRef
  169         ///< [IN]
  170 );
  171 
  172 //--------------------------------------------------------------------------------------------------
  173 /**
  174  * Request the default data connection
  175  *
  176  * @return
  177  *      - Reference to the data connection (to be used later for releasing the connection)
  178  *      - NULL if the data connection requested could not be processed
  179  */
  180 //--------------------------------------------------------------------------------------------------
  181 LE_SHARED le_data_RequestObjRef_t ifgen_le_data_Request
  182 (
  183     le_msg_SessionRef_t _ifgen_sessionRef
  184 );
  185 
  186 //--------------------------------------------------------------------------------------------------
  187 /**
  188  * Release a previously requested data connection
  189  */
  190 //--------------------------------------------------------------------------------------------------
  191 LE_SHARED void ifgen_le_data_Release
  192 (
  193     le_msg_SessionRef_t _ifgen_sessionRef,
  194         le_data_RequestObjRef_t requestRef
  195         ///< [IN] Reference to a previously requested data connection
  196 );
  197 
  198 //--------------------------------------------------------------------------------------------------
  199 /**
  200  * Set the rank of the technology used for the data connection service
  201  *
  202  * @return
  203  *      - @ref LE_OK if the technology is added to the list
  204  *      - @ref LE_BAD_PARAMETER if the technology is unknown
  205  *      - @ref LE_UNSUPPORTED if the technology is not available
  206  */
  207 //--------------------------------------------------------------------------------------------------
  208 LE_SHARED le_result_t ifgen_le_data_SetTechnologyRank
  209 (
  210     le_msg_SessionRef_t _ifgen_sessionRef,
  211         uint32_t rank,
  212         ///< [IN] Rank of the used technology
  213         le_data_Technology_t technology
  214         ///< [IN] Technology
  215 );
  216 
  217 //--------------------------------------------------------------------------------------------------
  218 /**
  219  * Get the first technology to use
  220  * @return
  221  *      - One of the technologies from @ref le_data_Technology_t enumerator if the list is not empty
  222  *      - @ref LE_DATA_MAX if the list is empty
  223  */
  224 //--------------------------------------------------------------------------------------------------
  225 LE_SHARED le_data_Technology_t ifgen_le_data_GetFirstUsedTechnology
  226 (
  227     le_msg_SessionRef_t _ifgen_sessionRef
  228 );
  229 
  230 //--------------------------------------------------------------------------------------------------
  231 /**
  232  * Get the next technology to use
  233  * @return
  234  *      - One of the technologies from @ref le_data_Technology_t enumerator if the list is not empty
  235  *      - @ref LE_DATA_MAX if the list is empty or the end of the list is reached
  236  */
  237 //--------------------------------------------------------------------------------------------------
  238 LE_SHARED le_data_Technology_t ifgen_le_data_GetNextUsedTechnology
  239 (
  240     le_msg_SessionRef_t _ifgen_sessionRef
  241 );
  242 
  243 //--------------------------------------------------------------------------------------------------
  244 /**
  245  * Get the technology of the currently connected data connection. In the absence of an actively
  246  * connected data connection, @ref LE_DATA_MAX is returned.
  247  *
  248  * @return
  249  *      - One of the technologies from @ref le_data_Technology_t enumerator
  250  *      - @ref LE_DATA_MAX if not connected
  251  */
  252 //--------------------------------------------------------------------------------------------------
  253 LE_SHARED le_data_Technology_t ifgen_le_data_GetTechnology
  254 (
  255     le_msg_SessionRef_t _ifgen_sessionRef
  256 );
  257 
  258 //--------------------------------------------------------------------------------------------------
  259 /**
  260  * Get the default route activation status for the data connection service interface.
  261  *
  262  * @return
  263  *      - true:  the default route is set by the data connection service
  264  *      - false: the default route is not set by the data connection service
  265  */
  266 //--------------------------------------------------------------------------------------------------
  267 LE_SHARED bool ifgen_le_data_GetDefaultRouteStatus
  268 (
  269     le_msg_SessionRef_t _ifgen_sessionRef
  270 );
  271 
  272 //--------------------------------------------------------------------------------------------------
  273 /**
  274  * Add a route on the data connection service interface, if the data session is connected using
  275  * the cellular technology and has an IPv4 or IPv6 address.
  276  *
  277  * @return
  278  *      - LE_OK             on success
  279  *      - LE_UNSUPPORTED    cellular technology not currently used
  280  *      - LE_BAD_PARAMETER  incorrect IP address
  281  *      - LE_FAULT          for all other errors
  282  *
  283  * @note Limitations:
  284  *      - only IPv4 is supported for the moment
  285  *      - route only added for a cellular connection
  286  */
  287 //--------------------------------------------------------------------------------------------------
  288 LE_SHARED le_result_t ifgen_le_data_AddRoute
  289 (
  290     le_msg_SessionRef_t _ifgen_sessionRef,
  291         const char* LE_NONNULL ipDestAddrStr
  292         ///< [IN] The destination IP address in dotted
  293         ///< format
  294 );
  295 
  296 //--------------------------------------------------------------------------------------------------
  297 /**
  298  * Delete a route on the data connection service interface, if the data session is connected using
  299  * the cellular technology and has an IPv4 or IPv6 address.
  300  *
  301  * @return
  302  *      - LE_OK             on success
  303  *      - LE_UNSUPPORTED    cellular technology not currently used
  304  *      - LE_BAD_PARAMETER  incorrect IP address
  305  *      - LE_FAULT          for all other errors
  306  *
  307  * @note Limitations:
  308  *      - only IPv4 is supported for the moment
  309  *      - route only removed for a cellular connection
  310  */
  311 //--------------------------------------------------------------------------------------------------
  312 LE_SHARED le_result_t ifgen_le_data_DelRoute
  313 (
  314     le_msg_SessionRef_t _ifgen_sessionRef,
  315         const char* LE_NONNULL ipDestAddrStr
  316         ///< [IN] The destination IP address in dotted
  317         ///< format
  318 );
  319 
  320 //--------------------------------------------------------------------------------------------------
  321 /**
  322  * Get the cellular profile index used by the data connection service when the cellular technology
  323  * is active.
  324  *
  325  * @return
  326  *      - Cellular profile index
  327  */
  328 //--------------------------------------------------------------------------------------------------
  329 LE_SHARED int32_t ifgen_le_data_GetCellularProfileIndex
  330 (
  331     le_msg_SessionRef_t _ifgen_sessionRef
  332 );
  333 
  334 //--------------------------------------------------------------------------------------------------
  335 /**
  336  * Set the cellular profile index used by the data connection service when the cellular technology
  337  * is active.
  338  *
  339  * @return
  340  *      - LE_OK             on success
  341  *      - LE_BAD_PARAMETER  if the profile index is invalid
  342  *      - LE_BUSY           the cellular connection is in use
  343  */
  344 //--------------------------------------------------------------------------------------------------
  345 LE_SHARED le_result_t ifgen_le_data_SetCellularProfileIndex
  346 (
  347     le_msg_SessionRef_t _ifgen_sessionRef,
  348         int32_t profileIndex
  349         ///< [IN] Cellular profile index to be used
  350 );
  351 
  352 //--------------------------------------------------------------------------------------------------
  353 /**
  354  * Get the date from the configured server using the configured time protocol.
  355  *
  356  * @warning To get the date and time, use GetDateTime rather than sequential calls to GetDate and
  357  * GetTime to avoid the possibility of a date change between the two calls.
  358  *
  359  * @warning An active data connection is necessary to retrieve the date.
  360  *
  361  * @return
  362  *      - LE_OK             on success
  363  *      - LE_BAD_PARAMETER  if a parameter is incorrect
  364  *      - LE_FAULT          if an error occurred
  365  */
  366 //--------------------------------------------------------------------------------------------------
  367 LE_SHARED le_result_t ifgen_le_data_GetDate
  368 (
  369     le_msg_SessionRef_t _ifgen_sessionRef,
  370         uint16_t* yearPtr,
  371         ///< [OUT] UTC Year A.D. [e.g. 2017].
  372         uint16_t* monthPtr,
  373         ///< [OUT] UTC Month into the year [range 1...12].
  374         uint16_t* dayPtr
  375         ///< [OUT] UTC Days into the month [range 1...31].
  376 );
  377 
  378 //--------------------------------------------------------------------------------------------------
  379 /**
  380  * Get the time from the configured server using the configured time protocol.
  381  *
  382  * @warning To get the date and time, use GetDateTime rather than sequential calls to GetDate and
  383  * GetTime to avoid the possibility of a date change between the two calls.
  384  *
  385  * @warning An active data connection is necessary to retrieve the time.
  386  *
  387  * @return
  388  *      - LE_OK             on success
  389  *      - LE_BAD_PARAMETER  if a parameter is incorrect
  390  *      - LE_FAULT          if an error occurred
  391  */
  392 //--------------------------------------------------------------------------------------------------
  393 LE_SHARED le_result_t ifgen_le_data_GetTime
  394 (
  395     le_msg_SessionRef_t _ifgen_sessionRef,
  396         uint16_t* hoursPtr,
  397         ///< [OUT] UTC Hours into the day [range 0..23].
  398         uint16_t* minutesPtr,
  399         ///< [OUT] UTC Minutes into the hour [range 0..59].
  400         uint16_t* secondsPtr,
  401         ///< [OUT] UTC Seconds into the minute [range 0..59].
  402         uint16_t* millisecondsPtr
  403         ///< [OUT] UTC Milliseconds into the second [range 0..999].
  404 );
  405 
  406 //--------------------------------------------------------------------------------------------------
  407 /**
  408  * Get the date and time from the configured server using the configured time protocol.
  409  *
  410  * @warning An active data connection is necessary to retrieve the time.
  411  *
  412  * @return
  413  *      - LE_OK             on success
  414  *      - LE_BAD_PARAMETER  if a parameter is incorrect
  415  *      - LE_FAULT          if an error occurred
  416  */
  417 //--------------------------------------------------------------------------------------------------
  418 LE_SHARED le_result_t ifgen_le_data_GetDateTime
  419 (
  420     le_msg_SessionRef_t _ifgen_sessionRef,
  421         uint16_t* yearPtr,
  422         ///< [OUT] UTC Year A.D. [e.g. 2017].
  423         uint16_t* monthPtr,
  424         ///< [OUT] UTC Month into the year [range 1...12].
  425         uint16_t* dayPtr,
  426         ///< [OUT] UTC Days into the month [range 1...31].
  427         uint16_t* hoursPtr,
  428         ///< [OUT] UTC Hours into the day [range 0..23].
  429         uint16_t* minutesPtr,
  430         ///< [OUT] UTC Minutes into the hour [range 0..59].
  431         uint16_t* secondsPtr,
  432         ///< [OUT] UTC Seconds into the minute [range 0..59].
  433         uint16_t* millisecondsPtr
  434         ///< [OUT] UTC Milliseconds into the second [range 0..999].
  435 );
  436 /** @} **/
  437 #endif // LE_DATA_COMMON_H_INCLUDE_GUARD
le_dcs_common.h
LE_SHARED
#define LE_SHARED
Definition: le_basics.h:287
LE_DATA_MAX
Unknown state. 
Definition: le_data_common.h:66
le_result_t
le_result_t
Definition: le_basics.h:46
le_clkSync_common.h
LE_DATA_TP
Time Protocol, defined in RFC 868. 
Definition: le_data_common.h:79
LE_DATA_NTP
Network Time Protocol, defined in RFC 5905. 
Definition: le_data_common.h:81
LE_DATA_CELLULAR
Cellular. 
Definition: le_data_common.h:64
le_data_Technology_t
le_data_Technology_t
Definition: le_data_common.h:60
LE_DATA_WIFI
Wi-Fi. 
Definition: le_data_common.h:62
le_msg_SessionRef_t
struct le_msg_Session * le_msg_SessionRef_t
Definition: le_messaging.h:860
legato.h
le_data_RequestObjRef_t
struct le_data_RequestObj * le_data_RequestObjRef_t
Definition: le_data_common.h:52
le_mdc_common.h
le_data_TimeProtocol_t
le_data_TimeProtocol_t
Definition: le_data_common.h:77
le_data_ConnectionStateHandlerRef_t
struct le_data_ConnectionStateHandler * le_data_ConnectionStateHandlerRef_t
Definition: le_data_common.h:92
le_data_ConnectionStateHandlerFunc_t
void(* le_data_ConnectionStateHandlerFunc_t)(const char *LE_NONNULL intfName, bool isConnected, void *contextPtr)
Definition: le_data_common.h:101