le_rtc_interface.h

Go to the documentation of this file.
1 /*
2  * ====================== WARNING ======================
3  *
4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
5  * DO NOT MODIFY IN ANY WAY.
6  *
7  * ====================== WARNING ======================
8  */
9 
10 /**
11  * @page c_rtc User Timebase
12  *
13  * @ref le_rtc_interface.h "API Reference" <br>
14  * @ref howToSetUserTimebase how-to
15  * <HR>
16  *
17  * This API provides definitions to read and set the @e user timebase for a target's real time clock (RTC).
18  *
19  * Usually, the time daemon automatically updates the system time (i.e., gets time value
20  * when calling le_clk_GetAbsoluteTime() or using Linux @c date command). In some cases, the RTC
21  * time value may require a user timebase value based on other domains (e.g., GPS) to offset
22  * differences between the battery-powered RTC and the system time.
23  *
24  * If you're synchronizng with cellular network time only, the time daemon will update the
25  * system time (the time you get when calling le_clk_GetAbsoluteTime() or using linux 'date'
26  * command) automatically.
27  *
28  * @section c_rtc_disableDaemon Disable Time Daemon
29 
30  * If you need to set the system time from a saved user timebase value, first disable the time
31  * daemon by commenting out the
32  * @c TIME_SERVICES="qcom_time" line in @c /etc/time_service.conf to prevent the system time from being
33  * updated if the modem receives a new time from a cellular network.
34  *
35  * @section c_rtc_getSet Get/Set Time Value
36  *
37  * You use le_rtc_GetUserTime() to read the current RTC time, and le_rtc_SetUserTime()
38  * to set the user timebase adjustment (plus/minus in milliseconds).
39  *
40  * The time stored in the user timebase is incremented on a millisecond basis;
41  * Unix time is incremented by the second. When storing Unix time in the user timebase, it
42  * must be multiplied by 1000, and must be divided by 1000 when retrieved.
43  *
44  * Typically, it's sufficient to use Unix epoch time x 1000 as the time base.
45  *
46  * <HR>
47  *
48  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
49  */
50 /**
51  * @file le_rtc_interface.h
52  *
53  * Legato @ref c_rtc include file.
54  *
55  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
56  */
57 
58 #ifndef LE_RTC_INTERFACE_H_INCLUDE_GUARD
59 #define LE_RTC_INTERFACE_H_INCLUDE_GUARD
60 
61 
62 #include "legato.h"
63 
64 //--------------------------------------------------------------------------------------------------
65 /**
66  *
67  * Connect the current client thread to the service providing this API. Block until the service is
68  * available.
69  *
70  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
71  * called before any other functions in this API. Normally, ConnectService is automatically called
72  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
73  *
74  * This function is created automatically.
75  */
76 //--------------------------------------------------------------------------------------------------
78 (
79  void
80 );
81 
82 //--------------------------------------------------------------------------------------------------
83 /**
84  *
85  * Try to connect the current client thread to the service providing this API. Return with an error
86  * if the service is not available.
87  *
88  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
89  * called before any other functions in this API. Normally, ConnectService is automatically called
90  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
91  *
92  * This function is created automatically.
93  *
94  * @return
95  * - LE_OK if the client connected successfully to the service.
96  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
97  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
98  * - LE_COMM_ERROR if the Service Directory cannot be reached.
99  */
100 //--------------------------------------------------------------------------------------------------
102 (
103  void
104 );
105 
106 //--------------------------------------------------------------------------------------------------
107 /**
108  *
109  * Disconnect the current client thread from the service providing this API.
110  *
111  * Normally, this function doesn't need to be called. After this function is called, there's no
112  * longer a connection to the service, and the functions in this API can't be used. For details, see
113  * @ref apiFilesC_client.
114  *
115  * This function is created automatically.
116  */
117 //--------------------------------------------------------------------------------------------------
119 (
120  void
121 );
122 
123 //--------------------------------------------------------------------------------------------------
124 /**
125  * Get the current time from the RTC
126  *
127  * @return
128  * - LE_OK Function succeeded.
129  * - LE_FAULT Function failed.
130  */
131 //--------------------------------------------------------------------------------------------------
133 (
134  uint64_t* millisecondsPastGpsEpochPtr
135  ///< [OUT]
136 );
137 
138 //--------------------------------------------------------------------------------------------------
139 /**
140  * Set the RTC with the given time string
141  *
142  * @return
143  * - LE_OK Function succeeded.
144  * - LE_FAULT Function failed.
145  */
146 //--------------------------------------------------------------------------------------------------
148 (
149  uint64_t millisecondsPastGpsEpoch
150  ///< [IN]
151 );
152 
153 
154 #endif // LE_RTC_INTERFACE_H_INCLUDE_GUARD
155 
le_result_t
Definition: le_basics.h:35
void le_rtc_ConnectService(void)
le_result_t le_rtc_SetUserTime(uint64_t millisecondsPastGpsEpoch)
le_result_t le_rtc_GetUserTime(uint64_t *millisecondsPastGpsEpochPtr)
void le_rtc_DisconnectService(void)
le_result_t le_rtc_TryConnectService(void)