Line data Source code
1 1 : /*
2 : * Copyright (c) 2017 Linaro Limited
3 : * Copyright (c) 2019 Intel Corporation
4 : *
5 : * SPDX-License-Identifier: Apache-2.0
6 : */
7 :
8 : /**
9 : * @file
10 : * @brief SNTP (Simple Network Time Protocol)
11 : */
12 :
13 : #ifndef ZEPHYR_INCLUDE_NET_SNTP_H_
14 : #define ZEPHYR_INCLUDE_NET_SNTP_H_
15 :
16 : #include <zephyr/net/socket.h>
17 : #include <zephyr/net/socket_service.h>
18 :
19 : #ifdef __cplusplus
20 : extern "C" {
21 : #endif
22 :
23 : /**
24 : * @brief Simple Network Time Protocol API
25 : * @defgroup sntp SNTP
26 : * @since 1.10
27 : * @version 0.8.0
28 : * @ingroup networking
29 : * @{
30 : */
31 :
32 : /** Time as returned by SNTP API, fractional seconds since 1 Jan 1970 */
33 1 : struct sntp_time {
34 1 : uint64_t seconds; /**< Second value */
35 1 : uint32_t fraction; /**< Fractional seconds value */
36 : #if defined(CONFIG_SNTP_UNCERTAINTY)
37 : uint64_t uptime_us; /**< Uptime in microseconds */
38 : uint32_t uncertainty_us; /**< Uncertainty in microseconds */
39 : #endif
40 : };
41 :
42 : /** SNTP context */
43 1 : struct sntp_ctx {
44 :
45 : /** @cond INTERNAL_HIDDEN */
46 : struct {
47 : struct zsock_pollfd fds[1];
48 : int nfds;
49 : int fd;
50 : } sock;
51 : /** @endcond */
52 :
53 : /** Timestamp when the request was sent from client to server.
54 : * This is used to check if the originated timestamp in the server
55 : * reply matches the one in client request.
56 : */
57 1 : struct sntp_time expected_orig_ts;
58 : };
59 :
60 : /**
61 : * @brief Initialize SNTP context
62 : *
63 : * @param ctx Address of sntp context.
64 : * @param addr IP address of NTP/SNTP server.
65 : * @param addr_len IP address length of NTP/SNTP server.
66 : *
67 : * @return 0 if ok, <0 if error.
68 : */
69 1 : int sntp_init(struct sntp_ctx *ctx, struct sockaddr *addr,
70 : socklen_t addr_len);
71 :
72 : /**
73 : * @brief Perform SNTP query
74 : *
75 : * @param ctx Address of sntp context.
76 : * @param timeout Timeout of waiting for sntp response (in milliseconds).
77 : * @param ts Timestamp including integer and fractional seconds since
78 : * 1 Jan 1970 (output).
79 : *
80 : * @return 0 if ok, <0 if error (-ETIMEDOUT if timeout).
81 : */
82 1 : int sntp_query(struct sntp_ctx *ctx, uint32_t timeout, struct sntp_time *ts);
83 :
84 : /**
85 : * @brief Attempt to receive an SNTP response after issuing a query
86 : *
87 : * @param ctx Address of sntp context.
88 : * @param timeout Timeout of waiting for sntp response (in milliseconds).
89 : * @param ts Timestamp including integer and fractional seconds since
90 : * 1 Jan 1970 (output).
91 : *
92 : * @return 0 if ok, <0 if error (-ETIMEDOUT if timeout).
93 : */
94 1 : int sntp_recv_response(struct sntp_ctx *ctx, uint32_t timeout, struct sntp_time *ts);
95 :
96 : /**
97 : * @brief Release SNTP context
98 : *
99 : * @param ctx Address of sntp context.
100 : */
101 1 : void sntp_close(struct sntp_ctx *ctx);
102 :
103 : /**
104 : * @brief Initialise SNTP context for async operation
105 : *
106 : * Asynchronous operation is powered by @kconfig{CONFIG_NET_SOCKETS_SERVICE}.
107 : *
108 : * @param ctx Address of sntp context.
109 : * @param addr IP address of NTP/SNTP server.
110 : * @param addr_len IP address length of NTP/SNTP server.
111 : * @param service Socket service defined by @ref NET_SOCKET_SERVICE_SYNC_DEFINE
112 : *
113 : * @return 0 if ok, <0 if error.
114 : */
115 1 : int sntp_init_async(struct sntp_ctx *ctx, struct sockaddr *addr, socklen_t addr_len,
116 : const struct net_socket_service_desc *service);
117 :
118 : /**
119 : * @brief Send the SNTP query
120 : *
121 : * @param ctx Address of sntp context.
122 : *
123 : * @return 0 if ok, <0 if error.
124 : */
125 1 : int sntp_send_async(struct sntp_ctx *ctx);
126 :
127 : /**
128 : * @brief Read the result of the SNTP query
129 : *
130 : * Must be called from the callback attached to the @ref net_socket_service_desc
131 : * context.
132 : *
133 : * @param event Event pointer extracted from the service work callback
134 : * @param ts Timestamp including integer and fractional seconds since
135 : * 1 Jan 1970 (output).
136 : *
137 : * @return 0 if ok, <0 if error
138 : */
139 1 : int sntp_read_async(struct net_socket_service_event *event, struct sntp_time *ts);
140 :
141 : /**
142 : * @brief Release SNTP context
143 : *
144 : * @param service Socket service defined by @ref NET_SOCKET_SERVICE_SYNC_DEFINE
145 : */
146 1 : void sntp_close_async(const struct net_socket_service_desc *service);
147 :
148 : /**
149 : * @brief Convenience function to query SNTP in one-shot fashion
150 : *
151 : * Convenience wrapper which calls getaddrinfo(), sntp_init(),
152 : * sntp_query(), and sntp_close().
153 : *
154 : * @param server Address of server in format addr[:port]
155 : * @param timeout Query timeout
156 : * @param ts Timestamp including integer and fractional seconds since
157 : * 1 Jan 1970 (output).
158 : *
159 : * @return 0 if ok, <0 if error (-ETIMEDOUT if timeout).
160 : */
161 1 : int sntp_simple(const char *server, uint32_t timeout,
162 : struct sntp_time *ts);
163 :
164 : /**
165 : * @brief Convenience function to query SNTP in one-shot fashion
166 : * using a pre-initialized address struct
167 : *
168 : * Convenience wrapper which calls sntp_init(), sntp_query() and
169 : * sntp_close().
170 : *
171 : * @param addr IP address of NTP/SNTP server.
172 : * @param addr_len IP address length of NTP/SNTP server.
173 : * @param timeout Query timeout
174 : * @param ts Timestamp including integer and fractional seconds since
175 : * 1 Jan 1970 (output).
176 : *
177 : * @return 0 if ok, <0 if error (-ETIMEDOUT if timeout).
178 : */
179 1 : int sntp_simple_addr(struct sockaddr *addr, socklen_t addr_len, uint32_t timeout,
180 : struct sntp_time *ts);
181 :
182 : #ifdef __cplusplus
183 : }
184 : #endif
185 :
186 : /**
187 : * @}
188 : */
189 :
190 : #endif
|
