coreSNTP v1.1.0
Client library for synchronizing device time with internet time using Simple Network Time Protocol (SNTP)
Callback Types

Callback function pointer types of the coreSNTP library. More...

Typedefs

typedef 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. The SNTP client library attempts to resolve the DNS of the time-server being used every time the Sntp_SendTimeRequest API is called. More...
 
typedef void(* SntpGetTime_t) (SntpTimestamp_t *pCurrentTime)
 Interface for user-defined function to obtain the current system time in SNTP timestamp format. More...
 
typedef 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 time server used for getting current time. More...
 
typedef 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 network over User Datagram Protocol (UDP). More...
 
typedef 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 the UdpTransportSendTo_t function), from the network over User Datagram Protocol (UDP). More...
 
typedef 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 buffer for the SNTP client to be authenticated by the time server, if a security mechanism is used. More...
 
typedef 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 present in its SNTP response to a time request, if a security mechanism is supported by the server. More...
 

Detailed Description

Callback function pointer types of the coreSNTP library.

Typedef Documentation

◆ SntpResolveDns_t

typedef 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. The SNTP client library attempts to resolve the DNS of the time-server being used every time the Sntp_SendTimeRequest API is called.

Parameters
[in]pServerAddrThe time-server whose IPv4 address is to be resolved.
[out]pIpV4AddrThis should be filled with the resolved IPv4 address. of pTimeServer.
Returns
true if DNS resolution is successful; otherwise false to represent failure.

◆ SntpGetTime_t

typedef void(* SntpGetTime_t) (SntpTimestamp_t *pCurrentTime)

Interface for user-defined function to obtain the current system time in SNTP timestamp format.

Note
If your platform follows UNIX representation of time, the SNTP_TIME_AT_UNIX_EPOCH_SECS and SNTP_FRACTION_VALUE_PER_MICROSECOND macros can be used to convert UNIX time to SNTP timestamp.
Parameters
[out]pCurrentTimeThis should be filled with the current system time in SNTP timestamp format.
Returns
true if obtaining system time is successful; otherwise false to represent failure.

◆ SntpSetTime_t

typedef 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 time server used for getting current time.

Parameters
[in]pTimeServerThe time server used to request time.
[in]pServerTimeThe current time returned by the pTimeServer.
[in]clockOffsetMsThe calculated clock offset (in milliseconds) of the system relative to the server time.
[in]leapSecondInfoInformation about whether there is about an upcoming leap second adjustment of insertion or deletion in the last minute before midnight on the last day of the current month. For more information on leap seconds, refer to https://www.nist.gov/pml/time-and-frequency-division/leap-seconds-faqs. Depending on the accuracy requirements of the system clock, the user can choose to account for the leap second or ignore it in their system clock update logic.
Note
If the clockOffsetMs is positive, then the system time is BEHIND the server time, and if the clockOffsetMs, the system time is AHEAD of the server time. To correct the system time, the user can use either of "step", "slew" OR combination of the two clock discipline methodologies depending on the application needs. If the application requires a smooth time continuum of system time, then the "slew" discipline methodology can be used with the clock offset value, clockOffSetMs, to correct the system clock gradually with a "slew rate". If the application can accept sudden jump in time (forward or backward), then the "step" discipline methodology can be used to directly update the system clock with the current server time, pServerTime, every time the coreSNTP library calls the interface.

◆ UdpTransportSendTo_t

typedef 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 network over User Datagram Protocol (UDP).

Note
It is RECOMMENDED that the send operation is non-blocking, i.e. it SHOULD immediately return when the entire UDP data cannot be sent over the network. In such a case, the coreSNTP library will re-try send operation for a maximum period of blocking time passed to the Sntp_SendTimeRequest API.
If the size of the SNTP packet exceeds the Maximum Transmission Unit (MTU) supported by the network interface of the device, the user-defined implementation MAY either support fragmentation of UDP packets OR use a size for authentication data that allows the SNTP packet to fit within the MTU required size threshold. (Note that the size of SNTP packet is SNTP_PACKET_BASE_SIZE + authentication data.)
Parameters
[in,out]pNetworkContextThe user defined NetworkContext_t which is opaque to the coreSNTP library.
[in]serverAddrThe IPv4 address of the time server to send the data to.
[in]serverPortThe port of the server to send data to.
[in]pBufferThe buffer containing the data to send over the network.
[in]bytesToSendThe size of data in pBuffer to send.
Returns
The function SHOULD return one of the following integer codes:
  • bytesToSend when all requested data is successfully transmitted over the network.
  • 0 when no data could be sent over the network (due to network buffer being full, for example), and the send operation can be retried.
  • < 0 when the send operation failed to send any data due to an internal error, and operation cannot be retried.

◆ UdpTransportRecvFrom_t

typedef 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 the UdpTransportSendTo_t function), from the network over User Datagram Protocol (UDP).

Note
It is RECOMMENDED that the read operation is non-blocking, i.e. it SHOULD immediately return when no data is available on the network. In such a case, the coreSNTP library will re-try send operation for a maximum period of blocking time passed through the Sntp_ReceiveTimeResponse API.
If the size of the SNTP response packet from the server exceeds the Maximum Transmission Unit (MTU) supported by the network interface of the device, the user-defined implementation of the interface MAY either support receiving and assembling fragmented UDP packets OR use an authentication data size that allows SNTP packet to fit within the MTU required packet size threshold. (Note that the size of SNTP packet is SNTP_PACKET_BASE_SIZE + authentication data.)
Parameters
[in,out]pNetworkContextThe user defined NetworkContext_t which is opaque to the coreSNTP library.
[in]serverAddrThe IPv4 address of the time server to receive data from.
[in]serverPortThe port of the server to receive data from.
[out]pBufferThis SHOULD be filled with data received from the network.
[in]bytesToRecvThe expected number of bytes to receive from the server.
Returns
The function SHOULD return one of the following integer codes:
  • bytesToRecv value if all the requested number of bytes are received from the network.
  • ZERO when no data is available on the network, and the operation can be retried.
  • < 0 when the read operation failed due to internal error, and operation cannot be retried.

◆ SntpGenerateAuthCode_t

typedef 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 buffer for the SNTP client to be authenticated by the time server, if a security mechanism is used.

The user can choose to implement with any security mechanism, symmetric key-based (like AES-CMAC) or asymmetric key-based (like Network Time Security), depending on the security mechanism supported by the time server being used to synchronize time with.

Note
The function SHOULD generate the authentication data for the first SNTP_PACKET_BASE_SIZE bytes of SNTP request packet present in the passed buffer pBuffer, and fill the generated authentication data after SNTP_PACKET_BASE_SIZE bytes in the buffer.
Parameters
[in,out]pContextThe user defined NetworkContext_t which is opaque to the coreSNTP library.
[in]pTimeServerThe time server being used to request time from. This parameter is useful to choose the security mechanism when multiple time servers are configured in the library, and they require different security mechanisms or authentication credentials to use.
[in,out]pBufferThis buffer SHOULD be filled with the authentication code generated from the SNTP_PACKET_BASE_SIZE bytes of SNTP request data present in it.
[in]bufferSizeThe maximum amount of data that can be held by the buffer, pBuffer.
[out]pAuthCodeSizeThis should be filled with size of the authentication data appended to the SNTP request buffer, pBuffer. This value plus SNTP_PACKET_BASE_SIZE should not exceed the buffer size, bufferSize.
Returns
The function SHOULD return one of the following integer codes:

◆ SntpValidateServerAuth_t

typedef 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 present in its SNTP response to a time request, if a security mechanism is supported by the server.

The user can choose to implement with any security mechanism, symmetric key-based (like AES-CMAC) or asymmetric key-based (like Network Time Security), depending on the security mechanism supported by the time server being used to synchronize time with.

Note
In an SNTP response, the authentication code is present only after the first SNTP_PACKET_BASE_SIZE bytes. Depending on the security mechanism used, the first SNTP_PACKET_BASE_SIZE bytes MAY be used in validating the authentication data sent by the server.
Parameters
[in,out]pContextThe user defined NetworkContext_t which is opaque to the coreSNTP library.
[in]pTimeServerThe time server that has to be authenticated from its SNTP response. This parameter is useful to choose the security mechanism when multiple time servers are configured in the library, and they require different security mechanisms or authentication credentials to use.
[in]pResponseDataThe SNTP response from the server that contains the authentication code after the first SNTP_PACKET_BASE_SIZE bytes.
[in]responseSizeThe total size of the response from the server.
Returns
The function SHOULD return one of the following integer codes: