coreSNTP v1.3.1
Client library for synchronizing device time with internet time using Simple Network Time Protocol (SNTP)
 
Loading...
Searching...
No Matches
core_sntp_client.h
Go to the documentation of this file.
1/*
2 * coreSNTP v1.3.1
3 * Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 *
5 * SPDX-License-Identifier: MIT
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a copy of
8 * this software and associated documentation files (the "Software"), to deal in
9 * the Software without restriction, including without limitation the rights to
10 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
11 * the Software, and to permit persons to whom the Software is furnished to do so,
12 * subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in all
15 * copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
20 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
21 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23 */
24
34#ifndef CORE_SNTP_CLIENT_H_
35#define CORE_SNTP_CLIENT_H_
36
37/* Standard include. */
38#include <stdint.h>
39#include <stddef.h>
40#include <stdbool.h>
41
42/* Include coreSNTP Serializer header. */
44
45/* *INDENT-OFF* */
46#ifdef __cplusplus
47 extern "C" {
48#endif
49/* *INDENT-ON* */
50
61#define SNTP_DEFAULT_SERVER_PORT ( 123U )
62
67typedef struct SntpServerInfo
68{
69 const char * pServerName;
71 uint16_t port;
74
89typedef bool ( * SntpResolveDns_t )( const SntpServerInfo_t * pServerAddr,
90 uint32_t * pIpV4Addr );
91
104typedef void ( * SntpGetTime_t )( SntpTimestamp_t * pCurrentTime );
105
134typedef void ( * SntpSetTime_t )( const SntpServerInfo_t * pTimeServer,
135 const SntpTimestamp_t * pServerTime,
136 int64_t clockOffsetMs,
137 SntpLeapSecondInfo_t leapSecondInfo );
138
147struct NetworkContext;
148typedef struct NetworkContext NetworkContext_t;
149
181typedef int32_t ( * UdpTransportSendTo_t )( NetworkContext_t * pNetworkContext,
182 uint32_t serverAddr,
183 uint16_t serverPort,
184 const void * pBuffer,
185 uint16_t bytesToSend );
186
221typedef int32_t ( * UdpTransportRecvFrom_t )( NetworkContext_t * pNetworkContext,
222 uint32_t serverAddr,
223 uint16_t serverPort,
224 void * pBuffer,
225 uint16_t bytesToRecv );
226
232typedef struct UdpTransportIntf
233{
239
248struct SntpAuthContext;
249typedef struct SntpAuthContext SntpAuthContext_t;
250
290 const SntpServerInfo_t * pTimeServer,
291 void * pBuffer,
292 size_t bufferSize,
293 uint16_t * pAuthCodeSize );
294
329 const SntpServerInfo_t * pTimeServer,
330 const void * pResponseData,
331 uint16_t responseSize );
332
342typedef struct SntpAuthenticationIntf
343{
350
355
362
368typedef struct SntpContext
369{
379
384
390
395 uint8_t * pNetworkBuffer;
396
401
406
411
417
423
433
441
448
457
465
508/* @[define_sntp_init] */
510 const SntpServerInfo_t * pTimeServers,
511 size_t numOfServers,
512 uint32_t serverResponseTimeoutMs,
513 uint8_t * pNetworkBuffer,
514 size_t bufferSize,
515 SntpResolveDns_t resolveDnsFunc,
516 SntpGetTime_t getSystemTimeFunc,
517 SntpSetTime_t setSystemTimeFunc,
518 const UdpTransportInterface_t * pTransportIntf,
519 const SntpAuthenticationInterface_t * pAuthIntf );
520/* @[define_sntp_init] */
521
522
565/* @[define_sntp_sendtimerequest] */
567 uint32_t randomNumber,
568 uint32_t blockTimeMs );
569/* @[define_sntp_sendtimerequest] */
570
571
626/* @[define_sntp_receivetimeresponse] */
628 uint32_t blockTimeMs );
629/* @[define_sntp_receivetimeresponse] */
630
642/* @[define_sntp_statustostr] */
643const char * Sntp_StatusToStr( SntpStatus_t status );
644/* @[define_sntp_statustostr] */
645
646/* *INDENT-OFF* */
647#ifdef __cplusplus
648 }
649#endif
650/* *INDENT-ON* */
651
652#endif /* ifndef CORE_SNTP_CLIENT_H_ */
const char * Sntp_StatusToStr(SntpStatus_t status)
Converts SntpStatus_t to its equivalent string.
Definition: core_sntp_client.c:920
SntpStatus_t Sntp_ReceiveTimeResponse(SntpContext_t *pContext, uint32_t blockTimeMs)
Receives a time response from the server that has been requested for time with the Sntp_SendTimeReque...
Definition: core_sntp_client.c:844
SntpStatus_t Sntp_SendTimeRequest(SntpContext_t *pContext, uint32_t randomNumber, uint32_t blockTimeMs)
Sends a request for time from the currently configured server (in the context). If the user has provi...
Definition: core_sntp_client.c:438
SntpStatus_t Sntp_Init(SntpContext_t *pContext, const SntpServerInfo_t *pTimeServers, size_t numOfServers, uint32_t serverResponseTimeoutMs, uint8_t *pNetworkBuffer, size_t bufferSize, SntpResolveDns_t resolveDnsFunc, SntpGetTime_t getSystemTimeFunc, SntpSetTime_t setSystemTimeFunc, const UdpTransportInterface_t *pTransportIntf, const SntpAuthenticationInterface_t *pAuthIntf)
Initializes a context for SNTP client communication with SNTP/NTP servers.
Definition: core_sntp_client.c:47
API for serializing SNTP request packets and, and de-serializing SNTP response packets....
int32_t(* UdpTransportRecvFrom_t)(NetworkContext_t *pNetworkContext, uint32_t serverAddr, uint16_t serverPort, void *pBuffer, uint16_t bytesToRecv)
Interface for user-defined function to receive the server response, to a time request (sent through t...
Definition: core_sntp_client.h:221
void(* SntpGetTime_t)(SntpTimestamp_t *pCurrentTime)
Interface for user-defined function to obtain the current system time in SNTP timestamp format.
Definition: core_sntp_client.h:104
SntpStatus_t(* SntpGenerateAuthCode_t)(SntpAuthContext_t *pContext, const SntpServerInfo_t *pTimeServer, void *pBuffer, size_t bufferSize, uint16_t *pAuthCodeSize)
Interface for user-defined function to generate and append authentication code in an SNTP request buf...
Definition: core_sntp_client.h:289
int32_t(* UdpTransportSendTo_t)(NetworkContext_t *pNetworkContext, uint32_t serverAddr, uint16_t serverPort, const void *pBuffer, uint16_t bytesToSend)
Interface for user-defined function to send time request as a single datagram to server on the networ...
Definition: core_sntp_client.h:181
void(* SntpSetTime_t)(const SntpServerInfo_t *pTimeServer, const SntpTimestamp_t *pServerTime, int64_t clockOffsetMs, SntpLeapSecondInfo_t leapSecondInfo)
Interface for user-defined function to update the system clock time so that it is synchronized the ti...
Definition: core_sntp_client.h:134
SntpStatus_t(* SntpValidateServerAuth_t)(SntpAuthContext_t *pContext, const SntpServerInfo_t *pTimeServer, const void *pResponseData, uint16_t responseSize)
Interface for user-defined function to authenticate server by validating the authentication code pres...
Definition: core_sntp_client.h:328
bool(* SntpResolveDns_t)(const SntpServerInfo_t *pServerAddr, uint32_t *pIpV4Addr)
Interface for user-defined function to resolve time server domain-name to an IPv4 address....
Definition: core_sntp_client.h:89
SntpLeapSecondInfo_t
Enumeration for leap second information that an SNTP server can send its response to a time request....
Definition: core_sntp_serializer.h:265
SntpStatus_t
Enumeration of status codes that can be returned by the coreSNTP Library API.
Definition: core_sntp_serializer.h:140
struct NetworkContext NetworkContext_t
A user-defined type for context that is passed to the transport interface functions....
Definition: core_sntp_client.h:148
struct SntpAuthContext SntpAuthContext_t
A user-defined type for context that is passed to the authentication interface functions....
Definition: core_sntp_client.h:249
Struct representing the authentication interface for securely communicating with time servers.
Definition: core_sntp_client.h:343
SntpGenerateAuthCode_t generateClientAuth
The user-defined function for appending client authentication data.
Definition: core_sntp_client.h:354
SntpAuthContext_t * pAuthContext
The user-defined context for storing information like key credentials required for cryptographic oper...
Definition: core_sntp_client.h:349
SntpValidateServerAuth_t validateServerAuth
The user-defined function for authenticating server from its SNTP response.
Definition: core_sntp_client.h:360
Structure for a context that stores state for managing a long-running SNTP client that periodically p...
Definition: core_sntp_client.h:369
UdpTransportInterface_t networkIntf
The user-defined interface for performing User Datagram Protocol (UDP) send and receive network opera...
Definition: core_sntp_client.h:422
SntpTimestamp_t lastRequestTime
Cache of the timestamp of sending the last time request to a server for replay attack protection by c...
Definition: core_sntp_client.h:447
uint32_t responseTimeoutMs
The timeout duration (in milliseconds) for receiving a response, through Sntp_ReceiveTimeResponse API...
Definition: core_sntp_client.h:463
SntpResolveDns_t resolveDnsFunc
The user-supplied function for resolving DNS name of time servers.
Definition: core_sntp_client.h:405
uint8_t * pNetworkBuffer
The user-supplied buffer for storing network data of both SNTP requests and SNTP response.
Definition: core_sntp_client.h:395
SntpSetTime_t setTimeFunc
The user-supplied function for correcting system time after receiving time from a server.
Definition: core_sntp_client.h:416
size_t numOfServers
Number of servers configured for use.
Definition: core_sntp_client.h:383
uint32_t currentServerAddr
Cache of the resolved Ipv4 address of the current server being used for time synchronization....
Definition: core_sntp_client.h:440
const SntpServerInfo_t * pTimeServers
List of time servers in decreasing priority order configured for the SNTP client. Only a single serve...
Definition: core_sntp_client.h:378
SntpGetTime_t getTimeFunc
The user-supplied function for obtaining the current system time.
Definition: core_sntp_client.h:410
uint16_t sntpPacketSize
State member for storing the size of the SNTP packet that includes both SNTP_PACKET_BASE_SIZE bytes p...
Definition: core_sntp_client.h:456
SntpAuthenticationInterface_t authIntf
The user-defined interface for incorporating security mechanism of adding client authentication in SN...
Definition: core_sntp_client.h:432
size_t currentServerIndex
The index for the currently configured time server for time querying from the list of time servers in...
Definition: core_sntp_client.h:389
size_t bufferSize
The size of the network buffer.
Definition: core_sntp_client.h:400
Structure representing information for a time server.
Definition: core_sntp_client.h:68
size_t serverNameLen
The length of the server name.
Definition: core_sntp_client.h:70
uint16_t port
The UDP port supported by the server for SNTP/NTP communication.
Definition: core_sntp_client.h:71
const char * pServerName
The time server name.
Definition: core_sntp_client.h:69
Structure representing an SNTP timestamp.
Definition: core_sntp_serializer.h:284
Struct representing the UDP transport interface for user-defined functions that coreSNTP library depe...
Definition: core_sntp_client.h:233
UdpTransportRecvFrom_t recvFrom
The user-defined UDP receive function.
Definition: core_sntp_client.h:237
UdpTransportSendTo_t sendTo
The user-defined UDP send function.
Definition: core_sntp_client.h:236
NetworkContext_t * pUserContext
The user-defined context for storing network socket information.
Definition: core_sntp_client.h:234