1 /* 2 * Copyright (C) 2015-2018 Alibaba Group Holding Limited 3 */ 4 5 #ifndef __OTA_EXPORT_H__ 6 #define __OTA_EXPORT_H__ 7 8 #include "linkkit/infra/infra_types.h" 9 #include "linkkit/infra/infra_defs.h" 10 11 #if defined(__cplusplus) 12 extern "C" { 13 #endif 14 15 #define OTA_CH_SIGNAL_MQTT (0) 16 #define OTA_CH_SIGNAL_COAP (1) 17 #define OTA_CH_FETCH_HTTP (1) 18 19 typedef enum { 20 IOT_OTAE_GENERAL = -1, 21 IOT_OTAE_INVALID_PARAM = -2, 22 IOT_OTAE_INVALID_STATE = -3, 23 IOT_OTAE_STR_TOO_LONG = -4, 24 IOT_OTAE_FETCH_FAILED = -5, 25 IOT_OTAE_NOMEM = -6, 26 IOT_OTAE_OSC_FAILED = -7, 27 IOT_OTAE_NONE = 0, 28 29 } IOT_OTA_Err_t; 30 31 /* State of OTA */ 32 typedef enum { 33 IOT_OTAS_UNINITED = 0, /* Uninitialized State */ 34 IOT_OTAS_INITED, /* Initialized State */ 35 IOT_OTAS_PUSHED, /* The mission has been pushed down */ 36 IOT_OTAS_FETCHING, /* Fetching firmware */ 37 IOT_OTAS_FETCHED /* Fetching firmware finish */ 38 } IOT_OTA_State_t; 39 40 typedef enum { 41 IOT_OTAT_NONE, 42 IOT_OTAT_COTA, 43 IOT_OTAT_FOTA 44 } IOT_OTA_Type_t; 45 46 /* Progress of OTA */ 47 typedef enum { 48 /* Burn firmware file failed */ 49 IOT_OTAP_BURN_FAILED = -4, 50 51 /* Check firmware file failed */ 52 IOT_OTAP_CHECK_FALIED = -3, 53 54 /* Fetch firmware file failed */ 55 IOT_OTAP_FETCH_FAILED = -2, 56 57 /* Initialized failed */ 58 IOT_OTAP_GENERAL_FAILED = -1, 59 60 /* [0, 100], percentage of fetch progress */ 61 62 /* The minimum percentage of fetch progress */ 63 IOT_OTAP_FETCH_PERCENTAGE_MIN = 0, 64 65 /* The maximum percentage of fetch progress */ 66 IOT_OTAP_FETCH_PERCENTAGE_MAX = 100 67 68 } IOT_OTA_Progress_t; 69 70 typedef enum { 71 IOT_OTAG_COTA_CONFIG_ID, 72 IOT_OTAG_COTA_CONFIG_SIZE, 73 IOT_OTAG_COTA_SIGN, 74 IOT_OTAG_COTA_SIGN_METHOD, 75 IOT_OTAG_COTA_URL, 76 IOT_OTAG_COTA_GETTYPE, 77 IOT_OTAG_OTA_TYPE, 78 IOT_OTAG_FETCHED_SIZE, /* option for get already fetched size */ 79 IOT_OTAG_FILE_SIZE, /* size of file */ 80 IOT_OTAG_MD5SUM, /* md5 in string format */ 81 IOT_OTAG_VERSION, /* version in string format */ 82 IOT_OTAG_CHECK_FIRMWARE, /* Check firmware is valid or not */ 83 IOT_OTAG_CHECK_CONFIG, /* Check config file is valid or not */ 84 IOT_OTAG_RESET_FETCHED_SIZE, /* reset the size_fetched parameter to be 0 */ 85 IOT_OTAG_RESET_STATE /* reset the ota state to inited */ 86 } IOT_OTA_CmdType_t; 87 88 typedef int (*ota_event_fpt)(void *); 89 /** @defgroup group_api api 90 * @{ 91 */ 92 93 /** @defgroup group_api_ota ota 94 * @{ 95 */ 96 97 /** 98 * @brief Initialize OTA module, and return handle. 99 * The MQTT client must be construct before calling this interface. 100 * 101 * @param [in] product_key: specify the product key. 102 * @param [in] device_name: specify the device name. 103 * @param [in] ch_signal: specify the signal channel. 104 * 105 * @retval 0 : Successful. 106 * @retval -1 : Failed. 107 * @see None. 108 */ 109 void *IOT_OTA_Init(const char *product_key, const char *device_name, 110 void *ch_signal); 111 112 /** 113 * @brief Deinitialize OTA module specified by the 'handle', and release the 114 * related resource. You must call this interface to release resource if reboot 115 * is not invoked after downloading. 116 * 117 * @param [in] handle: specify the OTA module. 118 * 119 * @retval 0 : Successful. 120 * @retval < 0 : Failed, the value is error code. 121 * @see None. 122 */ 123 int IOT_OTA_Deinit(void *handle); 124 125 /** 126 * @brief Report firmware version information to OTA server (optional). 127 * NOTE: please 128 * 129 * @param [in] handle: specify the OTA module. 130 * @param [in] version: specify the firmware version in string format. 131 * 132 * @retval 0 : Successful. 133 * @retval < 0 : Failed, the value is error code. 134 * @see None. 135 */ 136 int IOT_OTA_ReportVersion(void *handle, const char *version); 137 138 /** 139 * @brief Report detail progress to OTA server (optional). 140 * NOTE: please 141 * 142 * @param [in] handle: specify the OTA module. 143 * @param [in] progress: specify the progress defined by 'IOT_OTA_Progress_t'. 144 * @param [in] msg: detail progress information in string. 145 * 146 * @retval 0 : Successful. 147 * @retval < 0 : Failed, the value is error code. 148 * @see None. 149 */ 150 int IOT_OTA_ReportProgress(void *handle, IOT_OTA_Progress_t progress, 151 const char *msg); 152 153 /** 154 * @brief Check whether is on fetching state 155 * 156 * @param [in] handle: specify the OTA module. 157 * 158 * @retval 1 : Yes. 159 * @retval 0 : No. 160 * @see None. 161 */ 162 int IOT_OTA_IsFetching(void *handle); 163 164 /** 165 * @brief Check whether is on end-of-fetch state. 166 * 167 * @param [in] handle: specify the OTA module. 168 * 169 * @retval 1 : Yes. 170 * @retval 0 : False. 171 * @see None. 172 */ 173 int IOT_OTA_IsFetchFinish(void *handle); 174 175 /** 176 * @brief fetch firmware from remote server with specific timeout value. 177 * NOTE: If you want to download more faster, the bigger 'buf' should be 178 * given. 179 * 180 * @param [in] handle: specify the OTA module. 181 * @param [out] buf: specify the space for storing firmware data. 182 * @param [in] buf_len: specify the length of 'buf' in bytes. 183 * @param [in] timeout_s: specify the timeout value in second. 184 * 185 * @retval < 0 : Error occur.. 186 * @retval 0 : No any data be downloaded in 'timeout_s' timeout period. 187 * @retval (0, len] : The length of data be downloaded in 'timeout_s' timeout 188 * period in bytes. 189 * @see None. 190 */ 191 int IOT_OTA_FetchYield(void *handle, char *buf, uint32_t buf_len, 192 uint32_t timeout_s); 193 194 /** 195 * @brief Get OTA information specified by 'type'. 196 * By this interface, you can get information like state, size of file, 197 md5 of file, etc. 198 * 199 * @param [in] handle: handle of the specific OTA 200 * @param [in] type: specify what information you want, see detail 201 'IOT_OTA_CmdType_t' 202 * @param [out] buf: specify buffer for data exchange 203 * @param [in] buf_len: specify the length of 'buf' in byte. 204 * @return 205 @verbatim 206 NOTE: 207 1) When type is IOT_OTAG_FETCHED_SIZE, 'buf' should be pointer of 208 uint32_t, and 'buf_len' should be 4. 2) When type is IOT_OTAG_FILE_SIZE, 'buf' 209 should be pointer of uint32_t, and 'buf_len' should be 4. 3) When type is 210 IOT_OTAG_MD5SUM, 'buf' should be a buffer, and 'buf_len' should be 33. 4) When 211 type is IOT_OTAG_VERSION, 'buf' should be a buffer, and 'buf_len' should be 212 OTA_VERSION_LEN_MAX. 5) When type is IOT_OTAG_CHECK_FIRMWARE, 'buf' should be 213 pointer of uint32_t, and 'buf_len' should be 4. 0, firmware is invalid; 1, 214 firmware is valid. 215 @endverbatim 216 * 217 * @retval 0 : Successful. 218 * @retval < 0 : Failed, the value is error code. 219 * @see None. 220 */ 221 int IOT_OTA_Ioctl(void *handle, IOT_OTA_CmdType_t type, void *buf, int buf_len); 222 223 /** 224 * @brief Get last error code. 225 * 226 * @param [in] handle: specify the OTA module. 227 * 228 * @return The error code. 229 * @see None. 230 */ 231 int IOT_OTA_GetLastError(void *handle); 232 233 /** 234 * @brief set ota event callback. 235 * 236 * @param [in] handle: specify the OTA module. 237 * 238 * @param [in] cb: user callback. 239 * 240 * @return The error code. 241 * @see None. 242 */ 243 int IOT_OTA_SetOnPushedCallback(void *handle, int (*cb)(void *context)); 244 /** @} */ /* end of api_ota */ 245 /** @} */ /* end of api */ 246 247 #if defined(__cplusplus) 248 } 249 #endif 250 251 #endif /* __OTA_EXPORT_H__ */ 252