|
|
|
Network Services API
1.40.00.04
|
SNTP Client API. More...
Functions | |
| int | SNTP_getTime (struct sockaddr *server, uint32_t(*get)(void), void(*set)(uint32_t newtime)) |
| Get time from NTP server. More... | |
SNTP Error Codes | |
| #define | SNTP_EINVALIDARGS (-101) |
| Input arguments are invalid. More... | |
| #define | SNTP_ESOCKETFAIL (-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_ESOCKETOPTFAIL (-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... | |
SNTP Client API.
The SNTP client provides an API to synchronize the local system clock with a server that provides time synchronization services using Network Time Protocol (NTP).
To use the SNTP client service, the user is required to provide two system time keeping functions, as well as an NTP server's IP address.
Furthermore, the SNTP client has been written to conform to the BSD sockets support layer. As such, it is required that the file containing any calls to the SNTP client API conform to the BSD layer requirements.
The required time keeping functions are called by the SNTP client in order to get or set the current time in the system ("gettime" and "settime"). For example, these could be APIs which set or get the value of a Real Time Clock (RTC), such as the TI-RTOS Seconds module's Seconds_get() and Seconds_set() APIs. But, any equivalent API can be used.
The "gettime" and "settime" functions should have the following format:
The "gettime" function should return the number of seconds since the Epoch (January 1, 1970). The "settime" function sets the time to the value that is passed to it. The SNTP client uses the "gettime" function to write the current system time into a request to an NTP server. The "settime" function is used to set the system time to a new value received from the NTP server. The SNTP client handles the conversion of NTP time (time since January 1, 1900) to the local system's time (number of seconds since January 1, 1970).
Both IPv4 and IPv6 unicast server addresses are supported (host names are not supported). Structures of type 'struct sockaddr_in' must be used for IPv4 server addresses and of type 'struct sockaddr_in6' for IPv6 server addresses.
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 responsibilty to ensure that SNTP_getTime() is not called more than once in any 15 second time period.
SNTP uses BSD Socket APIs by including <ti/net/socket.h> which conditionally includes the BSD socket headers for the various networking layers. It is necessary to ensure that the following define is passed to the compiler in the application build to include the correct network layer BSD headers:
For SimpleLink WiFi networking layer: -DNET_SL
For NDK networking layer: -DNET_NDK
To use the SNTP client APIs, the application should include its header file as follows:
And, to the link line add the following SNTP library:
For SimpleLink WiFi networking layer: -l{NS_INSTALL_DIR}/source/ti/net/sntp/lib/sntp_sl.a{target}
For NDK networking layer: -l{NS_INSTALL_DIR}/source/ti/net/sntp/lib/sntp_ndk.a{target}
| #define SNTP_EINVALIDARGS (-101) |
Input arguments are invalid.
| #define SNTP_ESOCKETFAIL (-102) |
Failed to create a socket.
| #define SNTP_EINVALIDFAMILY (-103) |
The input socket address is not of AF_INET (IPv4) or AF_INET6 (IPv6) family type.
| #define SNTP_ESOCKETOPTFAIL (-104) |
Failed to set receive timeout on socket.
| #define SNTP_ECONNECTFAIL (-105) |
Failed to connect to the NTP server.
| #define SNTP_ESENDFAIL (-106) |
Failed to send a time request to the NTP server.
| #define SNTP_ERECVFAIL (-107) |
Failed to recieve the new time from the NTP server.
| #define SNTP_ERATEBACKOFF (-108) |
NTP Server requests to reduce the update rate (RFC 5905 kiss code RATE)
| #define SNTP_EFATALNORETRY (-109) |
NTP Server invalid or server requests to end all communications (RFC 5905 kiss code DENY or RSTR)
| int SNTP_getTime | ( | struct sockaddr * | server, |
| uint32_t(*)(void) | get, | ||
| void(*)(uint32_t newtime) | set | ||
| ) |
Get time from NTP server.
This function can be used to set the local time by providing the setters and getters of current time on system clock. It is the user's responsibility to periodically call this function to sync the time with NTP server. But note, the function should not be called more than once in a 15 second period to respect the NTP requirement.
| server | A pointer to a sockaddr_in or sockaddr_in6 structure containing NTP server address. |
| get | A pointer to a function that returns the number of seconds since January 1, 1970. |
| set | A pointer to a function that sets the time to the supplied value. |