Link Kit C-SDK  4.1.0
| 宏定义 | 类型定义 | 枚举 | 函数
aiot_ota_api.h 文件参考

OTA模块头文件, 提供设备获取固件升级和远程配置的能力 更多...

#include <stdint.h>
#include "aiot_http_download_api.h"
aiot_ota_api.h 的引用(Include)关系图:
此图展示该文件直接或间接的被哪些文件引用了:

浏览源代码.

struct  aiot_download_task_desc_t
 云端下推的固件升级任务的描述信息, 包括url, 大小, 签名等 更多...
 
struct  aiot_ota_recv_t
 云端下行的OTA消息, 包括其消息类型(固件升级/远程配置)和升级任务的具体描述 更多...
 
struct  aiot_download_recv_t
 下载固件过程中收到的分片的报文的描述, 包括类型, 以及所存储的buffer地址, buffer的长度, 以及当前的下载进度 更多...
 

宏定义

#define STATE_OTA_BASE   (-0x0900)
 -0x0900~-0x09FF表达SDK在OTA模块内的状态码, 也包含下载时使用的STATE_DOWNLOAD_XXX 更多...
 
#define STATE_OTA_DIGEST_MATCH   (-0x0901)
 OTA固件下载已完成, 校验和验证成功 更多...
 
#define STATE_OTA_REPORT_FAILED   (-0x0902)
 OTA下载进度消息或固件版本号消息上报到服务器时遇到失败 更多...
 
#define STATE_DOWNLOAD_RECV_ERROR   (-0x0903)
 OTA模块收取固件内容数据时出现错误 更多...
 
#define STATE_OTA_DIGEST_MISMATCH   (-0x0904)
 OTA模块下载固件时出现校验和签名验证错误 更多...
 
#define STATE_OTA_PARSE_JSON_ERROR   (-0x0905)
 OTA模块解析服务器下推的MQTT下行JSON报文时出错 更多...
 
#define STATE_DOWNLOAD_SEND_REQUEST_FAILED   (-0x0906)
 OTA模块发送HTTP报文, 请求下载固件时遇到失败 更多...
 
#define STATE_DOWNLOAD_RANGE_FINISHED   (-0x0907)
 OTA模块下载固件内容已到达之前设置的range末尾, 不会继续下载 更多...
 
#define STATE_OTA_PARSE_JSON_MALLOC_FAILED   (-0x0908)
 OTA模块为解析JSON报文而申请内存时, 未获取到所需内存而解析失败 更多...
 
#define STATE_OTA_DEINIT_HANDLE_IS_NULL   (-0x0909)
 销毁OTA会话实例时, 发现会话句柄为空, 中止销毁动作 更多...
 
#define STATE_OTA_SETOPT_HANDLE_IS_NULL   (-0x090A)
 配置OTA会话实例时, 发现会话句柄为空, 中止配置动作 更多...
 
#define STATE_OTA_SETOPT_DATA_IS_NULL   (-0x090B)
 配置OTA会话实例时, 发现配置数据为空, 中止配置动作 更多...
 
#define STATE_DOWNLOAD_DEINIT_HANDLE_IS_NULL   (-0x090C)
 销毁下载会话实例时, 发现会话句柄为空, 中止销毁动作 更多...
 
#define STATE_DOWNLOAD_SETOPT_HANDLE_IS_NULL   (-0x090D)
 配置下载会话实例时, 发现会话句柄为空, 中止配置动作 更多...
 
#define STATE_DOWNLOAD_SETOPT_DATA_IS_NULL   (-0x090E)
 配置下载会话实例时, 发现配置数据为空, 中止配置动作 更多...
 
#define STATE_DOWNLOAD_SETOPT_COPIED_DATA_IS_NULL   (-0x090F)
 配置下载会话实例时, 从OTA会话同步配置发生内部错误, 中止配置动作 更多...
 
#define STATE_OTA_REPORT_HANDLE_IS_NULL   (-0x0910)
 直连设备上报版本号时, OTA句柄为空, 中止执行上报 更多...
 
#define STATE_OTA_REPORT_VERSION_IS_NULL   (-0x0911)
 直连设备上报版本号时, 版本号字符串为空, 中止执行上报 更多...
 
#define STATE_OTA_REPORT_MQTT_HANDLE_IS_NULL   (-0x0912)
 直连设备上报版本号时, MQTT句柄为空, 中止执行上报 更多...
 
#define STATE_OTA_REPORT_EXT_HANELD_IS_NULL   (-0x0913)
 网关为子设备上报版本号时, OTA句柄为空, 中止执行上报 更多...
 
#define STATE_OTA_REPORT_EXT_VERSION_NULL   (-0x0914)
 网关为子设备上报版本号时, 版本号字符串为空, 中止执行上报 更多...
 
#define STATE_OTA_REPORT_EXT_PRODUCT_KEY_IS_NULL   (-0x0915)
 网关为子设备上报版本号时, 子设备productKey为空, 中止执行上报 更多...
 
#define STATE_OTA_REPORT_EXT_DEVICE_NAME_IS_NULL   (-0x0916)
 网关为子设备上报版本号时, 子设备deviceName为空, 中止执行上报 更多...
 
#define STATE_OTA_REPORT_EXT_MQTT_HANDLE_IS_NULL   (-0x0917)
 网关为子设备上报版本号时, MQTT会话句柄为空, 中止执行上报 更多...
 
#define STATE_DOWNLOAD_REPORT_HANDLE_IS_NULL   (-0x0918)
 上报下载进度或OTA错误码时, 下载会话句柄为空, 中止执行上报 更多...
 
#define STATE_DOWNLOAD_REPORT_TASK_DESC_IS_NULL   (-0x0919)
 上报下载进度或OTA错误码时, 任务描述数据结构为空, 中止执行上报 更多...
 
#define STATE_DOWNLOAD_RECV_HANDLE_IS_NULL   (-0x091A)
 调用aiot_download_recv接收固件内容时, 处理接收数据的用户回调为空值, 中止执行 更多...
 
#define STATE_DOWNLOAD_REQUEST_HANDLE_IS_NULL   (-0x091B)
 调用aiot_download_send_request发送固件下载请求时, 下载会话的句柄为空, 中止执行 更多...
 
#define STATE_DOWNLOAD_REQUEST_TASK_DESC_IS_NULL   (-0x091C)
 调用aiot_download_send_request发送固件下载请求时, 任务描述为空, 中止执行 更多...
 
#define STATE_DOWNLOAD_REQUEST_URL_IS_NULL   (-0x091D)
 调用aiot_download_send_request发送固件下载请求时, 任务描述中的固件URL为空, 中止执行 更多...
 
#define STATE_OTA_UNKNOWN_DIGEST_METHOD   (-0x091E)
 解析通知OTA的MQTT下行报文时, 其中的digest方法并非md5或sha256, SDK不支持 更多...
 
#define STATE_DOWNLOAD_FINISHED   (-0x091F)
 整个固件(而不是单独一次的下载片段)收取已完成, 收取的累计字节数与固件预期字节数一致 更多...
 
#define STATE_DOWNLOAD_HTTPRSP_CODE_ERROR   (-0x0920)
 设备向固件服务器发出GET请求时, 服务器返回的HTTP报文中Status Code错误, 既非200, 也非206 更多...
 
#define STATE_DOWNLOAD_HTTPRSP_HEADER_ERROR   (-0x0921)
 设备向固件服务器发出GET请求时, 服务器返回的HTTP报文header里, 没有说明Content-Length 更多...
 
#define STATE_DOWNLOAD_RENEWAL_REQUEST_SENT   (-0x0922)
 OTA固件下载失败后, 正在进行断点续传, SDK向服务端重新发起了下载请求 更多...
 
#define STATE_DOWNLOAD_SETOPT_MALLOC_SHA256_CTX_FAILED   (-0x0923)
 OTA模块为计算固件的SHA256校验和申请内存时遇到失败 更多...
 
#define STATE_DOWNLOAD_SETOPT_MALLOC_MD5_CTX_FAILED   (-0x0924)
 OTA模块为计算固件的MD5校验和内存时遇到失败 更多...
 
#define STATE_OTA_PARSE_URL_HOST_IS_NULL   (-0x0925)
 OTA模块从任务描述数据结构中解析固件下载URL时, 遇到HOST字段为空, 解析失败 更多...
 
#define STATE_OTA_PARSE_URL_PATH_IS_NULL   (-0x0926)
 OTA模块从任务描述数据结构中解析固件下载URL时, 遇到PATH字段为空, 解析失败 更多...
 
#define STATE_DOWNLOAD_FETCH_TOO_MANY   (-0x0927)
 OTA模块分多段下载固件时, 多段累计的总和大小超过了固件预期的值 更多...
 
#define STATE_OTA_QUERY_FIRMWARE_HANDLE_IS_NULL   (-0x0928)
 向云端查询OTA的升级任务时, OTA句柄为空 更多...
 
#define STATE_OTA_HOST_STRING_OVERFLOW   (-0x0929)
 OTA下行报文中url字段中的host字段超出长度限制 更多...
 
#define STATE_OTA_PATH_STRING_OVERFLOW   (-0x092A)
 OTA下行报文中url字段中的path字段超出长度限制 更多...
 

类型定义

typedef void(* aiot_ota_recv_handler_t) (void *handle, const aiot_ota_recv_t *const msg, void *userdata)
 设备收到OTA的mqtt下行报文时的接收回调函数.用户在这个回调函数中可以看到待升级固件的版本号, 决定升级策略(是否升级, 何时升级等) 更多...
 
typedef void(* aiot_download_recv_handler_t) (void *handle, const aiot_download_recv_t *packet, void *userdata)
 升级开始后, 设备收到分成一段段的固件内容时的收包回调函数.当前默认是通过https报文下推分段后的固件内容. 更多...
 

枚举

enum  aiot_ota_recv_type_t { AIOT_OTARECV_FOTA, AIOT_OTARECV_COTA }
 云端下行的OTA消息的类型, 分为固件升级和远程配置两种 更多...
 
enum  aiot_ota_digest_type_t { AIOT_OTA_DIGEST_MD5, AIOT_OTA_DIGEST_SHA256, AIOT_OTA_DIGEST_MAX }
 OTA过程中使用的digest方法类型, 分为MD5和SHA256两种 更多...
 
enum  aiot_ota_protocol_type_t { AIOT_OTA_PROTOCOL_HTTPS, AIOT_OTA_PROTOCOL_MQTT, AIOT_OTA_PROTOCOL_MAX }
 OTA下载升级文件的方式 更多...
 
enum  aiot_download_recv_type_t { AIOT_DLRECV_HTTPBODY }
 下载固件过程中收到的分片的报文的类型 更多...
 
enum  aiot_ota_protocol_errcode_t { AIOT_OTAERR_UPGRADE_FAILED = -1, AIOT_OTAERR_FETCH_FAILED = -2, AIOT_OTAERR_CHECKSUM_MISMATCH = -3, AIOT_OTAERR_BURN_FAILED = -4 }
 与云端约定的OTA过程中的错误码, 云端据此知道升级过程中出错在哪个环节 更多...
 
enum  aiot_ota_option_t {
  AIOT_OTAOPT_RECV_HANDLER, AIOT_OTAOPT_MQTT_HANDLE, AIOT_OTAOPT_USERDATA, AIOT_OTAOPT_MODULE,
  AIOT_OTAOPT_MAX
}
 调用 aiot_ota_setopt 接口时, option参数的可用值 更多...
 

函数

int32_t aiot_ota_query_firmware (void *handle)
 设备端主动向云端查询升级任务 更多...
 
void * aiot_ota_init ()
 创建一个OTA实例 更多...
 
int32_t aiot_ota_deinit (void **handle)
 销毁ota实例句柄 更多...
 
int32_t aiot_ota_report_version (void *handle, char *version)
 上报普通设备(非网关中的子设备)的版本号 更多...
 
int32_t aiot_ota_report_version_ext (void *handle, char *product_key, char *device_name, char *version)
 用于网关中的子设备上报版本号 更多...
 
int32_t aiot_ota_setopt (void *handle, aiot_ota_option_t option, void *data)
 设置ota句柄的参数 更多...
 

详细描述

OTA模块头文件, 提供设备获取固件升级和远程配置的能力

日期
2019-12-27

OTA模块可用于配合阿里云平台的固件升级服务, 在推送固件到设备页面有介绍OTA的控制操作流程

宏定义说明

#define STATE_OTA_BASE   (-0x0900)

-0x0900~-0x09FF表达SDK在OTA模块内的状态码, 也包含下载时使用的STATE_DOWNLOAD_XXX

#define STATE_OTA_DIGEST_MATCH   (-0x0901)

OTA固件下载已完成, 校验和验证成功

#define STATE_OTA_REPORT_FAILED   (-0x0902)

OTA下载进度消息或固件版本号消息上报到服务器时遇到失败

#define STATE_DOWNLOAD_RECV_ERROR   (-0x0903)

OTA模块收取固件内容数据时出现错误

#define STATE_OTA_DIGEST_MISMATCH   (-0x0904)

OTA模块下载固件时出现校验和签名验证错误

固件的md5或者sha256计算结果跟云端通知的期望值不匹配所致的错误

#define STATE_OTA_PARSE_JSON_ERROR   (-0x0905)

OTA模块解析服务器下推的MQTT下行JSON报文时出错

从云端下行的JSON报文中, 无法找到目标的key, 从而无法找到相应的value

#define STATE_DOWNLOAD_SEND_REQUEST_FAILED   (-0x0906)

OTA模块发送HTTP报文, 请求下载固件时遇到失败

OTA模块往存储固件的服务器发送GET请求失败

#define STATE_DOWNLOAD_RANGE_FINISHED   (-0x0907)

OTA模块下载固件内容已到达之前设置的range末尾, 不会继续下载

按照range下载的时候已经下载到了range_end字段指定的地方. 如果用户此时还是继续尝试去下载, SDK返回返回错误码提示用户

#define STATE_OTA_PARSE_JSON_MALLOC_FAILED   (-0x0908)

OTA模块为解析JSON报文而申请内存时, 未获取到所需内存而解析失败

#define STATE_OTA_DEINIT_HANDLE_IS_NULL   (-0x0909)

销毁OTA会话实例时, 发现会话句柄为空, 中止销毁动作

#define STATE_OTA_SETOPT_HANDLE_IS_NULL   (-0x090A)

配置OTA会话实例时, 发现会话句柄为空, 中止配置动作

#define STATE_OTA_SETOPT_DATA_IS_NULL   (-0x090B)

配置OTA会话实例时, 发现配置数据为空, 中止配置动作

#define STATE_DOWNLOAD_DEINIT_HANDLE_IS_NULL   (-0x090C)

销毁下载会话实例时, 发现会话句柄为空, 中止销毁动作

#define STATE_DOWNLOAD_SETOPT_HANDLE_IS_NULL   (-0x090D)

配置下载会话实例时, 发现会话句柄为空, 中止配置动作

#define STATE_DOWNLOAD_SETOPT_DATA_IS_NULL   (-0x090E)

配置下载会话实例时, 发现配置数据为空, 中止配置动作

#define STATE_DOWNLOAD_SETOPT_COPIED_DATA_IS_NULL   (-0x090F)

配置下载会话实例时, 从OTA会话同步配置发生内部错误, 中止配置动作

#define STATE_OTA_REPORT_HANDLE_IS_NULL   (-0x0910)

直连设备上报版本号时, OTA句柄为空, 中止执行上报

#define STATE_OTA_REPORT_VERSION_IS_NULL   (-0x0911)

直连设备上报版本号时, 版本号字符串为空, 中止执行上报

#define STATE_OTA_REPORT_MQTT_HANDLE_IS_NULL   (-0x0912)

直连设备上报版本号时, MQTT句柄为空, 中止执行上报

#define STATE_OTA_REPORT_EXT_HANELD_IS_NULL   (-0x0913)

网关为子设备上报版本号时, OTA句柄为空, 中止执行上报

#define STATE_OTA_REPORT_EXT_VERSION_NULL   (-0x0914)

网关为子设备上报版本号时, 版本号字符串为空, 中止执行上报

#define STATE_OTA_REPORT_EXT_PRODUCT_KEY_IS_NULL   (-0x0915)

网关为子设备上报版本号时, 子设备productKey为空, 中止执行上报

#define STATE_OTA_REPORT_EXT_DEVICE_NAME_IS_NULL   (-0x0916)

网关为子设备上报版本号时, 子设备deviceName为空, 中止执行上报

#define STATE_OTA_REPORT_EXT_MQTT_HANDLE_IS_NULL   (-0x0917)

网关为子设备上报版本号时, MQTT会话句柄为空, 中止执行上报

#define STATE_DOWNLOAD_REPORT_HANDLE_IS_NULL   (-0x0918)

上报下载进度或OTA错误码时, 下载会话句柄为空, 中止执行上报

#define STATE_DOWNLOAD_REPORT_TASK_DESC_IS_NULL   (-0x0919)

上报下载进度或OTA错误码时, 任务描述数据结构为空, 中止执行上报

#define STATE_DOWNLOAD_RECV_HANDLE_IS_NULL   (-0x091A)

调用aiot_download_recv接收固件内容时, 处理接收数据的用户回调为空值, 中止执行

#define STATE_DOWNLOAD_REQUEST_HANDLE_IS_NULL   (-0x091B)

调用aiot_download_send_request发送固件下载请求时, 下载会话的句柄为空, 中止执行

#define STATE_DOWNLOAD_REQUEST_TASK_DESC_IS_NULL   (-0x091C)

调用aiot_download_send_request发送固件下载请求时, 任务描述为空, 中止执行

#define STATE_DOWNLOAD_REQUEST_URL_IS_NULL   (-0x091D)

调用aiot_download_send_request发送固件下载请求时, 任务描述中的固件URL为空, 中止执行

#define STATE_OTA_UNKNOWN_DIGEST_METHOD   (-0x091E)

解析通知OTA的MQTT下行报文时, 其中的digest方法并非md5或sha256, SDK不支持

#define STATE_DOWNLOAD_FINISHED   (-0x091F)

整个固件(而不是单独一次的下载片段)收取已完成, 收取的累计字节数与固件预期字节数一致

#define STATE_DOWNLOAD_HTTPRSP_CODE_ERROR   (-0x0920)

设备向固件服务器发出GET请求时, 服务器返回的HTTP报文中Status Code错误, 既非200, 也非206

#define STATE_DOWNLOAD_HTTPRSP_HEADER_ERROR   (-0x0921)

设备向固件服务器发出GET请求时, 服务器返回的HTTP报文header里, 没有说明Content-Length

#define STATE_DOWNLOAD_RENEWAL_REQUEST_SENT   (-0x0922)

OTA固件下载失败后, 正在进行断点续传, SDK向服务端重新发起了下载请求

#define STATE_DOWNLOAD_SETOPT_MALLOC_SHA256_CTX_FAILED   (-0x0923)

OTA模块为计算固件的SHA256校验和申请内存时遇到失败

#define STATE_DOWNLOAD_SETOPT_MALLOC_MD5_CTX_FAILED   (-0x0924)

OTA模块为计算固件的MD5校验和内存时遇到失败

#define STATE_OTA_PARSE_URL_HOST_IS_NULL   (-0x0925)

OTA模块从任务描述数据结构中解析固件下载URL时, 遇到HOST字段为空, 解析失败

#define STATE_OTA_PARSE_URL_PATH_IS_NULL   (-0x0926)

OTA模块从任务描述数据结构中解析固件下载URL时, 遇到PATH字段为空, 解析失败

#define STATE_DOWNLOAD_FETCH_TOO_MANY   (-0x0927)

OTA模块分多段下载固件时, 多段累计的总和大小超过了固件预期的值

可能的一个原因是用户将固件划分了多个range来下载, 但是由于不同的range之间存在重叠等原因, 导致最终的下载总量超出了固件的总大小

#define STATE_OTA_QUERY_FIRMWARE_HANDLE_IS_NULL   (-0x0928)

向云端查询OTA的升级任务时, OTA句柄为空

需要先调用aiot_ota_init函数来初始化一个OTA句柄, 再把这个句柄传给aiot_ota_query_firmware. 如果这个句柄没有被初始化, 或者 初始化不成功, 就会报出这个错误

#define STATE_OTA_HOST_STRING_OVERFLOW   (-0x0929)

OTA下行报文中url字段中的host字段超出长度限制

在OTA的下行报文中, 包含了存储固件的url. url中包含host字段, 如果host字段超出限制(当前限1024个字节), 就会报出这个错误

#define STATE_OTA_PATH_STRING_OVERFLOW   (-0x092A)

OTA下行报文中url字段中的path字段超出长度限制

在OTA的下行报文中, 包含了存储固件的url. url中包含path字段, 如果path字段超出限制(当前限1024个字节), 就会报出这个错误

类型定义说明

typedef void(* aiot_ota_recv_handler_t) (void *handle, const aiot_ota_recv_t *const msg, void *userdata)

设备收到OTA的mqtt下行报文时的接收回调函数.用户在这个回调函数中可以看到待升级固件的版本号, 决定升级策略(是否升级, 何时升级等)

参数
[in]handleOTA实例句柄
[in]msg云端下行的OTA消息
[in]userdata用户上下文
返回
void
typedef void(* aiot_download_recv_handler_t) (void *handle, const aiot_download_recv_t *packet, void *userdata)

升级开始后, 设备收到分成一段段的固件内容时的收包回调函数.当前默认是通过https报文下推分段后的固件内容.

参数
[in]handledownload实例句柄
[in]packet云端下行的分段后的固件的报文
[in]userdata用户上下文
返回
void

枚举类型说明

云端下行的OTA消息的类型, 分为固件升级和远程配置两种

传入aiot_ota_recv_handler_t 的MQTT报文类型

枚举值
AIOT_OTARECV_FOTA 

收到的OTA消息为固件升级消息

AIOT_OTARECV_COTA 

收到的OTA消息为远程配置消息

OTA过程中使用的digest方法类型, 分为MD5和SHA256两种

枚举值
AIOT_OTA_DIGEST_MD5 

收到的OTA固件的digest方法为MD5

AIOT_OTA_DIGEST_SHA256 

收到的OTA固件的digest方法为SHA256

AIOT_OTA_DIGEST_MAX 

OTA下载升级文件的方式

枚举值
AIOT_OTA_PROTOCOL_HTTPS 

下载OTA文件的方式为HTTPS

AIOT_OTA_PROTOCOL_MQTT 

下载OTA文件的方式为MQTT

AIOT_OTA_PROTOCOL_MAX 

下载固件过程中收到的分片的报文的类型

枚举值
AIOT_DLRECV_HTTPBODY 

基于HTTP传输的固件分片报文

与云端约定的OTA过程中的错误码, 云端据此知道升级过程中出错在哪个环节

枚举值
AIOT_OTAERR_UPGRADE_FAILED 

与云端约定的设备升级出错的错误描述

AIOT_OTAERR_FETCH_FAILED 

与云端约定的设备下载出错的错误码描述

AIOT_OTAERR_CHECKSUM_MISMATCH 

与云端约定的固件校验数字签名时出错的错误码描述

AIOT_OTAERR_BURN_FAILED 

与云端约定的烧写固件出错的错误码描述

调用 aiot_ota_setopt 接口时, option参数的可用值

枚举值
AIOT_OTAOPT_RECV_HANDLER 

设置处理OTA消息的用户回调函数

在该回调中, 用户可能收到两种消息: 固件升级消息或者远程配置消息.

无论哪种消息, 都包含了url, version, digest method, sign等内容.

用户需要在该回调中决定升级策略, 包括是否升级和何时升级等. 如果需要升级, 则需要调用aiot_download_init初始化一个download实例句柄. 具体见demos目录下的fota_xxx_xxx.c的用例

数据类型: (void *)

AIOT_OTAOPT_MQTT_HANDLE 

设置MQTT的handle

OTA过程中使用MQTT的通道能力, 用以向云端上报版本号, 进度, 以及错误码

数据类型: (void *)

AIOT_OTAOPT_USERDATA 

用户需要SDK暂存的上下文

该上下文会在AIOT_OTAOPT_RECV_HANDLER 中传回给用户

数据类型: (void *)

AIOT_OTAOPT_MODULE 

如果当前ota是针对某个外接模块(mcu等), 需要通过该字段设置模块名

OTA可能会针对某个外接的模块进行, 在上报版本号的时候, 需要知道模块的名称. 模块的名称通过该字段来设置.

数据类型: (void *)

AIOT_OTAOPT_MAX 

函数说明

int32_t aiot_ota_query_firmware ( void *  handle)

设备端主动向云端查询升级任务

设备上线后, 云端如果部署了OTA任务, SDK会通过aiot_ota_recv_handler_t 将该任务透给用户. 出于当前业务繁忙等原因, 这个OTA任务可能被暂时忽略, 那么用户可以在业务空闲的时候通过调用本api来让云端再次下推这个OTA任务. 同样地, SDK会从aiot_ota_recv_handler_t 将该OTA任务透给用户

返回
int32_t
返回值
STATE_SUCCESS发送请求成功
STATE_OTA_QUERY_FIRMWARE_HANDLE_IS_NULL作为入参的handle句柄没有经过初始化, 需要调用aiot_ota_init 来进行初始化

函数调用图:

void* aiot_ota_init ( )

创建一个OTA实例

返回
void*
返回值
非NULLota实例句柄
NULL初始化失败, 或者是因为没有设置portfile, 或者是内存分配失败导致

函数调用图:

int32_t aiot_ota_deinit ( void **  handle)

销毁ota实例句柄

参数
[in]handle指向ota实例句柄的指针
返回
int32_t
返回值
STATE_OTA_DEINIT_HANDLE_IS_NULLhandle或者handle所指向的地址为空
STATE_SUCCESS执行成功

函数调用图:

int32_t aiot_ota_report_version ( void *  handle,
char *  version 
)

上报普通设备(非网关中的子设备)的版本号

如果云端不知道某台设备当前的固件版本号, 就不会为其提供OTA服务, 而如果不知道设备的新版本号, 也不会认为它升级成功

所以OTA要正常工作, 一般会要求设备在每次开机之后, 就调用这个接口, 将当前运行的固件版本号字符串上报给云端

参数的handle通过aiot_ota_init 得到, 比如, 上报当前版本号为"1.0.0"的代码写作

handle = aiot_ota_init();
...
aiot_ota_report_version(handle, "1.0.0");
参数
[in]handle指向ota实例句柄的指针
[in]version待上报的版本号
返回
int32_t
返回值
STATE_OTA_REPORT_HANDLE_IS_NULLota句柄为空
STATE_OTA_REPORT_VERSION_IS_NULL用户输入的版本号为空
STATE_OTA_REPORT_MQTT_HANDLE_IS_NULLota_handle句柄中的mqtt句柄为空
STATE_OTA_REPORT_FAILED中止执行上报
STATE_SUCCESS执行成功

函数调用图:

int32_t aiot_ota_report_version_ext ( void *  handle,
char *  product_key,
char *  device_name,
char *  version 
)

用于网关中的子设备上报版本号

参数
[in]handleota实例句柄
[in]product_key设备的product_key
[in]device_name设备的名称
[in]version版本号
返回
int32_t
返回值
STATE_SUCCESS上报成功
STATE_OTA_REPORT_EXT_HANELD_IS_NULLota句柄为空
STATE_OTA_REPORT_EXT_VERSION_NULL用户输入的版本号为空
STATE_OTA_REPORT_EXT_PRODUCT_KEY_IS_NULL子设备的product_key输入为空
STATE_OTA_REPORT_EXT_DEVICE_NAME_IS_NULL子设备的device_name输入为空
STATE_OTA_REPORT_EXT_MQTT_HANDLE_IS_NULLota句柄中的mqtt_handle为空
STATE_OTA_REPORT_FAILED中止执行上报

函数调用图:

int32_t aiot_ota_setopt ( void *  handle,
aiot_ota_option_t  option,
void *  data 
)

设置ota句柄的参数

对OTA会话进行配置, 常见的配置选项包括

  • AIOT_OTAOPT_MQTT_HANDLE: 把 aiot_mqtt_init 返回的MQTT会话句柄跟OTA会话关联起来
  • AIOT_OTAOPT_RECV_HANDLER: 设置OTA消息的数据处理回调, 这个用户回调在有OTA消息的时候, 会被 aiot_mqtt_recv 调用到
参数
[in]handleota句柄
[in]option配置选项, 更多信息请参考aiot_ota_option_t
[in]data配置选项数据, 更多信息请参考aiot_ota_option_t
返回
int32_t
返回值
STATE_OTA_SETOPT_HANDLE_IS_NULLota句柄为空
STATE_OTA_SETOPT_DATA_IS_NULL参数data字段为空
STATE_USER_INPUT_UNKNOWN_OPTIONoption不支持
STATE_SUCCESS参数设置成功

函数调用图: