接口及可变参数说明

最近更新时间:2019-11-22 18:16:22

设备端 C-SDK 供用户调用的 API 函数声明,常量以及可变参数定义等头文件位于 include 目录下面,本文档主要对该目录下面的可变参数以及 API 函数进行说明。

可变参数配置

C-SDK 是基于MQTT协议,使用可以根据具体场景需求,配置相应的参数,满足实际业务的运行。可变接入参数包括:

  1. MQTT 阻塞调用(包括连接, 订阅, 发布等)的超时时间,单位:毫秒。 建议5000毫秒。
  2. MQTT 协议发送消息和接受消息的 buffer 大小默认为2048字节,最大支持16KB。
  3. MQTT 心跳消息发送周期,最大值为690秒,单位:毫秒。
  4. 重连最大等待时间,单位:毫秒。设备断线重连时,若失败则等待时间会翻倍,当超过该最大等待时间则退出重连。

修改include/qcloud_iot_export_variables.h文件如下宏定义可以改变对应接入参数的配置。
修改完需要重新编译 SDK ,示例代码如下:

/* default MQTT/CoAP timeout value when connect/pub/sub (unit: ms) */
#define QCLOUD_IOT_MQTT_COMMAND_TIMEOUT                             (5 * 1000)

/* default MQTT keep alive interval (unit: ms) */
#define QCLOUD_IOT_MQTT_KEEP_ALIVE_INTERNAL                         (240 * 1000)

/* default MQTT Tx buffer size, MAX: 16*1024 */
#define QCLOUD_IOT_MQTT_TX_BUF_LEN                                  (2048)

/* default MQTT Rx buffer size, MAX: 16*1024 */
#define QCLOUD_IOT_MQTT_RX_BUF_LEN                                  (2048)

/* default COAP Tx buffer size, MAX: 1*1024 */
#define COAP_SENDMSG_MAX_BUFLEN                                     (512)

/* default COAP Rx buffer size, MAX: 1*1024 */
#define COAP_RECVMSG_MAX_BUFLEN                                     (512)

/* MAX MQTT reconnect interval (unit: ms) */
#define MAX_RECONNECT_WAIT_INTERVAL                                 (60 * 1000)

API 函数说明

以下是 C-SDK v3.1.0版本提供的主要功能和对应 API 接口说明,用于客户编写业务逻辑,更加详细的说明如接口参数及返回值可查看 SDK 代码include/exports/qcloud_iot_export_*.h等头文件中的注释。

数据模板接口

数据模板协议及功能介绍,请参见 数据模板协议

序号 函数名 说明
1 IOT_Template_Construct 构造数据模板客户端 Data_template_client 并连接 MQTT 云端服务
2 IOT_Template_Destroy 关闭 Data_template MQTT 连接并销毁 Data_template Client
3 IOT_Template_Yield 在当前线程上下文中,进行 MQTT 报文读取,消息处理,超时请求,心跳包及重连状态管理等任务
4 IOT_Template_Publish 数据模板客户端发布 MQTT 消息
5 IOT_Template_Subscribe 数据模板客户端订阅 MQTT 主题
6 IOT_Template_Unsubscribe 数据模板客户端取消订阅已订阅的 MQTT 主题
7 IOT_Template_IsConnected 查看当前数据模板客户端的 MQTT 是否已连接

数据模板属性接口

序号 函数名 说明
1 IOT_Template_Register_Property 注册当前设备的数据模板属性
2 IOT_Template_UnRegister_Property 删除已经注册过的数据模板属性
3 IOT_Template_Report 异步方式上报数据模板属性数据
4 IOT_Template_Report_Sync 同步方式上报数据模板属性数据
5 IOT_Template_GetStatus 异步方式获取数据模板属性数据
6 IOT_Template_GetStatus_sync 同步方式获取数据模板属性数据
7 IOT_Template_Report_SysInfo 异步方式上报系统信息
8 IOT_Template_Report_SysInfo_Sync 同步方式上报系统信息
9 IOT_Template_JSON_ConstructSysInfo 构造待上报的系统信息
10 IOT_Template_ControlReply 回复收到的数据模板属性控制消息
11 IOT_Template_ClearControl 删除数据模板属性控制消息,配合 IOT_Template_GetStatus 获取到 control 消息使用

数据模板事件接口

序号 函数名 说明
1 IOT_Post_Event 上报数据模板事件,传入事件,SDK 完成事件消息构造
2 IOT_Post_Event_Raw 上报数据模板事件,传入符合事件消息格式的数据,SDK 完成上报
3 IOT_Event_setFlag 置位事件标志,SDK 默认支持10个事件,可以扩展增加
4 IOT_Event_clearFlag 清除事件标志
5 IOT_Event_getFlag 获取事件标志

数据模板行为接口

序号 函数名 说明
1 IOT_ACTION_REPLY 回复数据模板行为消息

多线程环境使用说明

SDK 对于在多线程环境下的使用有如下注意事项:

  • 不允许多线程调用 IOT_Template_Yield,IOT_Template_Construct 以及IOT_Template_Destroy。
  • IOT_Template_Yield 作为从 socket 读取并处理 MQTT 报文的函数,应保证一定的执行时间,避免被长时间挂起或抢占。

OTA 接口

关于 OTA 固件下载功能介绍,请参见 设备固件升级

序号 函数名 说明
1 IOT_OTA_Init 初始化 OTA 模块,客户端在调用此接口之前需要先进行 MQTT/COAP 的初始化
2 IOT_OTA_Destroy 释放 OTA 模块相关的资源
3 IOT_OTA_ReportVersion 向 OTA 服务器报告本地固件版本信息
4 IOT_OTA_IsFetching 检查是否处于下载固件的状态
5 IOT_OTA_IsFetchFinish 检查固件是否已经下载完成
6 IOT_OTA_FetchYield 从具有特定超时值的远程服务器获取固件
7 IOT_OTA_Ioctl 获取指定的 OTA 信息
8 IOT_OTA_GetLastError 获取最后一个错误代码
9 IOT_OTA_StartDownload 根据获取到的固件更新地址以及本地固件信息偏移(是否断点续传),与固件服务器建立 HTTP 连接
10 IOT_OTA_UpdateClientMd5 断点续传前,计算本地固件的 MD5
11 IOT_OTA_ReportUpgradeBegin 当进行固件升级前,向服务器上报即将升级的状态
12 IOT_OTA_ReportUpgradeSuccess 当固件升级成功之后,向服务器上报升级成功的状态
13 IOT_OTA_ReportUpgradeFail 当固件升级失败之后,向服务器上报升级失败的状态

日志接口

设备日志上报云端功能的详细说明,请参考 SDK docs 目录下物联网通信平台文档设备日志上报功能部分。

序号 函数名 说明
1 IOT_Log_Set_Level 设置 SDK 日志的打印等级
2 IOT_Log_Get_Level 返回 SDK 日志打印的等级
3 IOT_Log_Set_MessageHandler 设置日志回调函数,重定向 SDK 日志于其它输出方式
4 IOT_Log_Init_Uploader 开启 SDK 日志上报云端的功能并初始化资源
5 IOT_Log_Fini_Uploader 停止 SDK 日志上报云端功能并释放资源
6 IOT_Log_Upload 将 SDK 运行日志上报到云端
7 IOT_Log_Set_Upload_Level 设置 SDK 日志的上报等级
8 IOT_Log_Get_Upload_Level 返回 SDK 日志上报的等级
9 Log_d/i/w/e 按级别打印添加 SDK 日志的接口

系统时间接口

序号 函数名 说明
1 IOT_Get_SysTime 获取 IoT Hub 后台系统时间,目前仅支持 MQTT 通道对时功能