1 /*
2  *  Copyright (c) 2018, The OpenThread Authors.
3  *  All rights reserved.
4  *
5  *  Redistribution and use in source and binary forms, with or without
6  *  modification, are permitted provided that the following conditions are met:
7  *  1. Redistributions of source code must retain the above copyright
8  *     notice, this list of conditions and the following disclaimer.
9  *  2. Redistributions in binary form must reproduce the above copyright
10  *     notice, this list of conditions and the following disclaimer in the
11  *     documentation and/or other materials provided with the distribution.
12  *  3. Neither the name of the copyright holder nor the
13  *     names of its contributors may be used to endorse or promote products
14  *     derived from this software without specific prior written permission.
15  *
16  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19  *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20  *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21  *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22  *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23  *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25  *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26  *  POSSIBILITY OF SUCH DAMAGE.
27  */
28 
29 /**
30  * @file
31  * @brief
32  *  This file defines the OpenThread Network Time Synchronization Service API.
33  */
34 
35 #ifndef OPENTHREAD_NETWORK_TIME_H_
36 #define OPENTHREAD_NETWORK_TIME_H_
37 
38 #include <openthread/error.h>
39 #include <openthread/instance.h>
40 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44 
45 /**
46  * @addtogroup api-network-time
47  *
48  * @brief
49  *   This module includes functions that control network time synchronization service.
50  *
51  * @{
52  *
53  */
54 
55 /**
56  * This enumeration represents OpenThread time synchronization status.
57  *
58  */
59 typedef enum otNetworkTimeStatus
60 {
61     OT_NETWORK_TIME_UNSYNCHRONIZED = -1, ///< The device hasn't attached to a network.
62     OT_NETWORK_TIME_RESYNC_NEEDED  = 0,  ///< The device hasn’t received time sync for more than two periods time.
63     OT_NETWORK_TIME_SYNCHRONIZED   = 1,  ///< The device network time is synchronized.
64 } otNetworkTimeStatus;
65 
66 /**
67  * This function pointer is called when a network time sync or status change occurs.
68  *
69  */
70 typedef void (*otNetworkTimeSyncCallbackFn)(void *aCallbackContext);
71 
72 /**
73  * zero is considered as invalid time synchronization sequence.
74  *
75  */
76 #define OT_TIME_SYNC_INVALID_SEQ 0
77 
78 /**
79  * Get the Thread network time.
80  *
81  * @param[in]    aInstance     The OpenThread instance structure.
82  * @param[inout] aNetworkTime  The Thread network time in microseconds.
83  *
84  * @returns The time synchronization status.
85  *
86  */
87 otNetworkTimeStatus otNetworkTimeGet(otInstance *aInstance, uint64_t *aNetworkTime);
88 
89 /**
90  * Set the time synchronization period.
91  *
92  * This function can only be called while Thread protocols are disabled.
93  *
94  * @param[in] aInstance         The OpenThread instance structure.
95  * @param[in] aTimeSyncPeriod   The time synchronization period, in seconds.
96  *
97  * @retval OT_ERROR_NONE           Successfully set the time sync period.
98  * @retval OT_ERROR_INVALID_STATE  Thread protocols are enabled.
99  *
100  */
101 otError otNetworkTimeSetSyncPeriod(otInstance *aInstance, uint16_t aTimeSyncPeriod);
102 
103 /**
104  * Get the time synchronization period.
105  *
106  * @param[in] aInstance  The OpenThread instance structure.
107  *
108  * @returns The time synchronization period.
109  *
110  */
111 uint16_t otNetworkTimeGetSyncPeriod(otInstance *aInstance);
112 
113 /**
114  * Set the time synchronization XTAL accuracy threshold for Router-Capable device.
115  *
116  * This function can only be called while Thread protocols are disabled.
117  *
118  * @param[in] aInstance        The OpenThread instance structure.
119  * @param[in] aXTALThreshold   The XTAL accuracy threshold for Router, in PPM.
120  *
121  * @retval OT_ERROR_NONE           Successfully set the time sync period.
122  * @retval OT_ERROR_INVALID_STATE  Thread protocols are enabled.
123  *
124  */
125 otError otNetworkTimeSetXtalThreshold(otInstance *aInstance, uint16_t aXTALThreshold);
126 
127 /**
128  * Get the time synchronization XTAL accuracy threshold for Router.
129  *
130  * @param[in] aInstance  The OpenThread instance structure.
131  *
132  * @returns The XTAL accuracy threshold for Router, in PPM.
133  *
134  */
135 uint16_t otNetworkTimeGetXtalThreshold(otInstance *aInstance);
136 
137 /**
138  * Set a callback to be called when a network time sync or status change occurs
139  *
140  * This callback shall be called only when the network time offset jumps by
141  * OPENTHREAD_CONFIG_TIME_SYNC_JUMP_NOTIF_MIN_US or when the status changes.
142  *
143  * @param[in] aInstance The OpenThread instance structure.
144  * @param[in] aCallbackFn The callback function to be called
145  * @param[in] aCallbackContext The context to be passed to the callback function upon invocation
146  *
147  */
148 void otNetworkTimeSyncSetCallback(otInstance *                aInstance,
149                                   otNetworkTimeSyncCallbackFn aCallbackFn,
150                                   void *                      aCallbackContext);
151 
152 /**
153  * @}
154  *
155  */
156 
157 #ifdef __cplusplus
158 } // extern "C"
159 #endif
160 
161 #endif // OPENTHREAD_NETWORK_TIME_H_
162