Control Interface

Functions to start the SNTP Client. More...

Typedefs
typedef void(*	netSNTPc_cb_t) (uint32_t seconds, uint32_t seconds_fraction)
	SNTP Client callback function. More...

Functions
netStatus	netSNTPc_GetTime (const NET_ADDR *addr, netSNTPc_cb_t cb_func)
	Determine current time from NTP or SNTP time server. [thread-safe]. More...
netStatus	netSNTPc_GetTimeX (const char *server, uint32_t *seconds, uint32_t *seconds_fraction)
	Determine current time from NTP or SNTP time server in blocking mode. [thread-safe]. More...
netStatus	netSNTPc_SetMode (netSNTPc_Mode mode)
	Set mode of operation for SNTP client. [thread-safe]. More...

Description

Functions to start the SNTP Client.

The SNTP Client is started by calling the function netSNTPc_GetTime. In unicast mode, SNTP client requests the UTC coded time from the SNTP time server specified by the IP address. You must specify a callback function, which is called from the SNTP Client when the session ends. This callback function will carry the UTC coded time stamp. In broadcast mode, SNTP Client opens UDP port for receiving broadcasted NTP messages in local network.

Typedef Documentation

netSNTPc_cb_t

void(* netSNTPc_cb_t)(uint32_t seconds, uint32_t seconds_fraction)

SNTP Client callback function.

Parameters

[in]	seconds	time in seconds,
[in]	seconds_fraction	fraction of seconds.

Returns

none.

Is the type definition for the SNTP callback function. Users must provide the function. The function is called by the SNTP client when an NTP message is received from the server.

The seconds argument of the callback function signals the time, specified in seconds, elapsed since 1.1.1970 (Unix epoch). A value of 0 reports an error.

The argument seconds_fraction signals the fraction of seconds.

Parameter for:

• netSNTPc_GetTime

Function Documentation

netSNTPc_GetTime()

netStatus netSNTPc_GetTime	(	const NET_ADDR *	addr,
		netSNTPc_cb_t	cb_func
	)

Determine current time from NTP or SNTP time server. [thread-safe].

Parameters

[in]	addr	structure containing IP address of NTP or SNTP server. NULL to use NTP server IP address from system configuration.
[in]	cb_func	callback function to call, when the session ends.

Returns

status code that indicates the execution status of the function.

In unicast mode, the non-blocking function netSNTPc_GetTime sends a get time request to NTP server specified with the argument addr. If the IP address is not specified (addr is NULL), then the IP address of the NTP Server configured in Net_Config_SNTP_Client.h is used.

In broadcast mode, it opens an UDP socket for receiving broadcast NTP messages. You can use broadcast mode, if you have a broadcasting NTP server in your local network. NTP messages that come from the specified NTP server are accepted. Messages that come from a different NTP server are ignored. If the specified NTP server address is unknown address (0.0.0.0), then messages from any NTP server are accepted.

The argument addr is a pointer to the structure containing the IP address and port of a local or public NTP server.

If the IP address is not specified (addr is NULL), then the IP address of the NTP Server configured in Net_Config_SNTP_Client.h is used. Broadcast Mode gets also enabled here.

The argument cb_func points to a user-defined callback function called by the SNTP client when an NTP message is received from the server. Refer to netSNTPc_cb_t.

Possible netStatus return values:

• netOK: Operation completed successfully.
• netInvalidParameter: Invalid or not supported parameter.
• netWrongState: SNTP client state incorrect for the current operating mode.
• netServerError: NTP or SNTP server IP address undefined.

Code Example

const NET_ADDR4 ntp_server = { NET_ADDR_IP4, 0, 217, 79, 179, 106 };
static void time_callback (uint32_t seconds, uint32_t seconds_fraction);
 
void get_time (void) {
  if (netSNTPc_GetTime ((NET_ADDR *)&ntp_server, time_callback) == netOK) {
    printf ("SNTP request sent.\n");
  }
  else {
    printf ("SNTP not ready or bad parameters.\n");
  }
}
 
static void time_callback (uint32_t seconds, uint32_t seconds_fraction) {
  if (seconds == 0) {
    printf ("Server not responding or bad response.\n");
  }
  else {
    printf ("%d seconds elapsed since 1.1.1970\n", seconds);
  }
}

netSNTPc_GetTimeX()

netStatus netSNTPc_GetTimeX	(	const char *	server,
		uint32_t *	seconds,
		uint32_t *	seconds_fraction
	)

Determine current time from NTP or SNTP time server in blocking mode. [thread-safe].

Parameters

[in]	server	server name or absolute IP address (FQDN or IP address). NULL to use NTP server IP address from system configuration.
[out]	seconds	pointer to the variable to return time in seconds.
[out]	seconds_fraction	pointer to the variable to return fraction of seconds. NULL for none.

Returns

status code that indicates the execution status of the function.

The blocking function netSNTPc_GetTimeX sends a get time request to NTP server specified with the argument server and returns current time retrieved from the server. If the address is not specified (server is NULL), then the IP address of the NTP Server configured in Net_Config_SNTP_Client.h is used.

The argument server is a fully qualified domain name or an absolute IP address of a local or public NTP server. If server is a hostname, the client uses the DNS resolver to resolve the destination IP address.

The argument seconds points to a user-provided variable, that will receive the time in seconds from the server.

The argument seconds_fraction points to a user-provided variable, that will receive the fraction of seconds. If the pointer is not specified (seconds_fraction is NULL), then the fraction of seconds is not returned.

Possible netStatus return values:

• netOK: Operation completed successfully.
• netInvalidParameter: Invalid or not supported parameter.
• netWrongState: SNTP client is busy in unicast mode.
• netDnsResolverError: DNS host resolver failed.
• netServerError: NTP or SNTP server IP address undefined.
• netError: Operation failed, returned time is not valid.

Note

• To use this function, you must enable the DNS client in the selection of RTE Components.
• The netSNTPc_GetTimeX function only works in unicast mode. Use the netSNTPc_GetTime for the broadcast mode.

Code Example

uint32_t ctime;
 
if (netSNTPc_GetTimeX ("time1.google.com", &ctime, NULL) == netOK) {
  printf ("%d seconds elapsed since 1.1.1970\n", ctime);
}
else {
  printf ("SNTP not ready or bad parameters.\n");
}

netSNTPc_SetMode()

netStatus netSNTPc_SetMode

(

netSNTPc_Mode

mode

)

Set mode of operation for SNTP client. [thread-safe].

Parameters

[in]

mode

SNTP client operation mode.

Returns

status code that indicates the execution status of the function.

The function netSNTPc_SetMode changes the operation mode of the SNTP client to unicast mode or broadcast mode. It is used to change the operation mode of SNTP client when the client is running.

The argument mode specifies the operation mode to change to.

Possible netStatus return values:

• netOK: Operation mode successfully set up.
• netInvalidParameter: Invalid operation mode provided.
• netWrongState: SNTP client is busy.

Code Example

netSNTPc_SetMode (netSNTPc_ModeBroadcast);