1 /* 2 * Copyright (c) 2020 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup OTA 18 * @{ 19 * 20 * @brief Provides system upgrades. 21 * 22 * @since 1.0 23 * @version 1.0 24 */ 25 26 /** 27 * @file hota_updater.h 28 * 29 * @brief Defines the functions for system upgrades. 30 * 31 * @since 1.0 32 * @version 1.0 33 */ 34 #ifndef OHOS_LITE_HOTA_UPDATER_H 35 #define OHOS_LITE_HOTA_UPDATER_H 36 37 #ifdef __cplusplus 38 #if __cplusplus 39 extern "C" { 40 #endif 41 #endif /* End of #ifdef __cplusplus */ 42 43 #define USE_DEFAULT_PKG 1 44 #define NOT_USE_DEFAULT_PKG 0 45 46 typedef enum { 47 HOTA_NOT_INIT = 0X01, 48 HOTA_INITED = 0x02, 49 HOTA_TRANSPORT_INFO_DONE = 0x03, 50 HOTA_TRANSPORT_ALL_DONE = 0x04, 51 HOTA_FAILED = 0x05, 52 HOTA_CANCELED = 0x06 53 } HotaStatus; 54 55 typedef enum { 56 HOTA_DATA_COMMON_ERR = 0, 57 HOTA_DATA_WRITE_ERR = 1, 58 HOTA_VERSION_INVALID = 2, 59 HOTA_DATA_SIGN_CHECK_ERR = 3, 60 HOTA_DATA_VERIFY_HASH_ERR = 4, 61 HOTA_DATA_COPY_TO_BUFFER_ERR = 5 62 } HotaErrorCode; 63 64 typedef void (*ErrorCallBackFunc)(HotaErrorCode errorCode); 65 typedef void (*StatusCallBackFunc)(HotaStatus status); 66 67 /** 68 * @brief Sets the switch for using the default upgrade package format. 69 * 70 * You can call this function to choose the default upgrade package format when developing the system upgrade 71 * capability. \n 72 * If the default upgrade package format is used, the system ensures the security and integrity of the 73 * upgrade package. \n 74 * If it is not used, you need to ensure the security and integrity of the upgrade package you have chosen. 75 * To be specific, you need to call the {@link HotaRead} function to read the data that has been written into 76 * flash memory, and then verify the data. \n 77 * 78 * @param flag Specifies whether to use the default system upgrade package format. The value <b>1</b> (default value) 79 * means to use it, and <b>0</b> means not to use it. 80 * 81 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise. 82 * 83 * @since 1.0 84 * @version 1.0 85 */ 86 int HotaSetPackageType(unsigned int flag); 87 88 /** 89 * @brief Obtains the index of the A/B partition to be upgraded. 90 * 91 * In the A/B upgrade scenario, you can use this function to determine whether partition A or B will be upgraded. \n 92 * 93 * @param index Indicates the index of a partition. The value <b>1</b> means partition A, and <b>2</b> 94 * means partition B. 95 * 96 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise. 97 * 98 * @since 1.0 99 * @version 1.0 100 */ 101 int HotaGetUpdateIndex(unsigned int *index); 102 103 /** 104 * @brief Initializes the OTA module. 105 * 106 * @param errorCallback Indicates the callback invoked when an error occurs during the upgrade. 107 * This parameter can be null. 108 * @param statusCallback Indicates the callback invoked when the upgrade status changes. This parameter can be null. 109 * 110 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise. 111 * 112 * @since 1.0 113 * @version 1.0 114 */ 115 int HotaInit(ErrorCallBackFunc errorCallback, StatusCallBackFunc statusCallback); 116 117 /** 118 * @brief Writes specified data into flash memory. 119 * 120 * @param buffer Indicates the data to be written into flash memory. 121 * @param offset Indicates the offset from where to start writing data. 122 * @param buffSize Indicates the size of the data to be written. 123 * 124 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise. 125 * 126 * @since 1.0 127 * @version 1.0 128 */ 129 int HotaWrite(unsigned char *buffer, unsigned int offset, unsigned int buffSize); 130 131 /** 132 * @brief Reads the data that has been written into flash memory. 133 * 134 * This function is required for verifying data correctness when the default upgrade package format is not used. \n 135 * It is not required when the default upgrade package format is used. \n 136 * 137 * @param offset Indicates the offset from where to start reading data. 138 * @param bufLen Indicates the length of the data to be read. 139 * @param buf Indicates the buffer to store the data that has been read. 140 * 141 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise. 142 * 143 * @since 1.0 144 * @version 1.0 145 */ 146 int HotaRead(unsigned int offset, unsigned int bufLen, unsigned char *buf); 147 148 /** 149 * @brief Cancels an upgrade. 150 * 151 * If an upgrade fails or is interrupted, you can use this function to cancel it. \n 152 * 153 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise. 154 * 155 * @since 1.0 156 * @version 1.0 157 */ 158 int HotaCancel(void); 159 160 /** 161 * @brief Sets the system state to be upgrading after data has been written into flash memory by {@link HotaWrite}. 162 * 163 * After this operation is successful, you need to call the {@link HotaRestart} function to complete the upgrade. \n 164 * 165 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise. 166 * 167 * @since 1.0 168 * @version 1.0 169 */ 170 int HotaSetBootSettings(void); 171 172 /** 173 * @brief Restarts the system after an upgrade. 174 * 175 * You need to call this function after you have called the {@link HotaSetBootSettings} function. \n 176 * 177 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise. 178 * 179 * @since 1.0 180 * @version 1.0 181 */ 182 int HotaRestart(void); 183 184 /** 185 * @brief get update ability. 186 * 187 * You need to call this function when update process init. \n 188 * 189 * @return Returns update abilty. 190 * 191 * @since 1.0 192 * @version 1.0 193 */ 194 int HotaGetUpdateAbility(void); 195 196 /** 197 * @brief get ota package update path. 198 * 199 * You need to call this function before update process. \n 200 * 201 * @param path Indicates where ota package you place. 202 * @param len Indicates path len. 203 * 204 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise. 205 * 206 * @since 1.0 207 * @version 1.0 208 */ 209 int HotaGetOtaPkgPath(char *path, int len); 210 211 /** 212 * @brief judge device can auto reboot. 213 * 214 * You need to call this function when update process init.\n 215 * 216 * @return Returns <b>1</b> if device can auto update; returns <b>0</b> if device can not auto update. 217 * 218 * @since 1.0 219 * @version 1.0 220 */ 221 int HotaIsDeviceCanReboot(void); 222 223 /** 224 * @brief judge is develop mode now. 225 * 226 * You need to call this function to get develop mode.\n 227 * 228 * @return Returns <b>1</b> if device is develop mode; returns <b>0</b> if device is not develop mode. 229 * 230 * @since 1.0 231 * @version 1.0 232 */ 233 int HotaIsDevelopMode(void); 234 235 /** 236 * @brief get update status. 237 * 238 * You need to call this function when update process .\n 239 * 240 * @return Returns UpdateStatus if the operation is successful; returns <b>-1</b> otherwise. 241 * 242 * @since 1.0 243 * @version 1.0 244 */ 245 int HotaGetUpdateStatus(void); 246 247 /** 248 * @brief reboot and clean userdata. 249 * 250 * You need to call this function when update process .\n 251 * 252 * @return Returns UpdateStatus if the operation is successful; returns <b>-1</b> otherwise. 253 * 254 * @since 1.0 255 * @version 1.0 256 */ 257 int HotaRebootAndCleanUserData(void); 258 259 /** 260 * @brief reboot and clean cache. 261 * 262 * You need to call this function when update process .\n 263 * 264 * @return Returns UpdateStatus if the operation is successful; returns <b>-1</b> otherwise. 265 * 266 * @since 1.0 267 * @version 1.0 268 */ 269 int HotaRebootAndCleanCache(void); 270 271 272 #ifdef __cplusplus 273 #if __cplusplus 274 } 275 #endif 276 #endif /* End of #ifdef __cplusplus */ 277 278 #endif /* End of #ifndef OHOS_LITE_HOTA_UPDATER_H */ 279 /** @} */ 280