Chapter 3 - Description of NetX Duo SNTP Client Services
This chapter contains a description of all NetX Duo SNTP Client services (listed below) in alphabetic order.
In the Return Values section in the following API descriptions, values in BOLD are not affected by the NX_DISABLE_ERROR_CHECKING define that is used to disable API error checking, while non-bold values are completely disabled.
nx_sntp_client_create
Create an SNTP Client
Prototype
UINT nx_sntp_client_create(
NX_SNTP_CLIENT *client_ptr,
NX_IP *ip_ptr,
UINT iface_index,
NX_PACKET_POOL *packet_pool_ptr,
UINT (*leap_second_handler)(
NX_SNTP_CLIENT *client_ptr,
UINT indicator),
UINT (*kiss_of_death_handler)(
NX_SNTP_CLIENT *client_ptr,
NX_SNTP_TIME_MESSAGE *server_time_msg),
VOID (random_number_generator)(
struct NX_SNTP_CLIENT_STRUCT *client_ptr,
ULONG *rand));Input Parameters
-
client_ptr: Pointer to SNTP Client control block
-
ip_ptr: Pointer to Client IP instance
-
iface_index: Index to SNTP network interface
-
packet_pool_ptr: Pointer to Client packet pool
-
leap_second_handler: Callback for application response to impending leap second
-
kiss_of_death_handler: Callback for application response to receiving Kiss of Death packet
-
random_number_generator: Callback to random number generator service
Return Values
-
NX_SUCCESS (0x00) Successful Client creation
-
NX_SNTP_INSUFFICIENT_PACKET_PAYLOAD (0xD2A) Invalid non pointer input
-
NX_PTR_ERROR (0x07) Invalid pointer input
-
NX_INVALID_INTERFACE (0x4C) Invalid network interface
Example
/* Create the SNTP Client on the primary interface. */
UINT iface_index = 0;
status = nx_sntp_client_create(&demo_client,
iface_index, &client_ip,
&client_packet_pool, leap_second_handler,
kiss_of_death_handler,
NULL /* no random_number_generator callback */);
/* If status is NX_SUCCESS an SNTP Client instance was successfully
created. */nx_sntp_client_delete
nx_sntp_client_get_local_time
Get the SNTP Client local time
Prototype
UINT nx_sntp_client_get_local_time(
NX_SNTP_CLIENT *client_ptr ,
ULONG *seconds,
ULONG *fraction,
CHAR *buffer);Description
This service gets the SNTP Client local time with an option buffer pointer input to receive the data in string message format.
This service is deprecated. Developers are encouraged to migrate to nx_sntp_client_get_local_time_extended().
Input Parameters
-
client_ptr: Pointer to SNTP Client control block
-
seconds: Pointer to local time seconds
-
fraction: Local time fraction component
-
buffer: Pointer to buffer to write time data
nx_sntp_client_get_local_time_extended
Get the extended SNTP Client local time
Prototype
UINT nx_sntp_client_get_local_time_extended(
NX_SNTP_CLIENT *client_ptr,
ULONG *seconds,
ULONG *fraction,
CHAR *buffer
UINT buffer_size);Description
This service gets the extended SNTP Client local time with an option buffer pointer input to receive the data in string message format.
Input Parameters
-
client_ptr: Pointer to SNTP Client control block
-
seconds: Pointer to local time seconds
-
fraction: Pointer to fraction component
-
buffer: Pointer to buffer to write time data
-
buffer_size: Length of buffer
Return Values
-
NX_SUCCESS (0x00) Successful Client creation
-
NX_PTR_ERROR (0x07) Invalid pointer input
-
NX_CALLER_ERROR (0x11) Invalid caller of service
-
NX_SIZE_ERROR (0x09) Check buffer_size fail
Example
/* Get the SNTP Client local time without the
string message option. */
#define BUFSIZE 50
ULONG seconds;
ULONG fraction;
CHAR buffer[BUFSIZE];
status = nx_sntp_client_get_local_time_extended(&demo_client,
&seconds,
&fraction,
buffer,
BUFSIZE);
/* If status is NX_SUCCESS an SNTP Client
time was successfully retrieved. */nx_sntp_client_initialize_broadcast
Initialize the Client for broadcast operation
Prototype
UINT nx_sntp_client_initialize_broadcast(
NX_SNTP_CLIENT *client_ptr,
ULONG multicast_server_address,
ULONG broadcast_time_servers);Description
This service initializes the Client for broadcast operation by setting the the SNTP Server IP address and initializing SNTP startup parameters and timeouts. If both multicast and broadcast addresses are non-null, the multicast address is selected. If both addresses are null an error is returned. Note this supports IPv4 server addresses only.
Input Parameters
-
client_ptr: Pointer to SNTP Client control block
-
multicast_server_address: SNTP multicast address
-
broadcast_time_server: SNTP server broadcast address
nxd_sntp_client_initialize_broadcast
Initialize the Client for IPv4 or IPv6 broadcast operation
Prototype
UINT nxd_sntp_client_initialize_broadcast(
NX_SNTP_CLIENT *client_ptr,
NXD_ADDRESS *multicast_server_address,
NXD_ADDRESS *broadcast_server_address);Description
This service initializes the Client for broadcast operation by setting up the SNTP Server IP address and initializing SNTP startup parameters and timeouts. If both broadcast and multicast address pointers are non null, the multicast address is selected. If both address pointers are null, an error is returned. This supports both IPv4 and IPv6 address types. Note that IPv6 does not support broadcast, so the broadcast address pointer is set to IPv6, an error is returned.
Input Parameters
-
client_ptr: Pointer to SNTP Client control block
-
multicast_server_address: SNTP server multicast address
-
broadcast_server_address: SNTP server broadcast address
Return Values
-
NX_SUCCESS (0x00) Client successfully initialized
-
NX_SNTP_PARAM_ERROR (0xD0D) Invalid non pointer input
-
NX_PTR_ERROR (0x07) Invalid pointer input
-
NX_CALLER_ERROR (0x11) Invalid caller of service
Example
/* Initialize the client for broadcast operation. */
NXD_ADDRESS broadcast_server;
Broadcast_server.nxd_ip_address = NX_IP_VERSION_V6;
Broadcast_server.nxd_ip_address.v6[0] = 0x20010db1;
Broadcast_server.nxd_ip_address.v6[1] = 0x0f101;
Broadcast_server.nxd_ip_address.v6[2] = 0x0;
Broadcast_server.nxd_ip_address.v6[3] = 0x101;
status = nxd_sntp_client_initialize_broadcast(client_ptr,0x0,
NX_NULL, &broadcast_server)
/* If status is NX_SUCCESS the Client
was successfully initialized. */nx_sntp_client_initialize_unicast
Set up the SNTP Client to run in unicast
Prototype
UINT nx_sntp_client_initialize_unicast(
NX_SNTP_CLIENT * client_ptr,
ULONG unicast_time_server);Description
This service initializes the Client for unicast operation by setting the SNTP Server IP address and initializing SNTP startup parameters and timeouts. Note this supports IPv4 server addresses only.
Input Parameters
-
client_ptr: Pointer to SNTP Client control block
-
unicast_time_server: SNTP server IP address
nxd_sntp_client_initialize_unicast
Set up the SNTP Client to run in IPv4 or IPv6 unicast
Prototype
UINT nxd_sntp_client_initialize_unicast(
NX_SNTP_CLIENT * client_ptr,
NXD_ADDRESS *unicast_time_server);Description
This service initializes the Client for unicast operation by setting up the SNTP Server IP address and initializing SNTP startup parameters and timeouts. This supports both IPv4 and IPv6 address types.
Input Parameters
-
client_ptr: Pointer to SNTP Client control block
-
unicast_time_server: SNTP server IP address
Return Values
-
NX_SUCCESS (0x00) Client successfully initialized
-
NX_INVALID_PARAMETERS (0x4D) Invalid non pointer input
-
NX_PTR_ERROR (0x07) Invalid pointer input
-
NX_CALLER_ERROR (0x11) Invalid caller of service
Example
/* Initialize the Client for unicast operation. */
NXD_ADDRESS unicast_server;
unicast _server.nxd_ip_address = NX_IP_VERSION_V6;
unicast _server.nxd_ip_address.v6[0] = 0x20010db1;
unicast _server.nxd_ip_address.v6[1] = 0x0f101;
unicast _server.nxd_ip_address.v6[2] = 0x0;
unicast _server.nxd_ip_address.v6[3] = 0x101;
status = nxd_sntp_client_initialize_unicast(&client_ptr,
*unicast_server);
/* If status is NX_SUCCESS the Client
is initialized for unicast operation. */nx_sntp_client_receiving_updates
Indicate if Client is receiving valid updates
Description
This service indicates if the Client is receiving valid SNTP updates. If the maximum time lapse without a valid update or limit on consecutive invalid updates is exceeded, the receive status is returned as false. Note that the SNTP Client is still running and if the application wishes to restart the SNTP Client with another unicast or broadcast/multicast server it must stop the SNTP Client using the nx_sntp_client_stop service, reinitialize the Client using one of the initialize services with another server.
Input Parameters
-
client_ptr: Pointer to SNTP Client control block.
-
receive_status: Pointer to indicator if Client is receiving valid updates.
nx_sntp_client_request_unicast_time
Send a unicast request directly to the NTP Server
Description
This service allows the application to directly send a unicast request to the NTP server asynchronously from the SNTP Client thread task. The wait option specifies how long to wait for a response. If successful, the application can use other SNTP Client services to obtain the latest time. See section SNTP Asynchronous Unicast Requests for more details.
Input Parameters
-
client_ptr: Pointer to SNTP Client control block.
-
Wait_option: Wait option for NTP response in timer ticks.
nx_sntp_client_run_broadcast
Run the Client in broadcast mode
Description
This service starts the Client in broadcast mode where it will wait to receive broadcasts from the SNTP server. If a valid broadcast SNTP message is received, the SNTP client timeout for maximum lapse without an update and count of consecutive invalid messages received are reset. If the either of these limits are exceeded, the SNTP Client sets the server status to invalid although it will still wait to receive updates. The application can poll the SNTP Client task for server status, and if invalid stop the SNTP Client and reinitialize it with another SNTP broadcast address. It can also switch to a unicast SNTP server.
nx_sntp_client_run_unicast
Run the Client in unicast mode
Description
This service starts the Client in unicast mode where it periodically sends a unicast request to its SNTP Server for a time update. If a valid SNTP message is received, the SNTP client timeout for maximum lapse without an update, initial polling interval and count of consecutive invalid messages received are reset. If the either of these limits are exceeded, the SNTP Client sets the Server status to invalid although it will still poll and wait to receive updates. The application can poll the SNTP Client task for server status, and if invalid stop the SNTP Client and reinitialize it with another SNTP unicast address. It can also switch to a broadcast SNTP server.
nx_sntp_client_set_local_time
Set the SNTP Client local time
Prototype
UINT nx_sntp_client_set_local_time(
NX_SNTP_CLIENT *client_ptr ,
ULONG seconds, ULONG fraction);Description
This service sets the SNTP Client local time with the input time, in SNTP format e.g. seconds and 'fraction' which is the format for putting fractions of a second in hexadecimal format. It is intended for updating the SNTP Client local time from an independent time keeper, e.g. a real time clock. The SNTP protocol is intended for SNTP time updates to keep local clock time from 'drifting'. SNTP server time updates can be, but are not intended to be the sole input to the SNTP Client local time if there is no independent time keeper on the application device.
This API can also be used to give the SNTP Client a base time before starting the SNTP Client thread. The SNTP Client local time is compared to received updates for valid time data. For the first time update received, there might be a very large discrepancy. Therefore there is an option for the SNTP Client to ignore the discrepancy on the first update. In this manner, the SNTP Client can start without a base time. Input time can be obtained from known epoch times (usually available on the Internet) and are computed as the number of seconds since January 1, 1900 (until 2036 when a new 'epoch' will be started.
Input Parameters
-
client_ptr: Pointer to SNTP Client control block
-
seconds: Seconds component of the time input
-
fraction: Subseconds component in the SNTP fraction format
nx_sntp_client_set_time_update_notify
Set the SNTP update callback
Prototype
UINT nx_sntp_client_set_time_update_notify(
NX_SNTP_CLIENT *client_ptr,
VOID (time_update_cb)(
NX_SNTP_TIME_MESSAGE *time_update_ptr,
NX_SNTP_TIME *local_time)));Description
This service sets callback to notify the application when the SNTP Client receives a valid time update. It supplies the actual SNTP message and the SNTP Client’s local time (usually the same) in NTP format. The application can use the NTP data directly or call the nx_sntp_client_utility_display_date_time service to convert the time to human readable format.
Input Parameters
-
client_ptr: Pointer to SNTP Client control block
-
time_update_cb: Pointer to callback function
Example
/* Set the SNTP Client time update callback. */
VOID client_time_update_notify(NX_SNTP_TIME_MESSAGE *time_update_ptr,
NX_SNTP_TIME *local time);
NX_SNTP_CLIENT demo_client;
status = nx_sntp_client_set_time_update_notify(&demo_client,
time_update_cb);
/* If status is NX_SUCCESS an SNTP Client
time update callback was successfully set. */nx_sntp_client_stop
Stop the SNTP Client thread
Description
This service stops the SNTP Client thread. The SNTP Client thread tasks, which runs in an infinite loop, pauses on every iteration to release control of the SNTP Client state and allow applications to make API calls on the SNTP Client.
nx_sntp_client_utility_display_date_time
Convert an NTP Time to Date and Time string
Prototype
UINT nx_sntp_client_utility_display_date_time (
NX_SNTP_CLIENT *client_ptr,
CHAR *buffer,
UINT length);Description
This service converts the SNTP Client local time to a year month date format and returns the date in the supplied buffer. The NX_SNTP_CURRENT_YEAR need not be the same year as the current Client time but it must be defined.
Input Parameters
-
client_ptr Pointer to SNTP Client*
-
buffer: Pointer to buffer to store date
-
length: Size of input buffer
nx_sntp_client_utility_msecs_to_fraction
Convert milliseconds to an NTP fraction component
Description
This service converts the input milliseconds to the NTP fraction component. It is intended for use with applications that have a starting base time for the SNTP Client but not in NTP seconds/fraction format. The number of milliseconds must be less than 1000 to make a valid fraction.
Input Parameters
-
milliseconds: Milliseconds to convert
-
fraction: Pointer to milliseconds converted to fraction
nx_sntp_client_utility_usecs_to_fraction
Convert microseconds to an NTP fraction component
Description
This service converts the input microseconds to the NTP fraction component. It is intended for use with applications that have a starting base time for the SNTP Client but not in NTP seconds/fraction format. The number of microseconds must be less than 1000000 to make a valid fraction.
Input Parameters
-
microseconds: Microseconds to convert
-
fraction: Pointer to microseconds converted to fraction