M2MB SNTP

This section describes the M2MB APIs to perform Simple Network Time Protocol(SNTP) operations. More...

#define	M2MB_SNTP_DEFAULT_SERVER   "pool.ntp.org"
#define	M2MB_SNTP_SERVER_NAME_SIZE   68
#define	M2MB_SNTP_SERVER_MAX   2
#define	M2MB_IP_ADDR_STR_LEN   48
#define	M2MB_SNTP_SYNC_DONE   0x0010
enum	M2MB_SNTP_SERVER_STATUS {   M2MB_SNTP_SERVER_STATUS_KOD = 1,   M2MB_SNTP_SERVER_STATUS_NORESP = 2 }
	Server status enumeration. More...
enum	M2MB_SNTP_SERVER_ID {   M2MB_SNTP_SERVER_ID_PRIMARY,   M2MB_SNTP_SERVER_ID_SECONDARY }
	Server ID enumeration. More...
enum	M2MB_SNTPC_RTC_STATUS_E {   M2MB_SNTPC_EVENT_SYSTEM_RTC_SET,   M2MB_SNTPC_EVENT_SYSTEM_RTC_NOT_SET }
	The enum indicates RTC SYCN status. More...
enum	M2MB_SNTPC_EVENTS_ID_E {   M2MB_SNTPC_EVENT_INIT,   M2MB_SNTPC_EVENT_INCORRECT_SVR_TYPE,   M2MB_SNTPC_EVENT_SYSTEM_SYNC_DONE,   M2MB_SNTPC_EVENT_SERVER_DELETED,   M2MB_SNTPC_EVENT_SERVER_ADDED }
	Events from SNTP module. More...
typedef enum M2MB_SNTP_SERVER_STATUS	M2MB_SNTP_SERVER_STATUS_E
	Server status enumeration. More...
typedef enum M2MB_SNTP_SERVER_ID	M2MB_SNTP_SERVER_ID_E
	Server ID enumeration. More...
typedef struct M2MB_SNTP_SERVER_ENTRY	M2MB_SNTP_SERVER_ENTRY_T
	SNTP server entry structure. More...
typedef struct M2MB_SNTP_SERVER_LIST	M2MB_SNTP_SERVER_LIST_T
	SNTP server list structure. More...
typedef struct M2MB_SNTP_TM	M2MB_SNTP_TM_T
	Time broken down. More...
typedef void(*	M2MB_SNTPC_APP_CB_t) (void *sntpc_ctx, uint32_t event, void *uData)
	User callback to indicate SNTP event. More...
INT32	m2mb_sntp_init (M2MB_SNTPC_APP_CB_t user_cb, void *user_ctx, uint32_t poll_interval)
	m2mb_sntp_init is called to initialize the SNTP user callback and continuous interval. More...
INT32	m2mb_sntp_start (VOID)
	m2mb_sntp_start is called to start SNTP. More...
INT32	m2mb_sntp_is_started (VOID)
	m2mb_sntp_is_started is called to check SNTP status. More...
INT32	m2mb_sntp_deinit (VOID)
	m2mb_sntp_deinit is called to de-initialize SNTP module. More...
INT32	m2mb_sntp_svr_add (M2MB_SNTP_SERVER_ID_E serverID, UINT8 *name)
	m2mb_sntp_svr_add is called to add a SNTP server to get the time. More...
INT32	m2mb_sntp_svr_delete (M2MB_SNTP_SERVER_ID_E serverID)
	m2mb_sntp_svr_delete is called to delete the SNTP server details. More...
INT32	m2mb_sntp_update (VOID)
	m2mb_sntp_update is called to update the system time from SNTP server. More...
INT32	m2mb_sntp_get_time (M2MB_SNTP_TM_T *tm)
	m2mb_sntp_get_time is called to get the current system time. More...
INT32	m2mb_sntp_get_server_list (M2MB_SNTP_SERVER_LIST_T *svr_List)
	m2mb_sntp_get_server_list is called to get the SNTP server list. More...

Detailed Description

This section describes the M2MB APIs to perform Simple Network Time Protocol(SNTP) operations.

Macro Definition Documentation

M2MB_IP_ADDR_STR_LEN

#define M2MB_IP_ADDR_STR_LEN   48

sntp sync done event mask

Definition at line 82 of file m2mb_sntp.h.

M2MB_SNTP_DEFAULT_SERVER

#define M2MB_SNTP_DEFAULT_SERVER   "pool.ntp.org"

< The default SNTP server if the server hostname/address is not specified. Byte length of the SNTP server name (DNS name or IPv4/IPv6 address).

Definition at line 73 of file m2mb_sntp.h.

M2MB_SNTP_SERVER_MAX

#define M2MB_SNTP_SERVER_MAX   2

IP address string length.

Definition at line 79 of file m2mb_sntp.h.

M2MB_SNTP_SERVER_NAME_SIZE

#define M2MB_SNTP_SERVER_NAME_SIZE   68

Maximum number of servers supported

Definition at line 76 of file m2mb_sntp.h.

M2MB_SNTP_SYNC_DONE

#define M2MB_SNTP_SYNC_DONE   0x0010

Definition at line 85 of file m2mb_sntp.h.

Typedef Documentation

M2MB_SNTP_SERVER_ENTRY_T

typedef struct M2MB_SNTP_SERVER_ENTRY M2MB_SNTP_SERVER_ENTRY_T

SNTP server entry structure.

This data structure is used with m2mb_sntp_get_server_list() to get server information.

M2MB_SNTP_SERVER_ID_E

typedef enum M2MB_SNTP_SERVER_ID M2MB_SNTP_SERVER_ID_E

Server ID enumeration.

This enum defines macros for SNTP server ID. This status signifies whether the server to be added is a Primary server or Secondary server.

M2MB_SNTP_SERVER_LIST_T

typedef struct M2MB_SNTP_SERVER_LIST M2MB_SNTP_SERVER_LIST_T

SNTP server list structure.

This data structure is used with m2mb_sntp_get_server_list() to maintain server list information.

M2MB_SNTP_SERVER_STATUS_E

typedef enum M2MB_SNTP_SERVER_STATUS M2MB_SNTP_SERVER_STATUS_E

Server status enumeration.

This enum defines macros for SNTP server status. This status signifies the reply from from the server.

M2MB_SNTP_TM_T

typedef struct M2MB_SNTP_TM M2MB_SNTP_TM_T

Time broken down.

This data structure is used to get the system time in a broken down format.

M2MB_SNTPC_APP_CB_t

typedef void(* M2MB_SNTPC_APP_CB_t) (void *sntpc_ctx, uint32_t event, void *uData)

User callback to indicate SNTP event.

This callback function pointer allows the application to get SNTP event.
This data type should be used to set the event callback to get event from the SNTP by calling sntpc_start.

Parameters

[in]	sntpc_ctx	sntpc_ctx passed by the user when registering the callback with API m2mb_sntp_init
[in]	event	event is event ID of type M2MB_SNTPC_EVENTS_ID_E.
[in]	uData	uData is data for user. User can interpret this based on M2MB_SNTPC_EVENTS_ID_E. If event ID is, M2MB_SNTPC_EVENT_INIT then uData is of type M2MB_STATUS_T. M2MB_SNTPC_EVENT_SYSTEM_SYNC_DONE then uData is of type M2MB_SNTPC_RTC_STATUS_E. others it is NULL.

Example

M2MB_SNTPC_APP_CB_t sntp_user_cb( void *user_ctx, M2MB_SNTPC_EVENTS_ID_E event, void *uData )
{
  user_ctx(event);
  ...
  ...
}

void *user_appln_cb(int event)
{
    ...
    ...
}

int main()
{
    INT32 status = 0;
    uint32_t poll_interval = 0; //(>30);
    void user_ctx = user_appln_cb;
    status =  m2mb_sntp_init(sntp_user_cb, &user_ctx, poll_interval);
}

Returns

returns status.

Definition at line 245 of file m2mb_sntp.h.

Enumeration Type Documentation

M2MB_SNTP_SERVER_ID

enum M2MB_SNTP_SERVER_ID

Server ID enumeration.

This enum defines macros for SNTP server ID. This status signifies whether the server to be added is a Primary server or Secondary server.

Enumerator
M2MB_SNTP_SERVER_ID_PRIMARY	Primary server ID.
M2MB_SNTP_SERVER_ID_SECONDARY	Secondary server ID.

Definition at line 106 of file m2mb_sntp.h.

M2MB_SNTP_SERVER_STATUS

enum M2MB_SNTP_SERVER_STATUS

Server status enumeration.

This enum defines macros for SNTP server status. This status signifies the reply from from the server.

Enumerator
M2MB_SNTP_SERVER_STATUS_KOD	Status of the SNTP server: Sent a KOD
M2MB_SNTP_SERVER_STATUS_NORESP	Status of SNTP server: No reply

Definition at line 94 of file m2mb_sntp.h.

M2MB_SNTPC_EVENTS_ID_E

enum M2MB_SNTPC_EVENTS_ID_E

Events from SNTP module.

This enum defines macros for different types of events involved in the process of SNTP protocol and helpful to user applications.

Note

This enum will be used internally by SNTP protocol implementation.

Enumerator
M2MB_SNTPC_EVENT_INIT	SNTP event carrying Initialization status as user data M2MB_OK or M2MB_ERROR
M2MB_SNTPC_EVENT_INCORRECT_SVR_TYPE	SNTP event on failing to add server because of incorrect server type, AY_UNRESOLVED/AF_UNSPEC/AF_INET/AF_INET6
M2MB_SNTPC_EVENT_SYSTEM_SYNC_DONE	SNTP event on getting UTC time
M2MB_SNTPC_EVENT_SERVER_DELETED
M2MB_SNTPC_EVENT_SERVER_ADDED

Definition at line 137 of file m2mb_sntp.h.

M2MB_SNTPC_RTC_STATUS_E

enum M2MB_SNTPC_RTC_STATUS_E

The enum indicates RTC SYCN status.

This enum is used by M2MB_SNTPC_EVENT_SYSTEM_SYNC_DONE event indicating the RTC status either updated or not.

Note

This enum will be used internally by SNTP protocol implementation.

Enumerator
M2MB_SNTPC_EVENT_SYSTEM_RTC_SET	returned as user data with M2MB_SNTPC_EVENT_SYSTEM_SYNC_DONE event indicating RTC updated
M2MB_SNTPC_EVENT_SYSTEM_RTC_NOT_SET	returned as user data with M2MB_SNTPC_EVENT_SYSTEM_SYNC_DONE event indicating Failed to update RTC due to time-stamp mismatch

Definition at line 121 of file m2mb_sntp.h.

Function Documentation

m2mb_sntp_deinit()

INT32 m2mb_sntp_deinit

(

VOID

)

m2mb_sntp_deinit is called to de-initialize SNTP module.

m2mb_sntp_deinit de-initializes the SNTP module. It frees up all memory allocated during initialization process.

Returns

Returns status.

Note

This API has to be called if the SNTP is already initialized. Example

M2MB_SNTPC_APP_CB_t sntp_user_cb( void *user_ctx, uint32_t event, void *uData )
{
  user_ctx(event);
  ...
  ...
}

void *user_appln_cb(int event)
{
    ...
    ...
}

int main()
{
    INT32 status = 0;
    uint32_t poll_interval = 0; //(>30);
    void user_ctx = user_appln_cb;
    status =  m2mb_sntp_init(sntp_user_cb, user_ctx, poll_interval);

    ...
    status = m2mb_sntp_deinit();
    ...
}  

m2mb_sntp_get_server_list()

INT32 m2mb_sntp_get_server_list

(

M2MB_SNTP_SERVER_LIST_T *

svr_List

)

m2mb_sntp_get_server_list is called to get the SNTP server list.

m2mb_sntp_get_server_list gets the list of configured SNTP servers.

Parameters

[in]

svr_List

Pointer to a buffer to contain the server list.

Returns

Returns M2MB_OK on success, a different value on error.

Note

This API has to be called after m2mb_sntp_start and m2mb_sntp_update API is called.

Example

<C code example>

m2mb_sntp_get_time()

INT32 m2mb_sntp_get_time

(

M2MB_SNTP_TM_T *

tm

)

m2mb_sntp_get_time is called to get the current system time.

m2mb_sntp_get_time gives the current system time.

Parameters

[in]

tm

Pointer to the SNTP time structure to store the current system time.

Returns

Returns M2MB_OK on success, a different value on error.

Note

This API has to be called after m2mb_sntp_start and m2mb_sntp_update API is called or or M2MB_SNTPC_EVENT_SYSTEM_RTC_SET event is called.

Example

M2MB_SNTPC_APP_CB_t sntp_user_cb( void *user_ctx, uint32_t event, void *uData )
{
  user_ctx(event);
  ...
  switch(event)
  {
    ...
    case M2MB_SNTPC_EVENT_SYSTEM_SYNC_DONE:
    {
      int user_data = *(INT32 *)uData;
      if ( user_data == M2MB_SNTPC_EVENT_SYSTEM_RTC_SET )
        status = m2mb_sntp_get_time(&tm);  
      
    }
    break;
    ...

  }
  ...
}

void *user_appln_cb(int event)
{
    ...
    ...
}
extern const M2MB_SYSTEM_CFG_T *pCfg;
int main()
{
    INT32 status = 0;
    uint32_t poll_interval = 0; //(>30);
    void user_ctx = user_appln_cb;
    M2MB_SNTP_TM_T tm = {0};

    status =  m2mb_sntp_init(sntp_user_cb, user_ctx, poll_interval);

    ...
    status = m2mb_sntp_start();
    ...
    status = m2mb_sntp_svr_add( pCfg->sntp.sntp_cfg.serverID, pCfg->sntp.sntp_cfg.serverName );
    ...
    status = m2mb_sntp_update();
    ...

    ...
    status = m2mb_sntp_svr_delete( pCfg->sntp.sntp_cfg.serverID );
}

m2mb_sntp_init()

INT32 m2mb_sntp_init	(	M2MB_SNTPC_APP_CB_t	user_cb,
		void *	user_ctx,
		uint32_t	poll_interval
	)

m2mb_sntp_init is called to initialize the SNTP user callback and continuous interval.

m2mb_sntp_init is called to initialize the SNTP user callback and continuous interval.

Parameters

[in]	user_cb	Callback set by user.
[in]	user_ctx	Pointer to a context set by user.
[in]	poll_interval	Continuous poll interval in seconds, Defaults are 15 seconds for initial and 30 seconds for continuous. If poll_interval is set to 0 than server will be polled only once and SNTP module will be stopped once you receive M2MB_SNTPC_EVENT_SYSTEM_SYNC_DONE event.

Returns

Returns M2MB_OK on success, a different value on error.

Note

This API has to be called before any other SNTP API is called.

Example

M2MB_SNTPC_APP_CB_t sntp_user_cb( void *user_ctx, uint32_t event, void *uData )
{
  user_ctx(event);
  ...
  ...
}

void *user_appln_cb(int event)
{
    ...
    ...
}

int main()
{
    INT32 status = 0;
    uint32_t poll_interval = 0; //(>30);
    void user_ctx = user_appln_cb;
    status =  m2mb_sntp_init(sntp_user_cb, user_ctx, poll_interval);
}

m2mb_sntp_is_started()

INT32 m2mb_sntp_is_started

(

VOID

)

m2mb_sntp_is_started is called to check SNTP status.

m2mb_sntp_is_started checks whether the SNTP client is started.

Returns

0 if not started or 1 if started.

Note

<Notes> Example

M2MB_SNTPC_APP_CB_t sntp_user_cb( void *user_ctx, uint32_t event, void *uData )
{
  user_ctx(event);
  ...
  ...
}

void *user_appln_cb(int event)
{
    ...
    ...
}

int main()
{
    INT32 status = 0;
    uint32_t poll_interval = 0; //(>30);
    void user_ctx = user_appln_cb;
    status =  m2mb_sntp_init(sntp_user_cb, user_ctx, poll_interval);

    ...
    status = m2mb_sntp_start();
    ...
    status = m2mb_sntp_is_started();
    ...
}

m2mb_sntp_start()

INT32 m2mb_sntp_start

(

VOID

)

m2mb_sntp_start is called to start SNTP.

m2mb_sntp_start initializes the SNTP module.

Returns

Returns status.

Note

This API has to be called after m2mb_sntp_init.

Example

M2MB_SNTPC_APP_CB_t sntp_user_cb( void *user_ctx, uint32_t event, void *uData )
{
  user_ctx(event);
  ...
  ...
}

void *user_appln_cb(int event)
{
    ...
    ...
}

int main()
{
    INT32 status = 0;
    uint32_t poll_interval = 0; //(>30);
    void user_ctx = user_appln_cb;
    status =  m2mb_sntp_init(sntp_user_cb, user_ctx, poll_interval);

    ...
    status = m2mb_sntp_start();
    ...
}

m2mb_sntp_svr_add()

INT32 m2mb_sntp_svr_add	(	M2MB_SNTP_SERVER_ID_E	serverID,
		UINT8 *	name
	)

m2mb_sntp_svr_add is called to add a SNTP server to get the time.

m2mb_sntp_svr_add stores the SNTP server address to get the time. The server name can be either an IP address or the hostname of SNTP server. The host name cannot be more than 68 bytes.

If user is passing the hostname then DNS client should have been initialized to fetch the IP address from the hostname.

Parameters

[in]	serverID	User is supposed to pass M2MB_SNTP_SERVER_PRIMARY or M2MB_SNTP_SERVER_SECONDARY to indicate whether the primary or secondary server has to be added.
[in]	name	Pointer to the name of the server. The name can be either hostname or IP address. If hostname is given then the host name can be maximum of 68 bytes length.

Returns

Returns M2MB_OK on success, a different value on error.

Note

This API has to be called after m2mb_sntp_init API is called.

Example

M2MB_SNTPC_APP_CB_t sntp_user_cb( void *user_ctx, uint32_t event, void *uData )
{
  user_ctx(event);
  ...
  ...
}

void *user_appln_cb(int event)
{
    ...
    ...
}

int main()
{
    INT32 status = 0;
    uint32_t poll_interval = 0; //(>30) and 0 for one time poll
    void user_ctx = user_appln_cb;
    status =  m2mb_sntp_init(sntp_user_cb, user_ctx, poll_interval);

    ...
    status = m2mb_sntp_start();
    ...
    status = m2mb_sntp_svr_add( M2MB_SNTP_SERVER_PRIMARY, M2MB_SNTP_DEFAULT_SERVER );
    ...
}

m2mb_sntp_svr_delete()

INT32 m2mb_sntp_svr_delete

(

M2MB_SNTP_SERVER_ID_E

serverID

)

m2mb_sntp_svr_delete is called to delete the SNTP server details.

m2mb_sntp_svr_delete deletes the SNTP server details.

Parameters

[in]

serverID

User is supposed to pass M2MB_SNTP_SERVER_PRIMARY or M2MB_SNTP_SERVER_SECONDARY to indicate whether the primary or secondary server has to be deleted.

Returns

Returns M2MB_OK on success, a different value on error.

Note

This API has to be called after m2mb_sntp_init API is called.

Example

M2MB_SNTPC_APP_CB_t sntp_user_cb( void *user_ctx, uint32_t event, void *uData )
{
  user_ctx(event);
  ...
  ...
}

void *user_appln_cb(int event)
{
    ...
    ...
}
extern const M2MB_SYSTEM_CFG_T *pCfg;
int main()
{
    INT32 status = 0;
    uint32_t poll_interval = 0; //(>30);
    void user_ctx = user_appln_cb;
    status =  m2mb_sntp_init(sntp_user_cb, user_ctx, poll_interval);

    ...
    status = m2mb_sntp_start();
    ...
    status = m2mb_sntp_svr_add( pCfg->sntp.sntp_cfg.serverID, pCfg->sntp.sntp_cfg.serverName );
    ...
    status = m2mb_sntp_svr_delete( pCfg->sntp.sntp_cfg.serverID );
}

m2mb_sntp_update()

INT32 m2mb_sntp_update

(

VOID

)

m2mb_sntp_update is called to update the system time from SNTP server.

m2mb_sntp_update initiates the SNTP procedure and updates the system time.

Note

This API has to be called after m2mb_sntp_init API is called. User has to make sure it has added at least one SNTP server by calling m2mb_sntp_svr_add. Example

M2MB_SNTPC_APP_CB_t sntp_user_cb( void *user_ctx, uint32_t event, void *uData )
{
  user_ctx(event);
  ...
  ...
}

void *user_appln_cb(int event)
{
    ...
    ...
}
extern const M2MB_SYSTEM_CFG_T *pCfg;
int main()
{
    INT32 status = 0;
    uint32_t poll_interval = 0; //(>30);
    void user_ctx = user_appln_cb;
    status =  m2mb_sntp_init(sntp_user_cb, user_ctx, poll_interval);

    ...
    status = m2mb_sntp_start();
    ...
    status = m2mb_sntp_svr_add( pCfg->sntp.sntp_cfg.serverID, pCfg->sntp.sntp_cfg.serverName );
    ...
    status = m2mb_sntp_update();
    ...
    status = m2mb_sntp_svr_delete( pCfg->sntp.sntp_cfg.serverID );
}