le_clkSync_interface.h

    1 
    2 
    3 /*
    4  * ====================== WARNING ======================
    5  *
    6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    7  * DO NOT MODIFY IN ANY WAY.
    8  *
    9  * ====================== WARNING ======================
   10  */
   11 
   12 /**
   13  * @page c_le_clkSync Clock Service's Clock Sync Interface
   14  *
   15  * @ref le_clkSync_interface.h "API Reference" <br>
   16  *
   17  * This clock sync interface is part of Legato's Clock Service for managing and syncing the clock
   18  * time on a Legato device. It includes the APIs for acquiring the current clock time from a given
   19  * time server, with or without setting it into the device's system clock.
   20  *
   21  * @section Clock Time Sources
   22  *
   23  * A current clock time can be queried from a time source via different protocols. While the various
   24  * types of sources are defined in @ref le_clkSync_ClockSource, the currently supported time
   25  * protocols are:
   26  *      - the Time Protocol, defined in <a href="https://tools.ietf.org/html/rfc868">RFC 868</a>.
   27  *      - the Network Time Protocol, defined in
   28  *        <a href="https://tools.ietf.org/html/rfc5905">RFC 5905</a>.
   29  *
   30  * Both of these sources run on an IP network and would require the device to have an active data
   31  * channel established via DCS ahead of time. Each time server of these source types is thus
   32  * specified by its IP address or host name. For each of these source types, 2 servers max can be
   33  * configured, i.e. 2 IP addresses or host names.
   34  *
   35  * @section Clock Time Source's Priority
   36  *
   37  * Each configured clock time source can be assigned a numeric priority within the range 0-9, with
   38  * 9 as the highest priority and 0 the lowest and the default if not explicitly specified. In an
   39  * execution of the system clock update via a call to @ref le_clkSync_UpdateSystemTime, the source
   40  * with the highest priority will first be attempted. And likewise down the prioritized list, each
   41  * will be tried until a successful update is resulted.
   42  *
   43  * @section Clock Time Configurations
   44  *
   45  * These configurations are to be installed and maintained on Clock Service's config tree path
   46  * clockTime:/source/. For each source, its priority and location configurations can be configured.
   47  * The path for the former is clockTime:/source/<source>/priority. With TP or NTP as the source,
   48  * its location configuration is the IP address or host name of its time server, and up to 2 can be
   49  * configured. The paths used
   50  * are clockTime:/source/<source>/config/1 and clockTime:/source/<source>/config/2.
   51  * The following is an example:
   52  * @verbatim
   53     clockTime:/
   54       source/
   55         ntp/
   56           priority<int> == 7
   57           config/
   58             1<string> == pool.ntp.org
   59         tp/
   60           config/
   61             1<string> == time-a.timefreq.bldrdoc.gov
   62             2<string> == time.nist.gov
   63           priority<int> == 9
   64    @endverbatim
   65  *
   66  * @note These clock time configurations can be installed and modified not only through the "config
   67  * set" command on a device's console and Legato's le_cfg_Set APIs, but also AVC's write operation
   68  * for Sierra Wireless' proprietary LWM2M object 33405 from a remote AirVantage server.
   69  *
   70  * @section Executing a Clock Time Update
   71  *
   72  * @warning It is a high risk system operation to update a device's system time, as there could be
   73  * other time-sensitive activities running on the device. Also, it is an asynchronous operation
   74  * that will take some time to try with different sources, complete acquiring the latest time,
   75  * and installing it into the system clock. Thus, users have to use due diligence in calling the
   76  * given API to trigger this execution. In many cases, it might even be necessary to schedule this
   77  * execution to a maintenance time window within which all other activities are minimal, and to
   78  * back off for a while by disallowing any new activities after it is triggered, and until the
   79  * update is fully complete.
   80  *
   81  * To execute a clock time update into a device's system clock, a client app can call @ref
   82  * le_clkSync_UpdateSystemTime. Upon such execution, a prioritized list of all the configured
   83  * sources will be internally generated and then walked from the highest priority to the lowest in
   84  * attempt to contact the source, acquire the current time, and install it into the system clock.
   85  * Such attempt terminates upon either a success or the end of the list. The result of the last
   86  * attempt with each source is archived, which is a per-source status and not a system-wide one.
   87  *
   88  * Note that this execution is asychronous. When @ref le_clkSync_UpdateSystemTime returns to its
   89  * caller, only the triggering of the update is complete, and not the update itself. This API's
   90  * input argument is an event handler of type @ref le_clkSync_UpdateSystemTimeHandlerFunc_t
   91  * provided by the caller which will be upon the completion of the update. This is the way for
   92  * caller to learn back about such completion. The output argument of this callback function is
   93  * the overall status of the update execution of type @ref le_result_t.
   94  *
   95  * For more granular details, the status of the update attempt using each source can be found via
   96  * the API @ref le_clkSync_GetUpdateSystemStatus, and this status code is defined in the enum @ref
   97  * le_clkSync_UpdateSystemStatus which is an exact correspondence to the status code defined in
   98  * Sierra Wireless' proprietary LWM2M object 33405's resource 3.
   99  *
  100  * <HR>
  101  *
  102  * Copyright (C) Sierra Wireless Inc.
  103  */
  104 /**
  105  * @file le_clkSync_interface.h
  106  *
  107  * Legato @ref c_le_clkSync include file.
  108  *
  109  * Copyright (C) Sierra Wireless Inc.
  110  */
  111 
  112 #ifndef LE_CLKSYNC_INTERFACE_H_INCLUDE_GUARD
  113 #define LE_CLKSYNC_INTERFACE_H_INCLUDE_GUARD
  114 
  115 
  116 #include "legato.h"
  117 
  118 // Internal includes for this interface
  119 #include "le_clkSync_common.h"
  120 /** @addtogroup le_clkSync le_clkSync API Reference
  121  * @{
  122  * @file le_clkSync_common.h
  123  * @file le_clkSync_interface.h **/
  124 //--------------------------------------------------------------------------------------------------
  125 /**
  126  * Type for handler called when a server disconnects.
  127  */
  128 //--------------------------------------------------------------------------------------------------
  129 typedef void (*le_clkSync_DisconnectHandler_t)(void *);
  130 
  131 //--------------------------------------------------------------------------------------------------
  132 /**
  133  *
  134  * Connect the current client thread to the service providing this API. Block until the service is
  135  * available.
  136  *
  137  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  138  * called before any other functions in this API.  Normally, ConnectService is automatically called
  139  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  140  *
  141  * This function is created automatically.
  142  */
  143 //--------------------------------------------------------------------------------------------------
  144 void le_clkSync_ConnectService
  145 (
  146     void
  147 );
  148 
  149 //--------------------------------------------------------------------------------------------------
  150 /**
  151  *
  152  * Try to connect the current client thread to the service providing this API. Return with an error
  153  * if the service is not available.
  154  *
  155  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  156  * called before any other functions in this API.  Normally, ConnectService is automatically called
  157  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  158  *
  159  * This function is created automatically.
  160  *
  161  * @return
  162  *  - LE_OK if the client connected successfully to the service.
  163  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  164  *    bound.
  165  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  166  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  167  */
  168 //--------------------------------------------------------------------------------------------------
  169 le_result_t le_clkSync_TryConnectService
  170 (
  171     void
  172 );
  173 
  174 //--------------------------------------------------------------------------------------------------
  175 /**
  176  * Set handler called when server disconnection is detected.
  177  *
  178  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  179  * to continue without exiting, it should call longjmp() from inside the handler.
  180  */
  181 //--------------------------------------------------------------------------------------------------
  182 LE_FULL_API void le_clkSync_SetServerDisconnectHandler
  183 (
  184     le_clkSync_DisconnectHandler_t disconnectHandler,
  185     void *contextPtr
  186 );
  187 
  188 //--------------------------------------------------------------------------------------------------
  189 /**
  190  *
  191  * Disconnect the current client thread from the service providing this API.
  192  *
  193  * Normally, this function doesn't need to be called. After this function is called, there's no
  194  * longer a connection to the service, and the functions in this API can't be used. For details, see
  195  * @ref apiFilesC_client.
  196  *
  197  * This function is created automatically.
  198  */
  199 //--------------------------------------------------------------------------------------------------
  200 void le_clkSync_DisconnectService
  201 (
  202     void
  203 );
  204 
  205 
  206 //--------------------------------------------------------------------------------------------------
  207 /**
  208  * Clock source type. Note that these defined values are the same as defined in Sierra Wireless'
  209  * proprietary LWM2M object 33405's instance ID
  210  */
  211 //--------------------------------------------------------------------------------------------------
  212 
  213 
  214 //--------------------------------------------------------------------------------------------------
  215 /**
  216  * Clock source's update status. Note that these defined values are the same as defined in Sierra
  217  * Wireless' proprietary LWM2M object 33405's resource 3
  218  */
  219 //--------------------------------------------------------------------------------------------------
  220 
  221 
  222 //--------------------------------------------------------------------------------------------------
  223 /**
  224  * Data structure for clock time
  225  */
  226 //--------------------------------------------------------------------------------------------------
  227 
  228 
  229 //--------------------------------------------------------------------------------------------------
  230 /**
  231  * Handler for the receiving the status of the execution of a system time update
  232  */
  233 //--------------------------------------------------------------------------------------------------
  234 
  235 
  236 //--------------------------------------------------------------------------------------------------
  237 /**
  238  * Retrieve the current clock time from the clock source(s) configured and return it back to the
  239  * caller without updating it into the system clock
  240  *
  241  * @return
  242  *      - LE_OK             Function successful
  243  *      - LE_BAD_PARAMETER  A parameter is incorrect
  244  *      - LE_FAULT          Function failed
  245  *      - LE_UNSUPPORTED    Function not supported by the target
  246  */
  247 //--------------------------------------------------------------------------------------------------
  248 le_result_t le_clkSync_GetCurrentTime
  249 (
  250     le_clkSync_ClockTime_t * timePtr,
  251         ///< [OUT] Clock time retrieved from configured source
  252     le_clkSync_ClockSource_t* sourcePtr
  253         ///< [OUT] Clock source from which the current time is acquired
  254 );
  255 
  256 //--------------------------------------------------------------------------------------------------
  257 /**
  258  * Retrieve the status of the execution of a system time update using the given source
  259  *
  260  * @return
  261  *      - le_clkSync_UpdateSystemStatus_t
  262  */
  263 //--------------------------------------------------------------------------------------------------
  264 le_clkSync_UpdateSystemStatus_t le_clkSync_GetUpdateSystemStatus
  265 (
  266     le_clkSync_ClockSource_t source
  267         ///< [IN] Clock source used to get the current time
  268 );
  269 
  270 //--------------------------------------------------------------------------------------------------
  271 /**
  272  * Execute a system clock time update that will be completed asynchronously & return the resulting
  273  * status back via its callback UpdateSystemTimeHandler
  274  */
  275 //--------------------------------------------------------------------------------------------------
  276 void le_clkSync_UpdateSystemTime
  277 (
  278     le_clkSync_UpdateSystemTimeHandlerFunc_t handlerPtr,
  279         ///< [IN] Requester's handler for receiving results
  280     void* contextPtr
  281         ///< [IN]
  282 );
  283 
  284 /** @} **/
  285 
  286 #endif // LE_CLKSYNC_INTERFACE_H_INCLUDE_GUARD
le_clkSync_ClockSource_t
le_clkSync_ClockSource_t
Definition: le_clkSync_common.h:98
le_result_t
le_result_t
Definition: le_basics.h:46
le_clkSync_GetCurrentTime
le_result_t le_clkSync_GetCurrentTime(le_clkSync_ClockTime_t *timePtr, le_clkSync_ClockSource_t *sourcePtr)
le_clkSync_common.h
le_clkSync_ClockTime_t
Definition: le_clkSync_common.h:149
le_clkSync_ConnectService
void le_clkSync_ConnectService(void)
le_clkSync_UpdateSystemTime
void le_clkSync_UpdateSystemTime(le_clkSync_UpdateSystemTimeHandlerFunc_t handlerPtr, void *contextPtr)
le_clkSync_UpdateSystemStatus_t
le_clkSync_UpdateSystemStatus_t
Definition: le_clkSync_common.h:118
le_clkSync_GetUpdateSystemStatus
le_clkSync_UpdateSystemStatus_t le_clkSync_GetUpdateSystemStatus(le_clkSync_ClockSource_t source)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
legato.h
le_clkSync_UpdateSystemTimeHandlerFunc_t
void(* le_clkSync_UpdateSystemTimeHandlerFunc_t)(le_result_t status, void *contextPtr)
Definition: le_clkSync_common.h:168
le_clkSync_DisconnectService
void le_clkSync_DisconnectService(void)
le_clkSync_SetServerDisconnectHandler
LE_FULL_API void le_clkSync_SetServerDisconnectHandler(le_clkSync_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_clkSync_DisconnectHandler_t
void(* le_clkSync_DisconnectHandler_t)(void *)
Definition: le_clkSync_interface.h:129
le_clkSync_TryConnectService
le_result_t le_clkSync_TryConnectService(void)