C Link SDK OTA升级所需API参考-物联网平台-阿里云

IOT_OTA_Init

接口原型

void *IOT_OTA_Init(const char *product_key, const char *device_name, void *ch_signal);

接口说明
初始化OTA模块，需要先建立与云端的MQTT连接后才能使用。

参数说明

参数	数据类型	方向	说明
product_key	const char *	输入	设备证书中的Product Key。
device_name	const char *	输入	设备证书中的Device Name。
ch_signal	void *	输入	MQTT句柄。

返回值说明

值

说明

NULL

失败

非NULL

OTA句柄

IOT_OTA_Deinit

接口原型
```
int IOT_OTA_Deinit(void *handle)
```
接口说明
反初始化OTA模块，释放所有资源。

参数说明

参数	数据类型	方向	说明
handle	void *	输入	OTA句柄

返回值说明

值

说明

0

成功

< 0

失败

IOT_OTA_ReportVersion

接口原型

int IOT_OTA_ReportVersion(void *handle, const char *version);

接口说明
向云端上报当前SDK版本号。

参数说明

参数	数据类型	方向	说明
handle	void *	输入	OTA句柄
version	const char *	输入	版本号

返回值说明

值

说明

0

成功

< 0

失败

IOT_OTA_ReportProgress

接口原型

int IOT_OTA_ReportProgress(void *handle, IOT_OTA_Progress_t progress, const char *msg);

接口说明
向云端上报升级进度。

参数说明

参数	数据类型	方向	说明
handle	void *	输入	OTA句柄。
progress	IOT_OTA_Progress_t	输入	当前升级进度。
msg	const char *	输入	升级状态的描述信息，可以为NULL。

参数附加说明

typedef enum {
    IOT_OTAP_BURN_FAILED = -4,
    IOT_OTAP_CHECK_FAILED = -3,
    IOT_OTAP_FETCH_FAILED = -2,
    IOT_OTAP_GENERAL_FAILED = -1,
    IOT_OTAP_FETCH_PERCENTAGE_MIN = 0,
    IOT_OTAP_FETCH_PERCENTAGE_MAX = 100
} IOT_OTA_Progress_t;

参数	说明
IOT_OTAP_BURN_FAILED	固件烧写失败。
IOT_OTAP_CHECK_FAILED	固件校验失败。
IOT_OTAP_FETCH_FAILED	固件下载失败。
IOT_OTAP_GENERAL_FAILED	OTA其他错误。
IOT_OTAP_FETCH_PERCENTAGE_MIN	固件OTA进度最小值，为0。
IOT_OTAP_FETCH_PERCENTAGE_MAX	固件OTA进度最大值，为100。
升级进度取值范围	[0,100]区间的整数。

返回值说明

值

说明

0

成功

< 0

失败

IOT_OTA_IsFetching

接口原型
```
int IOT_OTA_IsFetching(void *handle);
```
接口说明
检测当前OTA模块是否处于从云端获取数据的状态。

参数说明

参数	数据类型	方向	说明
handle	void *	输入	OTA句柄

返回值说明

值	说明
0	未处于获取数据状态
1	正在从云端获取数据

IOT_OTA_IsFetchFinish

接口原型

int IOT_OTA_IsFetchFinish(void *handle);

接口说明
检测当前OTA模块是否获取数据完成。

参数说明

参数	数据类型	方向	说明
handle	void *	输入	OTA句柄

返回值说明

值	说明
0	获取数据未完成
1	已从云端获取数据完成

IOT_OTA_FetchYield

接口原型

int IOT_OTA_FetchYield(void *handle, char *buf, uint32_t buf_len, uint32_t timeout_s);

接口说明
该接口用于从网络接收报文，需要用户周期性调用。

参数说明

参数	数据类型	方向	说明
handle	void *	输入	OTA句柄。
buf	void *	输入	用于获取配置文件的临时buffer。
buf_len	int	输入	`data_buf`的长度。

返回值说明

值

说明

0

成功

< 0

失败

IOT_OTA_Ioctl

接口原型

int IOT_OTA_Ioctl(void *handle, IOT_OTA_CmdType_t type, void *buf, size_t buf_len);

接口说明
用于设置OTA部分参数或获取当前OTA运行状态。

参数说明

参数	数据类型	方向	说明
handle	void *	输入	OTA句柄
type	IOT_OTA_CmdType_t	输入	命令类型
buf	void *	输入/输出	命令buffer
buf_len	size_t	输入	`buf`的长度

参数附加说明

typedef enum {
    IOT_OTAG_COTA_CONFIG_ID,
    IOT_OTAG_COTA_CONFIG_SIZE,
    IOT_OTAG_COTA_SIGN,
    IOT_OTAG_COTA_SIGN_METHOD,
    IOT_OTAG_COTA_URL,
    IOT_OTAG_COTA_GETTYPE,
    IOT_OTAG_OTA_TYPE,
    IOT_OTAG_FETCHED_SIZE,     /* option for get already fetched size */
    IOT_OTAG_FILE_SIZE,        /* size of file */
    IOT_OTAG_MD5SUM,           /* md5 in string format */
    IOT_OTAG_VERSION,          /* version in string format */
    IOT_OTAG_CHECK_FIRMWARE,    /* Check firmware is valid or not */
    IOT_OTAG_CHECK_CONFIG,      /* Check config file is valid or not */
    IOT_OTAG_RESET_FETCHED_SIZE  /* reset the size_fetched parameter to be 0 */
} IOT_OTA_CmdType_t;

参数	说明
IOT_OTAG_COTA_CONFIG_ID	当前可升级配置文件的ID。
IOT_OTAG_COTA_CONFIG_SIZE	当前可升级配置文件的大小。
IOT_OTAG_COTA_SIGN	当前可升级配置文件的签名。
IOT_OTAG_COTA_SIGN_METHOD	当前可升级配置文件计算签名的方法。
IOT_OTAG_COTA_URL	当前可升级配置文件的下载地址。
IOT_OTAG_COTA_GETTYPE	当前可升级配置文件的类型。
IOT_OTAG_OTA_TYPE	当前OTA类型，COTA或FOTA。
IOT_OTAG_FETCHED_SIZE	当前可升级配置文件已下载大小。
IOT_OTAG_FILE_SIZE	当前可升级固件文件的大小。
IOT_OTAG_MD5SUM	当前已下载文件的MD5值。
IOT_OTAG_VERSION	当前可升级固件的版本号。
IOT_OTAG_CHECK_FIRMWARE	对已下载固件文件进行校验。
IOT_OTAG_CHECK_CONFIG	对已下载配置文件进行校验。
IOT_OTAG_RESET_FETCHED_SIZE	下载开始前，将已下载的数据量大小size_fetched值清零。

返回值说明

值

说明

0

成功

< 0

失败

IOT_OTA_GetLastError

接口原型
```
int IOT_OTA_GetLastError(void *handle);
```
接口说明
获取最近一次的错误码。

参数说明

参数	数据类型	方向	说明
handle	void *	输入	OTA句柄

返回值说明

值	说明
0	最近一次错误码为成功
< 0	最近一次错误码为失败

值	说明
NULL	失败
非NULL	OTA句柄

值	说明
0	成功
< 0	失败

值	说明
0	成功
< 0	失败

值	说明
0	成功
< 0	失败