coreSNTP v1.0.0
Client library for synchronizing device time with internet time using Simple Network Time Protocol (SNTP)
core_sntp_serializer.h
Go to the documentation of this file.
1/*
2 * coreSNTP v1.0.0
3 * Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a copy of
6 * this software and associated documentation files (the "Software"), to deal in
7 * the Software without restriction, including without limitation the rights to
8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9 * the Software, and to permit persons to whom the Software is furnished to do so,
10 * subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in all
13 * copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 */
22
31#ifndef CORE_SNTP_SERIALIZER_H_
32#define CORE_SNTP_SERIALIZER_H_
33
34/* Standard include. */
35#include <stdint.h>
36#include <stddef.h>
37
38/* *INDENT-OFF* */
39#ifdef __cplusplus
40 extern "C" {
41#endif
42/* *INDENT-ON* */
43
52#define SNTP_PACKET_BASE_SIZE ( 48U )
53
66#define SNTP_FRACTION_VALUE_PER_MICROSECOND ( 4295U )
67
83#define SNTP_TIME_AT_UNIX_EPOCH_SECS ( 2208988800U )
84
97#define SNTP_TIME_AT_LARGEST_UNIX_TIME_SECS ( 61505151U )
98
110#define UNIX_TIME_SECS_AT_SNTP_ERA_1_SMALLEST_TIME ( 2085978496U )
111
120#define SNTP_KISS_OF_DEATH_CODE_LENGTH ( 4U )
121
130#define SNTP_KISS_OF_DEATH_CODE_NONE ( 0U )
131
137typedef enum SntpStatus
138{
143
148
154
159
165
171
178
183
189
195
201
209
216
223
229
235
241
248
262typedef enum SntpLeapSecondInfo
263{
264 NoLeapSecond = 0x00,
270
281typedef struct SntpTimestamp
282{
283 uint32_t seconds;
284 uint32_t fractions;
287
293typedef struct SntpResponse
294{
299
305
318
345
346
379/* @[define_sntp_serializerequest] */
381 uint32_t randomNumber,
382 void * pBuffer,
383 size_t bufferSize );
384/* @[define_sntp_serializerequest] */
385
445/* @[define_sntp_deserializeresponse] */
447 const SntpTimestamp_t * pResponseRxTime,
448 const void * pResponseBuffer,
449 size_t bufferSize,
450 SntpResponseData_t * pParsedResponse );
451/* @[define_sntp_deserializeresponse] */
452
486/* @[define_sntp_calculatepollinterval] */
487SntpStatus_t Sntp_CalculatePollInterval( uint16_t clockFreqTolerance,
488 uint16_t desiredAccuracy,
489 uint32_t * pPollInterval );
490/* @[define_sntp_calculatepollinterval] */
491
492
521/* @[define_sntp_converttounixtime] */
523 uint32_t * pUnixTimeSecs,
524 uint32_t * pUnixTimeMicrosecs );
525/* @[define_sntp_converttounixtime] */
526
527/* *INDENT-OFF* */
528#ifdef __cplusplus
529 }
530#endif
531/* *INDENT-ON* */
532
533#endif /* ifndef CORE_SNTP_SERIALIZER_H_ */
SntpStatus_t Sntp_DeserializeResponse(const SntpTimestamp_t *pRequestTime, const SntpTimestamp_t *pResponseRxTime, const void *pResponseBuffer, size_t bufferSize, SntpResponseData_t *pParsedResponse)
De-serializes an SNTP packet received from a server as a response to a SNTP request.
Definition: core_sntp_serializer.c:666
SntpStatus_t Sntp_CalculatePollInterval(uint16_t clockFreqTolerance, uint16_t desiredAccuracy, uint32_t *pPollInterval)
Utility to calculate the poll interval of sending periodic time queries to servers to achieve a desir...
Definition: core_sntp_serializer.c:738
SntpStatus_t Sntp_ConvertToUnixTime(const SntpTimestamp_t *pSntpTime, uint32_t *pUnixTimeSecs, uint32_t *pUnixTimeMicrosecs)
Utility to convert SNTP timestamp (that uses 1st Jan 1900 as the epoch) to UNIX timestamp (that uses ...
Definition: core_sntp_serializer.c:802
SntpStatus_t Sntp_SerializeRequest(SntpTimestamp_t *pRequestTime, uint32_t randomNumber, void *pBuffer, size_t bufferSize)
Serializes an SNTP request packet to use for querying a time server.
Definition: core_sntp_serializer.c:601
SntpLeapSecondInfo_t
Enumeration for leap second information that an SNTP server can send its response to a time request....
Definition: core_sntp_serializer.h:263
SntpStatus_t
Enumeration of status codes that can be returned by the coreSNTP Library API.
Definition: core_sntp_serializer.h:138
@ LastMinuteHas59Seconds
A leap second should be inserted in the last minute before midnight.
Definition: core_sntp_serializer.h:266
@ LastMinuteHas61Seconds
There is no upcoming leap second adjustment.
Definition: core_sntp_serializer.h:265
@ AlarmServerNotSynchronized
A leap second should be deleted from the last minute before midnight.
Definition: core_sntp_serializer.h:267
@ SntpErrorSendTimeout
A timeout occurred in sending time request packet over the network to a server through the Sntp_SendT...
Definition: core_sntp_serializer.h:228
@ SntpErrorBadParameter
Invalid parameter passed to an API function.
Definition: core_sntp_serializer.h:147
@ SntpErrorBufferTooSmall
Application provided insufficient buffer space for serializing or de-serializing an SNTP packet....
Definition: core_sntp_serializer.h:177
@ SntpZeroPollInterval
Poll interval value is under 1 second which cannot be calculated by Sntp_CalculatePollInterval.
Definition: core_sntp_serializer.h:188
@ SntpErrorResponseTimeout
A timeout has occurred in receiving server response with the Sntp_ReceiveTimeResponse API.
Definition: core_sntp_serializer.h:234
@ SntpNoResponseReceived
No SNTP packet for server response is received from the network by the Sntp_ReceiveTimeResponse API.
Definition: core_sntp_serializer.h:240
@ SntpInvalidResponse
Server response failed validation checks for expected data in SNTP packet.
Definition: core_sntp_serializer.h:182
@ SntpErrorAuthFailure
Failure from the user-supplied authentication interface, SntpAuthenticationInterface_t,...
Definition: core_sntp_serializer.h:222
@ SntpErrorNetworkFailure
Networking operation of sending or receiving SNTP packet through the user-defined UDP transport inter...
Definition: core_sntp_serializer.h:208
@ SntpErrorDnsFailure
The user-defined DNS resolution interface, SntpResolveDns_t, failed to resolve address for a time ser...
Definition: core_sntp_serializer.h:200
@ SntpRejectedResponseChangeServer
Server sent a Kiss-o'-Death message with non-retryable code (i.e. DENY or RSTR).
Definition: core_sntp_serializer.h:158
@ SntpRejectedResponseRetryWithBackoff
Server sent a Kiss-o'-Death message with a RATE code, which means that client should back-off before ...
Definition: core_sntp_serializer.h:164
@ SntpSuccess
Successful operation of an SNTP API.
Definition: core_sntp_serializer.h:142
@ SntpRejectedResponse
Server sent a Kiss-o'-Death message to reject the request for time. This status can be returned by th...
Definition: core_sntp_serializer.h:153
@ SntpServerNotAuthenticated
Time server is not authenticated from the authentication data in its response. This status can be ret...
Definition: core_sntp_serializer.h:215
@ SntpRejectedResponseOtherCode
Server sent a Kiss-o'-Death message with a code, specific to the server. Application can inspect the ...
Definition: core_sntp_serializer.h:170
@ SntpErrorTimeNotSupported
SNTP timestamp cannot be converted to UNIX time as time does not lie in time range supported by Sntp_...
Definition: core_sntp_serializer.h:194
@ SntpErrorContextNotInitialized
The SNTP context passed to Sntp_SendTimeRequest or Sntp_ReceiveTimeResponse APIs is is uninitialized.
Definition: core_sntp_serializer.h:246
Structure representing data parsed from an SNTP response from server as well as data of arithmetic ca...
Definition: core_sntp_serializer.h:294
SntpTimestamp_t serverTime
The timestamp sent by the server.
Definition: core_sntp_serializer.h:298
uint32_t rejectedResponseCode
If a server responded with Kiss-o'-Death message to reject time request, this is the fixed length ASC...
Definition: core_sntp_serializer.h:317
SntpLeapSecondInfo_t leapSecondType
The information of an upcoming leap second in the server response.
Definition: core_sntp_serializer.h:304
int64_t clockOffsetMs
The offset (in milliseconds) of the system clock relative to the server time calculated from timestam...
Definition: core_sntp_serializer.h:343
Structure representing an SNTP timestamp.
Definition: core_sntp_serializer.h:282
uint32_t fractions
The fractions part of the SNTP timestamp with resolution of 2^(-32) ~ 232 picoseconds.
Definition: core_sntp_serializer.h:284
uint32_t seconds
Number of seconds since epoch time.
Definition: core_sntp_serializer.h:283