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.
Create an SNTP Client
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));
This service creates an SNTP Client instance.
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
Initialization, Threads
/* 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. */
Delete an SNTP Client
UINT nx_sntp_client_delete(NX_SNTP_CLIENT *client_ptr);
This service deletes an SNTP Client instance.
NX_SUCCESS (0x00) Successful Client creation
NX_PTR_ERROR (0x07) Invalid pointer input
NX_CALLER_ERROR (0x11) Invalid caller of service
Threads
/* Delete the SNTP Client. */
status = nx_sntp_client_delete(&demo_client);
/* If status is NX_SUCCESS an SNTP Client
instance was successfully deleted. */
Get the SNTP Client local time
UINT nx_sntp_client_get_local_time(
NX_SNTP_CLIENT *client_ptr ,
ULONG *seconds,
ULONG *fraction,
CHAR *buffer);
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().
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_SUCCESS (0x00) Successful Client creation
NX_PTR_ERROR (0x07) Invalid pointer input
NX_CALLER_ERROR (0x11) Invalid caller of service
Threads
/* Get the SNTP Client local time without the
string message option. */
ULONG base_seconds;
ULONG base_fraction;
status = nx_sntp_client_get_local_time(&demo_client,
&base_seconds,
&base_fraction,
NX_NULL);
/* If status is NX_SUCCESS an SNTP Client time was successfully
retrieved. */
Get the extended SNTP Client local time
UINT nx_sntp_client_get_local_time_extended(
NX_SNTP_CLIENT *client_ptr,
ULONG *seconds,
ULONG *fraction,
CHAR *buffer
UINT buffer_size);
This service gets the extended SNTP Client local time with an option buffer pointer input to receive the data in string message format.
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
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
Threads
/* 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. */
Initialize the Client for broadcast operation
UINT nx_sntp_client_initialize_broadcast(
NX_SNTP_CLIENT *client_ptr,
ULONG multicast_server_address,
ULONG broadcast_time_servers);
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.
client_ptr: Pointer to SNTP Client control block
multicast_server_address: SNTP multicast address
broadcast_time_server: SNTP server broadcast address
NX_SUCCESS (0x00) Successful Client Creation
NX_INVALID_PARAMETERS (0x4D) Invalid non pointer input
NX_PTR_ERROR (0x07) Invalid pointer input
NX_CALLER_ERROR (0x11) Invalid caller of service
Initialization, Threads
/* Initialize the client for broadcast operation. */
status = nx_sntp_client_initialize_broadcast(client_ptr,0x0,
NX_NULL, IP_ADDRESS(192,2,2,255);
/* If status is NX_SUCCESS the Client
was successfully initialized. */
Initialize the Client for IPv4 or IPv6 broadcast operation
UINT nxd_sntp_client_initialize_broadcast(
NX_SNTP_CLIENT *client_ptr,
NXD_ADDRESS *multicast_server_address,
NXD_ADDRESS *broadcast_server_address);
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.
client_ptr: Pointer to SNTP Client control block
multicast_server_address: SNTP server multicast address
broadcast_server_address: SNTP server broadcast address
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
Initialization, Threads
/* 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. */
Set up the SNTP Client to run in unicast
UINT nx_sntp_client_initialize_unicast(
NX_SNTP_CLIENT * client_ptr,
ULONG unicast_time_server);
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.
client_ptr: Pointer to SNTP Client control block
unicast_time_server: SNTP server IP address
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
Initialization, Threads
/* Initialize the Client for unicast operation. */
status = nx_sntp_client_initialize_unicast(&client_ptr,
IP_ADDRESS(192,2,2,1));
/* If status is NX_SUCCESS the Client
is initialized for unicast operation. */
Set up the SNTP Client to run in IPv4 or IPv6 unicast
UINT nxd_sntp_client_initialize_unicast(
NX_SNTP_CLIENT * client_ptr,
NXD_ADDRESS *unicast_time_server);
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.
client_ptr: Pointer to SNTP Client control block
unicast_time_server: SNTP server IP address
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
Initialization, Threads
/* 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. */
Indicate if Client is receiving valid updates
UINT nx_sntp_client_receiving_updates(
NX_SNTP_CLIENT *client_ptr,
UINT *receive_status);
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.
client_ptr: Pointer to SNTP Client control block.
receive_status: Pointer to indicator if Client is receiving valid updates.
NX_SUCCESS (0x00) Client successfully received update status
NX_PTR_ERROR (0x07) Invalid pointer input
Initialization, Threads
/* Determine if the SNTP Client is receiving valid updates. */
UINT receive_status;
status = nx_sntp_client_receiving_updates(client_ptr,
&receive_status);
/* If status is NX_SUCCESS and receive_status is NX_TRUE,
the client is currently receiving valid updates. */
Send a unicast request directly to the NTP Server
UINT nx_sntp_client_request_unicast_time(
NX_SNTP_CLIENT *client_ptr,
UINT wait_option);
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.
client_ptr: Pointer to SNTP Client control block.
Wait_option: Wait option for NTP response in timer ticks.
NX_SUCCESS (0x00) Client successfully sends and receives unicast update
NX_SNTP_CLIENT_NOT_STARTED (0xD0B) Client thread not started
NX_PTR_ERROR (0x07) Invalid pointer input
NX_CALLER_ERROR (0x11) Invalid caller of service
Threads
/* Determine if the SNTP Client is receiving valid updates. */
UINT receive_status;
status = nx_sntp_client_request_unicast_time(client_ptr, 400);
/* If status is NX_SUCCESS and receive_status is NX_TRUE,
the client is received a valid response to the unicast request. */
Run the Client in broadcast mode
UINT nx_sntp_client_run_broadcast(NX_SNTP_CLIENT *client_ptr);
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.
status Actual completion status
NX_SNTP_CLIENT_ALREADY_STARTED (0xD0C) Client already started
NX_SNTP_CLIENT_NOT_INITIALIZED (0xD01) Client not initialized
NX_PTR_ERROR (0x07) Invalid pointer input
NX_CALLER_ERROR (0x11) Invalid caller of service
Threads
/* Start Client running in broadcast mode. */
status = nx_sntp_client_run_broadcast(client_ptr);
/* If status is NX_SUCCESS, the client is successfully started. */
Run the Client in unicast mode
UINT nx_sntp_client_run_unicast(NX_SNTP_CLIENT *client_ptr);
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_SUCCESS (0x00) Successfully started Client in unicast mode
NX_SNTP_CLIENT_ALREADY_STARTED (0xD0C) Client already started
NX_SNTP_CLIENT_NOT_INITIALIZED (0xD01) Client not initialized
NX_PTR_ERROR (0x07) Invalid pointer input
NX_CALLER_ERROR (0x11) Invalid caller of service
Threads
/* Start the Client in unicast mode. */
status = nx_sntp_client_run_unicast(client_ptr);
/* If status = NX_SUCCESS, the Client was successfully started. */
Set the SNTP Client local time
UINT nx_sntp_client_set_local_time(
NX_SNTP_CLIENT *client_ptr ,
ULONG seconds, ULONG fraction);
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.
client_ptr: Pointer to SNTP Client control block
seconds: Seconds component of the time input
fraction: Subseconds component in the SNTP fraction format
NX_SUCCESS (0x00) Successfully set local time
NX_PTR_ERROR (0x07) Invalid pointer input
Initialization
/* Set the SNTP Client local time. */
base_seconds = 0xd2c50b71;
base_fraction = 0xa132db1e;
status = nx_sntp_client_set_local_time(&demo_client,
base_seconds,
base_fraction);
/* If status is NX_SUCCESS an SNTP Client time
was successfully set. */
Set the SNTP update callback
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)));
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.
client_ptr: Pointer to SNTP Client control block
time_update_cb: Pointer to callback function
NX_SUCCESS (0x00) Successfully set callback
NX_PTR_ERROR (0x07) Invalid pointer input
Initialization
/* 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. */
Stop the SNTP Client thread
UINT nx_sntp_client_stop(NX_SNTP_CLIENT *client_ptr);
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_SUCCESS (0x00) Successful stopped Client thread
NX_SNTP_CLIENT_NOT_STARTED (0xDB) SNTP Client thread not started
NX_PTR_ERROR (0x07) Invalid pointer input
Initialization, Threads
/* Stop the SNTP Client. */
status = nx_sntp_client_stop(&demo_client);
/* If status is NX_SUCCESS an SNTP
Client instance was successfully stopped. */
Convert an NTP Time to Date and Time string
UINT nx_sntp_client_utility_display_date_time (
NX_SNTP_CLIENT *client_ptr,
CHAR *buffer,
UINT length);
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.
*client_ptr Pointer to SNTP Client**
buffer: Pointer to buffer to store date
length: Size of input buffer
NX_SUCCESS (0x00) Successful conversion
NX_SNTP_ERROR_CONVERTING_DATETIME (0xD08) NX_SNTP_CURRENT_YEAR not defined or no local client time established
NX_SNTP_INVALID_DATETIME_BUFFER (0xD07) Insufficient buffer length
Initialization, Threads
/* Convert and display the Client's local time. */
status = nx_sntp_client_utility_display_date_time(client_ptr ,
buffer, sizeof(buffer));
/* If status is NX_SUCCESS,
date was successfully written to buffer. */
Convert milliseconds to an NTP fraction component
UINT nx_sntp_client_utility_msecs_to_fraction (
ULONG milliseconds,
ULONG *fraction);
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.
milliseconds: Milliseconds to convert
fraction: Pointer to milliseconds converted to fraction
NX_SUCCESS (0x00) Successful conversion
NX_SNTP_OVERFLOW_ERROR (0xD32) Error converting time to a date
NX_SNTP_INVALID_TIME (0xD30) Invalid SNTP data input
Initialization, Threads
/* Convert the milliseconds to a fraction. */
status = nx_sntp_client_utility_msecs_to_fraction(milliseconds,
&fraction);
/* If status is NX_SUCCESS,
data was successfully converted. */
Convert microseconds to an NTP fraction component
UINT nx_sntp_client_utility_usecs_to_fraction (
ULONG microseconds,
ULONG *fraction);
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.
microseconds: Microseconds to convert
fraction: Pointer to microseconds converted to fraction
NX_SUCCESS (0x00) Successful conversion
NX_SNTP_OVERFLOW_ERROR (0xD32) Error converting time to a date
NX_SNTP_INVALID_TIME (0xD30) Invalid SNTP data input
Initialization, Threads
/* Convert the microseconds to a fraction. */
status = nx_sntp_client_utility_msecs_to_fraction(microseconds,
&fraction);
/* If status is NX_SUCCESS, data was successfully converted. */
Convert an NTP fraction component to microseconds
UINT nx_sntp_client_utility_fraction_to_usecs(
ULONG fraction,
ULONG *microseconds);
This service converts the input NTP fraction component to microseconds.
fraction: Fraction to convert
microseconds: Pointer to fraction converted to microseconds
NX_SUCCESS (0x00) Successful conversion
NX_SNTP_INVALID_TIME (0xD30) Invalid SNTP data input
Initialization, Threads
/* Convert the fraction to microseconds. */
status = nx_sntp_client_utility_fraction_to_msecs(fraction,
µseconds);
/* If status is NX_SUCCESS, data was successfully converted. */