1# @ohos.request (上传下载) 2 3request部件主要给应用提供上传下载文件、后台传输代理的基础能力。 4 5> **说明：** 6> 7> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10## 导入模块 11 12 13```js 14import request from '@ohos.request'; 15``` 16 17## 常量 18 19**需要权限**：ohos.permission.INTERNET 20 21**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。 22 23### 网络类型 24下载支持自定义网络类型，可以在[DownloadConfig](#downloadconfig)中通过networkType配置成以下网络类型。 25 26| 名称 | 参数类型 | 数值 | 说明 | 27| -------- | -------- | -------- | -------- | 28| NETWORK_MOBILE | number | 0x00000001 | 使用蜂窝网络时允许下载的位标志。 | 29| NETWORK_WIFI | number | 0x00010000 | 使用WLAN时允许下载的位标志。 | 30 31### 下载任务的错误码 32下载[on('fail')<sup>7+</sup>](#onfail7)事件callback的错误参数、[getTaskInfo<sup>9+</sup>](#gettaskinfo9)返回值的failedReason字段取值。 33 34| 名称 | 参数类型 | 数值 | 说明 | 35| -------- | -------- | -------- | -------- | 36| ERROR_CANNOT_RESUME<sup>7+</sup> | number | 0 | 网络原因导致恢复下载失败。 | 37| ERROR_DEVICE_NOT_FOUND<sup>7+</sup> | number | 1 | 找不到SD卡等存储设备。 | 38| ERROR_FILE_ALREADY_EXISTS<sup>7+</sup> | number | 2 | 要下载的文件已存在，下载会话不能覆盖现有文件。 | 39| ERROR_FILE_ERROR<sup>7+</sup> | number | 3 | 文件操作失败。 | 40| ERROR_HTTP_DATA_ERROR<sup>7+</sup> | number | 4 | HTTP传输失败。 | 41| ERROR_INSUFFICIENT_SPACE<sup>7+</sup> | number | 5 | 存储空间不足。 | 42| ERROR_TOO_MANY_REDIRECTS<sup>7+</sup> | number | 6 | 网络重定向过多导致的错误。 | 43| ERROR_UNHANDLED_HTTP_CODE<sup>7+</sup> | number | 7 | 无法识别的HTTP代码。 | 44| ERROR_UNKNOWN<sup>7+</sup> | number | 8 | 未知错误。 | 45| ERROR_OFFLINE<sup>9+</sup> | number | 9 | 网络未连接。 | 46| ERROR_UNSUPPORTED_NETWORK_TYPE<sup>9+</sup> | number | 10 | 网络类型不匹配。 | 47 48 49### 下载任务暂停原因 50下载相关[getTaskInfo<sup>9+</sup>](#gettaskinfo9)返回值的pausedReason字段取值。 51 52| 名称 | 参数类型 | 数值 | 说明 | 53| -------- | -------- | -------- | -------- | 54| PAUSED_QUEUED_FOR_WIFI<sup>7+</sup> | number | 0 | 下载被暂停并等待WLAN连接，因为文件大小超过了使用蜂窝网络的会话允许的最大值。 | 55| PAUSED_WAITING_FOR_NETWORK<sup>7+</sup> | number | 1 | 由于网络问题（例如网络断开）而暂停下载。 | 56| PAUSED_WAITING_TO_RETRY<sup>7+</sup> | number | 2 | 发生网络错误，将重试下载会话。 | 57| PAUSED_BY_USER<sup>9+</sup> | number | 3 | 用户暂停会话。 | 58| PAUSED_UNKNOWN<sup>7+</sup> | number | 4 | 未知原因导致暂停下载。 | 59 60### 下载任务状态码 61下载相关[getTaskInfo<sup>9+</sup>](#gettaskinfo9)返回值的status字段取值。 62 63| 名称 | 参数类型 | 数值 | 说明 | 64| -------- | -------- | -------- | -------- | 65| SESSION_SUCCESSFUL<sup>7+</sup> | number | 0 | 下载会话已完成。 | 66| SESSION_RUNNING<sup>7+</sup> | number | 1 | 下载会话正在进行中。 | 67| SESSION_PENDING<sup>7+</sup> | number | 2 | 正在调度下载会话。 | 68| SESSION_PAUSED<sup>7+</sup> | number | 3 | 下载会话已暂停。 | 69| SESSION_FAILED<sup>7+</sup> | number | 4 | 下载会话已失败，将不会重试。 | 70 71 72## request.uploadFile<sup>9+</sup> 73 74uploadFile(context: BaseContext, config: UploadConfig): Promise<UploadTask> 75 76上传，异步方法，使用promise形式返回结果。通过[on('complete'|'fail')<sup>9+</sup>](#oncomplete--fail9)可获取任务上传时的错误信息。 77 78**需要权限**：ohos.permission.INTERNET 79 80**系统能力**: SystemCapability.MiscServices.Upload 81 82**参数：** 83 84 | 参数名 | 类型 | 必填 | 说明 | 85 | -------- | -------- | -------- | -------- | 86 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 87 | config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 | 88 89 90**返回值：** 91 92 | 类型 | 说明 | 93 | -------- | -------- | 94 | Promise<[UploadTask](#uploadtask)> | 返回上传任务。 | 95 96**错误码：** 97 98以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 99 100 | 错误码ID | 错误信息 | 101 | -------- | -------- | 102 | 13400002 | bad file path. | 103 104**示例：** 105 106 ```ts 107 let uploadTask: request.UploadTask; 108 let uploadConfig: request.UploadConfig = { 109 url: 'http://www.example.com', //需要手动替换为真实服务器地址 110 header: { 'Accept': '*/*' }, 111 method: "POST", 112 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 113 data: [{ name: "name123", value: "123" }], 114 }; 115 try { 116 request.uploadFile(getContext(), uploadConfig).then((data: request.UploadTask) => { 117 uploadTask = data; 118 }).catch((err: BusinessError) => { 119 console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`); 120 }); 121 } catch (err) { 122 console.error(`Failed to request the upload. err: ${JSON.stringify(err)}`); 123 } 124 ``` 125 126> **说明：** 127> 128> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 129 130 131## request.uploadFile<sup>9+</sup> 132 133uploadFile(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void 134 135上传，异步方法，使用callback形式返回结果。通过[on('complete'|'fail')<sup>9+</sup>](#oncomplete--fail9)可获取任务上传时的错误信息。 136 137**需要权限**：ohos.permission.INTERNET 138 139**系统能力**: SystemCapability.MiscServices.Upload 140 141**参数：** 142 143 | 参数名 | 类型 | 必填 | 说明 | 144 | -------- | -------- | -------- | -------- | 145 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 146 | config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 | 147 | callback | AsyncCallback<[UploadTask](#uploadtask)> | 是 | 回调函数，异步返回UploadTask对象。 | 148 149**错误码：** 150 151以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 152 153 | 错误码ID | 错误信息 | 154 | -------- | -------- | 155 | 13400002 | bad file path. | 156 157**示例：** 158 159 ```ts 160 let uploadTask: request.UploadTask; 161 let uploadConfig: request.UploadConfig = { 162 url: 'http://www.example.com', //需要手动替换为真实服务器地址 163 header: { 'Accept': '*/*' }, 164 method: "POST", 165 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 166 data: [{ name: "name123", value: "123" }], 167 }; 168 try { 169 request.uploadFile(getContext(), uploadConfig, (err: BusinessError, data: request.UploadTask) => { 170 if (err) { 171 console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`); 172 return; 173 } 174 uploadTask = data; 175 }); 176 } catch (err) { 177 console.error(`Failed to request the upload. err: ${JSON.stringify(err)}`); 178 } 179 ``` 180 181> **说明：** 182> 183> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 184 185## request.upload<sup>(deprecated)</sup> 186 187upload(config: UploadConfig): Promise<UploadTask> 188 189上传，异步方法，使用promise形式返回结果。 190 191**模型约束**：此接口仅可在FA模型下使用 192 193> **说明：** 从API Version 9开始不再维护，建议使用[request.uploadFile<sup>9+</sup>](#requestuploadfile9)替代。 194 195**需要权限**：ohos.permission.INTERNET 196 197**系统能力**: SystemCapability.MiscServices.Upload 198 199**参数：** 200 201 | 参数名 | 类型 | 必填 | 说明 | 202 | -------- | -------- | -------- | -------- | 203 | config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 | 204 205**返回值：** 206 207 | 类型 | 说明 | 208 | -------- | -------- | 209 | Promise<[UploadTask](#uploadtask)> | 返回上传任务。 | 210 211**示例：** 212 213 ```js 214 let uploadTask; 215 let uploadConfig = { 216 url: 'http://www.example.com', //需要手动替换为真实服务器地址 217 header: { 'Accept': '*/*' }, 218 method: "POST", 219 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 220 data: [{ name: "name123", value: "123" }], 221 }; 222 request.upload(uploadConfig).then((data) => { 223 uploadTask = data; 224 }).catch((err) => { 225 console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`); 226 }) 227 ``` 228 229 230## request.upload<sup>(deprecated)</sup> 231 232upload(config: UploadConfig, callback: AsyncCallback<UploadTask>): void 233 234上传，异步方法，使用callback形式返回结果。 235 236**模型约束**：此接口仅可在FA模型下使用 237 238> **说明：** 从API Version 9开始不再维护，建议使用[request.uploadFile<sup>9+</sup>](#requestuploadfile9-1)替代。 239 240**需要权限**：ohos.permission.INTERNET 241 242**系统能力**: SystemCapability.MiscServices.Upload 243 244**参数：** 245 246 | 参数名 | 类型 | 必填 | 说明 | 247 | -------- | -------- | -------- | -------- | 248 | config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 | 249 | callback | AsyncCallback<[UploadTask](#uploadtask)> | 是 | 回调函数，异步返回UploadTask对象。 | 250 251**示例：** 252 253 ```js 254 let uploadTask; 255 let uploadConfig = { 256 url: 'http://www.example.com', //需要手动替换为真实服务器地址 257 header: { 'Accept': '*/*' }, 258 method: "POST", 259 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 260 data: [{ name: "name123", value: "123" }], 261 }; 262 request.upload(uploadConfig, (err, data) => { 263 if (err) { 264 console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`); 265 return; 266 } 267 uploadTask = data; 268 }); 269 ``` 270 271## UploadTask 272 273上传任务，使用下列方法前，需要先获取UploadTask对象，promise形式通过[request.uploadFile<sup>9+</sup>](#requestuploadfile9)获取，callback形式通过[request.uploadFile<sup>9+</sup>](#requestuploadfile9-1)获取。 274 275 276 277### on('progress') 278 279on(type: 'progress', callback:(uploadedSize: number, totalSize: number) => void): void 280 281订阅上传任务进度监听，同步方法，使用callback形式返回结果。 282 283> **说明：** 284> 285> 当应用处于后台时，为满足功耗性能要求，不支持调用此接口进行回调。 286 287**需要权限**：ohos.permission.INTERNET 288 289**系统能力**: SystemCapability.MiscServices.Upload 290 291**参数：** 292 293 | 参数名 | 类型 | 必填 | 说明 | 294 | -------- | -------- | -------- | -------- | 295 | type | string | 是 | 订阅的事件类型，取值为'progress'（上传的进度信息）。 | 296 | callback | function | 是 | 上传进度的回调函数。 | 297 298 回调函数的参数 299 300| 参数名 | 类型 | 必填 | 说明 | 301| -------- | -------- | -------- | -------- | 302| uploadedSize | number | 是 | 当前已上传文件大小，单位为B。 | 303| totalSize | number | 是 | 上传文件的总大小，单位为B。 | 304 305**示例：** 306 307 ```ts 308 let upProgressCallback = (uploadedSize: number, totalSize: number) => { 309 console.info("upload totalSize:" + totalSize + " uploadedSize:" + uploadedSize); 310 }; 311 uploadTask.on('progress', upProgressCallback); 312 ``` 313 314 315### on('headerReceive')<sup>7+</sup> 316 317on(type: 'headerReceive', callback: (header: object) => void): void 318 319订阅上传任务HTTP标头监听，同步方法，使用callback形式返回结果。 320 321**需要权限**：ohos.permission.INTERNET 322 323**系统能力**: SystemCapability.MiscServices.Upload 324 325**参数：** 326 327 | 参数名 | 类型 | 必填 | 说明 | 328 | -------- | -------- | -------- | -------- | 329 | type | string | 是 | 订阅的事件类型，取值为'headerReceive'（接收响应头）。 | 330 | callback | function | 是 | HTTP Response Header事件的回调函数。 | 331 332 回调函数的参数： 333 334| 参数名 | 类型 | 必填 | 说明 | 335| -------- | -------- | -------- | -------- | 336| header | object | 是 | HTTP Response Header。 | 337 338**示例：** 339 340 ```ts 341 let headerCallback = (headers: object) => { 342 console.info("upOnHeader headers:" + JSON.stringify(headers)); 343 }; 344 uploadTask.on('headerReceive', headerCallback); 345 ``` 346 347 348### on('complete' | 'fail')<sup>9+</sup> 349 350 on(type:'complete' | 'fail', callback: Callback<Array<TaskState>>): void; 351 352订阅上传任务完成或失败监听，同步方法，使用callback形式返回结果。 353 354**需要权限**：ohos.permission.INTERNET 355 356**系统能力**: SystemCapability.MiscServices.Upload 357 358**参数：** 359 360 | 参数名 | 类型 | 必填 | 说明 | 361 | -------- | -------- | -------- | -------- | 362 | type | string | 是 | 订阅的事件类型，取值为'complete'，表示上传任务完成；取值为'fail'，表示上传任务失败。| 363 | callback | Callback<Array<TaskState>> | 是 | 上传任务完成或失败的回调函数。 | 364 365 回调函数的参数 366 367| 参数名 | 类型 | 必填 | 说明 | 368| -------- | -------- | -------- | -------- | 369| taskstates | Array<[TaskState](#taskstate9)> | 是 | 上传任务返回结果 | 370 371**示例：** 372 373 ```ts 374 let upCompleteCallback = (taskStates: Array<request.TaskState>) => { 375 for (let i = 0; i < taskStates.length; i++) { 376 console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i])); 377 } 378 }; 379 uploadTask.on('complete', upCompleteCallback); 380 381 let upFailCallback = (taskStates: Array<request.TaskState>) => { 382 for (let i = 0; i < taskStates.length; i++) { 383 console.info("upOnFail taskState:" + JSON.stringify(taskStates[i])); 384 } 385 }; 386 uploadTask.on('fail', upFailCallback); 387 ``` 388 389 390### off('progress') 391 392off(type: 'progress', callback?: (uploadedSize: number, totalSize: number) => void): void 393 394取消订阅上传任务进度监听，同步方法。 395 396**需要权限**：ohos.permission.INTERNET 397 398**系统能力**: SystemCapability.MiscServices.Upload 399 400**参数：** 401 402 | 参数名 | 类型 | 必填 | 说明 | 403 | -------- | -------- | -------- | -------- | 404 | type | string | 是 | 取消订阅的事件类型，取值为'progress'（上传的进度信息）。 | 405 | callback | function | 否 | 需要删除的上传任务进度的回调函数。<br/>uploadedSize：当前已上传文件的大小，单位为B。<br/>totalSize：上传文件的总大小，单位为B。 | 406 407**示例：** 408 409 ```ts 410 let upProgressCallback = (uploadedSize: number, totalSize: number) => { 411 console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize); 412 }; 413 uploadTask.off('progress', upProgressCallback); 414 ``` 415 416 417### off('headerReceive')<sup>7+</sup> 418 419off(type: 'headerReceive', callback?: (header: object) => void): void 420 421取消订阅上传任务HTTP标头监听，同步方法。 422 423**需要权限**：ohos.permission.INTERNET 424 425**系统能力**: SystemCapability.MiscServices.Upload 426 427**参数：** 428 429 | 参数名 | 类型 | 必填 | 说明 | 430 | -------- | -------- | -------- | -------- | 431 | type | string | 是 | 取消订阅的事件类型，取值为'headerReceive'（接收响应头）。 | 432 | callback | function | 否 | HTTP Response 需要删除的Header事件的回调函数。<br/>header：HTTP Response Header。 | 433 434**示例：** 435 436 ```ts 437 let headerCallback = (header: object) => { 438 console.info(`Upload delete headerReceive notification. header: ${JSON.stringify(header)}`); 439 }; 440 uploadTask.off('headerReceive', headerCallback); 441 ``` 442 443### off('complete' | 'fail')<sup>9+</sup> 444 445 off(type:'complete' | 'fail', callback?: Callback<Array<TaskState>>): void; 446 447取消订阅上传任务完成或失败监听，同步方法。 448 449**需要权限**：ohos.permission.INTERNET 450 451**系统能力**: SystemCapability.MiscServices.Upload 452 453**参数：** 454 455 | 参数名 | 类型 | 必填 | 说明 | 456 | -------- | -------- | -------- | -------- | 457 | type | string | 是 | 订阅的事件类型，取值为'complete'，表示上传任务完成；取值为'fail'，表示上传任务失败。| 458 | callback | Callback<Array<TaskState>> | 否 | 需要删除的上传任务完成或失败的回调函数。<br/>taskstates：上传任务返回结果 | 459 460**示例：** 461 462 ```ts 463 let upCompleteCallback = (taskStates: Array<request.TaskState>) => { 464 console.info('Upload delete complete notification.'); 465 for (let i = 0; i < taskStates.length; i++) { 466 console.info('taskState:' + JSON.stringify(taskStates[i])); 467 } 468 }; 469 uploadTask.off('complete', upCompleteCallback); 470 471 let upFailCallback = (taskStates: Array<request.TaskState>) => { 472 console.info('Upload delete fail notification.'); 473 for (let i = 0; i < taskStates.length; i++) { 474 console.info('taskState:' + JSON.stringify(taskStates[i])); 475 } 476 }; 477 uploadTask.off('fail', upFailCallback); 478 ``` 479 480### delete<sup>9+</sup> 481delete(): Promise<boolean> 482 483移除上传的任务，异步方法，使用promise形式返回结果。 484 485**需要权限**：ohos.permission.INTERNET 486 487**系统能力**: SystemCapability.MiscServices.Upload 488 489**返回值：** 490 491 | 类型 | 说明 | 492 | -------- | -------- | 493 | Promise<boolean> | 移除任务是否成功。true：成功，false：不成功。 | 494 495**示例：** 496 497 ```ts 498 uploadTask.delete().then((result: boolean) => { 499 console.info('Succeeded in deleting the upload task.'); 500 }).catch((err: BusinessError) => { 501 console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`); 502 }); 503 ``` 504 505 506### delete<sup>9+</sup> 507 508delete(callback: AsyncCallback<boolean>): void 509 510移除上传的任务，异步方法，使用callback形式返回结果。 511 512**需要权限**：ohos.permission.INTERNET 513 514**系统能力**: SystemCapability.MiscServices.Upload 515 516**参数：** 517 518 | 参数名 | 类型 | 必填 | 说明 | 519 | -------- | -------- | -------- | -------- | 520 | callback | AsyncCallback<boolean> | 是 | 移除任务的回调函数。 | 521 522**示例：** 523 524 ```ts 525 uploadTask.delete((err: BusinessError, result: boolean) => { 526 if (err) { 527 console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`); 528 return; 529 } 530 console.info('Succeeded in deleting the upload task.'); 531 }); 532 ``` 533 534 535### remove<sup>(deprecated)</sup> 536 537remove(): Promise<boolean> 538 539移除上传的任务，异步方法，使用promise形式返回结果。 540 541> **说明：** 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9)替代。 542 543**需要权限**：ohos.permission.INTERNET 544 545**系统能力**: SystemCapability.MiscServices.Upload 546 547**返回值：** 548 549 | 类型 | 说明 | 550 | -------- | -------- | 551 | Promise<boolean> | 移除任务是否成功。true：成功，false：不成功。 | 552 553**示例：** 554 555 ```js 556 uploadTask.remove().then((result) => { 557 console.info('Succeeded in removing the upload task.'); 558 }).catch((err) => { 559 console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`); 560 }); 561 ``` 562 563 564### remove<sup>(deprecated)</sup> 565 566remove(callback: AsyncCallback<boolean>): void 567 568移除上传的任务，异步方法，使用callback形式返回结果。 569 570> **说明：** 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9-1)替代。 571 572**需要权限**：ohos.permission.INTERNET 573 574**系统能力**: SystemCapability.MiscServices.Upload 575 576**参数：** 577 578 | 参数名 | 类型 | 必填 | 说明 | 579 | -------- | -------- | -------- | -------- | 580 | callback | AsyncCallback<boolean> | 是 | 移除任务的回调函数。 | 581 582**示例：** 583 584 ```js 585 uploadTask.remove((err, result) => { 586 if (err) { 587 console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`); 588 return; 589 } 590 if (result) { 591 console.info('Succeeded in removing the upload task.'); 592 } else { 593 console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`); 594 } 595 }); 596 ``` 597 598## UploadConfig 599上传任务的配置信息。 600 601**需要权限**：ohos.permission.INTERNET 602 603**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。 604 605| 名称 | 类型 | 必填 | 说明 | 606| -------- | -------- | -------- | -------- | 607| url | string | 是 | 资源地址。 | 608| header | Object | 是 | 添加要包含在上传请求中的HTTP或HTTPS标志头。 | 609| method | string | 是 | 请求方法：POST、PUT。缺省为POST。 | 610| files | Array<[File](#file)> | 是 | 要上传的文件列表。请使用 multipart/form-data提交。 | 611| data | Array<[RequestData](#requestdata)> | 是 | 请求的表单数据。 | 612 613## TaskState<sup>9+</sup> 614上传任务信息，[on('complete' | 'fail')<sup>9+</sup>](#oncomplete--fail9)和[off('complete' | 'fail')<sup>9+</sup>](#offcomplete--fail9)接口的回调参数。 615 616**需要权限**：ohos.permission.INTERNET 617 618**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。 619 620| 名称 | 类型 | 必填 | 说明 | 621| -------- | -------- | -------- | -------- | 622| path | string | 是 | 文件路径 | 623| responseCode | number | 是 | 上传任务返回值，0表示任务成功，其它返回码为失败，具体请查看message上传任务结果描述信息 | 624| message | string | 是 | 上传任务结果描述信息 | 625 626## File 627[UploadConfig](#uploadconfig)中的文件列表。 628 629**需要权限**：ohos.permission.INTERNET 630 631**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。 632 633| 名称 | 类型 | 必填 | 说明 | 634| -------- | -------- | -------- | -------- | 635| filename | string | 是 | multipart提交时，请求头中的文件名。 | 636| name | string | 是 | multipart提交时，表单项目的名称，缺省为file。 | 637| uri | string | 是 | 文件的本地存储路径。<br/>仅支持"internal"协议类型，"internal://cache/"为必填字段，示例：<br/>internal://cache/path/to/file.txt | 638| type | string | 是 | 文件的内容类型，默认根据文件名或路径的后缀获取。 | 639 640 641## RequestData 642[UploadConfig](#uploadconfig)中的表单数据。 643 644**需要权限**：ohos.permission.INTERNET 645 646**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。 647 648| 名称 | 类型 | 必填 | 说明 | 649| -------- | -------- | -------- | -------- | 650| name | string | 是 | 表示表单元素的名称。 | 651| value | string | 是 | 表示表单元素的值。 | 652 653## request.downloadFile<sup>9+</sup> 654 655downloadFile(context: BaseContext, config: DownloadConfig): Promise<DownloadTask> 656 657下载，异步方法，使用promise形式返回结果。通过[on('complete'|'pause'|'remove')<sup>7+</sup>](#oncompletepauseremove7)可获取任务下载时的状态信息，包括任务完成、暂停或移除。通过[on('fail')<sup>7+</sup>](#onfail7)可获取任务下载时的错误信息。 658 659 660**需要权限**：ohos.permission.INTERNET 661 662**系统能力**: SystemCapability.MiscServices.Download 663 664**参数：** 665 666 | 参数名 | 类型 | 必填 | 说明 | 667 | -------- | -------- | -------- | -------- | 668 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 669 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 670 671**返回值：** 672 673 | 类型 | 说明 | 674 | -------- | -------- | 675 | Promise<[DownloadTask](#downloadtask)> | 返回下载任务。 | 676 677**错误码：** 678 679以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 680 681 | 错误码ID | 错误信息 | 682 | -------- | -------- | 683 | 13400001 | file operation error. | 684 | 13400002 | bad file path. | 685 | 13400003 | task service ability error. | 686 687**示例：** 688 689 ```ts 690 let downloadTask: request.DownloadTask; 691 try { 692 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 693 downloadTask = data; 694 }).catch((err: BusinessError) => { 695 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 696 }) 697 } catch (err) { 698 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 699 } 700 ``` 701 702> **说明：** 703> 704> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 705 706 707## request.downloadFile<sup>9+</sup> 708 709downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void; 710 711下载，异步方法，使用callback形式返回结果。通过[on('complete'|'pause'|'remove')<sup>7+</sup>](#oncompletepauseremove7)可获取任务下载时的状态信息，包括任务完成、暂停或移除。通过[on('fail')<sup>7+</sup>](#onfail7)可获取任务下载时的错误信息。 712 713 714**需要权限**：ohos.permission.INTERNET 715 716**系统能力**: SystemCapability.MiscServices.Download 717 718**参数：** 719 720 | 参数名 | 类型 | 必填 | 说明 | 721 | -------- | -------- | -------- | -------- | 722 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 723 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 724 | callback | AsyncCallback<[DownloadTask](#downloadtask)> | 是 | 下载接口的回调函数。 | 725 726**错误码：** 727 728以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 729 730 | 错误码ID | 错误信息 | 731 | -------- | -------- | 732 | 13400001 | file operation error. | 733 | 13400002 | bad file path. | 734 | 13400003 | task service ability error. | 735 736**示例：** 737 738 ```ts 739 let downloadTask: request.DownloadTask; 740 try { 741 request.downloadFile(getContext(), { 742 url: 'https://xxxx/xxxxx.hap', 743 filePath: 'xxx/xxxxx.hap' 744 }, (err: BusinessError, data: request.DownloadTask) => { 745 if (err) { 746 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 747 return; 748 } 749 downloadTask = data; 750 }); 751 } catch (err) { 752 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 753 } 754 ``` 755 756> **说明：** 757> 758> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 759 760## request.download<sup>(deprecated)</sup> 761 762download(config: DownloadConfig): Promise<DownloadTask> 763 764下载，异步方法，使用promise形式返回结果。 765 766> **说明：** 从API Version 9开始不再维护，建议使用[request.downloadFile<sup>9+</sup>](#requestdownloadfile9)替代。 767 768**模型约束**：此接口仅可在FA模型下使用 769 770**需要权限**：ohos.permission.INTERNET 771 772**系统能力**: SystemCapability.MiscServices.Download 773 774**参数：** 775 776 | 参数名 | 类型 | 必填 | 说明 | 777 | -------- | -------- | -------- | -------- | 778 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 779 780**返回值：** 781 782 | 类型 | 说明 | 783 | -------- | -------- | 784 | Promise<[DownloadTask](#downloadtask)> | 返回下载任务。 | 785 786**示例：** 787 788 ```js 789 let downloadTask; 790 request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => { 791 downloadTask = data; 792 }).catch((err) => { 793 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 794 }) 795 ``` 796 797 798## request.download<sup>(deprecated)</sup> 799 800download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void 801 802下载，异步方法，使用callback形式返回结果。 803 804> **说明：** 从API Version 9开始不再维护，建议使用[request.downloadFile<sup>9+</sup>](#requestdownloadfile9-1)替代。 805 806**模型约束**：此接口仅可在FA模型下使用 807 808**需要权限**：ohos.permission.INTERNET 809 810**系统能力**: SystemCapability.MiscServices.Download 811 812**参数：** 813 814 | 参数名 | 类型 | 必填 | 说明 | 815 | -------- | -------- | -------- | -------- | 816 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 817 | callback | AsyncCallback<[DownloadTask](#downloadtask)> | 是 | 下载接口的回调函数。 | 818 819**示例：** 820 821 ```js 822 let downloadTask; 823 request.download({ url: 'https://xxxx/xxxxx.hap', 824 filePath: 'xxx/xxxxx.hap'}, (err, data) => { 825 if (err) { 826 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 827 return; 828 } 829 downloadTask = data; 830 }); 831 ``` 832 833## DownloadTask 834 835下载任务，使用下列方法前，需要先获取DownloadTask对象，promise形式通过[request.downloadFile<sup>9+</sup>](#requestdownloadfile9)获取，callback形式通过[request.downloadFile<sup>9+</sup>](#requestdownloadfile9-1)获取。 836 837 838### on('progress') 839 840on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void 841 842订阅下载任务进度监听，同步方法，使用callback形式返回结果。 843 844> **说明：** 845> 846> 当应用处于后台时，为满足功耗性能要求，不支持调用此接口进行回调。 847 848**需要权限**：ohos.permission.INTERNET 849 850**系统能力**: SystemCapability.MiscServices.Download 851 852**参数：** 853 854 | 参数名 | 类型 | 必填 | 说明 | 855 | -------- | -------- | -------- | -------- | 856 | type | string | 是 | 订阅的事件类型，取值为'progress'（下载的进度信息）。 | 857 | callback | function | 是 | 下载任务进度的回调函数。 | 858 859 回调函数的参数： 860 861| 参数名 | 类型 | 必填 | 说明 | 862| -------- | -------- | -------- | -------- | 863| receivedSize | number | 是 | 当前下载的进度，单位为B。 | 864| totalSize | number | 是 | 下载文件的总大小，单位为B。 | 865 866**示例：** 867 868 ```ts 869 let progressCallback = (receivedSize: number, totalSize: number) => { 870 console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); 871 }; 872 downloadTask.on('progress', progressCallback); 873 ``` 874 875 876### off('progress') 877 878off(type: 'progress', callback?: (receivedSize: number, totalSize: number) => void): void 879 880取消订阅下载任务进度监听，同步方法。 881 882**需要权限**：ohos.permission.INTERNET 883 884**系统能力**: SystemCapability.MiscServices.Download 885 886**参数：** 887 888 | 参数名 | 类型 | 必填 | 说明 | 889 | -------- | -------- | -------- | -------- | 890 | type | string | 是 | 取消订阅的事件类型，取值为'progress'（下载的进度信息）。 | 891 | callback | function | 否 | 需要删除的下载任务进度的回调。 <br/>receivedSize：当前下载任务的进度；<br/>totalSize：下载文件的总大小。 | 892 893**示例：** 894 895 ```ts 896 let progressCallback = (receivedSize: number, totalSize: number) => { 897 console.info('Download delete progress notification.' + 'receivedSize:' + receivedSize + 'totalSize:' + totalSize); 898 }; 899 downloadTask.off('progress', progressCallback); 900 ``` 901 902 903### on('complete'|'pause'|'remove')<sup>7+</sup> 904 905on(type: 'complete'|'pause'|'remove', callback:() => void): void 906 907订阅下载任务相关的监听，异步方法，使用callback形式返回。 908 909**需要权限**：ohos.permission.INTERNET 910 911**系统能力**: SystemCapability.MiscServices.Download 912 913**参数：** 914 915 | 参数名 | 类型 | 必填 | 说明 | 916 | -------- | -------- | -------- | -------- | 917 | type | string | 是 | 订阅的事件类型。<br>- 取值为'complete'，表示下载任务完成；<br/>- 取值为'pause'，表示下载任务暂停；<br/>- 取值为'remove'，表示下载任务移除。 | 918 | callback | function | 是 | 下载任务相关的回调函数。| 919 920**示例：** 921 922 ```ts 923 let completeCallback = () => { 924 console.info('Download task completed.'); 925 }; 926 downloadTask.on('complete', completeCallback); 927 928 let pauseCallback = () => { 929 console.info('Download task pause.'); 930 }; 931 downloadTask.on('pause', pauseCallback); 932 933 let removeCallback = () => { 934 console.info('Download task remove.'); 935 }; 936 downloadTask.on('remove', removeCallback); 937 ``` 938 939 940### off('complete'|'pause'|'remove')<sup>7+</sup> 941 942off(type: 'complete'|'pause'|'remove', callback?:() => void): void 943 944取消订阅下载任务相关的监听，同步方法。 945 946**需要权限**：ohos.permission.INTERNET 947 948**系统能力**: SystemCapability.MiscServices.Download 949 950**参数：** 951 952 | 参数名 | 类型 | 必填 | 说明 | 953 | -------- | -------- | -------- | -------- | 954 | type | string | 是 | 取消订阅的事件类型。<br/>- 取值为'complete'，表示下载任务完成；<br/>- 取值为'pause'，表示下载任务暂停；<br/>- 取值为'remove'，表示下载任务移除。 | 955 | callback | function | 否 | 需要删除的下载任务相关的回调。 | 956 957**示例：** 958 959 ```ts 960 let completeCallback = () => { 961 console.info('Download delete complete notification.'); 962 }; 963 downloadTask.off('complete', completeCallback); 964 965 let pauseCallback = () => { 966 console.info('Download delete pause notification.'); 967 }; 968 downloadTask.off('pause', pauseCallback); 969 970 let removeCallback = () => { 971 console.info('Download delete remove notification.'); 972 }; 973 downloadTask.off('remove', removeCallback); 974 ``` 975 976 977### on('fail')<sup>7+</sup> 978 979on(type: 'fail', callback: (err: number) => void): void 980 981订阅下载任务失败监听，同步方法，使用callback形式返回结果。 982 983**需要权限**：ohos.permission.INTERNET 984 985**系统能力**: SystemCapability.MiscServices.Download 986 987**参数：** 988 989 | 参数名 | 类型 | 必填 | 说明 | 990 | -------- | -------- | -------- | -------- | 991 | type | string | 是 | 订阅的事件类型，取值为'fail'（下载失败）。 | 992 | callback | function | 是 | 下载失败的回调函数。 | 993 994 回调函数的参数： 995 996| 参数名 | 类型 | 必填 | 说明 | 997| -------- | -------- | -------- | -------- | 998| err | number | 是 | 下载失败的错误码，错误原因见[下载任务的错误码](#下载任务的错误码)。 | 999 1000**示例：** 1001 1002 ```ts 1003 let failCallback = (err: number) => { 1004 console.error(`Failed to download the task. Code: ${err}`); 1005 }; 1006 downloadTask.on('fail', failCallback); 1007 ``` 1008 1009 1010### off('fail')<sup>7+</sup> 1011 1012off(type: 'fail', callback?: (err: number) => void): void 1013 1014取消订阅下载任务失败监听，同步方法。 1015 1016**需要权限**：ohos.permission.INTERNET 1017 1018**系统能力**: SystemCapability.MiscServices.Download 1019 1020**参数：** 1021 1022 | 参数名 | 类型 | 必填 | 说明 | 1023 | -------- | -------- | -------- | -------- | 1024 | type | string | 是 | 取消订阅的事件类型，取值为'fail'（下载失败）。 | 1025 | callback | function | 否 | 需要删除的下载失败的回调函数。<br/>err：下载失败的错误码。 | 1026 1027**示例：** 1028 1029 ```ts 1030 let failCallback = (err: number) => { 1031 console.error(`Failed to download the task. Code: ${err}`); 1032 }; 1033 downloadTask.off('fail', failCallback); 1034 ``` 1035 1036### delete<sup>9+</sup> 1037 1038delete(): Promise<boolean> 1039 1040移除下载的任务，异步方法，使用promise形式返回结果。 1041 1042**需要权限**：ohos.permission.INTERNET 1043 1044**系统能力**: SystemCapability.MiscServices.Download 1045 1046**返回值：** 1047 1048 | 类型 | 说明 | 1049 | -------- | -------- | 1050 | Promise<boolean> | 移除任务是否成功。 | 1051 1052**示例：** 1053 1054 ```ts 1055 downloadTask.delete().then((result: boolean) => { 1056 console.info('Succeeded in removing the download task.'); 1057 }).catch((err: BusinessError) => { 1058 console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); 1059 }); 1060 ``` 1061 1062 1063### delete<sup>9+</sup> 1064 1065delete(callback: AsyncCallback<boolean>): void 1066 1067移除下载的任务，异步方法，使用callback形式返回结果。 1068 1069**需要权限**：ohos.permission.INTERNET 1070 1071**系统能力**: SystemCapability.MiscServices.Download 1072 1073**参数：** 1074 1075 | 参数名 | 类型 | 必填 | 说明 | 1076 | -------- | -------- | -------- | -------- | 1077 | callback | AsyncCallback<boolean> | 是 | 移除任务是否成功。 | 1078 1079**示例：** 1080 1081 ```ts 1082 downloadTask.delete((err: BusinessError, result: boolean) => { 1083 if (err) { 1084 console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); 1085 return; 1086 } 1087 console.info('Succeeded in removing the download task.'); 1088 }); 1089 ``` 1090 1091 1092### getTaskInfo<sup>9+</sup> 1093 1094getTaskInfo(): Promise<DownloadInfo> 1095 1096查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。 1097 1098**需要权限**：ohos.permission.INTERNET 1099 1100**系统能力**: SystemCapability.MiscServices.Download 1101 1102**返回值：** 1103 1104 | 类型 | 说明 | 1105 | -------- | -------- | 1106 | Promise<[DownloadInfo](#downloadinfo7)> | 查询下载任务信息。 | 1107 1108**示例：** 1109 1110 ```ts 1111 downloadTask.getTaskInfo().then((downloadInfo: request.DownloadInfo) => { 1112 console.info('Succeeded in querying the download task') 1113 }).catch((err: BusinessError) => { 1114 console.error(`Failed to query the download task. Code: ${err.code}, message: ${err.message}`) 1115 }); 1116 ``` 1117 1118 1119### getTaskInfo<sup>9+</sup> 1120 1121getTaskInfo(callback: AsyncCallback<DownloadInfo>): void 1122 1123查询下载的任务，异步方法，使用callback形式返回结果。 1124 1125**需要权限**：ohos.permission.INTERNET 1126 1127**系统能力**: SystemCapability.MiscServices.Download 1128 1129**参数：** 1130 1131 | 参数名 | 类型 | 必填 | 说明 | 1132 | -------- | -------- | -------- | -------- | 1133 | callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | 是 | 查询下载任务的回调函数。 | 1134 1135**示例：** 1136 1137 ```ts 1138 downloadTask.getTaskInfo((err: BusinessError, downloadInfo: request.DownloadInfo) => { 1139 if (err) { 1140 console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`); 1141 } else { 1142 console.info('Succeeded in querying the download mimeType'); 1143 } 1144 }); 1145 ``` 1146 1147 1148### getTaskMimeType<sup>9+</sup> 1149 1150getTaskMimeType(): Promise<string> 1151 1152查询下载的任务的 MimeType，异步方法，使用promise形式返回结果。 1153 1154**需要权限**：ohos.permission.INTERNET 1155 1156**系统能力**: SystemCapability.MiscServices.Download 1157 1158**返回值：** 1159 1160 | 类型 | 说明 | 1161 | -------- | -------- | 1162 | Promise<string> | 查询下载任务的MimeType。 | 1163 1164**示例：** 1165 1166 ```ts 1167 downloadTask.getTaskMimeType().then((data: string) => { 1168 console.info('Succeeded in querying the download MimeType'); 1169 }).catch((err: BusinessError) => { 1170 console.error(`Failed to query the download MimeType. Code: ${err.code}, message: ${err.message}`) 1171 }); 1172 ``` 1173 1174 1175### getTaskMimeType<sup>9+</sup> 1176 1177getTaskMimeType(callback: AsyncCallback<string>): void; 1178 1179查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。 1180 1181**需要权限**：ohos.permission.INTERNET 1182 1183**系统能力**: SystemCapability.MiscServices.Download 1184 1185**参数：** 1186 1187 | 参数名 | 类型 | 必填 | 说明 | 1188 | -------- | -------- | -------- | -------- | 1189 | callback | AsyncCallback<string> | 是 | 查询下载任务的MimeType的回调函数。 | 1190 1191**示例：** 1192 1193 ```ts 1194 downloadTask.getTaskMimeType((err: BusinessError, data: string) => { 1195 if (err) { 1196 console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`); 1197 } else { 1198 console.info('Succeeded in querying the download mimeType'); 1199 } 1200 }); 1201 ``` 1202 1203 1204### suspend<sup>9+</sup> 1205 1206suspend(): Promise<boolean> 1207 1208暂停下载任务，异步方法，使用promise形式返回结果。 1209 1210**需要权限**：ohos.permission.INTERNET 1211 1212**系统能力**: SystemCapability.MiscServices.Download 1213 1214**返回值：** 1215 1216 | 类型 | 说明 | 1217 | -------- | -------- | 1218 | Promise<boolean> | 暂停下载任务是否成功。 | 1219 1220**示例：** 1221 1222 ```ts 1223 downloadTask.suspend().then((result: boolean) => { 1224 console.info('Succeeded in pausing the download task.'); 1225 }).catch((err: BusinessError) => { 1226 console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); 1227 }); 1228 ``` 1229 1230 1231### suspend<sup>9+</sup> 1232 1233suspend(callback: AsyncCallback<boolean>): void 1234 1235暂停下载任务，异步方法，使用callback形式返回结果。 1236 1237**需要权限**：ohos.permission.INTERNET 1238 1239**系统能力**: SystemCapability.MiscServices.Download 1240 1241**参数：** 1242 1243 | 参数名 | 类型 | 必填 | 说明 | 1244 | -------- | -------- | -------- | -------- | 1245 | callback | AsyncCallback<boolean> | 是 | 暂停下载任务的回调函数。 | 1246 1247**示例：** 1248 1249 ```ts 1250 downloadTask.suspend((err: BusinessError, result: boolean) => { 1251 if (err) { 1252 console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); 1253 return; 1254 } 1255 console.info('Succeeded in pausing the download task.'); 1256 }); 1257 ``` 1258 1259 1260### restore<sup>9+</sup> 1261 1262restore(): Promise<boolean> 1263 1264重新启动暂停的下载任务，异步方法，使用promise形式返回结果。 1265 1266**需要权限**：ohos.permission.INTERNET 1267 1268**系统能力**: SystemCapability.MiscServices.Download 1269 1270**返回值：** 1271 1272 | 类型 | 说明 | 1273 | -------- | -------- | 1274 | Promise<boolean> | 重新启动暂停的下载任务是否成功。 | 1275 1276**示例：** 1277 1278 ```ts 1279 downloadTask.restore().then((result: boolean) => { 1280 console.info('Succeeded in resuming the download task.') 1281 }).catch((err: BusinessError) => { 1282 console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); 1283 }); 1284 ``` 1285 1286 1287### restore<sup>9+</sup> 1288 1289restore(callback: AsyncCallback<boolean>): void 1290 1291重新启动暂停的下载任务，异步方法，使用callback形式返回结果。 1292 1293**需要权限**：ohos.permission.INTERNET 1294 1295**系统能力**: SystemCapability.MiscServices.Download 1296 1297**参数：** 1298 1299 | 参数名 | 类型 | 必填 | 说明 | 1300 | -------- | -------- | -------- | -------- | 1301 | callback | AsyncCallback<boolean> | 是 | 重新启动暂停的下载任务的回调函数。 | 1302 1303**示例：** 1304 1305 ```ts 1306 downloadTask.restore((err: BusinessError, result: boolean) => { 1307 if (err) { 1308 console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); 1309 return; 1310 } 1311 console.info('Succeeded in resuming the download task.'); 1312 }); 1313 ``` 1314 1315 1316### remove<sup>(deprecated)</sup> 1317 1318remove(): Promise<boolean> 1319 1320移除下载的任务，异步方法，使用promise形式返回结果。 1321 1322> **说明：** 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9-2)替代。 1323 1324**需要权限**：ohos.permission.INTERNET 1325 1326**系统能力**: SystemCapability.MiscServices.Download 1327 1328**返回值：** 1329 1330 | 类型 | 说明 | 1331 | -------- | -------- | 1332 | Promise<boolean> | 移除任务是否成功。 | 1333 1334**示例：** 1335 1336 ```js 1337 downloadTask.remove().then((result) => { 1338 console.info('Succeeded in removing the download task.'); 1339 }).catch ((err) => { 1340 console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); 1341 }); 1342 ``` 1343 1344 1345### remove<sup>(deprecated)</sup> 1346 1347remove(callback: AsyncCallback<boolean>): void 1348 1349移除下载的任务，异步方法，使用callback形式返回结果。 1350 1351> **说明：** 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9-3)替代。 1352 1353**需要权限**：ohos.permission.INTERNET 1354 1355**系统能力**: SystemCapability.MiscServices.Download 1356 1357**参数：** 1358 1359 | 参数名 | 类型 | 必填 | 说明 | 1360 | -------- | -------- | -------- | -------- | 1361 | callback | AsyncCallback<boolean> | 是 | 移除任务是否成功。 | 1362 1363**示例：** 1364 1365 ```js 1366 downloadTask.remove((err, result)=>{ 1367 if(err) { 1368 console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); 1369 return; 1370 } 1371 console.info('Succeeded in removing the download task.'); 1372 }); 1373 ``` 1374 1375 1376### query<sup>(deprecated)</sup> 1377 1378query(): Promise<DownloadInfo> 1379 1380查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。 1381 1382> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskInfo<sup>9+</sup>](#gettaskinfo9)替代。 1383 1384**需要权限**：ohos.permission.INTERNET 1385 1386**系统能力**: SystemCapability.MiscServices.Download 1387 1388**返回值：** 1389 1390 | 类型 | 说明 | 1391 | -------- | -------- | 1392 | Promise<[DownloadInfo](#downloadinfo7)> | 查询下载任务信息。 | 1393 1394**示例：** 1395 1396 ```js 1397 downloadTask.query().then((downloadInfo) => { 1398 console.info('Succeeded in querying the download task.') 1399 }) .catch((err) => { 1400 console.error(`Failed to query the download task. Code: ${err.code}, message: ${err.message}`) 1401 }); 1402 ``` 1403 1404 1405### query<sup>(deprecated)</sup> 1406 1407query(callback: AsyncCallback<DownloadInfo>): void 1408 1409查询下载的任务，异步方法，使用callback形式返回结果。 1410 1411> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskInfo<sup>9+</sup>](#gettaskinfo9-1)替代。 1412 1413**需要权限**：ohos.permission.INTERNET 1414 1415**系统能力**: SystemCapability.MiscServices.Download 1416 1417**参数：** 1418 1419 | 参数名 | 类型 | 必填 | 说明 | 1420 | -------- | -------- | -------- | -------- | 1421 | callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | 是 | 查询下载任务的回调函数。 | 1422 1423**示例：** 1424 1425 ```js 1426 downloadTask.query((err, downloadInfo)=>{ 1427 if(err) { 1428 console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`); 1429 } else { 1430 console.info('Succeeded in querying the download task.'); 1431 } 1432 }); 1433 ``` 1434 1435 1436### queryMimeType<sup>(deprecated)</sup> 1437 1438queryMimeType(): Promise<string> 1439 1440查询下载的任务的 MimeType，异步方法，使用promise形式返回结果。 1441 1442> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskMimeType<sup>9+</sup>](#gettaskmimetype9)替代。 1443 1444**需要权限**：ohos.permission.INTERNET 1445 1446**系统能力**: SystemCapability.MiscServices.Download 1447 1448**返回值：** 1449 1450 | 类型 | 说明 | 1451 | -------- | -------- | 1452 | Promise<string> | 查询下载任务的MimeType。 | 1453 1454**示例：** 1455 1456 ```js 1457 downloadTask.queryMimeType().then((data) => { 1458 console.info('Succeeded in querying the download MimeType.'); 1459 }).catch((err) => { 1460 console.error(`Failed to query the download MimeType. Code: ${err.code}, message: ${err.message}`) 1461 }); 1462 ``` 1463 1464 1465### queryMimeType<sup>(deprecated)</sup> 1466 1467queryMimeType(callback: AsyncCallback<string>): void; 1468 1469查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。 1470 1471> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskMimeType<sup>9+</sup>](#gettaskmimetype9-1)替代。 1472 1473**需要权限**：ohos.permission.INTERNET 1474 1475**系统能力**: SystemCapability.MiscServices.Download 1476 1477**参数：** 1478 1479 | 参数名 | 类型 | 必填 | 说明 | 1480 | -------- | -------- | -------- | -------- | 1481 | callback | AsyncCallback<string> | 是 | 查询下载任务的MimeType的回调函数。 | 1482 1483**示例：** 1484 1485 ```js 1486 downloadTask.queryMimeType((err, data)=>{ 1487 if(err) { 1488 console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`); 1489 } else { 1490 console.info('Succeeded in querying the download mimeType.'); 1491 } 1492 }); 1493 ``` 1494 1495 1496### pause<sup>(deprecated)</sup> 1497 1498pause(): Promise<void> 1499 1500暂停下载任务，异步方法，使用promise形式返回结果。 1501 1502> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[suspend<sup>9+</sup>](#suspend9)替代。 1503 1504**需要权限**：ohos.permission.INTERNET 1505 1506**系统能力**: SystemCapability.MiscServices.Download 1507 1508**返回值：** 1509 1510 | 类型 | 说明 | 1511 | -------- | -------- | 1512 | Promise<void> | 暂停下载任务是否成功。 | 1513 1514**示例：** 1515 1516 ```js 1517 downloadTask.pause().then((result) => { 1518 console.info('Succeeded in pausing the download task.'); 1519 }).catch((err) => { 1520 console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); 1521 }); 1522 ``` 1523 1524 1525### pause<sup>(deprecated)</sup> 1526 1527pause(callback: AsyncCallback<void>): void 1528 1529> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[suspend<sup>9+</sup>](#suspend9-1)替代。 1530 1531暂停下载任务，异步方法，使用callback形式返回结果。 1532 1533**需要权限**：ohos.permission.INTERNET 1534 1535**系统能力**: SystemCapability.MiscServices.Download 1536 1537**参数：** 1538 1539 | 参数名 | 类型 | 必填 | 说明 | 1540 | -------- | -------- | -------- | -------- | 1541 | callback | AsyncCallback<void> | 是 | 暂停下载任务的回调函数。 | 1542 1543**示例：** 1544 1545 ```js 1546 downloadTask.pause((err, result)=>{ 1547 if(err) { 1548 console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); 1549 return; 1550 } 1551 console.info('Succeeded in pausing the download task.'); 1552 }); 1553 ``` 1554 1555 1556### resume<sup>(deprecated)</sup> 1557 1558resume(): Promise<void> 1559 1560重新启动暂停的下载任务，异步方法，使用promise形式返回结果。 1561 1562> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[restore<sup>9+</sup>](#restore9)替代。 1563 1564**需要权限**：ohos.permission.INTERNET 1565 1566**系统能力**: SystemCapability.MiscServices.Download 1567 1568**返回值：** 1569 1570 | 类型 | 说明 | 1571 | -------- | -------- | 1572 | Promise<void> | 重新启动暂停的下载任务是否成功。 | 1573 1574**示例：** 1575 1576 ```js 1577 downloadTask.resume().then((result) => { 1578 console.info('Succeeded in resuming the download task.') 1579 }).catch((err) => { 1580 console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); 1581 }); 1582 ``` 1583 1584 1585### resume<sup>(deprecated)</sup> 1586 1587resume(callback: AsyncCallback<void>): void 1588 1589> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[restore<sup>9+</sup>](#restore9-1)替代。 1590 1591重新启动暂停的下载任务，异步方法，使用callback形式返回结果。 1592 1593**需要权限**：ohos.permission.INTERNET 1594 1595**系统能力**: SystemCapability.MiscServices.Download 1596 1597**参数：** 1598 1599 | 参数名 | 类型 | 必填 | 说明 | 1600 | -------- | -------- | -------- | -------- | 1601 | callback | AsyncCallback<void> | 是 | 重新启动暂停的下载任务的回调函数。 | 1602 1603**示例：** 1604 1605 ```js 1606 downloadTask.resume((err, result)=>{ 1607 if (err) { 1608 console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); 1609 return; 1610 } 1611 console.info('Succeeded in resuming the download task.'); 1612 }); 1613 ``` 1614 1615 1616## DownloadConfig 1617下载任务的配置信息。 1618 1619**需要权限**：ohos.permission.INTERNET 1620 1621**系统能力**: SystemCapability.MiscServices.Download 1622 1623| 名称 | 类型 | 必填 | 说明 | 1624| -------- | -------- | -------- | -------- | 1625| url | string | 是 | 资源地址。 | 1626| header | Object | 否 | 添加要包含在下载请求中的HTTPS标志头。<br/>开发者可以通过header的X-TLS-Version参数指定需要使用的TLS版本(如果不指定，则默认使用CURL_SSLVERSION_TLSv1_2版本，指定则使用指定版本。)<br/>CURL_SSLVERSION_TLSv1_0<br/>CURL_SSLVERSION_TLSv1_1<br/>CURL_SSLVERSION_TLSv1_2<br/>CURL_SSLVERSION_TLSv1_3<br/>通过header的X-Cipher-List参数指定需要使用的密码套件(如果不指定，则默认使用安全密码套件，指定则使用指定密码套件。)<br/>-1.2允许使用的密码套件白名单：<br/>TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,<br/>TLS_DHE_DSS_WITH_AES_128_GCM_SHA256,TLS_DSS_RSA_WITH_AES_256_GCM_SHA384,<br/>TLS_PSK_WITH_AES_256_GCM_SHA384,TLS_DHE_PSK_WITH_AES_128_GCM_SHA256,<br/>TLS_DHE_PSK_WITH_AES_256_GCM_SHA384,TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256,<br/>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,<br/>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,<br/>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256,<br/>TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256,TLS_ECDHE_PSK_WITH_AES_256_GCM_SHA384,<br/>TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_CCM,<br/>TLS_DHE_RSA_WITH_AES_256_CCM,TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256,<br/>TLS_PSK_WITH_AES_256_CCM,TLS_DHE_PSK_WITH_AES_128_CCM,<br/>TLS_DHE_PSK_WITH_AES_256_CCM,TLS_ECDHE_ECDSA_WITH_AES_128_CCM,<br/>TLS_ECDHE_ECDSA_WITH_AES_256_CCM,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256<br/>-1.3允许使用的密码套件白名单：<br/>TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_CCM_SHA256<br/>-1.3新增国密算法套：<br/>TLS_SM4_GCM_SM3,TLS_SM4_CCM_SM3 | 1627| enableMetered | boolean | 否 | 设置是否允许在按流量计费的连接下下载(默认使用false)。Wi-Fi为非计费网络，数据流量为计费网络。<br/>- true：是<br/>- false：否 | 1628| enableRoaming | boolean | 否 | 设置是否允许在漫游网络中下载(默认使用false)。 <br/>- true：是<br/>- false：否| 1629| description | string | 否 | 设置下载会话的描述。 | 1630| filePath<sup>7+</sup> | string | 否 | 设置下载路径。<br/>- FA模型下使用[context](js-apis-inner-app-context.md#contextgetcachedir) 获取应用存储路径，比如：\`${featureAbility.getContext().getFilesDir()}/test.txt\`，并将文件存储在此路径下。<br/>- Stage模型下使用[AbilityContext](js-apis-inner-application-context.md) 类获取文件路径，比如：\`${globalThis.abilityContext.tempDir}/test.txt\`，并将文件存储在此路径下。| 1631| networkType | number | 否 | 设置允许下载的网络类型(默认使用NETWORK_MOBILE&NETWORK_WIFI)。<br/>- NETWORK_MOBILE：0x00000001<br/>- NETWORK_WIFI：0x00010000| 1632| title | string | 否 | 设置下载任务名称。 | 1633| background<sup>9+</sup> | boolean | 否 | 后台任务通知开关，开启后可在通知中显示下载状态(默认使用false)。 | 1634 1635 1636## DownloadInfo<sup>7+</sup> 1637下载任务信息，[getTaskInfo<sup>9+</sup>](#gettaskinfo9)接口的回调参数。 1638 1639**需要权限**：ohos.permission.INTERNET 1640 1641**系统能力**: SystemCapability.MiscServices.Download 1642 1643| 名称 | 类型 |必填 | 说明 | 1644| -------- | -------- | -------- | -------- | 1645| downloadId | number |是 | 下载任务ID。 | 1646| failedReason | number|是 | 下载失败原因，可以是任何[下载任务的错误码](#下载任务的错误码)常量。 | 1647| fileName | string |是| 下载的文件名。 | 1648| filePath | string |是| 存储文件的URI。 | 1649| pausedReason | number |是| 会话暂停的原因，可以是任何[下载任务暂停原因](#下载任务暂停原因)常量。 | 1650| status | number |是| 下载状态码，可以是任何[下载任务状态码](#下载任务状态码)常量。 | 1651| targetURI | string |是| 下载文件的URI。 | 1652| downloadTitle | string |是| 下载任务名称。 | 1653| downloadTotalBytes | number |是| 下载的文件的总大小（int bytes）。 | 1654| description | string |是| 待下载任务的描述信息。 | 1655| downloadedBytes | number |是| 实时下载大小（int bytes）。 | 1656 1657## Action<sup>10+</sup> 1658 1659定义操作选项。 1660 1661**系统能力**: SystemCapability.Request.FileTransferAgent 1662 1663| 名称 | 值 |说明 | 1664| -------- | -------- |-------- | 1665| DOWNLOAD | 0 |表示下载任务。 | 1666| UPLOAD | 1 |表示上传任务。 | 1667 1668 1669## Mode<sup>10+</sup> 1670定义模式选项。 1671 1672**系统能力**: SystemCapability.Request.FileTransferAgent 1673 1674| 名称 | 值 |说明 | 1675| -------- | -------- |-------- | 1676| BACKGROUND | 0 |表示后台任务。 | 1677| FOREGROUND | 1 |表示前端任务。 | 1678 1679## Network<sup>10+</sup> 1680 1681定义网络选项。 1682 1683**系统能力**: SystemCapability.Request.FileTransferAgent 1684 1685| 名称 | 值 |说明 | 1686| -------- | -------- |-------- | 1687| ANY | 0 |表示不限网络类型。 | 1688| WIFI | 1 |表示无线网络。 | 1689| CELLULAR | 2 |表示蜂窝数据网络。 | 1690 1691## FileSpec<sup>10+</sup> 1692表单项的文件信息。 1693 1694**系统能力**: SystemCapability.Request.FileTransferAgent 1695 1696| 名称 | 类型 | 必填 | 说明 | 1697| -------- | -------- | -------- | -------- | 1698| path | string | 是 | 文件路径位于调用方的缓存文件夹下的相对路径。 | 1699| mimeType | string | 否 | 文件的mimetype通过文件名获取。 | 1700| filename | string | 否 | 文件名，默认值通过路径获取。 | 1701| extras | Object | 否 | 文件信息的附加内容。 | 1702 1703 1704## FormItem<sup>10+</sup> 1705任务的表单项信息。 1706 1707**系统能力**: SystemCapability.Request.FileTransferAgent 1708 1709| 名称 | 类型 | 必填 | 说明 | 1710| -------- | -------- | -------- | -------- | 1711| name | string | 是 | 表单参数名。 | 1712| value | string \| [FileSpec](#filespec10) \| Array<[FileSpec](#filespec10)> | 是 | 表单参数值。 | 1713 1714 1715## Config<sup>10+</sup> 1716上传/下载任务的配置信息。 1717 1718**系统能力**: SystemCapability.Request.FileTransferAgent 1719 1720| 名称 | 类型 | 必填 | 说明 | 1721| -------- | -------- | -------- | -------- | 1722| action | [Action](#action10) | 是 | 任务操作选项。<br/>-UPLOAD表示上传任务。<br/>-DOWNLOAD表示下载任务。 | 1723| url | string | 是 | 资源地址，其最大长度为2048个字符。 | 1724| title | string | 否 | 任务标题，其最大长度为256个字符，默认值为空。 | 1725| description | string | 否 | 任务的详细信息，其最大长度为1024个字符，默认值为空字符串。 | 1726| mode | [Mode](#mode10) | 否 | 任务模式,默认为后台任务。<br/>-对于前端任务，有回调通知。<br/>-对于后台任务，有系统通知、检测网络连接、恢复、自动重试功能。 | 1727| overwrite | boolean | 否 | 下载过程中路径已存在时的解决方案选择，默认为false。<br/>- true，覆盖已存在的文件。<br/>- false，下载失败。 | 1728| method | string | 否 | 上传或下载的HTTP标准方法，包括GET、POST和PUT，不区分大小写。<br/>-上传时，使用PUT或POST，默认值为PUT。<br/>-下载时，使用GET或POST，默认值为GET。 | 1729| headers | object | 否 | 添加要包含在任务中的HTTP协议标志头。<br/>-对于上传请求，默认的Content-Type为"multipart/form-data"。<br/>-对于下载请求，默认的Content-Type为"application/json"。 | 1730| data | string \| Array<[FormItem](#formitem10)> | 否 | -下载时，data为字符串类型，通常使用json(object将被转换为json文本)，默认为空。<br/>-上传时，data是表单项数组Array<[FormItem](#formitem10)>，默认为空。 | 1731| saveas | string | 否 | 保存下载文件的路径，包括如下两种：<br/>-相对路径，如"./xxx/yyy/zzz.html"、"xxx/yyy/zzz.html"，位于调用方的缓存路径下。<br/>-uri路径，如"datashare://bundle/xxx/yyy/zzz.html"，仅对具有访问url路径权限的应用开放。该功能暂不支持。<br/>默认为相对路径，即下载至应用当前缓存路径下。 | 1732| network | [Network](#network10) | 否 | 网络选项，当前支持无线网络WIFI和蜂窝数据网络CELLULAR，默认为ANY（WIFI或CELLULAR）。 | 1733| metered | boolean | 否 | 是否允许在按流量计费的网络中工作，默认为false。<br/>-true：是 <br/>-false：否| 1734| roaming | boolean | 否 | 是否允许在漫游网络中工作，默认为true。<br/>-true：是 <br/>-false：否 | 1735| retry | boolean | 否 | 是否为后台任务启用自动重试，仅应用于后台任务，默认为true。<br/>-true：是 <br/>-false：否 | 1736| redirect | boolean | 否 | 是否允许重定向，默认为true。<br/>-true：是 <br/>-false：否 | 1737| index | number | 否 | 任务的路径索引，通常用于任务断点续传，默认为0。 | 1738| begins | number | 否 | 文件起点，通常用于断点续传。默认值为0，取值为闭区间。<br/>-下载时，请求读取服务器开始下载文件时的起点位置（http协议中设置"Range"选项）。<br/>-上传时，在上传开始时读取。 | 1739| ends | number | 否 | 文件终点，通常用于断点续传。默认值为-1，取值为闭区间。<br/>-下载时，请求读取服务器开始下载文件时的结束位置（http协议中设置"Range"选项）。<br/>-上传时，在上传时结束读取。 | 1740| gauge | boolean | 否 | 后台任务的过程进度通知策略，仅应用于后台任务，默认值为false。<br/>-false：代表仅完成或失败的通知。<br/>-true，发出每个进度已完成或失败的通知。 | 1741| precise | boolean | 否 | -如果设置为true，在上传/下载无法获取文件大小时任务失败。<br/>-如果设置为false，将文件大小设置为-1时任务继续。<br/>默认值为false。 | 1742| token | string | 否 | 当创建了一个带有token的任务后，token则为正常查询期间必须提供的，否则将无法通过查询进行检索。其最小为8个字节，最大为2048个字节。默认为空。 | 1743| extras | object | 否 | 配置的附加功能，默认为空。 | 1744 1745## State<sup>10+</sup> 1746 1747定义任务当前的状态。 1748 1749**系统能力**: SystemCapability.Request.FileTransferAgent 1750 1751| 名称 | 值 |说明 | 1752| -------- | -------- |-------- | 1753| INITIALIZED | 0x00 |通过配置信息（[Config](#config10)）创建初始化任务。 | 1754| WAITING | 0x10 |表示任务缺少运行或重试的资源与网络状态不匹配。 | 1755| RUNNING | 0x20 |表示正在处理的任务。 | 1756| RETRYING | 0x21 |表示任务至少失败一次，现在正在再次处理中。 | 1757| PAUSED | 0x30 |表示任务暂停，通常后续会恢复任务。 | 1758| STOPPED | 0x31 |表示任务停止。 | 1759| COMPLETED | 0x40 |表示任务完成。 | 1760| FAILED | 0x41 |表示任务失败。 | 1761| REMOVED | 0x50 |表示任务移除。 | 1762 1763 1764## Progress<sup>10+</sup> 1765任务进度的数据结构。 1766 1767**系统能力**: SystemCapability.Request.FileTransferAgent 1768 1769| 名称 | 类型 | 必填 | 说明 | 1770| -------- | -------- | -------- | -------- | 1771| state | [State](#state10) | 是 | 任务当前的状态。 | 1772| index | number | 是 | 任务中当前正在处理的文件索引。 | 1773| processed | number | 是 | 任务中当前文件的已处理数据大小，单位为B。| 1774| sizes | Array<number> | 是 | 任务中文件的大小，单位为B。 | 1775| extras | object | 否 | 交互的额外内容，例如来自服务器的响应的header和body。 | 1776 1777 1778## Faults<sup>10+</sup> 1779 1780定义任务失败的原因。 1781 1782**系统能力**: SystemCapability.Request.FileTransferAgent 1783 1784| 名称 | 值 |说明 | 1785| -------- | -------- |-------- | 1786| OTHERS | 0xFF |表示其他故障。 | 1787| DISCONNECTED | 0x00 |表示网络断开连接。 | 1788| TIMEOUT | 0x10 |表示任务超时。 | 1789| PROTOCOL | 0x20 |表示协议错误，例如:服务器内部错误（500）、无法处理的数据区间（416）等。 | 1790| FSIO | 0x40 |表示文件系统io错误，例如打开/查找/读取/写入/关闭。 | 1791 1792 1793## Filter<sup>10+</sup> 1794过滤条件。 1795 1796**系统能力**: SystemCapability.Request.FileTransferAgent 1797 1798| 名称 | 类型 | 必填 | 说明 | 1799| -------- | -------- | -------- | -------- | 1800| bundle | string | 否 | 指定应用程序的包名，仅对系统应用开放。<br/>**系统接口**：此接口为系统接口。 | 1801| before | number | 否 | 结束的Unix时间戳（毫秒），默认为调用时刻。 | 1802| after | number | 否 | 开始的Unix时间戳（毫秒），默认值为调用时刻减24小时。 | 1803| state | [State](#state10) | 否 | 指定任务的状态。 | 1804| action | [Action](#action10) | 否 | 任务操作选项。<br/>-UPLOAD表示上传任务。<br/>-DOWNLOAD表示下载任务。 | 1805| mode | [Mode](#mode10) | 否 | 任务模式。<br/>-FOREGROUND表示前端任务。<br/>-BACKGROUND表示后台任务。 | 1806 1807## TaskInfo<sup>10+</sup> 1808查询结果的任务信息数据结构，提供普通查询和系统查询，两种字段的可见范围不同。 1809 1810**系统能力**: SystemCapability.Request.FileTransferAgent 1811 1812| 名称 | 类型 | 必填 | 说明 | 1813| -------- | -------- | -------- | -------- | 1814| uid | string | 否 | 应用程序的UID，仅用于系统查询。<br/>**系统接口**：此接口为系统接口。| 1815| bundle | string | 否 | 应用程序的包名，仅用于系统查询。<br/>**系统接口**：此接口为系统接口。| 1816| saveas | string | 否 | 保存下载文件的路径，包括如下两种：<br/>-相对路径，如"./xxx/yyy/zzz.html"、"xxx/yyy/zzz.html"，位于调用方的缓存路径下。<br/>-uri路径，如"datashare://bundle/xxx/yyy/zzz.html"，仅对具有访问url路径权限的应用开放。该功能暂不支持。<br/>默认为相对路径，即下载至应用当前缓存路径下。| 1817| url | string | 否 | 任务的url。<br/>- 通过[request.agent.show<sup>10+</sup>](#requestagentshow10-1)、[request.agent.touch<sup>10+</sup>](#requestagenttouch10-1)、[request.agent.query<sup>10+</sup>](#requestagentquery10-1)进行查询。其中，使用[request.agent.query<sup>10+</sup>](#requestagentquery10-1)进行查询时会返回空字符串。 | 1818| data | string \| Array<[FormItem](#formitem10)> | 否 | 任务值。<br/>- 通过[request.agent.show<sup>10+</sup>](#requestagentshow10-1)、[request.agent.touch<sup>10+</sup>](#requestagenttouch10-1)、[request.agent.query<sup>10+</sup>](#requestagentquery10-1)进行查询。其中，使用[request.agent.query<sup>10+</sup>](#requestagentquery10-1)进行查询时会返回空字符串。 | 1819| tid | string | 是 | 任务id。 | 1820| title | string | 是 | 任务标题。 | 1821| description | string | 是 | 任务描述。 | 1822| action | [Action](#action10) | 是 | 任务操作选项。<br/>-UPLOAD表示上传任务。<br/>-DOWNLOAD表示下载任务。 | 1823| mode | [Mode](#mode10) | 是 | 指定任务模式。<br/>-FOREGROUND表示前端任务。<br/>-BACKGROUND表示后台任务。 | 1824| mimeType | string | 是 | 任务配置中的mimetype。 | 1825| progress | [Progress](#progress10) | 是 | 任务的过程进度。 | 1826| gauge | boolean | 是 | 后台任务的进度通知策略。 | 1827| ctime | number | 是 | 创建任务的Unix时间戳（毫秒），由当前设备的系统生成。<br/>说明：使用[request.agent.search<sup>10+</sup>](#requestagentsearch10-1)进行查询时，该值需处于[after,before]区间内才可正常查询到任务id，before和after信息详见[Filter](#filter10)。 1828| mtime | number | 是 | 任务状态改变时的Unix时间戳（毫秒），由当前设备的系统生成。| 1829| retry | boolean | 是 | 任务的重试开关，仅应用于后台任务。 | 1830| tries | number | 是 | 任务的尝试次数。 | 1831| faults | [Faults](#faults10) | 是 | 任务的失败原因。<br/>-OTHERS表示其他故障。<br/>-DISCONNECT表示网络断开连接。<br/>-TIMEOUT表示任务超时。<br/>-PROTOCOL表示协议错误。<br/>-FSIO表示文件系统io错误。| 1832| reason | string | 是 | 等待/失败/停止/暂停任务的原因。| 1833| extras | string | 否 | 任务的额外部分。| 1834 1835 1836## Task<sup>10+</sup> 1837上传或下载任务。使用该方法前需要先获取Task对象，promise形式通过[request.agent.create<sup>10+</sup>](#requestagentcreate10-1)获取，callback形式通过[request.agent.create<sup>10+</sup>](#requestagentcreate10)获取。 1838 1839### 属性 1840包括任务id和任务的配置信息。 1841 1842**系统能力**: SystemCapability.Request.FileTransferAgent 1843 1844| 名称 | 类型 | 必填 | 说明 | 1845| -------- | -------- | -------- | -------- | 1846| tid | string | 是 | 任务id，在系统上是唯一的，由系统自动生成。 | 1847| config | [Config](#config10) | 是 | 任务的配置信息。 | 1848 1849 1850### on('progress')<sup>10+</sup> 1851 1852on(event: 'progress', callback: (progress: Progress) => void): void 1853 1854订阅任务进度的监听。 1855 1856**系统能力**: SystemCapability.Request.FileTransferAgent 1857 1858**参数：** 1859 1860 | 参数名 | 类型 | 必填 | 说明 | 1861 | -------- | -------- | -------- | -------- | 1862 | event | string | 是 | 订阅的事件类型。<br>- 取值为'progress'，表示任务进度。 | 1863 | callback | function | 是 | 发生相关的事件时触发该回调方法，返回任务进度的数据结构。| 1864 1865**错误码：** 1866 1867以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 1868 1869 | 错误码ID | 错误信息 | 1870 | -------- | -------- | 1871 | 21900005 | task mode error. | 1872 1873**示例：** 1874 1875 ```ts 1876 let attachments: Array<request.agent.FormItem> = [{ 1877 name: "taskOnTest", 1878 value: { 1879 filename: "taskOnTest.avi", 1880 mimeType: "application/octet-stream", 1881 path: "./taskOnTest.avi", 1882 } 1883 }]; 1884 let config: request.agent.Config = { 1885 action: request.agent.Action.UPLOAD, 1886 url: 'http://127.0.0.1', 1887 title: 'taskOnTest', 1888 description: 'Sample code for event listening', 1889 mode: request.agent.Mode.FOREGROUND, 1890 overwrite: false, 1891 method: "PUT", 1892 data: attachments, 1893 saveas: "./", 1894 network: request.agent.Network.CELLULAR, 1895 metered: false, 1896 roaming: true, 1897 retry: true, 1898 redirect: true, 1899 index: 0, 1900 begins: 0, 1901 ends: -1, 1902 gauge: false, 1903 precise: false, 1904 token: "it is a secret" 1905 }; 1906 let createOnCallback = (progress: request.agent.Progress) => { 1907 console.info('upload task progress.'); 1908 }; 1909 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 1910 task.on('progress', createOnCallback); 1911 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 1912 }).catch((err: BusinessError) => { 1913 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 1914 }); 1915 ``` 1916 1917> **说明：** 1918> 1919> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 1920 1921### on('completed')<sup>10+</sup> 1922 1923on(event: 'completed', callback: (progress: Progress) => void): void 1924 1925订阅任务完成的监听。 1926 1927**系统能力**: SystemCapability.Request.FileTransferAgent 1928 1929**参数：** 1930 1931 | 参数名 | 类型 | 必填 | 说明 | 1932 | -------- | -------- | -------- | -------- | 1933 | event | string | 是 | 订阅的事件类型。<br>- 取值为'completed'，表示任务完成。 | 1934 | callback | function | 是 | 发生相关的事件时触发该回调方法，返回任务进度的数据结构。 | 1935 1936**错误码：** 1937 1938以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 1939 1940 | 错误码ID | 错误信息 | 1941 | -------- | -------- | 1942 | 21900005 | task mode error. | 1943 1944**示例：** 1945 1946 ```ts 1947 let attachments: Array<request.agent.FormItem> = [{ 1948 name: "taskOnTest", 1949 value: { 1950 filename: "taskOnTest.avi", 1951 mimeType: "application/octet-stream", 1952 path: "./taskOnTest.avi", 1953 } 1954 }]; 1955 let config: request.agent.Config = { 1956 action: request.agent.Action.UPLOAD, 1957 url: 'http://127.0.0.1', 1958 title: 'taskOnTest', 1959 description: 'Sample code for event listening', 1960 mode: request.agent.Mode.FOREGROUND, 1961 overwrite: false, 1962 method: "PUT", 1963 data: attachments, 1964 saveas: "./", 1965 network: request.agent.Network.CELLULAR, 1966 metered: false, 1967 roaming: true, 1968 retry: true, 1969 redirect: true, 1970 index: 0, 1971 begins: 0, 1972 ends: -1, 1973 gauge: false, 1974 precise: false, 1975 token: "it is a secret" 1976 }; 1977 let createOnCallback = (progress: request.agent.Progress) => { 1978 console.info('upload task completed.'); 1979 }; 1980 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 1981 task.on('completed', createOnCallback); 1982 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 1983 }).catch((err: BusinessError) => { 1984 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 1985 }); 1986 ``` 1987 1988> **说明：** 1989> 1990> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 1991 1992### on('failed')<sup>10+</sup> 1993 1994on(event: 'failed', callback: (progress: Progress) => void): void 1995 1996订阅任务失败的监听。 1997 1998**系统能力**: SystemCapability.Request.FileTransferAgent 1999 2000**参数：** 2001 2002 | 参数名 | 类型 | 必填 | 说明 | 2003 | -------- | -------- | -------- | -------- | 2004 | event | string | 是 | 订阅的事件类型。<br>- 取值为'failed'，表示任务失败。 | 2005 | callback | function | 是 | 发生相关的事件时触发该回调方法，返回任务进度的数据结构。 | 2006 2007**错误码：** 2008 2009以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2010 2011 | 错误码ID | 错误信息 | 2012 | -------- | -------- | 2013 | 21900005 | task mode error. | 2014 2015**示例：** 2016 2017 ```ts 2018 let attachments: Array<request.agent.FormItem> = [{ 2019 name: "taskOnTest", 2020 value: { 2021 filename: "taskOnTest.avi", 2022 mimeType: "application/octet-stream", 2023 path: "./taskOnTest.avi", 2024 } 2025 }]; 2026 let config: request.agent.Config = { 2027 action: request.agent.Action.UPLOAD, 2028 url: 'http://127.0.0.1', 2029 title: 'taskOnTest', 2030 description: 'Sample code for event listening', 2031 mode: request.agent.Mode.FOREGROUND, 2032 overwrite: false, 2033 method: "PUT", 2034 data: attachments, 2035 saveas: "./", 2036 network: request.agent.Network.CELLULAR, 2037 metered: false, 2038 roaming: true, 2039 retry: true, 2040 redirect: true, 2041 index: 0, 2042 begins: 0, 2043 ends: -1, 2044 gauge: false, 2045 precise: false, 2046 token: "it is a secret" 2047 }; 2048 let createOnCallback = (progress: request.agent.Progress) => { 2049 console.info('upload task failed.'); 2050 }; 2051 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2052 task.on('failed', createOnCallback); 2053 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2054 }).catch((err: BusinessError) => { 2055 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2056 }); 2057 ``` 2058 2059> **说明：** 2060> 2061> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2062 2063 2064### off('progress')<sup>10+</sup> 2065 2066off(event: 'progress', callback?: (progress: Progress) => void): void 2067 2068取消订阅任务进度的监听。 2069 2070**系统能力**: SystemCapability.Request.FileTransferAgent 2071 2072**参数：** 2073 2074 | 参数名 | 类型 | 必填 | 说明 | 2075 | -------- | -------- | -------- | -------- | 2076 | event | string | 是 | 订阅的事件类型。<br>- 取值为'progress'，表示任务进度。 | 2077 | callback | function | 否 | 发生相关的事件时触发该回调方法，返回任务进度的数据结构。 | 2078 2079**错误码：** 2080 2081以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2082 2083 | 错误码ID | 错误信息 | 2084 | -------- | -------- | 2085 | 21900005 | task mode error. | 2086 2087**示例：** 2088 2089 ```ts 2090 let attachments: Array<request.agent.FormItem> = [{ 2091 name: "taskOffTest", 2092 value: { 2093 filename: "taskOffTest.avi", 2094 mimeType: "application/octet-stream", 2095 path: "./taskOffTest.avi", 2096 } 2097 }]; 2098 let config: request.agent.Config = { 2099 action: request.agent.Action.UPLOAD, 2100 url: 'http://127.0.0.1', 2101 title: 'taskOffTest', 2102 description: 'Sample code for event listening', 2103 mode: request.agent.Mode.FOREGROUND, 2104 overwrite: false, 2105 method: "PUT", 2106 data: attachments, 2107 saveas: "./", 2108 network: request.agent.Network.CELLULAR, 2109 metered: false, 2110 roaming: true, 2111 retry: true, 2112 redirect: true, 2113 index: 0, 2114 begins: 0, 2115 ends: -1, 2116 gauge: false, 2117 precise: false, 2118 token: "it is a secret" 2119 }; 2120 let createOffCallback = (progress: request.agent.Progress) => { 2121 console.info('upload task progress.'); 2122 }; 2123 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2124 task.on('progress', createOffCallback); 2125 task.off('progress', createOffCallback); 2126 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2127 }).catch((err: BusinessError) => { 2128 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2129 }); 2130 ``` 2131 2132> **说明：** 2133> 2134> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2135 2136### off('completed')<sup>10+</sup> 2137 2138off(event: 'completed', callback?: (progress: Progress) => void): void 2139 2140取消订阅任务完成的监听。 2141 2142**系统能力**: SystemCapability.Request.FileTransferAgent 2143 2144**参数：** 2145 2146 | 参数名 | 类型 | 必填 | 说明 | 2147 | -------- | -------- | -------- | -------- | 2148 | event | string | 是 | 订阅的事件类型。<br>- 取值为'completed'，表示任务完成。 | 2149 | callback | function | 否 | 发生相关的事件时触发该回调方法，返回任务进度的数据结构。 | 2150 2151**错误码：** 2152 2153以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2154 2155 | 错误码ID | 错误信息 | 2156 | -------- | -------- | 2157 | 21900005 | task mode error. | 2158 2159**示例：** 2160 2161 ```ts 2162 let attachments: Array<request.agent.FormItem> = [{ 2163 name: "taskOffTest", 2164 value: { 2165 filename: "taskOffTest.avi", 2166 mimeType: "application/octet-stream", 2167 path: "./taskOffTest.avi", 2168 } 2169 }]; 2170 let config: request.agent.Config = { 2171 action: request.agent.Action.UPLOAD, 2172 url: 'http://127.0.0.1', 2173 title: 'taskOffTest', 2174 description: 'Sample code for event listening', 2175 mode: request.agent.Mode.FOREGROUND, 2176 overwrite: false, 2177 method: "PUT", 2178 data: attachments, 2179 saveas: "./", 2180 network: request.agent.Network.CELLULAR, 2181 metered: false, 2182 roaming: true, 2183 retry: true, 2184 redirect: true, 2185 index: 0, 2186 begins: 0, 2187 ends: -1, 2188 gauge: false, 2189 precise: false, 2190 token: "it is a secret" 2191 }; 2192 let createOffCallback = (progress: request.agent.Progress) => { 2193 console.info('upload task completed.'); 2194 }; 2195 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2196 task.on('completed', createOffCallback); 2197 task.off('completed', createOffCallback); 2198 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2199 }).catch((err: BusinessError) => { 2200 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2201 }); 2202 ``` 2203 2204> **说明：** 2205> 2206> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2207 2208### off('failed')<sup>10+</sup> 2209 2210off(event: 'failed', callback?: (progress: Progress) => void): void 2211 2212取消订阅任务失败的监听。 2213 2214**系统能力**: SystemCapability.Request.FileTransferAgent 2215 2216**参数：** 2217 2218 | 参数名 | 类型 | 必填 | 说明 | 2219 | -------- | -------- | -------- | -------- | 2220 | event | string | 是 | 订阅的事件类型。<br>- 取值为'failed'，表示任务失败。 | 2221 | callback | function | 否 | 发生相关的事件时触发该回调方法，返回任务进度的数据结构。 | 2222 2223**错误码：** 2224 2225以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2226 2227 | 错误码ID | 错误信息 | 2228 | -------- | -------- | 2229 | 21900005 | task mode error. | 2230 2231**示例：** 2232 2233 ```ts 2234 let attachments: Array<request.agent.FormItem> = [{ 2235 name: "taskOffTest", 2236 value: { 2237 filename: "taskOffTest.avi", 2238 mimeType: "application/octet-stream", 2239 path: "./taskOffTest.avi", 2240 } 2241 }]; 2242 let config: request.agent.Config = { 2243 action: request.agent.Action.UPLOAD, 2244 url: 'http://127.0.0.1', 2245 title: 'taskOffTest', 2246 description: 'Sample code for event listening', 2247 mode: request.agent.Mode.FOREGROUND, 2248 overwrite: false, 2249 method: "PUT", 2250 data: attachments, 2251 saveas: "./", 2252 network: request.agent.Network.CELLULAR, 2253 metered: false, 2254 roaming: true, 2255 retry: true, 2256 redirect: true, 2257 index: 0, 2258 begins: 0, 2259 ends: -1, 2260 gauge: false, 2261 precise: false, 2262 token: "it is a secret" 2263 }; 2264 let createOffCallback = (progress: request.agent.Progress) => { 2265 console.info('upload task failed.'); 2266 }; 2267 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2268 task.on('failed', createOffCallback); 2269 task.off('failed', createOffCallback); 2270 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2271 }).catch((err: BusinessError) => { 2272 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2273 }); 2274 ``` 2275 2276> **说明：** 2277> 2278> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2279 2280### start<sup>10+</sup> 2281 2282start(callback: AsyncCallback<void>): void 2283 2284启动任务，无法启动已初始化的任务。使用callback异步回调。 2285 2286**需要权限**：ohos.permission.INTERNET 2287 2288**系统能力**: SystemCapability.Request.FileTransferAgent 2289 2290**参数：** 2291 2292 | 参数名 | 类型 | 必填 | 说明 | 2293 | -------- | -------- | -------- | -------- | 2294 | callback | function | 是 | 回调函数，开启任务成功，err为undefined，否则为错误对象。 | 2295 2296**错误码：** 2297 2298以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2299 2300 | 错误码ID | 错误信息 | 2301 | -------- | -------- | 2302 | 13400003 | task service ability error. | 2303 | 21900007 | task state error. | 2304 2305**示例：** 2306 2307 ```ts 2308 let config: request.agent.Config = { 2309 action: request.agent.Action.DOWNLOAD, 2310 url: 'http://127.0.0.1', 2311 title: 'taskStartTest', 2312 description: 'Sample code for start the download task', 2313 mode: request.agent.Mode.BACKGROUND, 2314 overwrite: false, 2315 method: "GET", 2316 data: "", 2317 saveas: "./", 2318 network: request.agent.Network.CELLULAR, 2319 metered: false, 2320 roaming: true, 2321 retry: true, 2322 redirect: true, 2323 index: 0, 2324 begins: 0, 2325 ends: -1, 2326 gauge: false, 2327 precise: false, 2328 token: "it is a secret" 2329 }; 2330 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2331 task.start((err: BusinessError) => { 2332 if (err) { 2333 console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`); 2334 return; 2335 } 2336 console.info(`Succeeded in starting a download task.`); 2337 }); 2338 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2339 }).catch((err: BusinessError) => { 2340 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2341 }); 2342 ``` 2343 2344> **说明：** 2345> 2346> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2347 2348### start<sup>10+</sup> 2349 2350start(): Promise<void> 2351 2352启动任务，无法启动已初始化的任务。使用Promise异步回调。 2353 2354**需要权限**：ohos.permission.INTERNET 2355 2356**系统能力**: SystemCapability.Request.FileTransferAgent 2357 2358**返回值：** 2359 2360| 类型 | 说明 | 2361| ------------------- | ------------------------- | 2362| Promise<void> | Promise对象。无返回结果的Promise对象。 | 2363 2364**错误码：** 2365 2366以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2367 2368 | 错误码ID | 错误信息 | 2369 | -------- | -------- | 2370 | 13400003 | task service ability error. | 2371 | 21900007 | task state error. | 2372 2373**示例：** 2374 2375 ```ts 2376 let config: request.agent.Config = { 2377 action: request.agent.Action.DOWNLOAD, 2378 url: 'http://127.0.0.1', 2379 title: 'taskStartTest', 2380 description: 'Sample code for start the download task', 2381 mode: request.agent.Mode.BACKGROUND, 2382 overwrite: false, 2383 method: "GET", 2384 data: "", 2385 saveas: "./", 2386 network: request.agent.Network.CELLULAR, 2387 metered: false, 2388 roaming: true, 2389 retry: true, 2390 redirect: true, 2391 index: 0, 2392 begins: 0, 2393 ends: -1, 2394 gauge: false, 2395 precise: false, 2396 token: "it is a secret" 2397 }; 2398 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2399 task.start().then(() => { 2400 console.info(`Succeeded in starting a download task.`); 2401 }).catch((err: BusinessError) => { 2402 console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`); 2403 }); 2404 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2405 }).catch((err: BusinessError) => { 2406 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2407 }); 2408 ``` 2409 2410> **说明：** 2411> 2412> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2413 2414### pause<sup>10+</sup> 2415 2416pause(callback: AsyncCallback<void>): void 2417 2418暂停任务，可以暂停正在等待/正在运行/正在重试的后台任务。使用callback异步回调。 2419 2420**系统能力**: SystemCapability.Request.FileTransferAgent 2421 2422**参数：** 2423 2424 | 参数名 | 类型 | 必填 | 说明 | 2425 | -------- | -------- | -------- | -------- | 2426 | callback | function | 是 | 回调函数，暂停任务成功，err为undefined，否则为错误对象。 | 2427 2428**错误码：** 2429 2430以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2431 2432 | 错误码ID | 错误信息 | 2433 | -------- | -------- | 2434 | 13400003 | task service ability error. | 2435 | 21900005 | task mode error. | 2436 | 21900007 | task state error. | 2437 2438**示例：** 2439 2440 ```ts 2441 let config: request.agent.Config = { 2442 action: request.agent.Action.DOWNLOAD, 2443 url: 'http://127.0.0.1', 2444 title: 'taskPauseTest', 2445 description: 'Sample code for pause the download task', 2446 mode: request.agent.Mode.BACKGROUND, 2447 overwrite: false, 2448 method: "GET", 2449 data: "", 2450 saveas: "./", 2451 network: request.agent.Network.CELLULAR, 2452 metered: false, 2453 roaming: true, 2454 retry: true, 2455 redirect: true, 2456 index: 0, 2457 begins: 0, 2458 ends: -1, 2459 gauge: false, 2460 precise: false, 2461 token: "it is a secret" 2462 }; 2463 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2464 task.pause((err: BusinessError) => { 2465 if (err) { 2466 console.error(`Failed to pause the download task, Code: ${err.code}, message: ${err.message}`); 2467 return; 2468 } 2469 console.info(`Succeeded in pausing a download task. `); 2470 }); 2471 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2472 }).catch((err: BusinessError) => { 2473 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2474 }); 2475 ``` 2476 2477 2478### pause<sup>10+</sup> 2479 2480pause(): Promise<void> 2481 2482暂停任务，可以暂停正在等待/正在运行/正在重试的后台任务。使用Promise异步回调。 2483 2484**系统能力**: SystemCapability.Request.FileTransferAgent 2485 2486**返回值：** 2487 2488| 类型 | 说明 | 2489| ------------------- | ------------------------- | 2490| Promise<void> | Promise对象。无返回结果的Promise对象。 | 2491 2492**错误码：** 2493 2494以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2495 2496 | 错误码ID | 错误信息 | 2497 | -------- | -------- | 2498 | 13400003 | task service ability error. | 2499 | 21900005 | task mode error. | 2500 | 21900007 | task state error. | 2501 2502**示例：** 2503 2504 ```ts 2505 let config: request.agent.Config = { 2506 action: request.agent.Action.DOWNLOAD, 2507 url: 'http://127.0.0.1', 2508 title: 'taskPauseTest', 2509 description: 'Sample code for pause the download task', 2510 mode: request.agent.Mode.BACKGROUND, 2511 overwrite: false, 2512 method: "GET", 2513 data: "", 2514 saveas: "./", 2515 network: request.agent.Network.CELLULAR, 2516 metered: false, 2517 roaming: true, 2518 retry: true, 2519 redirect: true, 2520 index: 0, 2521 begins: 0, 2522 ends: -1, 2523 gauge: false, 2524 precise: false, 2525 token: "it is a secret" 2526 }; 2527 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2528 task.pause().then(() => { 2529 console.info(`Succeeded in pausing a download task. `); 2530 }).catch((err: BusinessError) => { 2531 console.error(`Failed to pause the upload task, Code: ${err.code}, message: ${err.message}`); 2532 }); 2533 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2534 }).catch((err: BusinessError) => { 2535 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2536 }); 2537 ``` 2538 2539 2540### resume<sup>10+</sup> 2541 2542resume(callback: AsyncCallback<void>): void 2543 2544重新启动任务，可以恢复暂停的后台任务。使用callback异步回调。 2545 2546**需要权限**：ohos.permission.INTERNET 2547 2548**系统能力**: SystemCapability.Request.FileTransferAgent 2549 2550**参数：** 2551 2552 | 参数名 | 类型 | 必填 | 说明 | 2553 | -------- | -------- | -------- | -------- | 2554 | callback | function | 是 | 回调函数，重新启动任务成功，err为undefined，否则为错误对象 | 2555 2556**错误码：** 2557 2558以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2559 2560 | 错误码ID | 错误信息 | 2561 | -------- | -------- | 2562 | 13400003 | task service ability error. | 2563 | 21900005 | task mode error. | 2564 | 21900007 | task state error. | 2565 2566**示例：** 2567 2568 ```ts 2569 let config: request.agent.Config = { 2570 action: request.agent.Action.DOWNLOAD, 2571 url: 'http://127.0.0.1', 2572 title: 'taskResumeTest', 2573 description: 'Sample code for resume the download task', 2574 mode: request.agent.Mode.BACKGROUND, 2575 overwrite: false, 2576 method: "GET", 2577 data: "", 2578 saveas: "./", 2579 network: request.agent.Network.CELLULAR, 2580 metered: false, 2581 roaming: true, 2582 retry: true, 2583 redirect: true, 2584 index: 0, 2585 begins: 0, 2586 ends: -1, 2587 gauge: false, 2588 precise: false, 2589 token: "it is a secret" 2590 }; 2591 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2592 task.resume((err: BusinessError) => { 2593 if (err) { 2594 console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`); 2595 return; 2596 } 2597 console.info(`Succeeded in resuming a download task. `); 2598 }); 2599 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2600 }).catch((err: BusinessError) => { 2601 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2602 }); 2603 ``` 2604 2605 2606### resume<sup>10+</sup> 2607 2608resume(): Promise<void> 2609 2610重新启动任务，可以恢复暂停的后台任务。使用Promise异步回调。 2611 2612**需要权限**：ohos.permission.INTERNET 2613 2614**系统能力**: SystemCapability.Request.FileTransferAgent 2615 2616**返回值：** 2617 2618| 类型 | 说明 | 2619| ------------------- | ------------------------- | 2620| Promise<void> | Promise对象。无返回结果的Promise对象。 | 2621 2622**错误码：** 2623 2624以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2625 2626 | 错误码ID | 错误信息 | 2627 | -------- | -------- | 2628 | 13400003 | task service ability error. | 2629 | 21900005 | task mode error. | 2630 | 21900007 | task state error. | 2631 2632**示例：** 2633 2634 ```ts 2635 let config: request.agent.Config = { 2636 action: request.agent.Action.DOWNLOAD, 2637 url: 'http://127.0.0.1', 2638 title: 'taskResumeTest', 2639 description: 'Sample code for resume the download task', 2640 mode: request.agent.Mode.BACKGROUND, 2641 overwrite: false, 2642 method: "GET", 2643 data: "", 2644 saveas: "./", 2645 network: request.agent.Network.CELLULAR, 2646 metered: false, 2647 roaming: true, 2648 retry: true, 2649 redirect: true, 2650 index: 0, 2651 begins: 0, 2652 ends: -1, 2653 gauge: false, 2654 precise: false, 2655 token: "it is a secret" 2656 }; 2657 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2658 task.resume().then(() => { 2659 console.info(`Succeeded in resuming a download task. `); 2660 }).catch((err: BusinessError) => { 2661 console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`); 2662 }); 2663 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2664 }).catch((err: BusinessError) => { 2665 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2666 }); 2667 ``` 2668 2669 2670### stop<sup>10+</sup> 2671 2672stop(callback: AsyncCallback<void>): void 2673 2674停止任务，可以停止正在运行/正在等待/正在重试的任务。使用callback异步回调。 2675 2676**系统能力**: SystemCapability.Request.FileTransferAgent 2677 2678**参数：** 2679 2680 | 参数名 | 类型 | 必填 | 说明 | 2681 | -------- | -------- | -------- | -------- | 2682 | callback | function | 是 | 回调函数，停止任务成功，err为undefined，否则为错误对象 | 2683 2684**错误码：** 2685 2686以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2687 2688 | 错误码ID | 错误信息 | 2689 | -------- | -------- | 2690 | 13400003 | task service ability error. | 2691 | 21900007 | task state error. | 2692 2693**示例：** 2694 2695 ```ts 2696 let config: request.agent.Config = { 2697 action: request.agent.Action.DOWNLOAD, 2698 url: 'http://127.0.0.1', 2699 title: 'taskStopTest', 2700 description: 'Sample code for stop the download task', 2701 mode: request.agent.Mode.BACKGROUND, 2702 overwrite: false, 2703 method: "GET", 2704 data: "", 2705 saveas: "./", 2706 network: request.agent.Network.CELLULAR, 2707 metered: false, 2708 roaming: true, 2709 retry: true, 2710 redirect: true, 2711 index: 0, 2712 begins: 0, 2713 ends: -1, 2714 gauge: false, 2715 precise: false, 2716 token: "it is a secret" 2717 }; 2718 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2719 task.stop((err: BusinessError) => { 2720 if (err) { 2721 console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`); 2722 return; 2723 } 2724 console.info(`Succeeded in stopping a download task. `); 2725 }); 2726 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2727 }).catch((err: BusinessError) => { 2728 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2729 }); 2730 ``` 2731 2732 2733### stop<sup>10+</sup> 2734 2735stop(): Promise<void> 2736 2737停止任务，可以停止正在运行/正在等待/正在重试的任务。使用Promise异步回调。 2738 2739**系统能力**: SystemCapability.Request.FileTransferAgent 2740 2741**返回值：** 2742 2743| 类型 | 说明 | 2744| ------------------- | ------------------------- | 2745| Promise<void> | Promise对象。无返回结果的Promise对象。 | 2746 2747**错误码：** 2748 2749以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2750 2751 | 错误码ID | 错误信息 | 2752 | -------- | -------- | 2753 | 13400003 | task service ability error. | 2754 | 21900007 | task state error. | 2755 2756**示例：** 2757 2758 ```ts 2759 let config: request.agent.Config = { 2760 action: request.agent.Action.DOWNLOAD, 2761 url: 'http://127.0.0.1', 2762 title: 'taskStopTest', 2763 description: 'Sample code for stop the download task', 2764 mode: request.agent.Mode.BACKGROUND, 2765 overwrite: false, 2766 method: "GET", 2767 data: "", 2768 saveas: "./", 2769 network: request.agent.Network.CELLULAR, 2770 metered: false, 2771 roaming: true, 2772 retry: true, 2773 redirect: true, 2774 index: 0, 2775 begins: 0, 2776 ends: -1, 2777 gauge: false, 2778 precise: false, 2779 token: "it is a secret" 2780 }; 2781 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2782 task.stop().then(() => { 2783 console.info(`Succeeded in stopping a download task. `); 2784 }).catch((err: BusinessError) => { 2785 console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`); 2786 }); 2787 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2788 }).catch((err: BusinessError) => { 2789 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2790 }); 2791 ``` 2792 2793## request.agent.create<sup>10+</sup> 2794 2795create(context: BaseContext, config: Config, callback: AsyncCallback<Task>): void 2796 2797创建要上传或下载的任务，并将其排入队列，每个应用最多支持创建10个未完成的任务。使用callback异步回调。 2798 2799 2800**需要权限**：ohos.permission.INTERNET 2801 2802**系统能力**: SystemCapability.Request.FileTransferAgent 2803 2804**参数：** 2805 2806 | 参数名 | 类型 | 必填 | 说明 | 2807 | -------- | -------- | -------- | -------- | 2808 | config | [Config](#config10) | 是 | 上传/下载任务的配置信息。 | 2809 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 2810 | callback | AsyncCallback<[Task](#task10)> | 是 | 回调函数，返回创建任务的配置信息。 | 2811 2812**错误码：** 2813 2814以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2815 2816 | 错误码ID | 错误信息 | 2817 | -------- | -------- | 2818 | 13400001 | file operation error. | 2819 | 13400003 | task service ability error. | 2820 | 21900004 | application task queue full error. | 2821 | 21900005 | task mode error. | 2822 2823**示例：** 2824 2825 ```ts 2826 let attachments: Array<request.agent.FormItem> = [{ 2827 name: "createTest", 2828 value: { 2829 filename: "createTest.avi", 2830 mimeType: "application/octet-stream", 2831 path: "./createTest.avi", 2832 } 2833 }]; 2834 let config: request.agent.Config = { 2835 action: request.agent.Action.UPLOAD, 2836 url: 'http://127.0.0.1', 2837 title: 'createTest', 2838 description: 'Sample code for create task', 2839 mode: request.agent.Mode.BACKGROUND, 2840 overwrite: false, 2841 method: "PUT", 2842 data: attachments, 2843 saveas: "./", 2844 network: request.agent.Network.CELLULAR, 2845 metered: false, 2846 roaming: true, 2847 retry: true, 2848 redirect: true, 2849 index: 0, 2850 begins: 0, 2851 ends: -1, 2852 gauge: false, 2853 precise: false, 2854 token: "it is a secret" 2855 }; 2856 request.agent.create(getContext(), config, (err: BusinessError, task: request.agent.Task) => { 2857 if (err) { 2858 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2859 return; 2860 } 2861 console.info(`Succeeded in creating a download task. result: ${task.config}`); 2862 }); 2863 ``` 2864 2865> **说明：** 2866> 2867> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2868 2869## request.agent.create<sup>10+</sup> 2870 2871create(context: BaseContext, config: Config): Promise<Task> 2872 2873创建要上传或下载的任务，并将其排入队列，每个应用最多支持创建10个未完成的任务。使用Promise异步回调。 2874 2875 2876**需要权限**：ohos.permission.INTERNET 2877 2878**系统能力**: SystemCapability.Request.FileTransferAgent 2879 2880**参数：** 2881 2882 | 参数名 | 类型 | 必填 | 说明 | 2883 | -------- | -------- | -------- | -------- | 2884 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 2885 | config | [Config](#config10) | 是 | 上传/下载任务的配置信息。 | 2886 2887**返回值：** 2888 2889| 类型 | 说明 | 2890| ------------------- | ------------------------- | 2891| Promise<[Task](#task10)> | Promise对象。返回任务配置信息的Promise对象。 | 2892 2893**错误码：** 2894 2895以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2896 2897 | 错误码ID | 错误信息 | 2898 | -------- | -------- | 2899 | 13400001 | file operation error. | 2900 | 13400003 | task service ability error. | 2901 | 21900004 | application task queue full error. | 2902 | 21900005 | task mode error. | 2903 2904**示例：** 2905 2906 ```ts 2907 let attachments: Array<request.agent.FormItem> = [{ 2908 name: "createTest", 2909 value: { 2910 filename: "createTest.avi", 2911 mimeType: "application/octet-stream", 2912 path: "./createTest.avi", 2913 } 2914 }]; 2915 let config: request.agent.Config = { 2916 action: request.agent.Action.UPLOAD, 2917 url: 'http://127.0.0.1', 2918 title: 'createTest', 2919 description: 'Sample code for create task', 2920 mode: request.agent.Mode.BACKGROUND, 2921 overwrite: false, 2922 method: "PUT", 2923 data: attachments, 2924 saveas: "./", 2925 network: request.agent.Network.CELLULAR, 2926 metered: false, 2927 roaming: true, 2928 retry: true, 2929 redirect: true, 2930 index: 0, 2931 begins: 0, 2932 ends: -1, 2933 gauge: false, 2934 precise: false, 2935 token: "it is a secret" 2936 }; 2937 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2938 console.info(`Succeeded in creating a download task. result: ${task.config}`); 2939 }).catch((err) => { 2940 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2941 }); 2942 ``` 2943 2944> **说明：** 2945> 2946> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2947 2948## request.agent.remove<sup>10+</sup> 2949 2950remove(id: string, callback: AsyncCallback<void>): void 2951 2952移除属于调用方的指定任务，如果正在处理中，该任务将被迫停止。使用callback异步回调。 2953 2954**系统能力**: SystemCapability.Request.FileTransferAgent 2955 2956**参数：** 2957 2958 | 参数名 | 类型 | 必填 | 说明 | 2959 | -------- | -------- | -------- | -------- | 2960 | id | string | 是 | 任务id。 | 2961 | callback | AsyncCallback<void> | 是 | 回调函数，删除指定任务成功，err为undefined，否则为错误对象。 | 2962 2963**错误码：** 2964 2965以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2966 2967 | 错误码ID | 错误信息 | 2968 | -------- | -------- | 2969 | 13400003 | task service ability error. | 2970 | 21900006 | task not found error. | 2971 2972**示例：** 2973 2974 ```ts 2975 request.agent.remove("123456", (err: BusinessError) => { 2976 if (err) { 2977 console.error(`Failed to removing a download task, Code: ${err.code}, message: ${err.message}`); 2978 return; 2979 } 2980 console.info(`Succeeded in creating a download task.`); 2981 }); 2982 ``` 2983 2984 2985## request.agent.remove<sup>10+</sup> 2986 2987remove(id: string): Promise<void> 2988 2989移除属于调用方的指定任务，如果正在处理中，该任务将被迫停止，使用Promise异步回调。 2990 2991**系统能力**: SystemCapability.Request.FileTransferAgent 2992 2993**参数：** 2994 2995 | 参数名 | 类型 | 必填 | 说明 | 2996 | -------- | -------- | -------- | -------- | 2997 | id | string | 是 | 任务id。 | 2998 2999**返回值：** 3000 3001| 类型 | 说明 | 3002| ------------------- | ------------------------- | 3003| Promise<void> | Promise对象。无返回结果的Promise对象。 | 3004 3005**错误码：** 3006 3007以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3008 3009 | 错误码ID | 错误信息 | 3010 | -------- | -------- | 3011 | 13400003 | task service ability error. | 3012 | 21900006 | task not found error. | 3013 3014**示例：** 3015 3016 ```ts 3017 request.agent.remove("123456").then(() => { 3018 console.info(`Succeeded in removing a download task. `); 3019 }).catch((err: BusinessError) => { 3020 console.error(`Failed to remove a download task, Code: ${err.code}, message: ${err.message}`); 3021 }); 3022 ``` 3023 3024 3025## request.agent.show<sup>10+</sup> 3026 3027show(id: string, callback: AsyncCallback<TaskInfo>): void 3028 3029根据任务id查询任务的详细信息。使用callback异步回调。 3030 3031**系统能力**: SystemCapability.Request.FileTransferAgent 3032 3033**参数：** 3034 3035 | 参数名 | 类型 | 必填 | 说明 | 3036 | -------- | -------- | -------- | -------- | 3037 | id | string | 是 | 任务id。 | 3038 | callback | AsyncCallback<TaskInfo> | 是 | 回调函数，返回任务详细信息。 | 3039 3040**错误码：** 3041以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3042 3043 | 错误码ID | 错误信息 | 3044 | -------- | -------- | 3045 | 13400003 | task service ability error. | 3046 | 21900006 | task not found error. | 3047 3048**示例：** 3049 3050 ```ts 3051 request.agent.show("123456", (err: BusinessError, taskInfo: request.agent.TaskInfo) => { 3052 if (err) { 3053 console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`); 3054 return; 3055 } 3056 console.info(`Succeeded in showing a upload task.`); 3057 }); 3058 ``` 3059 3060 3061## request.agent.show<sup>10+</sup> 3062 3063show(id: string): Promise<TaskInfo> 3064 3065根据任务id查询任务的详细信息。使用Promise异步回调。 3066 3067**系统能力**: SystemCapability.Request.FileTransferAgent 3068 3069**参数：** 3070 3071 | 参数名 | 类型 | 必填 | 说明 | 3072 | -------- | -------- | -------- | -------- | 3073 | id | string | 是 | 任务id。 | 3074 3075**返回值：** 3076 3077| 类型 | 说明 | 3078| ------------------- | ------------------------- | 3079| Promise<TaskInfo> | Promise对象。返回任务详细信息的Promise对象。 | 3080 3081**错误码：** 3082以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3083 3084 | 错误码ID | 错误信息 | 3085 | -------- | -------- | 3086 | 13400003 | task service ability error. | 3087 | 21900006 | task not found error. | 3088 3089**示例：** 3090 3091 ```ts 3092 request.agent.show("123456").then((taskInfo: request.agent.TaskInfo) => { 3093 console.info(`Succeeded in showing a upload task.`); 3094 }).catch((err: BusinessError) => { 3095 console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`); 3096 }); 3097 ``` 3098 3099 3100## request.agent.touch<sup>10+</sup> 3101 3102touch(id: string, token: string, callback: AsyncCallback<TaskInfo>): void 3103 3104根据任务id和token查询任务的详细信息。使用callback异步回调。 3105 3106**系统能力**: SystemCapability.Request.FileTransferAgent 3107 3108**参数：** 3109 3110 | 参数名 | 类型 | 必填 | 说明 | 3111 | -------- | -------- | -------- | -------- | 3112 | id | string | 是 | 任务id。 | 3113 | token | string | 是 | 任务查询token。 | 3114 | callback | AsyncCallback<void> | 是 | 回调函数，返回任务详细信息。 | 3115 3116**错误码：** 3117以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3118 3119 | 错误码ID | 错误信息 | 3120 | -------- | -------- | 3121 | 13400003 | task service ability error. | 3122 | 21900006 | task not found error. | 3123 3124**示例：** 3125 3126 ```ts 3127 request.agent.touch("123456", "token", (err: BusinessError, taskInfo: request.agent.TaskInfo) => { 3128 if (err) { 3129 console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`); 3130 return; 3131 } 3132 console.info(`Succeeded in touching a upload task.`); 3133 }); 3134 ``` 3135 3136 3137## request.agent.touch<sup>10+</sup> 3138 3139touch(id: string, token: string): Promise<TaskInfo> 3140 3141根据任务id和token查询任务的详细信息。使用Promise异步回调。 3142 3143**系统能力**: SystemCapability.Request.FileTransferAgent 3144 3145**参数：** 3146 3147 | 参数名 | 类型 | 必填 | 说明 | 3148 | -------- | -------- | -------- | -------- | 3149 | id | string | 是 | 任务id。 | 3150 | token | string | 是 | 任务查询token。 | 3151 3152**返回值：** 3153 3154| 类型 | 说明 | 3155| ------------------- | ------------------------- | 3156| Promise<TaskInfo> | Promise对象。返回任务详细信息的Promise对象。 | 3157 3158**错误码：** 3159以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3160 3161 | 错误码ID | 错误信息 | 3162 | -------- | -------- | 3163 | 13400003 | task service ability error. | 3164 | 21900006 | task not found error. | 3165 3166**示例：** 3167 3168 ```ts 3169 request.agent.touch("123456", "token").then((taskInfo: request.agent.TaskInfo) => { 3170 console.info(`Succeeded in touching a upload task. `); 3171 }).catch((err: BusinessError) => { 3172 console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`); 3173 }); 3174 ``` 3175 3176## request.agent.search<sup>10+</sup> 3177 3178search(callback: AsyncCallback<Array<string>>): void 3179 3180根据默认[Filter](#filter10)过滤条件查找任务id。使用callback异步回调。 3181 3182**系统能力**: SystemCapability.Request.FileTransferAgent 3183 3184**参数：** 3185 3186 | 参数名 | 类型 | 必填 | 说明 | 3187 | -------- | -------- | -------- | -------- | 3188 | callback | AsyncCallback<Array<string>> | 是 | 回调函数，返回满足条件任务id。 | 3189 3190**错误码：** 3191以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3192 3193 | 错误码ID | 错误信息 | 3194 | -------- | -------- | 3195 | 13400003 | task service ability error. | 3196 3197**示例：** 3198 3199 ```ts 3200 request.agent.search((err: BusinessError, data: Array<string>) => { 3201 if (err) { 3202 console.error(`Failed to search a upload task, Code: ${err.code}, message: ${err.message}`); 3203 return; 3204 } 3205 console.info(`Succeeded in searching a upload task. `); 3206 }); 3207 ``` 3208 3209## request.agent.search<sup>10+</sup> 3210 3211search(filter: Filter, callback: AsyncCallback<Array<string>>): void 3212 3213根据[Filter](#filter10)过滤条件查找任务id。使用callback异步回调。 3214 3215**系统能力**: SystemCapability.Request.FileTransferAgent 3216 3217**参数：** 3218 3219 | 参数名 | 类型 | 必填 | 说明 | 3220 | -------- | -------- | -------- | -------- | 3221 | filter | [Filter](#filter10) | 是 | 过滤条件。 | 3222 | callback | AsyncCallback<Array<string>> | 是 | 回调函数，返回满足条件任务id。 | 3223 3224**错误码：** 3225以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3226 3227 | 错误码ID | 错误信息 | 3228 | -------- | -------- | 3229 | 13400003 | task service ability error. | 3230 3231**示例：** 3232 3233 ```ts 3234 let filter: request.agent.Filter = { 3235 bundle: "com.example.myapplication", 3236 action: request.agent.Action.UPLOAD, 3237 mode: request.agent.Mode.BACKGROUND 3238 } 3239 request.agent.search(filter, (err: BusinessError, data: Array<string>) => { 3240 if (err) { 3241 console.error(`Failed to search a upload task, Code: ${err.code}, message: ${err.message}`); 3242 return; 3243 } 3244 console.info(`Succeeded in searching a upload task. `); 3245 }); 3246 ``` 3247 3248 3249## request.agent.search<sup>10+</sup> 3250 3251search(filter?: Filter): Promise<Array<string>> 3252 3253根据[Filter](#filter10)过滤条件查找任务id。使用Promise异步回调。 3254 3255**系统能力**: SystemCapability.Request.FileTransferAgent 3256 3257**参数：** 3258 3259 | 参数名 | 类型 | 必填 | 说明 | 3260 | -------- | -------- | -------- | -------- | 3261 | filter | [Filter](#filter10) | 否 | 过滤条件。 | 3262 3263**返回值：** 3264 3265| 类型 | 说明 | 3266| ------------------- | ------------------------- | 3267| Promise<Array<string>> | Promise对象。返回满足条件任务id的Promise对象。 | 3268 3269**错误码：** 3270以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3271 3272 | 错误码ID | 错误信息 | 3273 | -------- | -------- | 3274 | 13400003 | task service ability error. | 3275 3276**示例：** 3277 3278 ```ts 3279 let filter: request.agent.Filter = { 3280 bundle: "com.example.myapplication", 3281 action: request.agent.Action.UPLOAD, 3282 mode: request.agent.Mode.BACKGROUND 3283 } 3284 request.agent.search(filter).then((data: Array<string>) => { 3285 console.info(`Succeeded in searching a upload task. `); 3286 }).catch((err: BusinessError) => { 3287 console.error(`Failed to search a upload task, Code: ${err.code}, message: ${err.message}`); 3288 }); 3289 ``` 3290 3291 3292## request.agent.query<sup>10+</sup> 3293 3294query(id: string, callback: AsyncCallback<TaskInfo>): void 3295 3296根据任务id查询任务的详细信息。使用callback异步回调。 3297 3298**需要权限**：ohos.permission.DOWNLOAD_SESSION_MANAGER 或 ohos.permission.UPLOAD_SESSION_MANAGER 3299 3300**系统能力**: SystemCapability.Request.FileTransferAgent 3301 3302**系统接口**：此接口为系统接口。 3303 3304**参数：** 3305 3306 | 参数名 | 类型 | 必填 | 说明 | 3307 | -------- | -------- | -------- | -------- | 3308 | id | string | 是 | 任务id。 | 3309 | callback | AsyncCallback<TaskInfo> | 是 | 回调函数，返回任务详细信息。 | 3310 3311**错误码：** 3312以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3313 3314 | 错误码ID | 错误信息 | 3315 | -------- | -------- | 3316 | 13400003 | task service ability error. | 3317 | 21900006 | task not found error. | 3318 3319**示例：** 3320 3321 ```ts 3322 request.agent.query("123456", (err: BusinessError, taskInfo: request.agent.TaskInfo) => { 3323 if (err) { 3324 console.error(`Failed to query a upload task, Code: ${err.code}, message: ${err.message}`); 3325 return; 3326 } 3327 console.info(`Succeeded in querying a upload task. result: ${taskInfo.uid}`); 3328 }); 3329 ``` 3330 3331 3332## request.agent.query<sup>10+</sup> 3333 3334query(id: string): Promise<TaskInfo> 3335 3336根据任务id查询任务的详细信息。使用Promise异步回调。 3337 3338**需要权限**：ohos.permission.DOWNLOAD_SESSION_MANAGER 或 ohos.permission.UPLOAD_SESSION_MANAGER 3339 3340**系统能力**: SystemCapability.Request.FileTransferAgent 3341 3342**系统接口**：此接口为系统接口。 3343 3344**参数：** 3345 3346 | 参数名 | 类型 | 必填 | 说明 | 3347 | -------- | -------- | -------- | -------- | 3348 | id | string | 是 | 任务id。 | 3349 3350**返回值：** 3351 3352| 类型 | 说明 | 3353| ------------------- | ------------------------- | 3354| Promise<TaskInfo> | Promise对象。返回任务详细信息的Promise对象。 | 3355 3356**错误码：** 3357以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3358 3359 | 错误码ID | 错误信息 | 3360 | -------- | -------- | 3361 | 13400003 | task service ability error. | 3362 | 21900006 | task not found error. | 3363 3364**示例：** 3365 3366 ```ts 3367 request.agent.query("123456").then((taskInfo: request.agent.TaskInfo) => { 3368 console.info(`Succeeded in querying a upload task. result: ${taskInfo.uid}`); 3369 }).catch((err: BusinessError) => { 3370 console.error(`Failed to query a upload task, Code: ${err.code}, message: ${err.message}`); 3371 }); 3372 ``` 3373 3374<!--no_check-->
