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_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,   M2MB_SNTPC_EVENT_SYNC_FAIL }
	Events from SNTP module. More...
enum	M2MB_SNTP_CONF_ID {   M2MB_SNTP_CONF_INVALID = 0,   M2MB_SNTP_CONF_SET_SRV_ADD = 1,   M2MB_SNTP_CONF_SET_SRV_DEL = 2,   M2MB_SNTP_CONF_GET_IS_STARTED = 4,   M2MB_SNTP_CONF_GET_TIME = 5,   M2MB_SNTP_CONF_GET_SERVER_LIST = 6 }
	SNTP GET/SET Configuration enumeration. 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 enum M2MB_SNTP_CONF_ID	M2MB_SNTP_CONF_ID_E
	SNTP GET/SET Configuration 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 event, VOID *uData)
	User callback to indicate SNTP event. More...
typedef struct M2MB_SNTP_SRV_ADD_INFO	M2MB_SNTP_SRV_ADD_INFO_T
	Structure is used by the Configuration ID M2MB_SNTP_CONF_SET_SRV_ADD to configure the given sntp server information. More...
typedef struct M2MB_SNTP_INIT_PARAMS	M2MB_SNTP_INIT_PARAMS_T
	SNTP initialization parameters. More...
M2MB_STATUS_T	m2mb_sntp_init (HANDLE *handle, M2MB_SNTP_INIT_PARAMS_T *init_params)
	m2mb_sntp_init is called to initialize the SNTP user callback and continuous interval. More...
M2MB_STATUS_T	m2mb_sntp_deinit (HANDLE handle)
	m2mb_sntp_deinit is called to de-initialize SNTP module. More...
M2MB_STATUS_T	m2mb_sntp_set_cfg (HANDLE handle, M2MB_SNTP_CONF_ID_E conf_id, M2MB_SNTP_CONF_PARAMS_T *conf_params)
	SET the SNTP configuration parameters. More...
M2MB_STATUS_T	m2mb_sntp_get_cfg (HANDLE handle, M2MB_SNTP_CONF_ID_E conf_id, M2MB_SNTP_CONF_PARAMS_T *conf_params)
	GET the SNTP configuration parameters. More...
M2MB_STATUS_T	m2mb_sntp_start (HANDLE handle)
	m2mb_sntp_start is called to start to send the sntp client request to the sntp server. More...
M2MB_STATUS_T	m2mb_sntp_update (HANDLE handle)
	m2mb_sntp_update is called to update the system time from SNTP server. More...

Detailed Description

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

SNTP

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_CONF_ID_E

typedef enum M2MB_SNTP_CONF_ID M2MB_SNTP_CONF_ID_E

SNTP GET/SET Configuration enumeration.

This enum defines macros for various GET/SET Configuration for SNTP module.

M2MB_SNTP_INIT_PARAMS_T

typedef struct M2MB_SNTP_INIT_PARAMS M2MB_SNTP_INIT_PARAMS_T

SNTP initialization parameters.

Contains information needed to initialize the SNTP module, such as user callback, user context and poll interval.

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_SRV_ADD_INFO_T

typedef struct M2MB_SNTP_SRV_ADD_INFO M2MB_SNTP_SRV_ADD_INFO_T

Structure is used by the Configuration ID M2MB_SNTP_CONF_SET_SRV_ADD to configure the given sntp server information.

Structure is used by the Configuration ID M2MB_SNTP_CONF_SET_SRV_ADD to configure the given sntp server ip address at the server id.

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 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_STATUS_T. others it is NULL.

Example

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

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

Returns

returns status.

Definition at line 244 of file m2mb_sntp.h.

Enumeration Type Documentation

M2MB_SNTP_CONF_ID

enum M2MB_SNTP_CONF_ID

SNTP GET/SET Configuration enumeration.

This enum defines macros for various GET/SET Configuration for SNTP module.

Enumerator
M2MB_SNTP_CONF_INVALID
M2MB_SNTP_CONF_SET_SRV_ADD	ONLY SET CONF, calls to add server API
M2MB_SNTP_CONF_SET_SRV_DEL	ONLY SET CONF, calls to delete the server API
M2MB_SNTP_CONF_GET_IS_STARTED	ONLY GET CONF, checks the SNTP module is started
M2MB_SNTP_CONF_GET_TIME	ONLY GET CONF, gives the time set by sntp module, needs to be used after m2mb_sntp_start_sync API is called
M2MB_SNTP_CONF_GET_SERVER_LIST	ONLY GET CONF, gives the list of the servers

Definition at line 139 of file m2mb_sntp.h.

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	SNTP event notifies on deleting server
M2MB_SNTPC_EVENT_SERVER_ADDED	SNTP event notifies on adding server
M2MB_SNTPC_EVENT_SYNC_FAIL	SNTP event notifies SNTP time synchronization failure

Definition at line 121 of file m2mb_sntp.h.

Function Documentation

m2mb_sntp_deinit()

M2MB_STATUS_T m2mb_sntp_deinit

(

HANDLE

handle

)

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.

Parameters

[in]

handle

Specifies the context handle initialized by m2mb_sntp_init API.

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 )
{
  if(user_ctx)
  user_ctx(event);
  ...
  ...
}

int main()
{
    INT32 status = 0;
    HANDLE handle = NULL;
    M2MB_SNTP_INIT_PARAMS_T sntp_init = {0};
    
    sntp_init.user_cb = sntp_user_cb; 
    sntp_init.user_ctx = NULL; 
    sntp_init.poll_interval = 0;

    status =  m2mb_sntp_init( &handle, sntp_init );
    if( status == M2MB_ERROR )
    {
      return M2MB_ERROR;
    }

    ...
    status = m2mb_sntp_deinit( handle );
    if( status == M2MB_ERROR )
    {
      return M2MB_ERROR;
    }

    ...
}

m2mb_sntp_get_cfg()

M2MB_STATUS_T m2mb_sntp_get_cfg	(	HANDLE	handle,
		M2MB_SNTP_CONF_ID_E	conf_id,
		M2MB_SNTP_CONF_PARAMS_T *	conf_params
	)

GET the SNTP configuration parameters.

This API is called to get the configuration of the SNTP module based on the conf IDs.

Parameters

[in]	handle	Specifies the pointer to the context handle initialized by m2mb_sntp_init API.
[in]	conf_id	GET configuration ID form enum M2MB_SNTP_CONF_ID_E.
[in]	conf_params	configuration params to be passed according to the configuration required.

Returns

Returns M2MB_OK on success, M2MB_ERROR on failure.

Note

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

int main()
{
    INT32 status = 0;        
    HANDLE handle = NULL;
    M2MB_SNTP_INIT_PARAMS_T sntp_init = {0};

    sntp_init.user_cb = sntp_user_cb; 
    sntp_init.user_ctx = NULL; 
    sntp_init.poll_interval = 0;

    status =  m2mb_sntp_init( &handle, sntp_init );
    if( status == M2MB_ERROR )
{
      return M2MB_ERROR;
    }

  ...

    status = m2mb_sntp_start( handle );
    if( status == M2MB_ERROR )
    {
      return M2MB_ERROR;
    }

  ...

    //To add the server
    M2MB_SNTP_SRV_ADD_INFO_T server_info = {0};
    server_info.ipAddr = "8.8.8.8";
    server_info.serverID = M2MB_SNTP_SERVER_PRIMARY;

    M2MB_SNTP_CONF_PARAMS_T sntp_conf;
    sntp_conf.srv_info = &server_info;
    status = m2mb_sntp_set_cfg( handle, M2MB_SNTP_CONF_SET_SRV_ADD, &sntp_conf );
    if( status == M2MB_ERROR )
{
      return M2MB_ERROR;
}

    // Get the server list
    M2MB_SNTP_SERVER_LIST_T srv_list = {0};          
    M2MB_SNTP_CONF_PARAMS_T sntp_conf = {0};
    sntp_conf.get_srv_list = &srv_list;
    status = m2mb_sntp_get_cfg( handle, M2MB_SNTP_CONF_GET_SERVER_LIST, &sntp_conf );
    if( status == M2MB_ERROR )
{
      return M2MB_ERROR;
    }
}    

m2mb_sntp_init()

M2MB_STATUS_T m2mb_sntp_init	(	HANDLE *	handle,
		M2MB_SNTP_INIT_PARAMS_T *	init_params
	)

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]	handle	Specifies the pointer to the context handle that can be used by other SNTP APIs.
[in]	init_params	Initialization parameters required for SNTP module initialization.

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 )
{
  if(user_ctx)
  user_ctx(event);
  ...
  ...
}

int main()
{
    INT32 status = 0;
    HANDLE handle = NULL;
    M2MB_SNTP_INIT_PARAMS_T sntp_init = {0};

    sntp_init.user_cb = sntp_user_cb; 
    sntp_init.user_ctx = NULL;
    sntp_init.poll_interval = 0;
    
    status =  m2mb_sntp_init( &handle, &sntp_init );
    if( status == M2MB_OK )
    {
        return M2MB_OK;
    }
    else
    {
        return M2MB_ERROR;
    }
}

m2mb_sntp_set_cfg()

M2MB_STATUS_T m2mb_sntp_set_cfg	(	HANDLE	handle,
		M2MB_SNTP_CONF_ID_E	conf_id,
		M2MB_SNTP_CONF_PARAMS_T *	conf_params
	)

SET the SNTP configuration parameters.

This API is called to configure the SNTP module based on the conf IDs.

Parameters

[in]	handle	Specifies the pointer to the context handle initialized by m2mb_sntp_init API.
[in]	conf_id	SET configuration ID form enum M2MB_SNTP_CONF_ID_E.
[in]	conf_params	configuration params to be passed according to the configuration to be done. To add the server, use conf ID M2MB_SNTP_CONF_SET_SRV_ADD need to pass the server name and server ID with M2MB_SNTP_SRV_ADD_INFO_T *srv_info of the M2MB_SNTP_CONF_PARAMS_T. To deleve the server, use conf ID M2MB_SNTP_CONF_SET_SRV_DEL and need to pass the infomation serverID of the M2MB_SNTP_CONF_PARAMS_T

Returns

Returns M2MB_OK on success, M2MB_ERROR on failure.

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 )
{
  if(user_ctx)
  user_ctx(event);
  ...
  ...
}

int main()
{
    INT32 status = 0;
    HANDLE handle = NULL;
    M2MB_SNTP_INIT_PARAMS_T sntp_init = {0};

    sntp_init.user_cb = sntp_user_cb; 
    sntp_init.user_ctx = NULL; 
    sntp_init.poll_interval = 0;

    status =  m2mb_sntp_init( &handle, sntp_init );
    if( status == M2MB_ERROR )
    {
      return M2MB_ERROR;
}

    ...

    status = m2mb_sntp_start( handle );
    if( status == M2MB_ERROR )
    {
      return M2MB_ERROR;
    }

    ...

    //To add the server
    M2MB_SNTP_SRV_ADD_INFO_T server_info = {0};
    server_info.ipAddr = "8.8.8.8";
    server_info.serverID = M2MB_SNTP_SERVER_PRIMARY;

    M2MB_SNTP_CONF_PARAMS_T sntp_conf = {0};
    sntp_conf.srv_info = &server_info;
    status = m2mb_sntp_set_cfg( handle, M2MB_SNTP_CONF_SET_SRV_ADD, &sntp_conf );
    if( status == M2MB_ERROR )
{
      return M2MB_ERROR;
}

    //To delete the server
    M2MB_SNTP_CONF_PARAMS_T sntp_conf = {0};
    sntp_conf.serverID = M2MB_SNTP_SERVER_PRIMARY;
    status = m2mb_sntp_set_cfg( handle, M2MB_SNTP_CONF_SET_SRV_DEL, &sntp_conf );
    if( status == M2MB_ERROR )
{
      return M2MB_ERROR;
    }
}

m2mb_sntp_start()

M2MB_STATUS_T m2mb_sntp_start

(

HANDLE

handle

)

m2mb_sntp_start is called to start to send the sntp client request to the sntp server.

m2mb_sntp_start starts to send the sntp client request to the sntp server.

Returns

Returns M2MB_OK on success, M2MB_ERROR on failure.

Note

This API has to be called after m2mb_sntp_init API.

Example

M2MB_SNTPC_APP_CB_T sntp_user_cb( void *user_ctx, uint32_t event, void *uData )
{
  if(user_ctx)
  user_ctx(event);
  ...
  ...
}
int main()
{
    INT32 status = 0;
    HANDLE handle = NULL;
    M2MB_SNTP_INIT_PARAMS_T sntp_init = {0};

    sntp_init.user_cb = sntp_user_cb; 
    sntp_init.user_ctx = NULL; 
    sntp_init.poll_interval = 0;

    status =  m2mb_sntp_init( &handle, sntp_init );
    if( status == M2MB_ERROR )
    {
      return M2MB_ERROR;
    }

    ...
    
    status = m2mb_sntp_start( handle );
    if( status == M2MB_ERROR )
    {
      return M2MB_ERROR;
    }
    
    ...
}

m2mb_sntp_update()

M2MB_STATUS_T m2mb_sntp_update

(

HANDLE

handle

)

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 )
{
  if(user_ctx)
  user_ctx(event);
  ...
  ...
}

int main()
{
    INT32 status = 0;
    HANDLE handle = NULL;
    M2MB_SNTP_INIT_PARAMS_T sntp_init = {0};

    sntp_init.user_cb = sntp_user_cb; 
    sntp_init.user_ctx = NULL; 
    sntp_init.poll_interval = 0;

    status =  m2mb_sntp_init( &handle, sntp_init );
    if( status == M2MB_ERROR )
    {
      return M2MB_ERROR;
}

    ...

    status = m2mb_sntp_start( handle );
    if( status == M2MB_ERROR )
    {
      return M2MB_ERROR;
    }

    ...      

    M2MB_SNTP_SRV_ADD_INFO_T server_info = {0};
    server_info.ipAddr = "8.8.8.8";
    server_info.serverID = M2MB_SNTP_SERVER_PRIMARY;

    M2MB_SNTP_CONF_PARAMS_T sntp_conf = {0};
    sntp_conf.srv_info = &server_info;
    status = m2mb_sntp_set_cfg( handle, M2MB_SNTP_CONF_SET_SRV_ADD, &sntp_conf );
    if( status == M2MB_ERROR )
{
      return M2MB_ERROR;
    }

  ...

    status = m2mb_sntp_update();
    if( status == M2MB_ERROR )
{
      return M2MB_ERROR;
}

    ...

    //To delete the server
    M2MB_SNTP_CONF_PARAMS_T sntp_conf = {0};
    sntp_conf.serverID = M2MB_SNTP_SERVER_PRIMARY;
    status = m2mb_sntp_set_cfg( handle, M2MB_SNTP_CONF_SET_SRV_DEL, &sntp_conf );
    if( status == M2MB_ERROR )
    {
      return M2MB_ERROR;
    }
}