1/* 2 * Copyright (c) 2023 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 16import type { AsyncCallback, Callback } from './@ohos.base'; 17 18/** 19 * Module providing backup and restore capabilities. 20 * 21 * @namespace backup 22 * @syscap SystemCapability.FileManagement.StorageService.Backup 23 * @systemapi 24 * @since 10 25 */ 26declare namespace backup { 27 /** 28 * Corresponding to a file's metadata. FileMeta is useful when doing IPC with the backup service. 29 * 30 * @interface FileMeta 31 * @syscap SystemCapability.FileManagement.StorageService.Backup 32 * @systemapi 33 * @since 10 34 */ 35 interface FileMeta { 36 /** 37 * Indicates the name of a bundle. 38 * 39 * @type { string } 40 * @syscap SystemCapability.FileManagement.StorageService.Backup 41 * @systemapi 42 * @since 10 43 */ 44 bundleName: string; 45 46 /** 47 * Indicates a uri to a file. 48 * 49 * @type { string } 50 * @syscap SystemCapability.FileManagement.StorageService.Backup 51 * @systemapi 52 * @since 10 53 */ 54 uri: string; 55 } 56 57 /** 58 * Corresponding to a file's data. Filedata is useful when doing IPC with the backup service. 59 * 60 * @interface FileData 61 * @syscap SystemCapability.FileManagement.StorageService.Backup 62 * @systemapi 63 * @since 10 64 */ 65 interface FileData { 66 /** 67 * Indicates a native file descriptor typically retrieved from the backup service to hold the file's content. 68 * 69 * @type { number } 70 * @syscap SystemCapability.FileManagement.StorageService.Backup 71 * @systemapi 72 * @since 10 73 */ 74 fd: number; 75 } 76 77 /** 78 * Corresponding to a file, including its metadata and data. 79 * File is useful when doing IPC with the backup service. 80 * 81 * @interface File 82 * @syscap SystemCapability.FileManagement.StorageService.Backup 83 * @systemapi 84 * @since 10 85 */ 86 interface File extends FileMeta, FileData {} 87 88 /** 89 * Obtain a Json file that describes local capabilities. 90 * 91 * @permission ohos.permission.BACKUP 92 * @returns { Promise<FileData> } A FileData holding all the local capabilities. The returned file is a temporal file that will be 93 * deleted automatically when closed. 94 * @throws { BusinessError } 13600001 - IPC error 95 * @throws { BusinessError } 13900005 - I/O error 96 * @throws { BusinessError } 13900011 - Out of memory 97 * @throws { BusinessError } 13900025 - No space left on device 98 * @throws { BusinessError } 13900042 - Unknown error 99 * @syscap SystemCapability.FileManagement.StorageService.Backup 100 * @systemapi 101 * @since 10 102 */ 103 function getLocalCapabilities(): Promise<FileData>; 104 105 /** 106 * Obtain a Json file that describes local capabilities. 107 * 108 * @permission ohos.permission.BACKUP 109 * @param { AsyncCallback<FileData> } callback A callback method, the argument FileData will holding all the local capabilities. 110 * The returned file is a temporal file that will be deleted automatically when closed. 111 * @throws { BusinessError } 13600001 - IPC error 112 * @throws { BusinessError } 13900005 - I/O error 113 * @throws { BusinessError } 13900011 - Out of memory 114 * @throws { BusinessError } 13900025 - No space left on device 115 * @throws { BusinessError } 13900042 - Unknown error 116 * @syscap SystemCapability.FileManagement.StorageService.Backup 117 * @systemapi 118 * @since 10 119 */ 120 function getLocalCapabilities(callback: AsyncCallback<FileData>): void; 121 122 /** 123 * General callbacks for both backup and restore procedure. 124 * The backup service will notify the client by these callbacks. 125 * 126 * @interface GeneralCallbacks 127 * @syscap SystemCapability.FileManagement.StorageService.Backup 128 * @systemapi 129 * @since 10 130 */ 131 interface GeneralCallbacks { 132 /** 133 * Callback called when the backup service tries to send files to the client. 134 * The File argument indicates a file to send to the client. 135 * The returned file is owned by the backup service and will be cleaned by the service once the file is closed. 136 * 137 * @throws { BusinessError } 13600001 - IPC error 138 * @throws { BusinessError } 13900005 - I/O error 139 * @throws { BusinessError } 13900011 - Out of memory 140 * @throws { BusinessError } 13900020 - Invalid argument 141 * @throws { BusinessError } 13900025 - No space left on device 142 * @throws { BusinessError } 13900042 - Unknown error 143 * @syscap SystemCapability.FileManagement.StorageService.Backup 144 * @systemapi 145 * @since 10 146 */ 147 onFileReady: AsyncCallback<File>; 148 149 /** 150 * Callback called when a backup/restore procedure for an bundle is started. 151 * The return string argument indicates the name of the bundle. 152 * 153 * @throws { BusinessError } 13600001 - IPC error 154 * @throws { BusinessError } 13900005 - I/O error 155 * @throws { BusinessError } 13900011 - Out of memory 156 * @throws { BusinessError } 13900020 - Invalid argument 157 * @throws { BusinessError } 13900025 - No space left on device 158 * @throws { BusinessError } 13900042 - Unknown error 159 * @syscap SystemCapability.FileManagement.StorageService.Backup 160 * @systemapi 161 * @since 10 162 */ 163 onBundleBegin: AsyncCallback<string>; 164 165 /** 166 * Callback called when a backup/restore procedure for an bundle ends successfully or gets aborted unexpectedly. 167 * The return string argument indicates the name of the bundle. 168 * 169 * @throws { BusinessError } 13600001 - IPC error 170 * @throws { BusinessError } 13900005 - I/O error 171 * @throws { BusinessError } 13900011 - Out of memory 172 * @throws { BusinessError } 13900020 - Invalid argument 173 * @throws { BusinessError } 13900025 - No space left on device 174 * @throws { BusinessError } 13900042 - Unknown error 175 * @syscap SystemCapability.FileManagement.StorageService.Backup 176 * @systemapi 177 * @since 10 178 */ 179 onBundleEnd: AsyncCallback<string>; 180 181 /** 182 * Callback called when the all the bundles to backup/restore are done or aborted unexpectedly. 183 * 184 * @throws { BusinessError } 13600001 - IPC error 185 * @throws { BusinessError } 13900005 - I/O error 186 * @throws { BusinessError } 13900011 - Out of memory 187 * @throws { BusinessError } 13900020 - Invalid argument 188 * @throws { BusinessError } 13900025 - No space left on device 189 * @throws { BusinessError } 13900042 - Unknown error 190 * @syscap SystemCapability.FileManagement.StorageService.Backup 191 * @systemapi 192 * @since 10 193 */ 194 onAllBundlesEnd: AsyncCallback<undefined>; 195 196 /** 197 * Callback called when the backup service dies unexpectedly. 198 * 199 * @syscap SystemCapability.FileManagement.StorageService.Backup 200 * @systemapi 201 * @since 10 202 */ 203 onBackupServiceDied: Callback<undefined>; 204 } 205 206 /** 207 * Control class for backup procedure. 208 * 209 * @syscap SystemCapability.FileManagement.StorageService.Backup 210 * @systemapi 211 * @since 10 212 */ 213 class SessionBackup { 214 /** 215 * Constructor for obtaining the instance of the SessionBackup class. 216 * 217 * @permission ohos.permission.BACKUP 218 * @param { GeneralCallbacks } callbacks Callbacks to be registered for the backup. 219 * @syscap SystemCapability.FileManagement.StorageService.Backup 220 * @systemapi 221 * @since 10 222 */ 223 constructor(callbacks: GeneralCallbacks); 224 225 /** 226 * Append new bundles to backup. 227 * 228 * @permission ohos.permission.BACKUP 229 * @param { string[] } bundlesToBackup Bundles to backup. 230 * @returns { Promise<void> } The promise returned by the function. 231 * @throws { BusinessError } 13600001 - IPC error 232 * @throws { BusinessError } 13900001 - Operation not permitted 233 * @throws { BusinessError } 13900005 - I/O error 234 * @throws { BusinessError } 13900011 - Out of memory 235 * @throws { BusinessError } 13900020 - Invalid argument 236 * @throws { BusinessError } 13900025 - No space left on device 237 * @throws { BusinessError } 13900042 - Unknown error 238 * @syscap SystemCapability.FileManagement.StorageService.Backup 239 * @systemapi 240 * @since 10 241 */ 242 appendBundles(bundlesToBackup: string[]): Promise<void>; 243 244 /** 245 * Append new bundles to backup. 246 * 247 * @permission ohos.permission.BACKUP 248 * @param { string[] } bundlesToBackup Bundles to backup. 249 * @param { AsyncCallback<void> } callback Asynchronous callback to be called when appendBundles has finished. 250 * @throws { BusinessError } 13600001 - IPC error 251 * @throws { BusinessError } 13900001 - Operation not permitted 252 * @throws { BusinessError } 13900005 - I/O error 253 * @throws { BusinessError } 13900011 - Out of memory 254 * @throws { BusinessError } 13900020 - Invalid argument 255 * @throws { BusinessError } 13900025 - No space left on device 256 * @throws { BusinessError } 13900042 - Unknown error 257 * @syscap SystemCapability.FileManagement.StorageService.Backup 258 * @systemapi 259 * @since 10 260 */ 261 appendBundles(bundlesToBackup: string[], callback: AsyncCallback<void>): void; 262 } 263 264 /** 265 * Control class for restore procedure. 266 * 267 * @syscap SystemCapability.FileManagement.StorageService.Backup 268 * @systemapi 269 * @since 10 270 */ 271 class SessionRestore { 272 /** 273 * Constructor for obtaining the instance of the SessionBackup class. 274 * 275 * @permission ohos.permission.BACKUP 276 * @param { GeneralCallbacks } callbacks Callbacks to be registered for the restore. 277 * @syscap SystemCapability.FileManagement.StorageService.Backup 278 * @systemapi 279 * @since 10 280 */ 281 constructor(callbacks: GeneralCallbacks); 282 283 /** 284 * Append new bundles to be restore up during the restore. 285 * 286 * @permission ohos.permission.BACKUP 287 * @param { number } remoteCapabilitiesFd Opened JSON file that stores remote device capabilities. 288 * You can use the getLocalCapabilities method to obtain the value. 289 * @param { string[] } bundlesToBackup Bundles to restore. 290 * @returns { Promise<void> } The promise returned by the function. 291 * @throws { BusinessError } 13600001 - IPC error 292 * @throws { BusinessError } 13900001 - Operation not permitted 293 * @throws { BusinessError } 13900005 - I/O error 294 * @throws { BusinessError } 13900011 - Out of memory 295 * @throws { BusinessError } 13900020 - Invalid argument 296 * @throws { BusinessError } 13900025 - No space left on device 297 * @throws { BusinessError } 13900042 - Unknown error 298 * @syscap SystemCapability.FileManagement.StorageService.Backup 299 * @systemapi 300 * @since 10 301 */ 302 appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[]): Promise<void>; 303 304 /** 305 * Append new bundles to be restore up during the restore. 306 * 307 * @permission ohos.permission.BACKUP 308 * @param { number } remoteCapabilitiesFd Opened JSON file that stores remote device capabilities. 309 * You can use the getLocalCapabilities method to obtain the value. 310 * @param { string[] } bundlesToBackup Bundles to restore. 311 * @param { AsyncCallback<void> } callback Asynchronous callback to be called when appendBundles has finished. 312 * @throws { BusinessError } 13600001 - IPC error 313 * @throws { BusinessError } 13900001 - Operation not permitted 314 * @throws { BusinessError } 13900005 - I/O error 315 * @throws { BusinessError } 13900011 - Out of memory 316 * @throws { BusinessError } 13900020 - Invalid argument 317 * @throws { BusinessError } 13900025 - No space left on device 318 * @throws { BusinessError } 13900042 - Unknown error 319 * @syscap SystemCapability.FileManagement.StorageService.Backup 320 * @systemapi 321 * @since 10 322 */ 323 appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[], callback: AsyncCallback<void>): void; 324 325 /** 326 * Publish the file handle to the backup service to make the service aware that the file's content is ready. 327 * This interface is part of the zero-copy feature. 328 * 329 * @permission ohos.permission.BACKUP 330 * @param { FileMeta } fileMeta Metadata of the file to be sent. Make sure that the backup framework holds 331 * this file by calling getFileHandle. 332 * @returns { Promise<void> } The promise returned by the function. 333 * @throws { BusinessError } 13600001 - IPC error 334 * @throws { BusinessError } 13900001 - Operation not permitted 335 * @throws { BusinessError } 13900020 - Invalid argument 336 * @throws { BusinessError } 13900042 - Unknown error 337 * @syscap SystemCapability.FileManagement.StorageService.Backup 338 * @systemapi 339 * @since 10 340 */ 341 publishFile(fileMeta: FileMeta): Promise<void>; 342 343 /** 344 * Publish the file handle to the backup service to make the service aware that the file's content is ready. 345 * This interface is part of the zero-copy feature. 346 * 347 * @permission ohos.permission.BACKUP 348 * @param { FileMeta } fileMeta Metadata of the file to be sent. Make sure that the backup framework holds 349 * this file by calling getFileHandle. 350 * @param { AsyncCallback<void> } callback Asynchronous callback to be called when publishFile has finished. 351 * @throws { BusinessError } 13600001 - IPC error 352 * @throws { BusinessError } 13900001 - Operation not permitted 353 * @throws { BusinessError } 13900020 - Invalid argument 354 * @throws { BusinessError } 13900042 - Unknown error 355 * @syscap SystemCapability.FileManagement.StorageService.Backup 356 * @systemapi 357 * @since 10 358 */ 359 publishFile(fileMeta: FileMeta, callback: AsyncCallback<void>): void; 360 361 /** 362 * Request to get a shared file from the service. This interface is part of the zero-copy feature. 363 * Developers could get the file through onFileReady callback. 364 * When the client accomplished the file, use publishFile to publish. 365 * 366 * @permission ohos.permission.BACKUP 367 * @param { FileMeta } fileMeta Metadata of the file to be sent. Note that all the files should come 368 * from the backup procedure or the getLocalCapabilities method. 369 * @returns { Promise<void> } The promise returned by the function. 370 * @throws { BusinessError } 13600001 - IPC error 371 * @throws { BusinessError } 13900001 - Operation not permitted 372 * @throws { BusinessError } 13900020 - Invalid argument 373 * @throws { BusinessError } 13900042 - Unknown error 374 * @syscap SystemCapability.FileManagement.StorageService.Backup 375 * @systemapi 376 * @since 10 377 */ 378 getFileHandle(fileMeta: FileMeta): Promise<void>; 379 380 /** 381 * Request to get a shared file from the service. This interface is part of the zero-copy feature. 382 * Developers could get the file through onFileReady callback. 383 * When the client accomplished the file, use publishFile to publish. 384 * 385 * @permission ohos.permission.BACKUP 386 * @param { FileMeta } fileMeta Metadata of the file to be sent. Note that all the files should come 387 * from the backup procedure or the getLocalCapabilities method. 388 * @param { AsyncCallback<void> } callback Asynchronous callback to be called when getFileHandle has finished. 389 * @throws { BusinessError } 13600001 - IPC error 390 * @throws { BusinessError } 13900001 - Operation not permitted 391 * @throws { BusinessError } 13900020 - Invalid argument 392 * @throws { BusinessError } 13900042 - Unknown error 393 * @syscap SystemCapability.FileManagement.StorageService.Backup 394 * @systemapi 395 * @since 10 396 */ 397 getFileHandle(fileMeta: FileMeta, callback: AsyncCallback<void>): void; 398 } 399} 400export default backup; 401