ntp模块头文件, 提供获取utc时间的能力更多...

#include <stdint.h>

aiot_ntp_api.h 的引用(Include)关系图:

类
struct	aiot_ntp_recv_t
	ntp模块收到从网络上来的报文时, 通知用户的报文内容更多...

struct	aiot_ntp_event_t
	NTP内部事件更多...

宏定义
#define	STATE_NTP_BASE (-0x1100)
	-0x1100~-0x11FF表达SDK在ntp模块内的状态码更多...

#define	STATE_NTP_MISSING_MQTT_HANDLE (-0x1101)
	MQTT会话句柄未设置, 请通过 aiot_ntp_setopt 设置MQTT会话句柄更多...

类型定义
typedef void(*	aiot_ntp_recv_handler_t) (void handle, const aiot_ntp_recv_t packet, void *userdata)
	ntp模块收到从网络上来的报文时, 通知用户所调用的数据回调函数更多...

typedef void(*	aiot_ntp_event_handler_t) (void handle, const aiot_ntp_event_t event, void *userdata)
	ntp事件回调函数更多...

枚举
enum	aiot_ntp_recv_type_t { AIOT_NTPRECV_LOCAL_TIME }
	ntp模块收到从网络上来的报文时, 通知用户的报文类型更多...

enum	aiot_ntp_event_type_t { AIOT_NTPEVT_INVALID_RESPONSE, AIOT_NTPEVT_INVALID_TIME_FORMAT }
	ntp内部事件类型更多...

enum	aiot_ntp_option_t { AIOT_NTPOPT_MQTT_HANDLE, AIOT_NTPOPT_TIME_ZONE, AIOT_NTPOPT_RECV_HANDLER, AIOT_NTPOPT_EVENT_HANDLER, AIOT_NTPOPT_USERDATA, AIOT_NTPOPT_DEINIT_TIMEOUT_MS, AIOT_NTPOPT_MAX }
	aiot_ntp_setopt 接口的option参数可选值. 更多...

函数
void *	aiot_ntp_init (void)
	创建ntp会话实例, 并以默认值配置会话参数更多...

int32_t	aiot_ntp_setopt (void handle, aiot_ntp_option_t option, void data)
	配置ntp会话更多...

int32_t	aiot_ntp_deinit (void **handle)
	结束ntp会话, 销毁实例并回收资源更多...

int32_t	aiot_ntp_send_request (void *handle)
	向ntp服务器发送ntp消息请求更多...

详细描述

ntp模块头文件, 提供获取utc时间的能力

版权所有: Copyright (C) 2015-2020 Alibaba Group Holding Limited

NTP模块用于从阿里云物联网平台上获取UTC时间, API的使用流程如下:

首先参考 aiot_mqtt_api.h 的说明, 保证成功建立与物联网平台的MQTT连接
调用 aiot_ntp_init 初始化ntp会话, 获取会话句柄
调用 aiot_ntp_setopt 配置NTP会话的参数, 常用配置项见 aiot_ntp_setopt 的说明
调用 aiot_ntp_send_request 发送NTP请求
收到的UTC时间经SDK处理后会调用由 aiot_ntp_setopt 配置的 AIOT_NTPOPT_RECV_HANDLER 回调函数, 通知用户当前的时间

宏定义说明

#define STATE_NTP_BASE (-0x1100)

-0x1100~-0x11FF表达SDK在ntp模块内的状态码

#define STATE_NTP_MISSING_MQTT_HANDLE (-0x1101)

MQTT会话句柄未设置, 请通过 aiot_ntp_setopt 设置MQTT会话句柄

类型定义说明

typedef void(* aiot_ntp_recv_handler_t) (void *handle, const aiot_ntp_recv_t *packet, void *userdata)

ntp模块收到从网络上来的报文时, 通知用户所调用的数据回调函数

参数

[in]	handle	ntp会话句柄
[in]	packet	ntp消息结构体, 存放收到的ntp报文内容
[in]	userdata	用户上下文

返回: void

typedef void(* aiot_ntp_event_handler_t) (void *handle, const aiot_ntp_event_t *event, void *userdata)

ntp事件回调函数

当NTP内部事件被触发时, 调用此函数

枚举类型说明

enum aiot_ntp_recv_type_t

ntp模块收到从网络上来的报文时, 通知用户的报文类型

枚举值
AIOT_NTPRECV_LOCAL_TIME

enum aiot_ntp_event_type_t

ntp内部事件类型

枚举值
AIOT_NTPEVT_INVALID_RESPONSE	收到的ntp应答中字段不合法
AIOT_NTPEVT_INVALID_TIME_FORMAT	收到的ntp应答中时间字段格式错误

enum aiot_ntp_option_t

aiot_ntp_setopt 接口的option参数可选值.

下文每个选项中的数据类型, 指的是aiot_ntp_setopt 中, data参数的数据类型

data的数据类型是char *时, 以配置AIOT_NTPOPT_MQTT_HANDLE 为例:

void *mqtt_handle = aiot_mqtt_init(); aiot_ntp_setopt(ntp_handle, AIOT_NTPOPT_MQTT_HANDLE, mqtt_handle);
data的数据类型是其他数据类型时, 以配置AIOT_NTPOPT_TIME_ZONE 为例:

int8_t time_zone = 8; aiot_mqtt_setopt(ntp_handle, AIOT_NTPOPT_TIME_ZONE, (void *)&time_zone);

枚举值
AIOT_NTPOPT_MQTT_HANDLE	ntp会话需要的MQTT句柄, 需要先建立MQTT连接, 再设置MQTT句柄数据类型: (void *)
AIOT_NTPOPT_TIME_ZONE	ntp会话获取到utc时间后会根据此时区值转换成本地时间, 再通过 aiot_ntp_recv_handler_t 通知取值示例: 东8区, 取值为8; 西3区, 取值为-3 数据类型: (int8_t *)
AIOT_NTPOPT_RECV_HANDLER	设置回调, 它在SDK收到网络报文的时候被调用, 告知用户数据类型: ( aiot_ntp_recv_handler_t )
AIOT_NTPOPT_EVENT_HANDLER	ntp内部发生的事件会从此回调函数进行通知数据类型: ( aiot_ntp_event_handler_t )
AIOT_NTPOPT_USERDATA	用户需要SDK暂存的上下文这个上下文指针会在 AIOT_NTPOPT_RECV_HANDLER 和 AIOT_NTPOPT_EVENT_HANDLER 设置的回调被调用时, 由SDK传给用户数据类型: (void *)
AIOT_NTPOPT_DEINIT_TIMEOUT_MS	销毁ntp实例时, 等待其他api执行完毕的时间当调用aiot_ntp_deinit 销毁NTP实例时, 若继续调用其他aiot_ntp_xxx API, API会返回STATE_USER_INPUT_EXEC_DISABLED 错误此时, 用户应该停止调用其他aiot_ntp_xxx API 数据类型: (uint32_t ) 默认值: (2 1000) ms
AIOT_NTPOPT_MAX

函数说明

void* aiot_ntp_init ( void )

创建ntp会话实例, 并以默认值配置会话参数

返回: void *

返回值

非NULL	ntp实例的句柄
NULL	初始化失败, 一般是内存分配失败导致

函数调用图:

int32_t aiot_ntp_setopt	(	void *	handle,
		aiot_ntp_option_t	option,
		void *	data
	)

配置ntp会话

常见的配置项如下

AIOT_NTPOPT_MQTT_HANDLE: 已建立连接的MQTT会话句柄
AIOT_NTPOPT_TIME_ZONE: 时区设置, SDK会将收到的UTC时间按配置的时区进行转换
AIOT_NTPOPT_RECV_HANDLER: 时间数据接收回调函数, SDK将UTC时间转换完成后, 通过此回调函数输出

参数

[in]	handle	ntp会话句柄
[in]	option	配置选项, 更多信息请参考aiot_ntp_option_t
[in]	data	配置选项数据, 更多信息请参考aiot_ntp_option_t

返回: int32_t

返回值

<STATE_SUCCESS	参数配置失败
>=STATE_SUCCESS	参数配置成功

函数调用图:

int32_t aiot_ntp_deinit ( void ** handle )

结束ntp会话, 销毁实例并回收资源

参数

[in] handle 指向ntp会话句柄的指针

返回: int32_t

返回值

<STATE_SUCCESS	执行失败
>=STATE_SUCCESS	执行成功

函数调用图:

int32_t aiot_ntp_send_request ( void * handle )

向ntp服务器发送ntp消息请求

发送NTP请求, 然后SDK会调用通过 aiot_ntp_setopt 配置的 AIOT_NTPOPT_RECV_HANDLER 回调函数, 通知用户当前的时间

参数

handle ntp会话句柄

返回: int32_t

返回值

<STATE_SUCCESS	请求发送失败
>=STATE_SUCCESS	请求发送成功

函数调用图: