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
107typedef void ( * SntpGetTime_t )( SntpTimestamp_t * pCurrentTime );
108
137typedef void ( * SntpSetTime_t )( const SntpServerInfo_t * pTimeServer,
138 const SntpTimestamp_t * pServerTime,
139 int64_t clockOffsetMs,
140 SntpLeapSecondInfo_t leapSecondInfo );
141
150struct NetworkContext;
151typedef struct NetworkContext NetworkContext_t;
152
184typedef int32_t ( * UdpTransportSendTo_t )( NetworkContext_t * pNetworkContext,
185 uint32_t serverAddr,
186 uint16_t serverPort,
187 const void * pBuffer,
188 uint16_t bytesToSend );
189
224typedef int32_t ( * UdpTransportRecvFrom_t )( NetworkContext_t * pNetworkContext,
225 uint32_t serverAddr,
226 uint16_t serverPort,
227 void * pBuffer,
228 uint16_t bytesToRecv );
229
235typedef struct UdpTransportIntf
236{
242
251struct SntpAuthContext;
252typedef struct SntpAuthContext SntpAuthContext_t;
253
293 const SntpServerInfo_t * pTimeServer,
294 void * pBuffer,
295 size_t bufferSize,
296 uint16_t * pAuthCodeSize );
297
332 const SntpServerInfo_t * pTimeServer,
333 const void * pResponseData,
334 uint16_t responseSize );
335
345typedef struct SntpAuthenticationIntf
346{
353
358
365
371typedef struct SntpContext
372{
382
387
393
398 uint8_t * pNetworkBuffer;
399
404
409
414
420
426
436
444
451
460
468
511/* @[define_sntp_init] */
513 const SntpServerInfo_t * pTimeServers,
514 size_t numOfServers,
515 uint32_t serverResponseTimeoutMs,
516 uint8_t * pNetworkBuffer,
517 size_t bufferSize,
518 SntpResolveDns_t resolveDnsFunc,
519 SntpGetTime_t getSystemTimeFunc,
520 SntpSetTime_t setSystemTimeFunc,
521 const UdpTransportInterface_t * pTransportIntf,
522 const SntpAuthenticationInterface_t * pAuthIntf );
523/* @[define_sntp_init] */
524
525
568/* @[define_sntp_sendtimerequest] */
570 uint32_t randomNumber,
571 uint32_t blockTimeMs );
572/* @[define_sntp_sendtimerequest] */
573
574
629/* @[define_sntp_receivetimeresponse] */
631 uint32_t blockTimeMs );
632/* @[define_sntp_receivetimeresponse] */
633
645/* @[define_sntp_statustostr] */
646const char * Sntp_StatusToStr( SntpStatus_t status );
647/* @[define_sntp_statustostr] */
648
649/* *INDENT-OFF* */
650#ifdef __cplusplus
651 }
652#endif
653/* *INDENT-ON* */
654
655#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:224
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:107
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:292
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:184
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:137
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:331
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:151
struct SntpAuthContext SntpAuthContext_t
A user-defined type for context that is passed to the authentication interface functions....
Definition: core_sntp_client.h:252
Struct representing the authentication interface for securely communicating with time servers.
Definition: core_sntp_client.h:346
SntpGenerateAuthCode_t generateClientAuth
The user-defined function for appending client authentication data.
Definition: core_sntp_client.h:357
SntpAuthContext_t * pAuthContext
The user-defined context for storing information like key credentials required for cryptographic oper...
Definition: core_sntp_client.h:352
SntpValidateServerAuth_t validateServerAuth
The user-defined function for authenticating server from its SNTP response.
Definition: core_sntp_client.h:363
Structure for a context that stores state for managing a long-running SNTP client that periodically p...
Definition: core_sntp_client.h:372
UdpTransportInterface_t networkIntf
The user-defined interface for performing User Datagram Protocol (UDP) send and receive network opera...
Definition: core_sntp_client.h:425
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:450
uint32_t responseTimeoutMs
The timeout duration (in milliseconds) for receiving a response, through Sntp_ReceiveTimeResponse API...
Definition: core_sntp_client.h:466
SntpResolveDns_t resolveDnsFunc
The user-supplied function for resolving DNS name of time servers.
Definition: core_sntp_client.h:408
uint8_t * pNetworkBuffer
The user-supplied buffer for storing network data of both SNTP requests and SNTP response.
Definition: core_sntp_client.h:398
SntpSetTime_t setTimeFunc
The user-supplied function for correcting system time after receiving time from a server.
Definition: core_sntp_client.h:419
size_t numOfServers
Number of servers configured for use.
Definition: core_sntp_client.h:386
uint32_t currentServerAddr
Cache of the resolved Ipv4 address of the current server being used for time synchronization....
Definition: core_sntp_client.h:443
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:381
SntpGetTime_t getTimeFunc
The user-supplied function for obtaining the current system time.
Definition: core_sntp_client.h:413
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:459
SntpAuthenticationInterface_t authIntf
The user-defined interface for incorporating security mechanism of adding client authentication in SN...
Definition: core_sntp_client.h:435
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:392
size_t bufferSize
The size of the network buffer.
Definition: core_sntp_client.h:403
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:236
UdpTransportRecvFrom_t recvFrom
The user-defined UDP receive function.
Definition: core_sntp_client.h:240
UdpTransportSendTo_t sendTo
The user-defined UDP send function.
Definition: core_sntp_client.h:239
NetworkContext_t * pUserContext
The user-defined context for storing network socket information.
Definition: core_sntp_client.h:237