Link Kit C-SDK  4.0.0
函数 | 变量
aiot_ota_api.c 文件参考

OTA模块接口实现文件, 其中包含了OTA的所有用户API. 更多...

#include "aiot_ota_api.h"
#include "core_mqtt.h"
#include "core_string.h"
#include "core_sha256.h"
#include "ota_md5.h"
#include "ota_private.h"
#include "core_log.h"
#include "core_global.h"
aiot_ota_api.c 的引用(Include)关系图:

函数

static int32_t _ota_subscribe (void *mqtt_handle, void *ota_handle)
 
static void _ota_mqtt_process (void *handle, const aiot_mqtt_recv_t *const packet, void *userdata)
 
static int32_t _ota_parse_json (aiot_sysdep_portfile_t *sysdep, void *in, uint32_t in_len, char *key_word, char **out)
 
static void _http_recv_handler (void *handle, const aiot_http_recv_t *recv_data, void *userdata)
 
static int32_t _ota_parse_list_array (char *str, int32_t str_len, ota_list_json *array)
 
static int32_t _process_single_file (aiot_sysdep_portfile_t *sysdep, char *data, uint32_t data_len, int type, aiot_download_task_desc_t *task_desc, ota_handle_t *ota_handle)
 
static int32_t _download_parse_url (const char *url, char *host, uint32_t max_host_len, char *path, uint32_t max_path_len)
 
static int32_t _download_digest_update (download_handle_t *download_handle, uint8_t *buffer, uint32_t buffer_len)
 
static int32_t _download_digest_verify (download_handle_t *download_handle)
 
static void * _download_deep_copy_base (aiot_sysdep_portfile_t *sysdep, char *in)
 
static void _ota_core_mqtt_process_handler (void *context, aiot_mqtt_event_t *event, core_mqtt_event_t *core_event)
 
static int32_t _ota_core_mqtt_operate_process_handler (ota_handle_t *ota_handle, core_mqtt_option_t option)
 
void * aiot_ota_init (void)
 创建一个OTA实例 更多...
 
int32_t aiot_ota_deinit (void **handle)
 销毁ota实例句柄 更多...
 
int32_t aiot_ota_setopt (void *handle, aiot_ota_option_t option, void *data)
 设置ota句柄的参数 更多...
 
void * aiot_download_init (void)
 初始化download实例并设置默认参数 更多...
 
int32_t aiot_download_deinit (void **handle)
 释放download实例句柄的资源 更多...
 
int32_t aiot_download_setopt (void *handle, aiot_download_option_t option, void *data)
 设置download句柄参数 更多...
 
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_query_firmware (void *handle)
 设备端主动向云端查询升级任务 更多...
 
int32_t aiot_download_report_progress (void *handle, int32_t percent)
 上报下载完成度的百分比或者错误码 更多...
 
int32_t aiot_download_recv (void *handle)
 通过download实例句柄下载一段buffer 更多...
 
int32_t _download_deep_free_task_desc (aiot_sysdep_portfile_t *sysdep, void *data)
 
int32_t _ota_prase_topic (aiot_sysdep_portfile_t *sysdep, char *topic, uint8_t topic_len, ota_type_t *type, char **product_key, char **device_name)
 
int32_t aiot_download_send_request (void *handle)
 向云端发送GET固件报文请求 更多...
 
void * _download_deep_copy_task_desc (aiot_sysdep_portfile_t *sysdep, void *data)
 
int32_t _ota_publish_base (void *handle, char *topic_prefix, char *product_key, char *device_name, char *suffix, char *params)
 

变量

static aiot_mqtt_topic_map_t g_ota_topic_map [OTA_TOPIC_NUM]
 

详细描述

OTA模块接口实现文件, 其中包含了OTA的所有用户API.

日期
2019-12-27
版权所有
Copyright (C) 2015-2018 Alibaba Group Holding Limited

函数说明

static int32_t _ota_subscribe ( void *  mqtt_handle,
void *  ota_handle 
)
static

函数调用图:

void _ota_mqtt_process ( void *  handle,
const aiot_mqtt_recv_t *const  packet,
void *  userdata 
)
static

函数调用图:

static int32_t _ota_parse_json ( aiot_sysdep_portfile_t *  sysdep,
void *  in,
uint32_t  in_len,
char *  key_word,
char **  out 
)
static
void _http_recv_handler ( void *  handle,
const aiot_http_recv_t *  recv_data,
void *  userdata 
)
static

函数调用图:

static int32_t _ota_parse_list_array ( char *  str,
int32_t  str_len,
ota_list_json *  array 
)
static
static int32_t _process_single_file ( aiot_sysdep_portfile_t *  sysdep,
char *  data,
uint32_t  data_len,
int  type,
aiot_download_task_desc_t *  task_desc,
ota_handle_t *  ota_handle 
)
static

函数调用图:

static int32_t _download_parse_url ( const char *  url,
char *  host,
uint32_t  max_host_len,
char *  path,
uint32_t  max_path_len 
)
static
static int32_t _download_digest_update ( download_handle_t *  download_handle,
uint8_t *  buffer,
uint32_t  buffer_len 
)
static
static int32_t _download_digest_verify ( download_handle_t *  download_handle)
static
static void * _download_deep_copy_base ( aiot_sysdep_portfile_t *  sysdep,
char *  in 
)
static
static void _ota_core_mqtt_process_handler ( void *  context,
aiot_mqtt_event_t *  event,
core_mqtt_event_t *  core_event 
)
static
static int32_t _ota_core_mqtt_operate_process_handler ( ota_handle_t *  ota_handle,
core_mqtt_option_t  option 
)
static

函数调用图:

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_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参数设置成功

函数调用图:

void* aiot_download_init ( )

初始化download实例并设置默认参数

返回
void*
返回值
非NULLdownload实例句柄
NULL初始化失败, 或者是没有设置portfile, 或者是内存不足无法分配download或者http实例

函数调用图:

int32_t aiot_download_deinit ( void **  handle)

释放download实例句柄的资源

参数
[in]handle指向download实例句柄的指针
返回
int32_t
返回值
STATE_DOWNLOAD_DEINIT_HANDLE_IS_NULLhandle或者handle指向的内容为空
STATE_SUCCESS执行成功

函数调用图:

int32_t aiot_download_setopt ( void *  handle,
aiot_download_option_t  option,
void *  data 
)

设置download句柄参数

配置固件下载会话的选项, 常见需要设置的选项包括

  • AIOT_DLOPT_RECV_HANDLER: 用户告诉SDK, 当SDK收到固件内容的时候, 调用哪个用户函数来传出固件内容缓冲区
  • AIOT_DLOPT_NETWORK_CRED: 可以配置是走HTTP还是走HTTPS下载固件内容
  • AIOT_DLOPT_BODY_BUFFER_MAX_LEN: 这是个缓冲区的长度, SDK下载中, 每当填满这个长度就调用一次用户回调, 所以这里设置的越大, 下载越快, 内存开销也越大
参数
[in]handledownload句柄
[in]option配置选项, 更多信息请参考aiot_download_option_t
[in]data配置选项数据, 更多信息请参考aiot_download_option_t
返回
int32_t
返回值
STATE_SUCCESS参数设置成功
STATE_DOWNLOAD_SETOPT_HANDLE_IS_NULLdownload句柄为空
STATE_DOWNLOAD_SETOPT_DATA_IS_NULLdata字段为空
STATE_DOWNLOAD_SETOPT_COPIED_DATA_IS_NULL拷贝task_desc失败
STATE_DOWNLOAD_SETOPT_MALLOC_SHA256_CTX_FAILED为shs256算法的context分配内存失败
STATE_DOWNLOAD_SETOPT_MALLOC_MD5_CTX_FAILED为MD5算法的context分配内存失败
其他出错信息请参考aiot_state_api.h

函数调用图:

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_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 来进行初始化

函数调用图:

int32_t aiot_download_report_progress ( void *  handle,
int32_t  percent 
)

上报下载完成度的百分比或者错误码

在设备开始下载固件的过程之后, 都可以用这个接口向云端上报进展情况, 包括下载进度或出错信息

  • 如果下载是正常的, 可以整数形式上报, 当前已下载的内容占固件整体大小的百分比, percent参数, SDK会自动计算好, 在回调中传给用户
  • 如果下载异常或者下载之后固件的烧录异常了, 也可以用这个接口把异常告诉云端, 设备和云端的协议错误码约定见 aiot_ota_protocol_errcode_t
  • 通过 aiot_download_report_progress 上报的内容都会影响控制台的显示, 比如显示OTA升级进度, 显示OTA升级失败等
参数
[in]handledownload句柄
[in]percent当前所下载内容完成度的百分比或者错误码
返回
int32_t
返回值
STATE_SUCCESS参数设置成功
STATE_DOWNLOAD_REPORT_HANDLE_IS_NULL上报时handle为空
STATE_DOWNLOAD_REPORT_TASK_DESC_IS_NULL上报时task_desc为空, 无法找到相应的product_key, device_name
其他出错信息请参考aiot_state_api.h

函数调用图:

int32_t aiot_download_recv ( void *  handle)

通过download实例句柄下载一段buffer

用户解析完OTA消息, 知道了固件的下载地址之后, 就可以用这个接口以HTTP下载固件内容

被下载到的内容, 会通过回调函数传递给用户, 用户调用 aiot_download_setopt 把自己的数据处理回调函数设置给SDK

参数
[in]handle指向download实例句柄的指针
返回
int32_t
返回值
>STATE_SUCCESS表示下载到的字节数
STATE_DOWNLOAD_HTTPRSP_CODE_ERROR下载所使用的url链接不可访问, 返回的code并非200或者206
STATE_DOWNLOAD_FINISHED整个固件包下载完成
STATE_DOWNLOAD_RANGE_FINISHED分段下载的时候, 单个分段下载完成
STATE_DOWNLOAD_HTTPRSP_HEADER_ERROR访问下载链接后http的回复报文中并没有Content-Length字段
STATE_DOWNLOAD_RECV_HANDLE_IS_NULLdownload句柄为空
STATE_DOWNLOAD_RENEWAL_REQUEST_SENT进行断点续传往固件服务器重新发送了下载请求
其他出错信息请参考aiot_state_api.h

函数调用图:

int32_t _download_deep_free_task_desc ( aiot_sysdep_portfile_t *  sysdep,
void *  data 
)
int32_t _ota_prase_topic ( aiot_sysdep_portfile_t *  sysdep,
char *  topic,
uint8_t  topic_len,
ota_type_t *  type,
char **  product_key,
char **  device_name 
)
int32_t aiot_download_send_request ( void *  handle)

向云端发送GET固件报文请求

设备通过OTA消息回调函数知道了固件下载地址后, 就可以调用这个接口, 下载一段固件

  • 这段长度可由AIOT_DLOPT_RANGE_START和AIOT_DLOPT_RANGE_END选项设置
  • 如果不做设置, 则默认SDK会整段去请求固件内容, 但每到填满1次用户buffer就会通知用户1次, buffer长度用AIOT_DLOPT_BODY_BUFFER_MAX_LEN选项配置
参数
[in]handledownload句柄, 包含了固件的url等信息
返回
int32_t
返回值
STATE_SUCCESS请求发送成功
STATE_DOWNLOAD_REQUEST_HANDLE_IS_NULL发送GET请求的时候handle为空
STATE_DOWNLOAD_REQUEST_URL_IS_NULL发送GET请求的时候task_desc不为空, 但是其中的url为空
STATE_DOWNLOAD_SEND_REQUEST_FAILED发送GET请求的时候http底层发包逻辑报错
STATE_DOWNLOAD_REQUEST_TASK_DESC_IS_NULL发送GET请求的时候task_desc字段为空
其他出错信息请参考aiot_state_api.h

函数调用图:

void* _download_deep_copy_task_desc ( aiot_sysdep_portfile_t *  sysdep,
void *  data 
)

函数调用图:

int32_t _ota_publish_base ( void *  handle,
char *  topic_prefix,
char *  product_key,
char *  device_name,
char *  suffix,
char *  params 
)

函数调用图:

变量说明

aiot_mqtt_topic_map_t g_ota_topic_map[OTA_TOPIC_NUM]
static
制作者   doxygen 1.8.11