设备端 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 接口
序号 | 函数名 | 说明 |
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 通道对时功能。 |
