SNTP Client Events

An SNTP client association is created by calling tfSntpUserCreate(), which receives a pointer to a callback function of type ttUserSntpCBFuncPtr() that you provide. Treck SNTP will call your function when any of the following events occur.

SNTP Client Callback Events

Event Name	Context	Parameter Type	Description
TM_SNTP_EVENT_SLEW	tfSntpUserExecute	struct timeval TM_FAR * (offset from local clock)	A time update message was received from the server. The local clock offset was below the step threshold, set with option TM_SNTP_OPT_STEP_TIME, default 0.2s. The parameter contains the relative offset from the local clock—a signed value to be added to the local clock, e.g. clock += (double)(long)tvPtr->tv_sec + ((double)tvPtr->tv_usec * 1e-6). Application note: you may wish to set your step threshold to your maximum clock error tolerance such that you can ignore all slew events.
TM_SNTP_EVENT_STEP	tfSntpUserExecute	struct timeval TM_FAR * (offset from Jan 1, 1970)	A time update message was received from the server. The local clock offset was between the step threshold and the panic threshold, set with options TM_SNTP_OPT_STEP_TIME and TM_SNTP_OPT_PANIC_TIME, default 0.2s and 1000s, respectively. The parameter contains the absolute offset from January 1, 1970—the clock value to be set, e.g. clock = (double)(unsigned long)tvPtr->tv_sec + ((double)tvPtr->tv_usec * 1e-6).
TM_SNTP_EVENT_PANIC	tfSntpUserExecute	struct timeval TM_FAR * (offset from Jan 1, 1970)	A time update message was received from the server. The local clock offset was above the panic threshold, set with option TM_SNTP_OPT_PANIC_TIME, default 1000s. The parameter contains the absolute offset from January 1, 1970—the clock value to be set, e.g. clock = (double)(unsigned long)tvPtr->tv_sec + ((double)tvPtr->tv_usec * 1e-6). On a typical O/S, a panic event would cause the SNTP client to terminate with an error. Treck SNTP takes no action on a panic event and leaves the decision on what to do up to the application. If an embedded system starts with no knowledge of the current time, you will likely get this event on the first update.
TM_SNTP_EVENT_KISS	tfSntpUserExecute	char TM_FAR * or ttUser32Bit TM_FAR *	A kiss-o-death status message was received from the server with a kiss code in the 32-bit Reference Id field of the message. The value should be nul terminated ASCII characters but there is no guarantee. The parameter paramPtr points to the string/value. A full list of kiss codes can be found in RFC 5905, section 7.4. A few important codes can be found in the table below. The RFC dictates that recipients of kiss codes MUST inspect them and take appropriate action (see the Receiving a Kiss-o-Death message section). Treck SNTP takes no action upon receiving a kiss-o-death message and leaves the decision on what to do up to the application.
TM_SNTP_EVENT_ERROR	tfSntpUserExecute	int TM_FAR *	(Blocking mode only) An error occurred that is not severe enough to cause an exit from tfSntpUserExecute(). The parameter *paramPtr is the Treck error code. The decision on what action to take is left up to the application. (Note: for non-blocking mode, errors are returned from tfSntpUserExecute().)
TM_SNTP_EVENT_SOCKET	Receive Task, Socket Callback	NULL	(Non-blocking mode only) A socket event occurred, e.g. message received. In non-blocking mode, the application calls tfSntpUserExecute() periodically to perform any outstanding work, in which case, you may ignore this event. If you need faster response to events, use this event to know exactly when you need to call tfSntpUserExecute(). However, do not call tfSntpUserExecute() from this context, as it will impact all sockets. Set a flag to tell your main task or event loop to call tfSntpUserExecute().
TM_SNTP_EVENT_TIMER	Timer Task, Timer Callback	NULL	(Non-blocking mode only) A timer event occurred, e.g. poll interval expired. In non-blocking mode, the application calls tfSntpUserExecute() periodically to perform any outstanding work, in which case, you may ignore this event. If you need faster response to events, use this event to know exactly when you need to call tfSntpUserExecute(). However, do not call tfSntpUserExecute() from this context, as it will impact all timers. Set a flag to tell your main task or event loop to call tfSntpUserExecute().