The SNTP client provides APIs to synchronize the local time with a server that provides time synchronization services using Network Time Protocol (NTP). More...

Functions
int32_t	SNTP_getTime (const char srvList[], const uint32_t srvCount, SlNetSock_Timeval_t timeout, uint64_t *ntpTimeStamp)
	Obtain the UTC time from NTP servers list. More...

int32_t	SNTP_getTimeByAddr (SlNetSock_Addr_t server, SlNetSock_Timeval_t timeout, uint64_t *ntpTimeStamp)
	Obtain the UTC time from NTP server address. More...

SNTP Error Codes
#define	SNTP_EGETHOSTBYNAMEFAIL (-100)
	Failed to resolve Host address. More...

#define	SNTP_EINVALIDARGS (-101)
	Input arguments are invalid. More...

#define	SNTP_ESOCKCREATEFAIL (-102)
	Failed to create a socket. More...

#define	SNTP_EINVALIDFAMILY (-103)
	The input socket address is not of AF_INET (IPv4) or AF_INET6 (IPv6) family type. More...

#define	SNTP_ESOCKOPTFAIL (-104)
	Failed to set receive timeout on socket. More...

#define	SNTP_ECONNECTFAIL (-105)
	Failed to connect to the NTP server. More...

#define	SNTP_ESENDFAIL (-106)
	Failed to send a time request to the NTP server. More...

#define	SNTP_ERECVFAIL (-107)
	Failed to recieve the new time from the NTP server. More...

#define	SNTP_ERATEBACKOFF (-108)
	NTP Server requests to reduce the update rate (RFC 5905 kiss code RATE) More...

#define	SNTP_EFATALNORETRY (-109)
	NTP Server invalid or server requests to end all communications (RFC 5905 kiss code DENY or RSTR) More...

#define	SNTP_EINVALIDRESP (-110)
	Server response with stratum == 0, with no kiss code. More...

Detailed Description

The SNTP client provides APIs to synchronize the local time with a server that provides time synchronization services using Network Time Protocol (NTP).

There are 3 general use cases supported:

You want to use default NTP servers (SNTP_getTime(), with a NULL server list)
You have the string names of one or more NTP servers (SNTP_getTime(), with your server list)
You have the sockaddr of the NTP server (SNTP_getTimeByAddr(), with your sockaddr)

The SNTP client service will return the seconds passed since January 1st 1900.

Important note on NTP protocol

The NTP protocol clearly specifies that an SNTP client must never send requests to an NTP server in intervals less than 15 seconds. It is important to respect this NTP requirement and it is the user's responsibility to ensure that SNTP_getTime() and/or SNTP_getTimeByAddr() are not called more than once, in any 15 second time period, to contact the same NTP server.

Library Usage

To use the SNTP client APIs, the application should include its header file as follows:

#include <ti/net/sntp/sntp.h>

And, add the following SNTP library to the link line:

.../source/ti/net/sntp/{toolchain}/{isa}/sntp_{profile}.a

Macro Definition Documentation

§ SNTP_EGETHOSTBYNAMEFAIL

#define SNTP_EGETHOSTBYNAMEFAIL (-100)

Failed to resolve Host address.

§ SNTP_EINVALIDARGS

#define SNTP_EINVALIDARGS (-101)

Input arguments are invalid.

§ SNTP_ESOCKCREATEFAIL

#define SNTP_ESOCKCREATEFAIL (-102)

Failed to create a socket.

§ SNTP_EINVALIDFAMILY

#define SNTP_EINVALIDFAMILY (-103)

The input socket address is not of AF_INET (IPv4) or AF_INET6 (IPv6) family type.

§ SNTP_ESOCKOPTFAIL

#define SNTP_ESOCKOPTFAIL (-104)

Failed to set receive timeout on socket.

§ SNTP_ECONNECTFAIL

#define SNTP_ECONNECTFAIL (-105)

Failed to connect to the NTP server.

§ SNTP_ESENDFAIL

#define SNTP_ESENDFAIL (-106)

Failed to send a time request to the NTP server.

§ SNTP_ERECVFAIL

#define SNTP_ERECVFAIL (-107)

Failed to recieve the new time from the NTP server.

§ SNTP_ERATEBACKOFF

#define SNTP_ERATEBACKOFF (-108)

NTP Server requests to reduce the update rate (RFC 5905 kiss code RATE)

§ SNTP_EFATALNORETRY

#define SNTP_EFATALNORETRY (-109)

NTP Server invalid or server requests to end all communications (RFC 5905 kiss code DENY or RSTR)

§ SNTP_EINVALIDRESP

#define SNTP_EINVALIDRESP (-110)

Server response with stratum == 0, with no kiss code.

Function Documentation

§ SNTP_getTime()

int32_t SNTP_getTime	(	const char *	srvList[],
		const uint32_t	srvCount,
		SlNetSock_Timeval_t *	timeout,
		uint64_t *	ntpTimeStamp
	)

Obtain the UTC time from NTP servers list.

Parameters

[in]	srvList	optional string array of server names
[in]	srvCount	number of entities in `srvList`
[in]	timeout	length of time to wait for NTP server reply
[out]	ntpTimeStamp	time value from server in NTP timestamp format

Remarks: srvList can be NULL to use the default list of NTP servers. In this case, srvCount must be set to zero.; If srvList is non-NULL, srvCount must indicate the number of servers in the srvList array.; Both IPv4 and IPv6 unicast server addresses are supported (address is internally resolved).; If srvList is NULL and srvCount is zero, a default list of time servers will be used.; The caller is responsible for correctly setting timeout. If a value of NULL is passed, the default timeout behavior for the socket will apply.; ntpTimeStamp contains time values which match the NTP timestamp specified by RFC 4330. That is, the upper 32 bits will contain the number of seconds since January 1st 1900, and the lower 32 bits will contain the seconds fraction. Both values are unsigned entities.

Returns: Success: 0; Failure: SNTP error

Examples: int32_t retVal;
uint32_t seconds;
uint32_t secondsFraction;
SlNetSock_Timeval_t timeval;
uint64_t ntpTimeStamp = 0;
timeval.tv_sec = 5;
timeval.tv_usec = 0;
retVal = SNTP_getTime(NULL, 0, &timeval, &ntpTimeStamp);
if (retVal == 0) {
// The seconds value is stored in the upper 32 bits
seconds = (0xFFFFFFFF00000000 & ntpTimeStamp) >> 32;
// The seconds fraction is stored in the lower 32 bits
secondsFraction = ntpTimeStamp;
}

§ SNTP_getTimeByAddr()

int32_t SNTP_getTimeByAddr	(	SlNetSock_Addr_t *	server,
		SlNetSock_Timeval_t *	timeout,
		uint64_t *	ntpTimeStamp
	)

Obtain the UTC time from NTP server address.