aiot_device_api.h 文件参考

设备基础功能头文件, 提供设备的连接与消息相关的能力，包含：设备建连，设备消息收发，设备订阅topic，设备动态注册，设备就近接入 更多...

#include <stdint.h>
#include "aiot_message_api.h"
#include "aiot_linkconfig_api.h"
#include "aiot_state_api.h"

浏览源代码.

结构体
struct	aiot_device_status_t
	设备状态变化时，描述设备状态的结构体 更多...
struct	aiot_device_msg_result_t
	设备消息发送后，返回的消息发送结果，包含pub/sub消息的ACK 更多...
struct	aiot_bootstrap_info_t
	就近接入返回的接入信息结构体 更多...
struct	aiot_dynamic_register_info_t
	设备动态注册，返回信息结构体，设备可用这些信息建连 更多...

类型定义
typedef void(*	aiot_device_msg_callback_t) (void *device, const aiot_msg_t *message, void *userdata)
	设备报文接收回调函数原型， 可通过 aiot_device_set_event_callback 设置 更多...
typedef void(*	aiot_device_status_callback_t) (void *device, const aiot_device_status_t *event, void *userdata)
	设备状态变化时回调函数原型, 用户定义回调函数后，可通过 aiot_device_set_event_callback 设置 更多...
typedef void(*	aiot_device_msg_result_callback_t) (void *device, const aiot_device_msg_result_t *result, void *userdata)
	设备接收到消息ACK时的回调函数原型， 可通过 aiot_device_set_event_callback 设置 更多...

枚举
enum	aiot_device_status_type_t { AIOT_DEVICE_STATUS_CONNECT, AIOT_DEVICE_STATUS_RECONNECT, AIOT_DEVICE_STATUS_DISCONNECT }
	device状态变化类型 更多...
enum	aiot_device_msg_result_type_t { AIOT_DEVICE_SEND_MESSAGE_RESULT, AIOT_DEVICE_REGISTER_TOPIC_RESULT, AIOT_DEVICE_UNREGISTER_TOPIC_RESULT }
	设备消息ack的类型 更多...

函数
void *	aiot_device_create (char *product_key, char *device_name)
	初始化设备并设置默认参数 更多...
int32_t	aiot_device_set_device_secret (void *device, char *device_secret)
	设置设备建连使用的设备密钥 更多...
int32_t	aiot_device_set_linkconfig (void *device, aiot_linkconfig_t *config)
	设置设备连接的参数 更多...
int32_t	aiot_device_set_conntype (void *device, int32_t conntype)
	设置连接设备的类型,该接口只有网关设备需要调用 更多...
int32_t	aiot_device_connect (void *device)
	设备与云平台进行连接，同步阻塞的 更多...
int32_t	aiot_device_connect_async (void *device)
	设备与云平台进行连接，异步非阻塞的 更多...
int32_t	aiot_device_send_message (void *device, const aiot_msg_t *message)
	设备向云平台发送消息 更多...
int32_t	aiot_device_set_event_callback (void *device, aiot_device_msg_callback_t msg_recv_callback, aiot_device_status_callback_t status_callback, aiot_device_msg_result_callback_t msg_result_callback, void *userdata)
	设置设备事件：包含消息回调，状态回调 更多...
int32_t	aiot_device_register_topic_filter (void *device, char *topic, aiot_device_msg_callback_t callback, uint8_t sub, void *userdata)
	设备注册感兴趣的topic，接收到该topic的消息，会执行对应回调 更多...
int32_t	aiot_device_deregister_topic_filter (void *device, char *topic, uint8_t unsub)
	设备注销topic，接收到该topic的消息，将不再执行回调 更多...
int32_t	aiot_device_disconnect (void *device)
	设备主动与平台断开连接 更多...
int32_t	aiot_device_delete (void **device)
	释放设备实例的资源 更多...
int32_t	aiot_device_bootstrap_request (void *device, aiot_protocol_type_t type, aiot_bootstrap_info_t *info)
	请求就近接入信息(host，port) 更多...
int32_t	aiot_device_dynamic_secret (void *device, aiot_linkconfig_t *linkconfig, char *out_device_seceret, int32_t out_secret_len)
	设备动态获取密钥(设备需先预注册) 更多...
int32_t	aiot_device_dynamic_register (void *device, aiot_linkconfig_t *linkconfig, aiot_dynamic_register_info_t *info)
	设备动态注册(设备无需预注册)，该请求会返回设备建连认证信息 更多...
char *	aiot_device_product_key (void *device)
	查询设备的product_key 更多...
char *	aiot_device_name (void *device)
	查询设备的device_name 更多...
int32_t	aiot_device_online (void *device)
	查询设备的状态 更多...

详细描述

设备基础功能头文件, 提供设备的连接与消息相关的能力，包含：设备建连，设备消息收发，设备订阅topic，设备动态注册，设备就近接入

日期

2022-01-20

版权所有

Copyright (C) 2020-2025 Alibaba Group Holding Limited

类型定义说明

typedef void(* aiot_device_msg_callback_t) (void *device, const aiot_msg_t *message, void *userdata)

设备报文接收回调函数原型， 可通过 aiot_device_set_event_callback 设置

参数

[in]	device	设备实例句柄
[in]	message	设备报文结构体, 存放收到的报文，数据结构参考 aiot_msg_t
[in]	userdata	用户上下文， 可通过 aiot_device_set_event_callback 设置

返回

void

typedef void(* aiot_device_status_callback_t) (void *device, const aiot_device_status_t *event, void *userdata)

设备状态变化时回调函数原型, 用户定义回调函数后，可通过 aiot_device_set_event_callback 设置

参数

[in]	device	设备实例句柄
[in]	event	描述设备状态变化事件, 数据结构 aiot_device_status_t
[in]	userdata	用户上下文 可通过 aiot_device_set_event_callback 设置

返回

void

typedef void(* aiot_device_msg_result_callback_t) (void *device, const aiot_device_msg_result_t *result, void *userdata)

设备接收到消息ACK时的回调函数原型， 可通过 aiot_device_set_event_callback 设置

参数

[in]	device	设备实例句柄
[in]	result	描述pub/sub消息的结果, 数据结构参考 aiot_device_msg_result_t
[in]	userdata	用户上下文， 可通过 aiot_device_set_event_callback 设置

返回

void

枚举类型说明

enum aiot_device_status_type_t

device状态变化类型

枚举值
AIOT_DEVICE_STATUS_CONNECT	当实例第一次连接网络成功时, 触发此事件
AIOT_DEVICE_STATUS_RECONNECT	当实例断开网络连接后重连成功时, 触发此事件
AIOT_DEVICE_STATUS_DISCONNECT	当实例断开网络连接时, 触发此事件

enum aiot_device_msg_result_type_t

设备消息ack的类型

枚举值
AIOT_DEVICE_SEND_MESSAGE_RESULT	消息发送的结果
AIOT_DEVICE_REGISTER_TOPIC_RESULT	订阅感兴趣的消息的结果
AIOT_DEVICE_UNREGISTER_TOPIC_RESULT	取消订阅消息的结果

函数说明

void* aiot_device_create	(	char *	product_key,
		char *	device_name
	)

初始化设备并设置默认参数

参数

[in]	product_key	设备认证信息中的产品key
[in]	device_name	设备认证信息中的设备名

返回

void*

返回值

非NULL	设备句柄
NULL	初始化失败, 一般是内存分配失败导致

int32_t aiot_device_set_device_secret	(	void *	device,
		char *	device_secret
	)

设置设备建连使用的设备密钥

参数

[in]	device	设备的句柄
[in]	device_secret	设备认证信息中的设备密钥

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

int32_t aiot_device_set_linkconfig	(	void *	device,
		aiot_linkconfig_t *	config
	)

设置设备连接的参数

参数

[in]	device	设备句柄
[in]	config	建连参数的句柄，初始化及配置参考 aiot_linkconfig_api.h

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

int32_t aiot_device_set_conntype	(	void *	device,
		int32_t	conntype
	)

设置连接设备的类型,该接口只有网关设备需要调用

0: 普通的直连设备，默认值
1: 状态相关的网关设备，网关离线，子设备也会离线
2: 状态无关的网关设备，网关离线，子设备不会离线，网关再上线，子设备不需要再次login。
备注：取值2时，说的子设备不离线是在云平台的状态标记，对于SDK来说，都会将设备标注为离线，
等网关再次上线时，会自动将子设备标记为在线

参数

[in]	device	设备句柄
[in]	conntype	连接的设备类型

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

int32_t aiot_device_connect

(

void *

device

)

设备与云平台进行连接，同步阻塞的

参数

[in]

device

设备句柄

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

int32_t aiot_device_connect_async

(

void *

device

)

设备与云平台进行连接，异步非阻塞的

参数

[in]

device

设备句柄

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

int32_t aiot_device_send_message	(	void *	device,
		const aiot_msg_t *	message
	)

设备向云平台发送消息

参数

[in]	device	设备句柄
[in]	message	需要发送的消息, 消息可由高级模块生成，也可由用户自定义生成 aiot_message_api.h

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

int32_t aiot_device_set_event_callback	(	void *	device,
		aiot_device_msg_callback_t	msg_recv_callback,
		aiot_device_status_callback_t	status_callback,
		aiot_device_msg_result_callback_t	msg_result_callback,
		void *	userdata
	)

设置设备事件：包含消息回调，状态回调

参数

[in]	device	设备句柄
[in]	msg_recv_callback	消息回调函数(所有消息都会有这个回调执行，如果只需要监听部分消息，可以使用aiot_device_register_topic_filter 订阅感兴趣的topic)
[in]	status_callback	设备状态变化回调函数
[in]	msg_result_callback	设备接收到ack回调函数
[in]	userdata	执行回调时返回给用户上下文

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

int32_t aiot_device_register_topic_filter	(	void *	device,
		char *	topic,
		aiot_device_msg_callback_t	callback,
		uint8_t	sub,
		void *	userdata
	)

设备注册感兴趣的topic，接收到该topic的消息，会执行对应回调

参数

[in]	device	设备句柄
[in]	topic	待注册的topic
[in]	callback	接收到该topic消息后的回调函数
[in]	sub	是否需要向云端发送订阅消息，设备只需要订阅一次即可，重启后一样有效 [1, 向云端发送订阅消息] [0, 不向云端发送订阅消息，接收到该消息一样会执行回调]
[in]	userdata	执行回调时返回给用户

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

int32_t aiot_device_deregister_topic_filter	(	void *	device,
		char *	topic,
		uint8_t	unsub
	)

设备注销topic，接收到该topic的消息，将不再执行回调

参数

[in]	device	设备句柄
[in]	topic	待注销的topic
[in]	unsub	是否需要向云端发送订阅消息，设备只需要订阅一次即可，重启后一样有效 [1, 向云端发送取消订阅消息] [0, 不向云端发送取消订阅消息]

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

int32_t aiot_device_disconnect

(

void *

device

)

设备主动与平台断开连接

参数

[in]

device

设备实例句柄

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

int32_t aiot_device_delete

(

void **

device

)

释放设备实例的资源

参数

[in]

device

指向device实例句柄的指针

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

int32_t aiot_device_bootstrap_request	(	void *	device,
		aiot_protocol_type_t	type,
		aiot_bootstrap_info_t *	info
	)

请求就近接入信息(host，port)

参数

[in]	device	指向device实例句柄的指针
[in]	type	就近接入的协议类型，目前仅支持MQTT_PROTOCOL
[out]	info	返回的接入信息结构体

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

int32_t aiot_device_dynamic_secret	(	void *	device,
		aiot_linkconfig_t *	linkconfig,
		char *	out_device_seceret,
		int32_t	out_secret_len
	)

设备动态获取密钥(设备需先预注册)

参数

[in]	device	指向device实例句柄的指针
[in]	linkconfig	动态注册连接云的参数配置
[out]	out_device_seceret	返回的设备密钥
[in]	out_secret_len	保存密钥的缓存长度，该长度建议设置为128

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

int32_t aiot_device_dynamic_register	(	void *	device,
		aiot_linkconfig_t *	linkconfig,
		aiot_dynamic_register_info_t *	info
	)

设备动态注册(设备无需预注册)，该请求会返回设备建连认证信息

参数

[in]	device	指向device实例句柄的指针
[in]	linkconfig	动态注册连接云的参数配置
[out]	info	设备建连认证信息, 可通过 aiot_linkconfig_mqtt_auth 设置进连接参数中

返回

int32_t

返回值

<STATE_SUCCESS	执行失败, 更多信息请参考aiot_state_api.h
>=STATE_SUCCESS	执行成功

char* aiot_device_product_key

(

void *

device

)

查询设备的product_key

参数

[in]

device

指向device实例句柄的指针

char* aiot_device_name

(

void *

device

)

查询设备的device_name

参数

[in]

device

指向device实例句柄的指针

int32_t aiot_device_online

(

void *

device

)

查询设备的状态

参数

[in]

device

指向device实例句柄的指针

返回

int32_t 1:在线 0:离线