/*
 * coreSNTP v1.2.0
 * Copyright (C) 2021 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
 *
 * SPDX-License-Identifier: MIT
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

/**
 * @file core_sntp_client.h
 * @brief API of an SNTPv4 client library that can send time requests and receive time response to/from
 * SNTP/NTP servers. The library follows the Best Practices suggested in the the SNTPv4 specification,
 * [RFC 4330](https://tools.ietf.org/html/rfc4330).
 * The library can be used to run an SNTP client in a dedicated deamon task to periodically synchronize
 * time from the Internet.
 */

#ifndef CORE_SNTP_CLIENT_H_
#define CORE_SNTP_CLIENT_H_

/* Standard include. */
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

/* Include coreSNTP Serializer header. */
#include "core_sntp_serializer.h"

/* *INDENT-OFF* */
#ifdef __cplusplus
    extern "C" {
#endif
/* *INDENT-ON* */

/**
 * @ingroup sntp_constants
 * @brief The default UDP port supported by SNTP/NTP servers for client-server
 * communication.
 *
 * @note It is possible for a server to use a different port number than
 * the default port when using the Network Time Security protocol as the security
 * mechanism for SNTP communication. For more information, refer to Section 4.1.8
 * of [RFC 8915](https://tools.ietf.org/html/rfc8915).
 */
#define SNTP_DEFAULT_SERVER_PORT    ( 123U )

/**
 * @ingroup sntp_struct_types
 * @brief Structure representing information for a time server.
 */
typedef struct SntpServerInfo
{
    const char * pServerName; /**<@brief The time server name. */
    size_t serverNameLen;     /**<@brief The length of the server name.*/
    uint16_t port;            /**<@brief The UDP port supported by the server
                               * for SNTP/NTP communication. */
} SntpServerInfo_t;

/**
 * @ingroup sntp_callback_types
 * @brief 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 @ref Sntp_SendTimeRequest API is called.
 *
 * @param[in] pServerAddr The time-server whose IPv4 address is to be resolved.
 * @param[out] pIpV4Addr This should be filled with the resolved IPv4 address.
 * of @p pTimeServer.
 *
 * @return `true` if DNS resolution is successful; otherwise `false` to represent
 * failure.
 */
typedef bool ( * SntpResolveDns_t )( const SntpServerInfo_t * pServerAddr,
                                     uint32_t * pIpV4Addr );

/**
 * @ingroup sntp_callback_types
 * @brief 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.
 *
 * @param[out] pCurrentTime This should be filled with the current system time
 * in SNTP timestamp format.
 *
 * @return `true` if obtaining system time is successful; otherwise `false` to
 * represent failure.
 */
typedef void ( * SntpGetTime_t )( SntpTimestamp_t * pCurrentTime );

/**
 * @ingroup sntp_callback_types
 * @brief Interface for user-defined function to update the system clock time
 * so that it is synchronized the time server used for getting current time.
 *
 * @param[in] pTimeServer The time server used to request time.
 * @param[in] pServerTime The current time returned by the @p pTimeServer.
 * @param[in] clockOffsetMs The calculated clock offset (in milliseconds) of the
 * system relative to the server time.
 * @param[in] leapSecondInfo Information 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 @p clockOffsetMs is positive, then the system time is BEHIND the server time,
 * and if the @p 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, @p 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, @p pServerTime, every time the coreSNTP library
 * calls the interface.
 */
typedef void ( * SntpSetTime_t )( const SntpServerInfo_t * pTimeServer,
                                  const SntpTimestamp_t * pServerTime,
                                  int64_t clockOffsetMs,
                                  SntpLeapSecondInfo_t leapSecondInfo );

/**
 * @ingroup sntp_struct_types
 * @typedef NetworkContext_t
 * @brief A user-defined type for context that is passed to the transport interface functions.
 * It MUST be defined by the user to use the library.
 * It is of incomplete type to allow user to define to the needs of their transport
 * interface implementation.
 */
struct NetworkContext;
typedef struct NetworkContext NetworkContext_t;

/**
 * @ingroup sntp_callback_types
 * @brief 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 @ref Sntp_SendTimeRequest API.
 *
 * @note 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.)
 *
 * @param[in,out] pNetworkContext The user defined NetworkContext_t which
 * is opaque to the coreSNTP library.
 * @param[in] serverAddr The IPv4 address of the time server to send the data to.
 * @param[in] serverPort The port of the server to send data to.
 * @param[in] pBuffer The buffer containing the data to send over the network.
 * @param[in] bytesToSend The size of data in @p pBuffer to send.
 *
 * @return The function SHOULD return one of the following integer codes:
 * - @p 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.
 */
typedef int32_t ( * UdpTransportSendTo_t )( NetworkContext_t * pNetworkContext,
                                            uint32_t serverAddr,
                                            uint16_t serverPort,
                                            const void * pBuffer,
                                            uint16_t bytesToSend );

/**
 * @ingroup sntp_callback_types
 * @brief Interface for user-defined function to receive the server response, to a time
 * request (sent through the @ref 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 @ref Sntp_ReceiveTimeResponse API.
 *
 * @note 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.)
 *
 * @param[in,out] pNetworkContext The user defined NetworkContext_t which
 * is opaque to the coreSNTP library.
 * @param[in] serverAddr The IPv4 address of the time server to receive data from.
 * @param[in] serverPort The port of the server to receive data from.
 * @param[out] pBuffer This SHOULD be filled with data received from the network.
 * @param[in] bytesToRecv The expected number of bytes to receive from the
 * server.
 *
 * @return The function SHOULD return one of the following integer codes:
 * - @p 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.
 */
typedef int32_t ( * UdpTransportRecvFrom_t )( NetworkContext_t * pNetworkContext,
                                              uint32_t serverAddr,
                                              uint16_t serverPort,
                                              void * pBuffer,
                                              uint16_t bytesToRecv );

/**
 * @ingroup sntp_struct_types
 * @brief Struct representing the UDP transport interface for user-defined functions
 * that coreSNTP library depends on for performing read/write network operations.
 */
typedef struct UdpTransportIntf
{
    NetworkContext_t * pUserContext; /**<@brief The user-defined context for storing
                                      * network socket information. */
    UdpTransportSendTo_t sendTo;     /**<@brief The user-defined UDP send function. */
    UdpTransportRecvFrom_t recvFrom; /**<@brief The user-defined UDP receive function. */
} UdpTransportInterface_t;

/**
 * @ingroup sntp_struct_types
 * @typedef SntpAuthContext_t
 * @brief A user-defined type for context that is passed to the authentication interface functions.
 * It MUST be defined by the user to use the library.
 * It is of incomplete type to allow user to defined to the the needs of their authentication
 * interface implementation.
 */
struct SntpAuthContext;
typedef struct SntpAuthContext SntpAuthContext_t;

/**
 * @ingroup sntp_callback_types
 * @brief 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
 * @p pBuffer, and fill the generated authentication data after #SNTP_PACKET_BASE_SIZE
 * bytes in the buffer.
 *
 * @param[in,out] pContext The user defined NetworkContext_t which
 * is opaque to the coreSNTP library.
 * @param[in] pTimeServer The 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.
 * @param[in, out] pBuffer This buffer SHOULD be filled with the authentication
 * code generated from the #SNTP_PACKET_BASE_SIZE bytes of SNTP request data
 * present in it.
 * @param[in] bufferSize The maximum amount of data that can be held by the buffer,
 * @p pBuffer.
 * @param[out] pAuthCodeSize This should be filled with size of the authentication
 * data appended to the SNTP request buffer, @p pBuffer. This value plus
 * #SNTP_PACKET_BASE_SIZE should not exceed the buffer size, @p bufferSize.
 *
 * @return The function SHOULD return one of the following integer codes:
 * - #SntpSuccess when the authentication data is successfully appended to @p pBuffer.
 * - #SntpErrorBufferTooSmall when the user-supplied buffer (to the SntpContext_t through
 * @ref Sntp_Init) is not large enough to hold authentication data.
 * - #SntpErrorAuthFailure for failure to generate authentication data due to internal
 * error.
 */
typedef SntpStatus_t (* SntpGenerateAuthCode_t )( SntpAuthContext_t * pContext,
                                                  const SntpServerInfo_t * pTimeServer,
                                                  void * pBuffer,
                                                  size_t bufferSize,
                                                  uint16_t * pAuthCodeSize );

/**
 * @ingroup sntp_callback_types
 * @brief 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.
 *
 * @param[in,out] pContext The user defined NetworkContext_t which
 * is opaque to the coreSNTP library.
 * @param[in] pTimeServer The 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.
 * @param[in] pResponseData The SNTP response from the server that contains the
 * authentication code after the first #SNTP_PACKET_BASE_SIZE bytes.
 * @param[in] responseSize The total size of the response from the server.
 *
 * @return The function SHOULD return one of the following integer codes:
 * - #SntpSuccess when the server is successfully authenticated.
 * - #SntpServerNotAuthenticated when server could not be authenticated.
 * - #SntpErrorAuthFailure for failure to authenticate server due to internal
 * error.
 */
typedef SntpStatus_t (* SntpValidateServerAuth_t )( SntpAuthContext_t * pContext,
                                                    const SntpServerInfo_t * pTimeServer,
                                                    const void * pResponseData,
                                                    uint16_t responseSize );

/**
 * @ingroup sntp_struct_types
 * @brief Struct representing the authentication interface for securely
 * communicating with time servers.
 *
 * @note Using a security mechanism is OPTIONAL for using the coreSNTP
 * library i.e. a user does not need to define the authentication interface
 * if they are not using a security mechanism for SNTP communication.
 */
typedef struct SntpAuthenticationIntf
{
    /**
     *@brief The user-defined context for storing information like
     * key credentials required for cryptographic operations in the
     * security mechanism used for communicating with server.
     */
    SntpAuthContext_t * pAuthContext;

    /**
     * @brief The user-defined function for appending client authentication data.
     * */
    SntpGenerateAuthCode_t generateClientAuth;

    /**
     * @brief The user-defined function for authenticating server from its SNTP
     * response.
     */
    SntpValidateServerAuth_t validateServerAuth;
} SntpAuthenticationInterface_t;

/**
 * @ingroup sntp_struct_types
 * @brief Structure for a context that stores state for managing a long-running
 * SNTP client that periodically polls time and synchronizes system clock.
 */
typedef struct SntpContext
{
    /**
     * @brief List of time servers in decreasing priority order configured
     * for the SNTP client.
     * Only a single server is configured for use at a time across polling
     * attempts until the server rejects a time request or there is a response
     * timeout, after which, the next server in the list is used for subsequent
     * polling requests.
     */
    const SntpServerInfo_t * pTimeServers;

    /**
     * @brief Number of servers configured for use.
     */
    size_t numOfServers;

    /**
     * @brief The index for the currently configured time server for time querying
     * from the list of time servers in @ref pTimeServers.
     */
    size_t currentServerIndex;

    /**
     * @brief The user-supplied buffer for storing network data of both SNTP requests
     * and SNTP response.
     */
    uint8_t * pNetworkBuffer;

    /**
     * @brief The size of the network buffer.
     */
    size_t bufferSize;

    /**
     * @brief The user-supplied function for resolving DNS name of time servers.
     */
    SntpResolveDns_t resolveDnsFunc;

    /**
     * @brief The user-supplied function for obtaining the current system time.
     */
    SntpGetTime_t getTimeFunc;

    /**
     * @brief The user-supplied function for correcting system time after receiving
     * time from a server.
     */
    SntpSetTime_t setTimeFunc;

    /**
     * @brief The user-defined interface for performing User Datagram Protocol (UDP)
     * send and receive network operations.
     */
    UdpTransportInterface_t networkIntf;

    /**
     * @brief The user-defined interface for incorporating security mechanism of
     * adding client authentication in SNTP request as well as authenticating server
     * from SNTP response.
     *
     * @note If the application will not use security mechanism for any of the
     * configured servers, then this interface can be undefined.
     */
    SntpAuthenticationInterface_t authIntf;

    /**
     * @brief Cache of the resolved Ipv4 address of the current server being used for
     * time synchronization.
     * As a Best Practice functionality, the client library attempts to resolve the
     * DNS of the time-server every time the @ref Sntp_SendTimeRequest API is called.
     */
    uint32_t currentServerAddr;

    /**
     * @brief Cache of the timestamp of sending the last time request to a server
     * for replay attack protection by checking that the server response contains
     * the same timestamp in its "originate timestamp" field.
     */
    SntpTimestamp_t lastRequestTime;

    /**
     * @brief State member for storing the size of the SNTP packet that includes
     * both #SNTP_PACKET_BASE_SIZE bytes plus any authentication data, if a security
     * mechanism is used.
     * This value is used for expecting the same size for an SNTP response
     * from the server.
     */
    uint16_t sntpPacketSize;

    /**
     * @brief The timeout duration (in milliseconds) for receiving a response, through
     * @ref Sntp_ReceiveTimeResponse API, from a server after the request for time is
     * sent to it through @ref Sntp_SendTimeRequest API.
     */
    uint32_t responseTimeoutMs;
} SntpContext_t;

/**
 * @brief Initializes a context for SNTP client communication with SNTP/NTP
 * servers.
 *
 * @param[out] pContext The user-supplied memory for the context that will be
 * initialized to represent an SNTP client.
 * @param[in] pTimeServers The list of decreasing order of priority of time
 * servers that should be used by the SNTP client. This list MUST stay in
 * scope for all the time of use of the context.
 * @param[in] numOfServers The number of servers in the list, @p pTimeServers.
 * @param[in] serverResponseTimeoutMs The timeout duration (in milliseconds) for
 * receiving server response for time requests. The same timeout value is used for
 * each server in the @p pTimeServers list.
 * @param[in] pNetworkBuffer The user-supplied memory that will be used for
 * storing network data for SNTP client-server communication. The buffer
 * MUST stay in scope for all the time of use of the context.
 * @param[in] bufferSize The size of the passed buffer @p pNetworkBuffer. The buffer
 * SHOULD be appropriately sized for storing an entire SNTP packet which includes
 * both #SNTP_PACKET_BASE_SIZE bytes of standard SNTP packet size, and space for
 * authentication data, if security mechanism is used to communicate with any of
 * the time servers configured for use.
 * @param[in] resolveDnsFunc The user-defined function for DNS resolution of time
 * server.
 * @param[in] getSystemTimeFunc The user-defined function for querying system
 * time.
 * @param[in] setSystemTimeFunc The user-defined function for correcting system
 * time for every successful time response received from a server.
 * @param[in] pTransportIntf The user-defined function for performing network
 * send/recv operations over UDP.
 * @param[in] pAuthIntf The user-defined interface for generating client authentication
 * in SNTP requests and authenticating servers in SNTP responses, if security mechanism
 * is used in SNTP communication with server(s). If security mechanism is not used in
 * communication with any of the configured servers (in @p pTimeServers), then the
 * @ref SntpAuthenticationInterface_t does not need to be defined and this parameter
 * can be NULL.
 *
 * @return This function returns one of the following:
 * - #SntpSuccess if the context is initialized.
 * - #SntpErrorBadParameter if any of the passed parameters in invalid.
 * - #SntpErrorBufferTooSmall if the buffer does not have the minimum size
 * required for a valid SNTP response packet.
 */
/* @[define_sntp_init] */
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 );
/* @[define_sntp_init] */


/**
 * @brief Sends a request for time from the currently configured server (in the
 * context).
 * If the user has provided an authentication interface, the client
 * authentication code is appended to the request before sending over the network
 * by calling the @ref SntpGenerateAuthCode_t function of the
 * @ref SntpAuthenticationInterface_t.
 *
 * @note This function will ONLY send a request if there is a server available
 * in the configured list that has not rejected an earlier request for time.
 * This adheres to the Best Practice functionality specified in [Section 10 Point 8
 * of SNTPv4 specification](https://tools.ietf.org/html/rfc4330#section-10).
 *
 * @param[in] pContext The context representing an SNTPv4 client.
 * @param[in] randomNumber A random number serializing the SNTP request packet
 * to protect against spoofing attacks by attackers that are off the network path
 * of the SNTP client-server communication. This mechanism is suggested by SNTPv4
 * specification in [RFC 4330 Section 3](https://tools.ietf.org/html/rfc4330#section-3).
 * @param[in] blockTimeMs The maximum duration of time (in milliseconds) the function will
 * block on attempting to send time request to the server over the network. If a zero
 * block time value is provided, then the function will attempt to send the packet ONLY
 * once.
 *
 * @note It is RECOMMENDED that a True Random Number Generator is used to generate the
 * random number by using a hardware module, like Hardware Security Module (HSM), Secure Element,
 * etc, as the entropy source.
 *
 * @return The API function returns one of the following:
 *  - #SntpSuccess if a time request is successfully sent to the currently configured
 * time server in the context.
 *  - #SntpErrorBadParameter if an invalid context is passed to the function.
 *  - #SntpErrorContextNotInitialized if an uninitialized or invalid context is passed
 * to the function.
 *  - #SntpErrorDnsFailure if there is failure in the user-defined function for
 * DNS resolution of the time server.
 *  - #SntpErrorNetworkFailure if the SNTP request could not be sent over the network
 * through the user-defined transport interface.
 *  - #SntpErrorAuthFailure if there was a failure in generating the client
 * authentication code in the user-defined authentication interface.
 *  - #SntpErrorSendTimeout if the time request packet could not be sent over the
 * network for the entire @p blockTimeMs duration.
 */
/* @[define_sntp_sendtimerequest] */
SntpStatus_t Sntp_SendTimeRequest( SntpContext_t * pContext,
                                   uint32_t randomNumber,
                                   uint32_t blockTimeMs );
/* @[define_sntp_sendtimerequest] */


/**
 * @brief Receives a time response from the server that has been requested for time with
 * the @ref Sntp_SendTimeRequest API function.
 * Once an accepted response containing time from server is received, this function calls
 * the user-defined @ref SntpSetTime_t function to update the system time.
 *
 * @note If the user has provided an authentication interface to the client
 * (through @ref Sntp_Init), the server response is authenticated by calling the
 * @ref SntpValidateServerAuth_t function of the @ref SntpAuthenticationInterface_t interface.
 *
 * @note On receiving a successful server response containing server time,
 * this API calculates the clock offset value of the system clock relative to the
 * server before calling the user-defined @ref SntpSetTime_t function for updating
 * the system time.
 *
 * @note For correct calculation of clock-offset, the server and client times MUST be within
 * ~68 years (or 2^31 seconds) of each other. In the special case when the server and client
 * times are exactly 2^31 seconds apart, the library ASSUMES that the server time is ahead
 * of the client time, and returns the positive clock-offset value of INT32_MAX seconds.
 *
 * @note This API will rotate the server of use in the library for the next time request
 * (through the @ref Sntp_SendTimeRequest) if either of following events occur:
 *  - The server has responded with a rejection for the time request.
 *                         OR
 *  - The server response wait has timed out.
 * If all the servers configured in the context have been used, the API will rotate server for
 * time query back to the first server in the list which will be used in next time request.
 *
 * @param[in] pContext The context representing an SNTPv4 client.
 * @param[in] blockTimeMs The maximum duration of time (in milliseconds) the function will
 * block on receiving a response from the server unless either the response is received
 * OR a response timeout occurs.
 *
 * @note This function can be called multiple times with zero or small blocking times
 * to poll whether server response is received until either the response response is
 * received from the server OR a response timeout has occurred.
 *
 * @return This API functions returns one of the following:
 *  - #SntpSuccess if a successful server response is received.
 *  - #SntpErrorContextNotInitialized if an uninitialized or invalid context is passed
 * to the function.
 *  - #SntpErrorBadParameter if an invalid context is passed to the function.
 *  - #SntpErrorNetworkFailure if there is a failure in the user-defined transport
 *  - #SntpErrorAuthFailure if an internal error occurs in the user-defined
 * authentication interface when validating the server response.
 *  - #SntpServerNotAuthenticated when the server could not be authenticated from
 * its response with the user-defined authentication interface.
 *  - #SntpInvalidResponse if the server response fails sanity checks expected in an
 * SNTP response packet.
 *  - #SntpErrorResponseTimeout if a timeout has occurred in receiving response from
 * the server.
 *  - #SntpRejectedResponse if the server responded with a rejection for the time
 * request.
 */
/* @[define_sntp_receivetimeresponse] */
SntpStatus_t Sntp_ReceiveTimeResponse( SntpContext_t * pContext,
                                       uint32_t blockTimeMs );
/* @[define_sntp_receivetimeresponse] */

/**
 * @brief Converts @ref SntpStatus_t to its equivalent
 * string.
 *
 * @note The returned string MUST NOT be modified.
 *
 * @param[in] status The status to convert to a string.
 *
 * @return The string representation of the status
 * code.
 */
/* @[define_sntp_statustostr] */
const char * Sntp_StatusToStr( SntpStatus_t status );
/* @[define_sntp_statustostr] */

/* *INDENT-OFF* */
#ifdef __cplusplus
    }
#endif
/* *INDENT-ON* */

#endif /* ifndef CORE_SNTP_CLIENT_H_ */