core_sntp_client.h

Go to the documentation of this file.

/*
 * coreSNTP
 * 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.
 */
 
#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* */
 
#define SNTP_LIBRARY_VERSION    "v2.0.0"
#define SNTP_DEFAULT_SERVER_PORT    ( 123U )
 
typedef struct SntpServerInfo
{
    const char * pServerName; 
    size_t serverNameLen;     
    uint16_t port;            
} SntpServerInfo_t;
 
typedef bool ( * SntpResolveDns_t )( const SntpServerInfo_t * pServerAddr,
                                     uint32_t * pIpV4Addr );
 
typedef void ( * SntpGetTime_t )( SntpTimestamp_t * pCurrentTime );
 
typedef void ( * SntpSetTime_t )( const SntpServerInfo_t * pTimeServer,
                                  const SntpTimestamp_t * pServerTime,
                                  int64_t clockOffsetMs,
                                  SntpLeapSecondInfo_t leapSecondInfo );
 
struct NetworkContext;
typedef struct NetworkContext NetworkContext_t;
 
typedef int32_t ( * UdpTransportSendTo_t )( NetworkContext_t * pNetworkContext,
                                            uint32_t serverAddr,
                                            uint16_t serverPort,
                                            const void * pBuffer,
                                            uint16_t bytesToSend );
 
typedef int32_t ( * UdpTransportRecvFrom_t )( NetworkContext_t * pNetworkContext,
                                              uint32_t serverAddr,
                                              uint16_t serverPort,
                                              void * pBuffer,
                                              uint16_t bytesToRecv );
 
typedef struct UdpTransportIntf
{
    NetworkContext_t * pUserContext; 
    UdpTransportSendTo_t sendTo;     
    UdpTransportRecvFrom_t recvFrom; 
} UdpTransportInterface_t;
 
struct SntpAuthContext;
typedef struct SntpAuthContext SntpAuthContext_t;
 
typedef SntpStatus_t (* SntpGenerateAuthCode_t )( SntpAuthContext_t * pContext,
                                                  const SntpServerInfo_t * pTimeServer,
                                                  void * pBuffer,
                                                  size_t bufferSize,
                                                  uint16_t * pAuthCodeSize );
 
typedef SntpStatus_t (* SntpValidateServerAuth_t )( SntpAuthContext_t * pContext,
                                                    const SntpServerInfo_t * pTimeServer,
                                                    const void * pResponseData,
                                                    uint16_t responseSize );
 
typedef struct SntpAuthenticationIntf
{
    SntpAuthContext_t * pAuthContext;
 
    SntpGenerateAuthCode_t generateClientAuth;
 
    SntpValidateServerAuth_t validateServerAuth;
} SntpAuthenticationInterface_t;
 
typedef struct SntpContext
{
    const SntpServerInfo_t * pTimeServers;
 
    size_t numOfServers;
 
    size_t currentServerIndex;
 
    uint8_t * pNetworkBuffer;
 
    size_t bufferSize;
 
    SntpResolveDns_t resolveDnsFunc;
 
    SntpGetTime_t getTimeFunc;
 
    SntpSetTime_t setTimeFunc;
 
    UdpTransportInterface_t networkIntf;
 
    SntpAuthenticationInterface_t authIntf;
 
    uint32_t currentServerAddr;
 
    SntpTimestamp_t lastRequestTime;
 
    uint16_t sntpPacketSize;
 
    uint32_t responseTimeoutMs;
} SntpContext_t;
 
/* @[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] */
 
 
/* @[define_sntp_sendtimerequest] */
SntpStatus_t Sntp_SendTimeRequest( SntpContext_t * pContext,
                                   uint32_t randomNumber,
                                   uint32_t blockTimeMs );
/* @[define_sntp_sendtimerequest] */
 
 
/* @[define_sntp_receivetimeresponse] */
SntpStatus_t Sntp_ReceiveTimeResponse( SntpContext_t * pContext,
                                       uint32_t blockTimeMs );
/* @[define_sntp_receivetimeresponse] */
 
/* @[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_ */