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 top-level sntp functions for the OpenThread library.
33  */
34 
35 #ifndef OPENTHREAD_SNTP_H_
36 #define OPENTHREAD_SNTP_H_
37 
38 #include <stdint.h>
39 
40 #include <openthread/ip6.h>
41 
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45 
46 /**
47  * @addtogroup api-sntp
48  *
49  * @brief
50  *   This module includes functions that control SNTP communication.
51  *
52  * @{
53  *
54  */
55 
56 #define OT_SNTP_DEFAULT_SERVER_IP "2001:4860:4806:8::" ///< Defines default SNTP Server address - Google NTP Server.
57 #define OT_SNTP_DEFAULT_SERVER_PORT 123                ///< Defines default SNTP Server port.
58 
59 /**
60  * Implements SNTP Query parameters.
61  *
62  */
63 typedef struct otSntpQuery
64 {
65     const otMessageInfo *mMessageInfo; ///< A reference to the message info related with SNTP Server.
66 } otSntpQuery;
67 
68 /**
69  * Pointer is called when a SNTP response is received.
70  *
71  * @param[in]  aContext   A pointer to application-specific context.
72  * @param[in]  aTime      Specifies the time at the server when the response left for the client, in UNIX time.
73  * @param[in]  aResult    A result of the SNTP transaction.
74  *
75  * @retval  OT_ERROR_NONE              A response was received successfully and time is provided
76  *                                     in @p aTime.
77  * @retval  OT_ERROR_ABORT             A SNTP transaction was aborted by stack.
78  * @retval  OT_ERROR_BUSY              The Kiss-o'-death packet has been received.
79  * @retval  OT_ERROR_RESPONSE_TIMEOUT  No SNTP response has been received within timeout.
80  * @retval  OT_ERROR_FAILED            A response was received but contains incorrect data.
81  *
82  */
83 typedef void (*otSntpResponseHandler)(void *aContext, uint64_t aTime, otError aResult);
84 
85 /**
86  * Sends a SNTP query.
87  *
88  * Is available only if feature `OPENTHREAD_CONFIG_SNTP_CLIENT_ENABLE` is enabled.
89  *
90  * @param[in]  aInstance   A pointer to an OpenThread instance.
91  * @param[in]  aQuery      A pointer to specify SNTP query parameters.
92  * @param[in]  aHandler    A function pointer that shall be called on response reception or time-out.
93  * @param[in]  aContext    A pointer to arbitrary context information.
94  *
95  */
96 otError otSntpClientQuery(otInstance           *aInstance,
97                           const otSntpQuery    *aQuery,
98                           otSntpResponseHandler aHandler,
99                           void                 *aContext);
100 
101 /**
102  * Sets the unix era number.
103  *
104  * The default value of unix era is set to 0. The subsequent eras start after year 2106.
105  *
106  * @param[in]  aInstance   A pointer to an OpenThread instance.
107  * @param[in]  aUnixEra    Unix era number.
108  *
109  */
110 void otSntpClientSetUnixEra(otInstance *aInstance, uint32_t aUnixEra);
111 
112 /**
113  * @}
114  *
115  */
116 
117 #ifdef __cplusplus
118 } // extern "C"
119 #endif
120 
121 #endif // OPENTHREAD_SNTP_H_
122