C Link SDK设备端开发核心API函数详解-物联网平台-阿里云

Alink协议是针对物联网开发领域设计的一种数据交换规范，数据格式是JSON，用于设备端和物联网平台的双向通信。本文介绍Alink协议涉及的API。

说明

JSON报文中，消息ID的取值范围是0~4294967295，ID是String类型的数字，如"12345"。

IOT_Linkkit_Open

接口原型

int IOT_Linkkit_Open(iotx_linkkit_dev_type_t dev_type, iotx_linkkit_dev_meta_info_t *meta_info);

接口说明
初始化设备资源，在对设备进行操作之前，必须先调用此接口，调用成功后会返回设备ID。
当使用其他接口时需要以设备ID作为入参，对指定的设备进行操作。
参数说明
参数
数据类型
方向
说明
dev_type
iotx_linkkit_dev_type_t
输入
需要创建资源的设备类型。
meta_info
iotx_linkkit_dev_meta_info_t
输入
设备证书。

参数附加说明

typedef enum {
    IOTX_LINKKIT_DEV_TYPE_MASTER,
    IOTX_LINKKIT_DEV_TYPE_SLAVE,
    IOTX_LINKKIT_DEV_TYPE_MAX
} iotx_linkkit_dev_type_t;

参数	说明
IOTX_LINKKIT_DEV_TYPE_MASTER	创建的设备为主设备，仅能创建一次。
IOTX_LINKKIT_DEV_TYPE_SLAVE	创建的设备为子设备。
IOTX_LINKKIT_DEV_TYPE_MAX	设备类型最大枚举值。

typedef struct {
    char product_key[PRODUCT_KEY_MAXLEN];
    char product_secret[PRODUCT_SECRET_MAXLEN];
    char device_name[DEVICE_NAME_MAXLEN];
    char device_secret[DEVICE_SECRET_MAXLEN];
} iotx_linkkit_dev_meta_info_t;

参数	说明
product_key	产品标识，最大长度为20字节。
product_secret	产品密钥，最大长度为64字节。
device_name	设备名称，最大长度为32字节。
device_secret	设备密钥，最大长度为64字节。

返回值说明
值
说明
>= 0
创建设备成功。
< 0
创建设备失败。

IOT_Linkkit_Connect

接口原型
```
int IOT_Linkkit_Connect(int devid);
```
接口说明
- 对于主设备来说，将会建立设备与云端的通信。
- 对于子设备来说，将向云端注册该子设备（如果需要的话）并添加主、子设备的拓扑关系。
参数说明
参数
数据类型
方向
说明
devid
int
输入
设备ID。
返回值说明
值
说明
0
成功。
< 0
失败。

IOT_Linkkit_Yield

接口原型
```
void IOT_Linkkit_Yield(int timeout_ms);
```
接口说明
若SDK占有独立线程，则该函数只将接收到的网络报文分发到用户的回调函数中，否则表示将CPU交给SDK让其接收网络报文并将消息分发到用户的回调函数中。
参数说明
参数
数据类型
方向
说明
timeout_ms
int
输入
单线程模式下，每次尝试接收网络报文的超时时间。
返回值说明
无返回值。

IOT_Linkkit_Close

接口原型
```
int IOT_Linkkit_Close(int devid);
```
接口说明
- 若设备ID为主设备，则关闭网络连接并释放Linkkit所有占用资源。
- 若设备ID为子设备，则子设备与云平台断开连接。
参数说明
参数
数据类型
方向
说明
devid
int
输入
设备ID。
返回值说明
值
说明
0
成功。
< 0
失败。

IOT_Linkkit_TriggerEvent

接口原型

int IOT_Linkkit_TriggerEvent(int devid, char *eventid, int eventid_len, char *payload, int payload_len);

接口说明
向云端上报设备事件。

参数说明

参数	数据类型	方向	说明
devid	int	输入	设备ID。
eventid	char *	输入	TSL中定义的事件ID。
eventid_len	int	输入	事件ID的长度。
payload	char *	输入	事件Payload。
payload_len	int	输入	事件Payload的长度。

返回值说明
值
说明
>= 1
消息ID
< 0
失败

IOT_Linkkit_Report

接口原型

int IOT_Linkkit_Report(int devid,
                        iotx_linkkit_msg_type_t msg_type,
                        unsigned char *payload,
                        int payload_len);

接口说明
向云端发送消息，包括属性上报、设备标签信息更新上报、设备标签信息删除上报、透传数据上报、子设备登录、子设备登出。

参数说明

参数	数据类型	方向	说明
devid	int	输入	设备ID。
msg_type	iotx_linkkit_msg_type_t	输入	需要上报的消息类型。
payload	unsigned char *	输入	消息Payload。
payload_len	int	输入	消息Payload的长度。

参数附加说明

typedef enum {
    ITM_MSG_POST_PROPERTY,
    ITM_MSG_DEVICEINFO_UPDATE,
    ITM_MSG_DEVICEINFO_DELETE,
    ITM_MSG_POST_RAW_DATA,
    ITM_MSG_LOGIN,
    ITM_MSG_LOGOUT,
    ...
    ...

    IOTX_LINKKIT_MSG_MAX
} iotx_linkkit_msg_type_t;

参数	说明
ITM_MSG_POST_PROPERTY	设备属性数据上报。
ITM_MSG_DEVICEINFO_UPDATE	设备标签更新信息上报。
ITM_MSG_DEVICEINFO_DELETE	设备标签删除信息上报。
ITM_MSG_POST_RAW_DATA	设备透传数据上报。
ITM_MSG_LOGIN	子设备登录。
ITM_MSG_LOGOUT	子设备退出。
ITM_MSG_DELETE_TOPO	删除子设备和网关之间的拓扑关系。
ITM_MSG_REPORT_SUBDEV_FIRMWARE_VERSION	上报子设备的固件版本号，用于子设备OTA升级功能。
ITM_MSG_PROPERTY_DESIRED_GET	获取云端缓存的属性值下发，用于高级版设备影子。
ITM_MSG_PROPERTY_DESIRED_DELETE	主动删除云端缓存的属性值，用于高级版设备影子。

返回值说明
值
说明
0
成功。
>= 1
消息ID。
< 0
失败。

IOT_Linkkit_Query

接口原型

int IOT_Linkkit_Query(int devid,
                        iotx_linkkit_msg_type_t msg_type,
                        unsigned char *payload,
                        int payload_len);

接口说明
向云端查询数据，包括查询时间戳、设备的拓扑关系列表、COTA升级的固件数据、COTA升级的Config文件数据、是否有可用的新固件、是否有可用的Config文件。

参数说明

参数	数据类型	方向	说明
devid	int	输入	设备ID。
msg_type	iotx_linkkit_msg_type_t	输入	需要上报的消息类型。
payload	unsigned char *	输入	消息Payload。
payload_len	int	输入	消息Payload的长度。

参数附加说明

typedef enum {
    ...
    ...
    ITM_MSG_QUERY_TIMESTAMP,
    ITM_MSG_QUERY_TOPOLIST,
    ITM_MSG_QUERY_FOTA_DATA,
    ITM_MSG_QUERY_COTA_DATA,
    ITM_MSG_REQUEST_COTA,
    ITM_MSG_REQUEST_FOTA_IMAGE,

    IOTX_LINKKIT_MSG_MAX
} iotx_linkkit_msg_type_t;

参数	说明
ITM_MSG_QUERY_TIMESTAMP	查询时间戳。
ITM_MSG_QUERY_TOPOLIST	查询设备的拓扑关系列表。
ITM_MSG_QUERY_FOTA_DATA	查询FOTA升级的固件数据。
ITM_MSG_QUERY_COTA_DATA	查询COTA升级的远程配置数据。
ITM_MSG_REQUEST_FOTA_IMAGE	查询是否有可用的新固件。
ITM_MSG_REQUEST_COTA	查询是否有可用的远程配置数据。

返回值说明
值
说明
0
成功。
>= 1
消息ID。
< 0
失败。

IOT_RegisterCallback

接口原型

define IOT_RegisterCallback(evt, cb)           iotx_register_for_##evt(cb);

接口说明
该接口用于注册事件的回调函数，当Linkkit SDK产生事件时，会调用对应的回调函数。
参数说明
参数
数据类型
方向
说明
evt
iotx_ioctl_event_t
输入
事件名称。
cb
根据evt的不同而不同
输入
回调函数。

事件清单

typedef enum {
    ...
    ITE_CONNECT_SUCC,
    ...
    ITE_DISCONNECTED,
    ITE_RAWDATA_ARRIVED,
    ITE_SERVICE_REQUEST,
    ITE_PROPERTY_SET,
    ITE_PROPERTY_GET,
    ITE_REPORT_REPLY,
    ITE_TRIGGER_EVENT_REPLY,
    ITE_TIMESTAMP_REPLY,
    ITE_TOPOLIST_REPLY,
    ITE_PERMIT_JOIN,
    ITE_INITIALIZE_COMPLETED,
    ITE_FOTA,
    ITE_COTA
} iotx_ioctl_event_t;

事件列表

事件	回调函数原型	事件触发条件说明
ITE_CONNECT_SUCC	int callback(void);	与云端连接成功时。
ITE_DISCONNECTED	int callback(void);	与云端连接断开时。
ITE_RAWDATA_ARRIVED	int callback(const int devid, const unsigned char *payload, const int payload_len);	Linkkit收到`raw data`数据时。
ITE_SERVICE_REQUEST	int callback(const int devid, const char serviceid, const int serviceid_len, const char request, const int request_len, char *response, int response_len);	Linkkit收到服务（同步/异步）调用请求时。
ITE_PROPERTY_SET	int callback(const int devid, const char *request, const int request_len);	Linkkit收到属性设置请求时。
ITE_PROPERTY_GET	int callback(const int devid, const char *request, const int request_len, char response, int response_len);	Linkkit收到属性获取请求时。
ITE_REPORT_REPLY	int callback(const int devid, const int msgid, const int code, const char *reply, const int reply_len);	Linkkit收到上报消息的应答时。
ITE_TRIGGER_EVENT_REPLY	int callback(const int devid, const int msgid, const int code, const char eventid, const int eventid_len, const char message, const int message_len);	Linkkit收到事件上报消息的应答时。
ITE_TIMESTAMP_REPLY	int callback(const char *timestamp);	当Linkkit收到查询时间戳请求的应答时。
ITE_TOPOLIST_REPLY	int callback(const int devid, const int msgid, const int code, const char * payload, const int payload_len);	Linkkit收到查询拓扑关系请求的应答时。
ITE_PERMIT_JOIN	int callback(const char * product_key, const int time);	Linkkit收到允许子设备入网的请求时。
ITE_INITIALIZE_COMPLETED	int callback(const int devid);	设备初始化完成时。
ITE_FOTA	int callback(int type, const char *version);	Linkkit收到可用固件的通知时。
ITE_COTA	int callback(int type, const char config_id, int config_size, const char get_type, const char sign, const char sign_method, const char *url);	Linkkit收到可用远程配置文件的通知时。

返回值说明
无返回值。

IOT_Ioctl

接口原型
```
int IOT_Ioctl(int option, void *data);
```
接口说明
用于配置SDK的一些全局选项, 在使用Linkkit高级版时, 需要在IOT_Linkkit_Connect前使用。
参数说明
参数
数据类型
方向
说明
option
int
输入
需要进行的操作。
data
void *
输入/输出
option需要的输入或输出参数。

参数附加说明

option选项如下：

typedef enum {
    IOTX_IOCTL_SET_REGION,
    IOTX_IOCTL_GET_REGION,
    IOTX_IOCTL_SET_MQTT_DOMAIN,
    IOTX_IOCTL_SET_HTTP_DOMAIN,
    IOTX_IOCTL_SET_DYNAMIC_REGISTER,
    IOTX_IOCTL_GET_DYNAMIC_REGISTER,
    IOTX_IOCTL_RECV_PROP_REPLY,
    IOTX_IOCTL_RECV_EVENT_REPLY,
    IOTX_IOCTL_SEND_PROP_SET_REPLY,
    IOTX_IOCTL_SET_SUBDEV_SIGN,
    IOTX_IOCTL_GET_SUBDEV_LOGIN
} iotx_ioctl_option_t;

参数	说明
IOTX_IOCTL_SET_REGION	设置登录服务器区域。`data`的数据类型为`int *`，取值见`iot_export.h`中的`iotx_cloud_region_types_t`枚举量。
IOTX_IOCTL_GET_REGION	获取当前登录服务器区域。`data`的数据类型为`int *`。
IOTX_IOCTL_SET_MQTT_DOMAIN	当`IOTX_IOCTL_SET_REGION`没有需要的服务器区域时，设置登录MQTT服务器的区域。`data`的数据类型为`char *`。
IOTX_IOCTL_SET_HTTP_DOMAIN	当`IOTX_IOCTL_SET_REGION`没有需要的服务器区域时, 设置登录HTTP服务器的区域，`data`的数据类型为`char *`。
IOTX_IOCTL_SET_DYNAMIC_REGISTER	设置是否需要使用一型一密。`data`的数据类型为`int *`。当data的值为1时，使用一型一密。当data的值为0时，不使用一型一密。
IOTX_IOCTL_GET_DYNAMIC_REGISTER	获取当前是否使用一型一密。
IOTX_IOCTL_RECV_PROP_REPLY	废弃，与`IOTX_IOCTL_RECV_EVENT_REPLY`功能相同。
IOTX_IOCTL_RECV_EVENT_REPLY	控制当用户上报属性和事件时，是否需要云端的应答消息。`data`的数据类型为`int *`。当data的值为1时，需要云端返回应答消息。当data的值为0时，不需要云端返回应答消息。
IOTX_IOCTL_SEND_PROP_SET_REPLY	控制当SDK收到云端的设置属性的消息时，是否需要向云端发送应答消息，`data`的数据类型为`int *`。当data的值为1时，SDK需要向云端发送设置属性的应答消息。当data的值为0时，SDK不需要向云端发送设置属性的应答消息。
IOTX_IOCTL_SET_SUBDEV_SIGN	预留。
IOTX_IOCTL_GET_SUBDEV_LOGIN	预留。
IOTX_IOCTL_QUERY_DEVID	获取ProductKey、DeviceName对应的子设备的Devid。输入为指向`iotx_linkkit_dev_meta_info_t`类型数据的指针。输出为Devid，如果子设备不存在则返回-1。以`linkkit_example_gateway.c`为例，下面代码即可获取子设备数组中subdevArr[2]对应的devid。 `int subdev_id = 0; subdev_id = IOT_Ioctl(IOTX_IOCTL_QUERY_DEVID, (void *)&subdevArr[2]);`

返回值说明
值
说明
>= 0
成功。
< 0
失败。

值	说明
>= 0	创建设备成功。
< 0	创建设备失败。

值	说明
0	成功。
< 0	失败。

值	说明
0	成功。
< 0	失败。

值	说明
>= 1	消息ID
< 0	失败