From 0b38f2007abdff98e28d0654b44e9c3d9c131377 Mon Sep 17 00:00:00 2001 From: libo Date: Fri, 4 Jul 2025 20:36:19 +0800 Subject: [PATCH] test Signed-off-by: BrainL --- arkuix/js-apis-request.md | 3483 +++++++++++++++++++++++++++++++++++++ 1 file changed, 3483 insertions(+) create mode 100644 arkuix/js-apis-request.md diff --git a/arkuix/js-apis-request.md b/arkuix/js-apis-request.md new file mode 100644 index 00000000000..97d4616967b --- /dev/null +++ b/arkuix/js-apis-request.md @@ -0,0 +1,3483 @@ +# @ohos.request (Upload and Download) + +The **request** module provides applications with basic upload, download, and background transmission agent capabilities. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. + + +## Modules to Import + + +```js +import request from '@ohos.request'; +``` + +## Constants + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +### Network Types +You can set **networkType** in [DownloadConfig](#downloadconfig) to specify the network type for the download service. + +| Name| Type| Value| Description| +| -------- | -------- | -------- | -------- | +| NETWORK_MOBILE | number | 0x00000001 | Whether download is allowed on a mobile network.| +| NETWORK_WIFI | number | 0x00010000 | Whether download is allowed on a WLAN.| + +### Download Error Codes +The table below lists the values of **err** in the callback of [on('fail')7+](#onfail7) and the values of **failedReason** returned by [getTaskInfo9+](#gettaskinfo9). + +| Name| Type| Value| Description| +| -------- | -------- | -------- | -------- | +| ERROR_CANNOT_RESUME7+ | number | 0 | Failure to resume the download due to network errors.| +| ERROR_DEVICE_NOT_FOUND7+ | number | 1 | Failure to find a storage device such as a memory card.| +| ERROR_FILE_ALREADY_EXISTS7+ | number | 2 | Failure to download the file because it already exists.| +| ERROR_FILE_ERROR7+ | number | 3 | File operation failure.| +| ERROR_HTTP_DATA_ERROR7+ | number | 4 | HTTP transmission failure.| +| ERROR_INSUFFICIENT_SPACE7+ | number | 5 | Insufficient storage space.| +| ERROR_TOO_MANY_REDIRECTS7+ | number | 6 | Error caused by too many network redirections.| +| ERROR_UNHANDLED_HTTP_CODE7+ | number | 7 | Unidentified HTTP code.| +| ERROR_UNKNOWN7+ | number | 8 | Unknown error.| +| ERROR_OFFLINE9+ | number | 9 | No network connection.| +| ERROR_UNSUPPORTED_NETWORK_TYPE9+ | number | 10 | Network type mismatch.| + + +### Causes of Download Pause +The table below lists the values of **pausedReason** returned by [getTaskInfo9+](#gettaskinfo9). + +| Name| Type| Value| Description| +| -------- | -------- | -------- | -------- | +| PAUSED_QUEUED_FOR_WIFI7+ | number | 0 | Download paused and queuing for a WLAN connection, because the file size exceeds the maximum value allowed by a mobile network session.| +| PAUSED_WAITING_FOR_NETWORK7+ | number | 1 | Download paused due to a network connection problem, for example, network disconnection.| +| PAUSED_WAITING_TO_RETRY7+ | number | 2 | Download paused and then retried.| +| PAUSED_BY_USER9+ | number | 3 | The user paused the session.| +| PAUSED_UNKNOWN7+ | number | 4 | Download paused due to unknown reasons.| + +### Download Task Status Codes +The table below lists the values of **status** returned by [getTaskInfo9+](#gettaskinfo9). + +| Name| Type| Value| Description| +| -------- | -------- | -------- | -------- | +| SESSION_SUCCESSFUL7+ | number | 0 | Successful download.| +| SESSION_RUNNING7+ | number | 1 | Download in progress.| +| SESSION_PENDING7+ | number | 2 | Download pending.| +| SESSION_PAUSED7+ | number | 3 | Download paused.| +| SESSION_FAILED7+ | number | 4 | Download failure without retry.| + + +## request.uploadFile9+ + +uploadFile(context: BaseContext, config: UploadConfig): Promise<UploadTask> + +Uploads files. This API uses a promise to return the result. You can use [on('complete'|'fail')9+](#oncomplete--fail9) to obtain the upload error information. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Upload + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| +| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| + + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object.| + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID| Error Message| +| -------- | -------- | +| 13400002 | bad file path. | + +**Example** + + ```js + let uploadTask; + let uploadConfig = { + url: 'http://patch', + header: { key1: "value1", key2: "value2" }, + method: "POST", + files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], + data: [{ name: "name123", value: "123" }], + }; + try { + request.uploadFile(globalThis.abilityContext, uploadConfig).then((data) => { + uploadTask = data; + }).catch((err) => { + console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); + }); + } catch (err) { + console.error('err.code : ' + err.code + ', err.message : ' + err.message); + } + ``` + + +## request.uploadFile9+ + +uploadFile(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void + +Uploads files. This API uses an asynchronous callback to return the result. You can use [on('complete'|'fail')9+](#oncomplete--fail9) to obtain the upload error information. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Upload + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| +| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| +| callback | AsyncCallback<[UploadTask](#uploadtask)> | Yes| Callback used to return the **UploadTask** object.| + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID| Error Message| +| -------- | -------- | +| 13400002 | bad file path. | + +**Example** + + ```js + let uploadTask; + let uploadConfig = { + url: 'http://patch', + header: { key1: "value1", key2: "value2" }, + method: "POST", + files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], + data: [{ name: "name123", value: "123" }], + }; + try { + request.uploadFile(globalThis.abilityContext, uploadConfig, (err, data) => { + if (err) { + console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); + return; + } + uploadTask = data; + }); + } catch (err) { + console.error('err.code : ' + err.code + ', err.message : ' + err.message); + } + ``` + +## UploadTask + +Implements file uploads. Before using any APIs of this class, you must obtain an **UploadTask** object through [request.uploadFile9+](#requestuploadfile9) in promise mode or [request.uploadFile9+](#requestuploadfile9-1) in callback mode. + + + +### on('progress') + +on(type: 'progress', callback:(uploadedSize: number, totalSize: number) => void): void + +Subscribes to upload progress events. This API uses a callback to return the result synchronously. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Upload + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (upload progress).| +| callback | function | Yes| Callback for the upload progress event.| + + Parameters of the callback function + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| uploadedSize | number | Yes| Size of the uploaded files, in bytes.| +| totalSize | number | Yes| Total size of the files to upload, in bytes.| + +**Example** + + ```js + let upProgressCallback = (uploadedSize, totalSize) => { + console.info("upload totalSize:" + totalSize + " uploadedSize:" + uploadedSize); + }; + uploadTask.on('progress', upProgressCallback); + ``` + + +### on('headerReceive')7+ + +on(type: 'headerReceive', callback: (header: object) => void): void + +Subscribes to HTTP header events for an upload task. This API uses a callback to return the result synchronously. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Upload + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the event to subscribe to. The value is **'headerReceive'** (response header).| +| callback | function | Yes| Callback for the HTTP Response Header event.| + + Parameters of the callback function + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| header | object | Yes| HTTP Response Header.| + +**Example** + + ```js + let headerCallback = (headers) => { + console.info("upOnHeader headers:" + JSON.stringify(headers)); + }; + uploadTask.on('headerReceive', headerCallback); + ``` + + +### on('complete' | 'fail')9+ + + on(type:'complete' | 'fail', callback: Callback<Array<TaskState>>): void; + +Subscribes to upload completion or failure events. This API uses a callback to return the result synchronously. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Upload + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the event to subscribe to. The value **'complete'** means the upload completion event, and **'fail'** means the upload failure event.| +| callback | Callback<Array<TaskState>> | Yes| Callback used to return the result.| + + Parameters of the callback function + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| taskstates | Array<[TaskState](#taskstate9)> | Yes| Upload result.| + +**Example** + + ```js + let upCompleteCallback = (taskStates) => { + for (let i = 0; i < taskStates.length; i++ ) { + console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i])); + } + }; + uploadTask.on('complete', upCompleteCallback); + + let upFailCallback = (taskStates) => { + for (let i = 0; i < taskStates.length; i++ ) { + console.info("upOnFail taskState:" + JSON.stringify(taskStates[i])); + } + }; + uploadTask.on('fail', upFailCallback); + ``` + + +### off('progress') + +off(type: 'progress', callback?: (uploadedSize: number, totalSize: number) => void): void + +Unsubscribes from upload progress events. This API uses a callback to return the result synchronously. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Upload + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (upload progress).| +| callback | function | No| Callback used to return the result.
**uploadedSize**: size of the uploaded files, in bytes.
**totalSize**: Total size of the files to upload, in bytes. | + +**Example** + + ```js + let upProgressCallback = (uploadedSize, totalSize) => { + console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize); + }; + uploadTask.off('progress', upProgressCallback); + ``` + + +### off('headerReceive')7+ + +off(type: 'headerReceive', callback?: (header: object) => void): void + +Unsubscribes from HTTP header events for an upload task. This API uses a callback to return the result synchronously. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Upload + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the event to unsubscribe from. The value is **'headerReceive'** (response header).| +| callback | function | No| Callback used to return the result.
**header**: HTTP response header.| + +**Example** + + ```js + let headerCallback = (header) => { + console.info(`Upload delete headerReceive notification. header: ${JSON.stringify(header)}`); + }; + uploadTask.off('headerReceive', headerCallback); + ``` + +### off('complete' | 'fail')9+ + + off(type:'complete' | 'fail', callback?: Callback<Array<TaskState>>): void; + +Unsubscribes from upload completion or failure events. This API uses a callback to return the result synchronously. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Upload + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the event to subscribe to. The value **'complete'** means the upload completion event, and **'fail'** means the upload failure event.| +| callback | Callback<Array<TaskState>> | No| Callback used to return the result.
**taskstates**: upload task result.| + +**Example** + + ```js + let upCompleteCallback = (taskStates) => { + console.info('Upload delete complete notification.'); + for (let i = 0; i < taskStates.length; i++ ) { + console.info('taskState:' + JSON.stringify(taskStates[i])); + } + }; + uploadTask.off('complete', upCompleteCallback); + + let upFailCallback = (taskStates) => { + console.info('Upload delete fail notification.'); + for (let i = 0; i < taskStates.length; i++ ) { + console.info('taskState:' + JSON.stringify(taskStates[i])); + } + }; + uploadTask.off('fail', upFailCallback); + ``` + +### delete9+ +delete(): Promise<boolean> + +Deletes this upload task. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Upload + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<boolean> | Promise used to return the task removal result. It returns **true** if the operation is successful and returns **false** otherwise.| + +**Example** + + ```js + uploadTask.delete().then((result) => { + if (result) { + console.info('Upload task removed successfully. '); + } else { + console.error('Failed to remove the upload task. '); + } + }).catch((err) => { + console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); + }); + ``` + + +### delete9+ + +delete(callback: AsyncCallback<boolean>): void + +Deletes this upload task. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Upload + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| + +**Example** + + ```js + uploadTask.delete((err, result) => { + if (err) { + console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); + return; + } + if (result) { + console.info('Upload task removed successfully.'); + } else { + console.error('Failed to remove the upload task.'); + } + }); + ``` + + +## UploadConfig +Describes the configuration for an upload task. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Upload + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| url | string | Yes| Resource URL.| +| header | Object | Yes| HTTP or HTTPS header added to an upload request.| +| method | string | Yes| Request method, which can be **'POST'** or **'PUT'**. The default value is **'POST'**.| +| files | Array<[File](#file)> | Yes| List of files to upload, which is submitted through **multipart/form-data**.| +| data | Array<[RequestData](#requestdata)> | Yes| Form data in the request body.| +| index20+ | number | No| Path index of the task. The default value is **0**.| +| begins20+ | number | No| Start point of the file read when the upload task begins. The default value is **0**. The value is a closed interval, indicating that the file is read from the beginning.| +| ends20+ | number | No| End point of the file read when the upload task is complete. The default value is **-1**. The value is a closed interval, indicating that the file is read till the end.| + +## TaskState9+ +Implements a **TaskState** object, which is the callback parameter of the [on('complete' | 'fail')9+](#oncomplete--fail9) and [off('complete' | 'fail')9+](#offcomplete--fail9) APIs. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Upload + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| path | string | Yes| File path.| +| responseCode | number | Yes| Return value of an upload task.| +| message | string | Yes| Description of the upload task result.| + +## File +Describes the list of files in [UploadConfig](#uploadconfig). + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| filename | string | Yes| File name in the header when **multipart** is used.| +| name | string | Yes| Name of a form item when **multipart** is used. The default value is **file**.| +| uri | string | Yes| Local path for storing files.
Only the **internal** protocol type is supported. In the value, **internal://cache/** is mandatory. Example:
internal://cache/path/to/file.txt | +| type | string | Yes| Type of the file content. By default, the type is obtained based on the extension of the file name or URI.| + + +## RequestData +Describes the form data in [UploadConfig](#uploadconfig). + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| name | string | Yes| Name of a form element.| +| value | string | Yes| Value of a form element.| + +## request.downloadFile9+ + +downloadFile(context: BaseContext, config: DownloadConfig): Promise<DownloadTask> + +Downloads files. This API uses a promise to return the result. You can use [on('complete'|'pause'|'remove')7+](#oncompletepauseremove7) to obtain the download task state, which can be completed, paused, or removed. You can also use [on('fail')7+](#onfail7) to obtain the task download error information. + + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| +| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<[DownloadTask](#downloadtask)> | Promise used to return the result.| + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID| Error Message| +| -------- | -------- | +| 13400001 | file operation error. | +| 13400002 | bad file path. | +| 13400003 | task manager service error. | + +**Example** + + ```js + let downloadTask; + try { + request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxx.hap' }).then((data) => { + downloadTask = data; + }).catch((err) => { + console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); + }) + } catch (err) { + console.error('err.code : ' + err.code + ', err.message : ' + err.message); + } + ``` + + +## request.downloadFile9+ + +downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void; + +Downloads files. This API uses an asynchronous callback to return the result. You can use [on('complete'|'pause'|'remove')7+](#oncompletepauseremove7) to obtain the download task state, which can be completed, paused, or removed. You can also use [on('fail')7+](#onfail7) to obtain the task download error information. + + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| +| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| +| callback | AsyncCallback<[DownloadTask](#downloadtask)> | Yes| Callback used to return the result.| + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID| Error Message| +| -------- | -------- | +| 13400001 | file operation error. | +| 13400002 | bad file path. | +| 13400003 | task manager service error. | + +**Example** + + ```js + let downloadTask; + try { + request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxxx.hap', + filePath: 'xxx/xxxxx.hap'}, (err, data) => { + if (err) { + console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); + return; + } + downloadTask = data; + }); + } catch (err) { + console.error('err.code : ' + err.code + ', err.message : ' + err.message); + } + ``` + +## DownloadTask + +Implements file downloads. Before using any APIs of this class, you must obtain a **DownloadTask** object through [request.downloadFile9+](#requestdownloadfile9) in promise mode or [request.downloadFile9+](#requestdownloadfile9-1) in callback mode. + + +### on('progress') + +on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void + +Subscribes to download progress events. This API uses a callback to return the result synchronously. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (download progress).| +| callback | function | Yes| Callback used to return the result.| + + Parameters of the callback function + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| receivedSize | number | Yes| Size of the downloaded files, in bytes.| +| totalSize | number | Yes| Total size of the files to download, in bytes.| + +**Example** + + ```js + let progresCallback = (receivedSize, totalSize) => { + console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); + }; + downloadTask.on('progress', progresCallback); + ``` + + +### off('progress') + +off(type: 'progress', callback?: (receivedSize: number, totalSize: number) => void): void + +Unsubscribes from download progress events. This API uses a callback to return the result synchronously. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (download progress).| +| callback | function | No| Callback used to return the result.
**receivedSize**: size of the downloaded files.
**totalSize**: total size of the files to download.| + +**Example** + + ```js + let progresCallback = (receivedSize, totalSize) => { + console.info('Download delete progress notification.' + 'receivedSize:' + receivedSize + 'totalSize:' + totalSize); + }; + downloadTask.off('progress', progresCallback); + ``` + + +### on('complete'|'pause'|'remove')7+ + +on(type: 'complete'|'pause'|'remove', callback:() => void): void + +Subscribes to download events. This API uses a callback to return the result synchronously. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the event to subscribe to.
- **'complete'**: download task completion event.
- **'pause'**: download task pause event.
- **'remove'**: download task removal event.| +| callback | function | Yes| Callback used to return the result.| + +**Example** + + ```js + let completeCallback = () => { + console.info('Download task completed.'); + }; + downloadTask.on('complete', completeCallback); + + let pauseCallback = () => { + console.info('Download task pause.'); + }; + downloadTask.on('pause', pauseCallback); + + let removeCallback = () => { + console.info('Download task remove.'); + }; + downloadTask.on('remove', removeCallback); + ``` + + +### off('complete'|'pause'|'remove')7+ + +off(type: 'complete'|'pause'|'remove', callback?:() => void): void + +Unsubscribes from download events. This API uses a callback to return the result synchronously. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the event to unsubscribe from.
- **'complete'**: download task completion event.
- **'pause'**: download task pause event.
- **'remove'**: download task removal event.| +| callback | function | No| Callback used to return the result.| + +**Example** + + ```js + let completeCallback = () => { + console.info('Download delete complete notification.'); + }; + downloadTask.off('complete', completeCallback); + + let pauseCallback = () => { + console.info('Download delete pause notification.'); + }; + downloadTask.off('pause', pauseCallback); + + let removeCallback = () => { + console.info('Download delete remove notification.'); + }; + downloadTask.off('remove', removeCallback); + ``` + + +### on('fail')7+ + +on(type: 'fail', callback: (err: number) => void): void + +Subscribes to download failure events. This API uses a callback to return the result synchronously. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the event to subscribe to. The value is **'fail'** (download failure).| +| callback | function | Yes| Callback for the download task failure event.| + + Parameters of the callback function + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| err | number | Yes| Error code of the download failure. For details about the error codes, see [Download Error Codes](#download-error-codes).| + +**Example** + + ```js + let failCallback = (err) => { + console.info('Download task failed. Cause:' + err); + }; + downloadTask.on('fail', failCallback); + ``` + + +### off('fail')7+ + +off(type: 'fail', callback?: (err: number) => void): void + +Unsubscribes from download failure events. This API uses a callback to return the result synchronously. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the event to unsubscribe from. The value is **'fail'** (download failure).| +| callback | function | No| Callback used to return the result.
**err**: error code of the download failure. | + +**Example** + + ```js + let failCallback = (err) => { + console.info(`Download delete fail notification. err: ${err.message}`); + }; + downloadTask.off('fail', failCallback); + ``` + +### delete9+ + +delete(): Promise<boolean> + +Removes this download task. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<boolean> | Promise used to return the task removal result.| + +**Example** + + ```js + downloadTask.delete().then((result) => { + if (result) { + console.info('Download task removed.'); + } else { + console.error('Failed to remove the download task.'); + } + }).catch ((err) => { + console.error('Failed to remove the download task.'); + }); + ``` + + +### delete9+ + +delete(callback: AsyncCallback<boolean>): void + +Deletes this download task. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | Yes| Callback used to return the task deletion result.| + +**Example** + + ```js + downloadTask.delete((err, result)=>{ + if(err) { + console.error('Failed to remove the download task.'); + return; + } + if (result) { + console.info('Download task removed.'); + } else { + console.error('Failed to remove the download task.'); + } + }); + ``` + + +### getTaskInfo9+ + +getTaskInfo(): Promise<DownloadInfo> + +Obtains the information about this download task. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<[DownloadInfo](#downloadinfo7)> | Promise used to return the download task information.| + +**Example** + + ```js + downloadTask.getTaskInfo().then((downloadInfo) => { + console.info('Download task queried. Data:' + JSON.stringify(downloadInfo)) + }) .catch((err) => { + console.error('Failed to query the download task. Cause:' + err) + }); + ``` + + +### getTaskInfo9+ + +getTaskInfo(callback: AsyncCallback<DownloadInfo>): void + +Obtains the information about this download task. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | Yes| Callback used to return the download task information.| + +**Example** + + ```js + downloadTask.getTaskInfo((err, downloadInfo)=>{ + if(err) { + console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); + } else { + console.info('download query success. data:'+ JSON.stringify(downloadInfo)); + } + }); + ``` + + +### getTaskMimeType9+ + +getTaskMimeType(): Promise<string> + +Obtains the **MimeType** of this download task. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<string> | Promise used to return the **MimeType** of the download task.| + +**Example** + + ```js + downloadTask.getTaskMimeType().then((data) => { + console.info('Download task queried. Data:' + JSON.stringify(data)); + }).catch((err) => { + console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err)) + }); + ``` + + +### getTaskMimeType9+ + +getTaskMimeType(callback: AsyncCallback<string>): void; + +Obtains the **MimeType** of this download task. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<string> | Yes| Callback used to return the **MimeType** of the download task.| + +**Example** + + ```js + downloadTask.getTaskMimeType((err, data)=>{ + if(err) { + console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); + } else { + console.info('Download task queried. data:' + JSON.stringify(data)); + } + }); + ``` + + +### suspend9+ + +suspend(): Promise<boolean> + +Pauses this download task. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<boolean> | Promise used to return the download task pause result.| + +**Example** + + ```js + downloadTask.suspend().then((result) => { + if (result) { + console.info('Download task paused. '); + } else { + console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); + } + }).catch((err) => { + console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); + }); + ``` + + +### suspend9+ + +suspend(callback: AsyncCallback<boolean>): void + +Pauses this download task. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| + +**Example** + + ```js + downloadTask.suspend((err, result)=>{ + if(err) { + console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); + return; + } + if (result) { + console.info('Download task paused. '); + } else { + console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); + } + }); + ``` + + +### restore9+ + +restore(): Promise<boolean> + +Resumes this download task. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<boolean> | Promise used to return the result.| + +**Example** + + ```js + downloadTask.restore().then((result) => { + if (result) { + console.info('Download task resumed.') + } else { + console.error('Failed to resume the download task. '); + } + console.info('Download task resumed.') + }).catch((err) => { + console.error('Failed to resume the download task. Cause:' + err); + }); + ``` + + +### restore9+ + +restore(callback: AsyncCallback<boolean>): void + +Resumes this download task. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| + +**Example** + + ```js + downloadTask.restore((err, result)=>{ + if (err) { + console.error('Failed to resume the download task. Cause:' + err); + return; + } + if (result) { + console.info('Download task resumed.'); + } else { + console.error('Failed to resume the download task.'); + } + }); + ``` + +## DownloadConfig +Defines the download task configuration. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| url | string | Yes| Resource URL.| +| header | Object | No| HTTPS flag header to be included in the download request.
The **X-TLS-Version** parameter in **header** specifies the TLS version to be used. If this parameter is not set, the CURL_SSLVERSION_TLSv1_2 version is used. Available options are as follows:
CURL_SSLVERSION_TLSv1_0
CURL_SSLVERSION_TLSv1_1
CURL_SSLVERSION_TLSv1_2
CURL_SSLVERSION_TLSv1_3
The **X-Cipher-List** parameter in **header** specifies the cipher suite list to be used. If this parameter is not specified, the secure cipher suite list is used. Available options are as follows:
- The TLS 1.2 cipher suite list includes the following ciphers:
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,
TLS_DHE_DSS_WITH_AES_128_GCM_SHA256,TLS_DSS_RSA_WITH_AES_256_GCM_SHA384,
TLS_PSK_WITH_AES_256_GCM_SHA384,TLS_DHE_PSK_WITH_AES_128_GCM_SHA256,
TLS_DHE_PSK_WITH_AES_256_GCM_SHA384,TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256,
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256,
TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256,TLS_ECDHE_PSK_WITH_AES_256_GCM_SHA384,
TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_CCM,
TLS_DHE_RSA_WITH_AES_256_CCM,TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
TLS_PSK_WITH_AES_256_CCM,TLS_DHE_PSK_WITH_AES_128_CCM,
TLS_DHE_PSK_WITH_AES_256_CCM,TLS_ECDHE_ECDSA_WITH_AES_128_CCM,
TLS_ECDHE_ECDSA_WITH_AES_256_CCM,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
- The TLS 1.3 cipher suite list includes the following ciphers:
TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_CCM_SHA256
- The TLS 1.3 cipher suite list adds the Chinese national cryptographic algorithm:
TLS_SM4_GCM_SM3,TLS_SM4_CCM_SM3 | +| enableMetered | boolean | No| Whether download is allowed on a metered connection. The default value is **false**. In general cases, a mobile data connection is metered, while a Wi-Fi connection is not.
- **true**: allowed
- **false**: not allowed| +| enableRoaming | boolean | No| Whether download is allowed on a roaming network. The default value is **false**.
- **true**: allowed
- **false**: not allowed| +| description | string | No| Description of the download session.| +| filePath7+ | string | No| Path where the downloaded file is stored.
- In the FA model, use [context](js-apis-inner-application-context.md) to obtain the cache directory of the application, for example, **\${featureAbility.getContext().getFilesDir()}/test.txt\**, and store the file in this directory.
- In the stage model, use [AbilityContext](js-apis-inner-application-context.md) to obtain the file path, for example, **\${globalThis.abilityContext.tempDir}/test.txt\**, and store the file in this path.| +| networkType | number | No| Network type allowed for download. The default value is **NETWORK_MOBILE and NETWORK_WIFI**.
- NETWORK_MOBILE: 0x00000001
- NETWORK_WIFI: 0x00010000| +| title | string | No| Download task name.| +| background9+ | boolean | No| Whether to enable background task notification so that the download status is displayed in the notification panel. The default value is false.| + + +## DownloadInfo7+ +Defines the download task information, which is the callback parameter of the [getTaskInfo9+](#gettaskinfo9) API. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +| Name| Type | Mandatory | Description | +| -------- | -------- | -------- | -------- | +| downloadId | number |Yes| ID of the download task.| +| failedReason | number|Yes| Cause of the download failure. The value can be any constant in [Download Error Codes](#download-error-codes).| +| fileName | string |Yes| Name of the downloaded file.| +| filePath | string |Yes| URI of the saved file.| +| pausedReason | number |Yes| Cause of download pause. The value can be any constant in [Causes of Download Pause](#causes-of-download-pause).| +| status | number |Yes| Download task status code. The value can be any constant in [Download Task Status Codes](#download-task-status-codes).| +| targetURI | string |Yes| URI of the downloaded file.| +| downloadTitle | string |Yes| Name of the download task.| +| downloadTotalBytes | number |Yes| Total size of the files to download, in bytes.| +| description | string |Yes| Description of the download task.| +| downloadedBytes | number |Yes| Size of the files downloaded, in bytes.| + +## Action10+ + +Defines action options. + +**System capability**: SystemCapability.Request.FileTransferAgent + +| Name | Value | Description | +| -------- | ----- | ----------- | +| DOWNLOAD | 0 | Download. | +| UPLOAD | 1 | Upload. | + + +## Mode10+ + +Defines mode options. + +**System capability**: SystemCapability.Request.FileTransferAgent + +| Name | Value | Description | +| ---------- | ----- | ---------------- | +| FOREGROUND | 0 | Foreground task. | + +## Network10+ + +Defines network options. + +**System capability**: SystemCapability.Request.FileTransferAgent + +| Name | Value | Description | +| -------- | ----- | ---------------------- | +| ANY | 0 | Network of any type. | +| WIFI | 1 | Wi-Fi network. | +| CELLULAR | 2 | Cellular data network. | + + +## FormItem10+ + +Describes the form item of a task. + +**System capability**: SystemCapability.Request.FileTransferAgent + +| Name | Type | Mandatory | Description | +| ----- | ------------------------------------------------------------ | --------- | --------------------- | +| name | string | Yes | Form parameter name. | +| value | string \| [FileSpec](#filespec10) \| Array<[FileSpec](#filespec10)> | Yes | Form parameter value. | + + +## Config10+ + +Provides the configuration information of an upload or download task. + +**System capability**: SystemCapability.Request.FileTransferAgent + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------------- | --------- | ------------------------------------------------------------ | +| action | [Action](#action10) | Yes | Task action.
- **UPLOAD**
- **DOWNLOAD** | +| url | string | Yes | Resource URL. The value contains a maximum of 2048 characters. | +| title | string | No | Task title. The value contains a maximum of 256 characters. The default value is a null string. | +| description | string | No | Task description. The value contains a maximum of 1024 characters. The default value is a null string. | +| mode | [Mode](#mode10) | No | Task mode. The default mode is foreground .
- For a foreground task, a callback is used for notification. | +| overwrite | boolean | No | Whether to overwrite an existing file during the download. The default value is **false**.
- **true**: Overwrite the existing file.
- **false**: Do not overwrite the existing file. In this case, the download fails. | +| method | string | No | Standard HTTP method for the task. The value can be **GET**, **POST**, or **PUT**, which is case-insensitive.
- If the task is an upload, use **PUT** or **POST**. The default value is **PUT**.
- If the task is a download, use **GET** or **POST**. The default value is **GET**. | +| headers | object | No | HTTP headers to be included in the task.
- If the task is an upload, the default **Content-Type** is **multipart/form-data**.
- If the task is a download, the default **Content-Type** is **application/json**. | +| data | string \| Array<[FormItem](#formitem10)> | No | Task data.
- If the task is a download, the value is a string, typically in JSON format (an object will be converted to a JSON string); the default value is null.
- If the task is an upload, the value is Array<[FormItem](#formitem10)>; the default value is null. | +| saveas | string | No | Path for storing downloaded files. The options are as follows:
- Relative path in the cache folder of the invoker, for example, **"./xxx/yyy/zzz.html"** and **"xxx/yyy/zzz.html"**.
- URI (applicable when the application has the permission to access the URI), for example, **"datashare://bundle/xxx/yyy/zzz.html"**. This option is not supported currently.
The default value is a relative path in the cache folder of the application. | +| network | [Network](#network10) | No | Network used for the task. The default value is **ANY** (Wi-Fi or cellular). | +| metered | boolean | No | Whether the task is allowed on a metered connection. The default value is **false**.
- **true**: The task is allowed on a metered connection.
- **false**: The task is not allowed on a metered connection. | +| roaming | boolean | No | Whether the task is allowed on a roaming network. The default value is **true**.
- **true**: The task is allowed on a roaming network.
- **false**: The task is not allowed on a roaming network. | +| redirect | boolean | No | Whether redirection is allowed. The default value is **true**.
- **true**: Redirection is allowed.
- **false**: Redirection is not allowed. | +| index | number | No | Path index of the task. It is usually used for resumable downloads. The default value is **0**. | +| begins | number | No | File start point of the task. It is usually used for resumable downloads. The default value is **0**. The value is a closed interval.
- If the task is a download, the value is obtained by sending an HTTP range request to read the start position when the server starts to download files.
- If the task is an upload, the value is obtained at the beginning of the upload. | +| ends | number | No | File end point of the task. It is usually used for resumable downloads. The default value is **-1**. The value is a closed interval.
- If the task is a download, the value is obtained by sending an HTTP range request to read the end position when the server starts to download files.
- If the task is an upload, the value is obtained at the end of the upload. | +| precise | boolean | No | - If this parameter is set to **true**, the task fails when the file size cannot be obtained.
- If this parameter is set to **false**, the task continues when the file size is set to **-1**.
The default value is **false**. | +| token | string | No | Token of the task. If the task has a token configured, this token is required for query of the task. The value contains 8 to 2048 bytes. This parameter is left empty by default. | +| extras | object | No | Additional information of the task. This parameter is left empty by default. | +| proxy20+ | string | No| Proxy address. The value contains a maximum of 512 characters.
It is in the format of http://\:\. By default, this parameter is left blank.| + +## State10+ + +Defines the current task status. + +**System capability**: SystemCapability.Request.FileTransferAgent + +| Name | Value | Description | +| ----------- | ----- | ------------------------------------------------------------ | +| INITIALIZED | 0x00 | The task is initialized based on the configuration specified in [Config](#config10). | +| WAITING | 0x10 | The task lacks resources for running or the resources for retries do not match the network status. | +| RUNNING | 0x20 | The task is being executed. | +| RETRYING | 0x21 | The task has failed at least once and is being executed again. | +| PAUSED | 0x30 | The task is suspended and will be resumed later. | +| STOPPED | 0x31 | The task is stopped. | +| COMPLETED | 0x40 | The task is complete. | +| FAILED | 0x41 | The task fails. | +| REMOVED | 0x50 | The task is removed. | + + +## Progress10+ + +Describes the data structure of the task progress. + +**System capability**: SystemCapability.Request.FileTransferAgent + +| Name | Type | Mandatory | Description | +| --------- | ------------------- | --------- | ------------------------------------------------------------ | +| state | [State](#state10) | Yes | Current task status. | +| index | number | Yes | Index of the file that is being processed in the task. | +| processed | number | Yes | Size of processed data in the current file in the task, in bytes. | +| sizes | Array<number> | Yes | Size of files in the task, in bytes. | +| extras | object | No | Extra information of the task, for example, the header of the response from the server. | + + +## Faults10+ + +Defines the cause of a task failure. + +**System capability**: SystemCapability.Request.FileTransferAgent + +| Name | Value | Description | +| ------------ | ----- | ------------------------------------------------------------ | +| OTHERS | 0xFF | Other fault. | +| DISCONNECTED | 0x00 | Network disconnection. | +| TIMEOUT | 0x10 | Timeout. | +| PROTOCOL | 0x20 | Protocol error, for example, an internal server error (500) or a data range that cannot be processed (416). | +| FSIO | 0x40 | File system I/O error, for example, an error that occurs during the open, search, read, write, or close operation. | + + +## Filter10+ + +Defines the filter criteria. + +**System capability**: SystemCapability.Request.FileTransferAgent + +| Name | Type | Mandatory | Description | +| ------ | ------------------- | --------- | ------------------------------------------------------------ | +| before | number | No | Unix timestamp of the end time, in milliseconds. The default value is the invoking time. | +| after | number | No | Unix timestamp of the start time, in milliseconds. The default value is the invoking time minus 24 hours. | +| state | [State](#state10) | No | Task state. | +| action | [Action](#action10) | No | Task action.
- **UPLOAD**
- **DOWNLOAD** | +| mode | [Mode](#mode10) | No | Task mode.
- **FOREGROUND** | + +## TaskInfo10+ + +Defines the data structure of the task information for query. The fields available vary depending on the query type. + +**System capability**: SystemCapability.Request.FileTransferAgent + +| Name | Type | Mandatory | Description | +| ----------- | ---------------------------------------------- | --------- | ------------------------------------------------------------ | +| saveas | string | No | Path for storing downloaded files. The options are as follows:
- Relative path in the cache folder of the invoker, for example, **"./xxx/yyy/zzz.html"** and **"xxx/yyy/zzz.html"**.
- URI (applicable when the application has the permission to access the URI), for example, **"datashare://bundle/xxx/yyy/zzz.html"**. This option is not supported currently.
The default value is a relative path in the cache folder of the application. | +| url | string | No | Task URL.
- It can be obtained through [request.agent.show10+](#requestagentshow10-1), [request.agent.touch10+](#requestagenttouch10-1), or [request.agent.query10+](#requestagentquery10-1). When [request.agent.query10+](#requestagentquery10-1) is used, an empty string is returned. | +| data | string \| Array<[FormItem](#formitem10)> | No | Task value.
- It can be obtained through [request.agent.show10+](#requestagentshow10-1), [request.agent.touch10+](#requestagenttouch10-1), or [request.agent.query10+](#requestagentquery10-1). When [request.agent.query10+](#requestagentquery10-1) is used, an empty string is returned. | +| tid | string | Yes | Task ID. | +| title | string | Yes | Task title. | +| description | string | Yes | Task description. | +| action | [Action](#action10) | Yes | Task action.
- **UPLOAD**
- **DOWNLOAD** | +| mode | [Mode](#mode10) | Yes | Task mode.
- **FOREGROUND** | +| mimeType | string | Yes | MIME type in the task configuration. | +| progress | [Progress](#progress10) | Yes | Task progress. | +| ctime | number | Yes | Unix timestamp when the task is created, in milliseconds. The value is generated by the system of the current device.
Note: When [request.agent.search10+](#requestagentsearch10-1) is used for query, this value must be within the range of [after,before] for the task ID to be obtained. For details about **before** and **after**, see [Filter](#filter10). | +| mtime | number | Yes | Unix timestamp when the task state changes, in milliseconds. The value is generated by the system of the current device. | +| faults | [Faults](#faults10) | Yes | Failure cause of the task.
- **OTHERS**: other fault.
- **DISCONNECT**: network disconnection.
- **TIMEOUT**: timeout.
- **PROTOCOL**: protocol error.
- **FSIO**: file system I/O error. | +| reason | string | Yes | Reason why the task is waiting, failed, stopped, or paused. | +| extras | string | No | Extra information of the task | +| priority20+ | number | Yes| Task priority. The priority of a foreground task is higher than that of a background task. For tasks in the same mode, a smaller value indicates a higher priority.| + +## HttpResponse20+ +Describes the data structure of the task response header. + +**System capability**: SystemCapability.Request.FileTransferAgent + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| version | string | Yes| HTTP version.| +| statusCode | number | Yes| HTTP response status code.| +| reason | string | Yes| HTTP response cause.| +| headers | Map<string, Array<string>> | Yes| HTTP response header.| + +## BroadcastEvent20+ + +Defines a custom system event. You can use a common event API to obtain the event. +The upload and download SA has the ohos.permission.SEND_TASK_COMPLETE_EVENT permission. You can configure the level-2 configuration file to which the metadata of an event points to intercept other event senders. + +Use the **CommonEventData** type to transmit data related to common events. The members in **CommonEventData** are different from those described in [CommonEventData](js-apis-inner-commonEvent-commonEventData.md). Specifically, **CommonEventData.code** indicates the task status, which is **0x40 COMPLETE** or **0x41 FAILED**, and **CommonEventData.data** indicates the task ID. + + +For details about how to obtain the event configuration and configure the level-2 configuration file, see [Subscribing to Common Events in Static Mode (for System Applications Only)](../../basic-services/common-event/common-event-static-subscription.md). + +**System capability**: SystemCapability.Request.FileTransferAgent + +| Name| Value| Description | +| -------- | ------- |-----------| +| COMPLETE | 'ohos.request.event.COMPLETE' | Task completion event. The returned event code can be **0x40** or **0x41**, depending on whether the task is successful or fails.| + + +## Task10+ + +Implements an upload or download task. Before using this API, you must obtain a **Task** object, from a promise through [request.agent.create10+](#requestagentcreate10-1) or from a callback through [request.agent.create10+](#requestagentcreate10). + +### Attributes + +Task attributes include the task ID and task configuration. + +**System capability**: SystemCapability.Request.FileTransferAgent + +| Name | Type | Mandatory | Description | +| ------ | ------------------- | --------- | ------------------------------------------------------------ | +| tid | string | Yes | Task ID, which is unique in the system and is automatically generated by the system. | +| config | [Config](#config10) | Yes | Task configuration. | + + +### on('progress')10+ + +on(event: 'progress', callback: (progress: Progress) => void): void + +Subscribes to foreground task progress changes. This API uses a callback to return the result asynchronously. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | -------- | --------- | ------------------------------------------------------------ | +| event | string | Yes | Type of the event to subscribe to.
The value is **'progress'**, indicating the task progress. | +| callback | function | Yes | Callback used to return the data structure of the task progress. | + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | ---------------- | +| 21900005 | task mode error. | + +**Example** + + ```ts +let attachments: Array = [{ + name: "taskOnTest", + value: { + filename: "taskOnTest.avi", + mimeType: "application/octet-stream", + path: "./taskOnTest.avi", + } +}]; +let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', + title: 'taskOnTest', + description: 'Sample code for event listening', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" +}; +let createOnCallback = (progress: request.agent.Progress) => { + console.info('upload task progress.'); +}; +request.agent.create(getContext(), config).then((task: request.agent.Task) => { + task.on('progress', createOnCallback); + console.info(`Succeeded in creating a upload task. result: ${task.tid}`); +}).catch((err: BusinessError) => { + console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); +}); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +### on('completed')10+ + +on(event: 'completed', callback: (progress: Progress) => void): void + +Subscribes to the foreground task completion event. This API uses a callback to return the result asynchronously. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | -------- | --------- | ------------------------------------------------------------ | +| event | string | Yes | Type of the event to subscribe to.
The value is **'completed'**, indicating task completion. | +| callback | function | Yes | Callback used to return the data structure of the task progress. | + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | ---------------- | +| 21900005 | task mode error. | + +**Example** + + ```ts +let attachments: Array = [{ + name: "taskOnTest", + value: { + filename: "taskOnTest.avi", + mimeType: "application/octet-stream", + path: "./taskOnTest.avi", + } +}]; +let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', + title: 'taskOnTest', + description: 'Sample code for event listening', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" +}; +let createOnCallback = (progress: request.agent.Progress) => { + console.info('upload task completed.'); +}; +request.agent.create(getContext(), config).then((task: request.agent.Task) => { + task.on('completed', createOnCallback); + console.info(`Succeeded in creating a upload task. result: ${task.tid}`); +}).catch((err: BusinessError) => { + console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); +}); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +### on('failed')10+ + +on(event: 'failed', callback: (progress: Progress) => void): void + +Subscribes to the foreground task failure event. This API uses a callback to return the result asynchronously. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | -------- | --------- | ------------------------------------------------------------ | +| event | string | Yes | Type of the event to subscribe to.
The value is **'failed'**, indicating task failure. | +| callback | function | Yes | Callback used to return the data structure of the task progress. | + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | ---------------- | +| 21900005 | task mode error. | + +**Example** + + ```ts +let attachments: Array = [{ + name: "taskOnTest", + value: { + filename: "taskOnTest.avi", + mimeType: "application/octet-stream", + path: "./taskOnTest.avi", + } +}]; +let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', + title: 'taskOnTest', + description: 'Sample code for event listening', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" +}; +let createOnCallback = (progress: request.agent.Progress) => { + console.info('upload task failed.'); +}; +request.agent.create(getContext(), config).then((task: request.agent.Task) => { + task.on('failed', createOnCallback); + console.info(`Succeeded in creating a upload task. result: ${task.tid}`); +}).catch((err: BusinessError) => { + console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); +}); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +### on('response')20+ + +on(event: 'response', callback: Callback<HttpResponse>): void + +Subscribes to task response headers. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| event | string | Yes| Type of the event to subscribe to.
- **'response'**: task response.| +| callback | Callback<[HttpResponse](#httpresponse12)> | Yes| Callback used to return the data structure of the task response header.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message| +| -------- | -------- | +| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. | + +**Example** + + ```ts + import { BusinessError } from '@kit.BasicServicesKit'; + import { common } from '@kit.AbilityKit'; + + // Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. + let context = this.getUIContext().getHostContext() as common.UIAbilityContext; + let attachments: Array = [{ + name: "taskOnTest", + value: { + filename: "taskOnTest.avi", + path: "./taskOnTest.avi", + } + }]; + let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', // Replace the URL with the HTTP address of the real server. + title: 'taskOnTest', + description: 'Sample code for event listening', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" + }; + let createOnCallback = (response: request.agent.HttpResponse) => { + console.info('upload task response.'); + }; + request.agent.create(context, config).then((task: request.agent.Task) => { + task.on('response', createOnCallback); + console.info(`Succeeded in creating a upload task. result: ${task.tid}`); + task.start(); + }).catch((err: BusinessError) => { + console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); + }); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +### on('pause')20+ + +on(event: 'pause', callback: (progress: [Progress](#progress10)) => void): void + +Subscribes to task pause events. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| event | string | Yes| Type of the event to subscribe to.
- **'pause'**: task pause.| +| callback | function | Yes| Callback used to return the data structure of the task progress.| + +Parameters of the callback function + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| progress | [Progress](#progress10) | Yes| Task progress.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message| +| -------- | -------- | +| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. | + +**Example** + + ```ts + import { BusinessError } from '@kit.BasicServicesKit'; + import { common } from '@kit.AbilityKit'; + + // Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. + let context = this.getUIContext().getHostContext() as common.UIAbilityContext; + let attachments: Array = [{ + name: "taskOnTest", + value: { + filename: "taskOnTest.avi", + path: "./taskOnTest.avi", + } + }]; + let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', // Replace the URL with the HTTP address of the real server. + title: 'taskOnTest', + description: 'Sample code for event listening', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" + }; + let createOnCallback = (progress: request.agent.Progress) => { + console.info('upload task pause.'); + }; + request.agent.create(context, config).then((task: request.agent.Task) => { + task.on('pause', createOnCallback); + console.info(`Succeeded in creating a upload task. result: ${task.tid}`); + task.start(); + for(let t = Date.now(); Date.now() - t <= 1000;); // To prevent asynchronous out-of-order, wait for 1 second before performing the next operation. + task.pause(); + }).catch((err: BusinessError) => { + console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); + }); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +### on('resume')20+ + +on(event: 'resume', callback: (progress: [Progress](#progress10)) => void): void + +Subscribes to task resume events. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| event | string | Yes| Type of the event to subscribe to.
- **'resume'**: task resume.| +| callback | function | Yes| Callback used to return the data structure of the task progress.| + +Parameters of the callback function + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| progress | [Progress](#progress10) | Yes| Task progress.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message| +| -------- | -------- | +| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. | + +**Example** + + ```ts + import { BusinessError } from '@kit.BasicServicesKit'; + import { common } from '@kit.AbilityKit'; + + // Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. + let context = this.getUIContext().getHostContext() as common.UIAbilityContext; + let attachments: Array = [{ + name: "taskOnTest", + value: { + filename: "taskOnTest.avi", + path: "./taskOnTest.avi", + } + }]; + let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', // Replace the URL with the HTTP address of the real server. + title: 'taskOnTest', + description: 'Sample code for event listening', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" + }; + let createOnCallback = (progress: request.agent.Progress) => { + console.info('upload task resume.'); + }; + request.agent.create(context, config).then((task: request.agent.Task) => { + task.on('resume', createOnCallback); + console.info(`Succeeded in creating a upload task. result: ${task.tid}`); + task.start(); + for(let t = Date.now(); Date.now() - t <= 1000;); // To prevent asynchronous out-of-order, wait for 1 second before performing the next operation. + task.pause(); + for(let t = Date.now(); Date.now() - t <= 1000;); // To prevent asynchronous out-of-order, wait for 1 second before performing the next operation. + task.resume(); + }).catch((err: BusinessError) => { + console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); + }); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +### on('remove')20+ + +on(event: 'remove', callback: (progress: [Progress](#progress10)) => void): void + +Subscribes to task removal events. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| event | string | Yes| Type of the event to subscribe to.
- **'remove'**: task removal.| +| callback | function | Yes| Callback used to return the data structure of the task progress.| + +Parameters of the callback function + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| progress | [Progress](#progress10) | Yes| Task progress.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message| +| -------- | -------- | +| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. | + +**Example** + + ```ts + import { BusinessError } from '@kit.BasicServicesKit'; + import { common } from '@kit.AbilityKit'; + + // Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. + let context = this.getUIContext().getHostContext() as common.UIAbilityContext; + let attachments: Array = [{ + name: "taskOnTest", + value: { + filename: "taskOnTest.avi", + path: "./taskOnTest.avi", + } + }]; + let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', // Replace the URL with the HTTP address of the real server. + title: 'taskOnTest', + description: 'Sample code for event listening', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" + }; + let createOnCallback = (progress: request.agent.Progress) => { + console.info('upload task remove.'); + }; + request.agent.create(context, config).then((task: request.agent.Task) => { + task.on('remove', createOnCallback); + console.info(`Succeeded in creating a upload task. result: ${task.tid}`); + task.start(); + for(let t = Date.now(); Date.now() - t <= 1000;); // To prevent asynchronous out-of-order, wait for 1 second before performing the next operation. + request.agent.remove(task.tid); + }).catch((err: BusinessError) => { + console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); + }); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + + + +### off('progress')10+ + +off(event: 'progress', callback?: (progress: Progress) => void): void + +Unsubscribes from foreground task progress changes. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | -------- | --------- | ------------------------------------------------------------ | +| event | string | Yes | Type of the event to subscribe to.
The value is **'progress'**, indicating the task progress. | +| callback | function | No | Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered. | + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | ---------------- | +| 21900005 | task mode error. | + +**Example** + + ```ts +let attachments: Array = [{ + name: "taskOffTest", + value: { + filename: "taskOffTest.avi", + mimeType: "application/octet-stream", + path: "./taskOffTest.avi", + } +}]; +let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', + title: 'taskOffTest', + description: 'Sample code for event listening', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" +}; +let createOffCallback1 = (progress: request.agent.Progress) => { + console.info('upload task progress.'); +}; +let createOffCallback2 = (progress: request.agent.Progress) => { + console.info('upload task progress.'); +}; +request.agent.create(getContext(), config).then((task: request.agent.Task) => { + task.on('progress', createOffCallback1); + task.on('progress', createOffCallback2); + // Unsubscribe from createOffCallback1. + task.off('progress', createOffCallback1); + // Unsubscribe from all callbacks of foreground task progress changes. + task.off('progress'); + console.info(`Succeeded in creating a upload task. result: ${task.tid}`); +}).catch((err: BusinessError) => { + console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); +}); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +### off('completed')10+ + +off(event: 'completed', callback?: (progress: Progress) => void): void + +Unsubscribes from the foreground task completion event. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | -------- | --------- | ------------------------------------------------------------ | +| event | string | Yes | Type of the event to subscribe to.
The value is **'completed'**, indicating task completion. | +| callback | function | No | Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered. | + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | ---------------- | +| 21900005 | task mode error. | + +**Example** + + ```ts +let attachments: Array = [{ + name: "taskOffTest", + value: { + filename: "taskOffTest.avi", + mimeType: "application/octet-stream", + path: "./taskOffTest.avi", + } +}]; +let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', + title: 'taskOffTest', + description: 'Sample code for event listening', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" +}; +let createOffCallback1 = (progress: request.agent.Progress) => { + console.info('upload task completed.'); +}; +let createOffCallback2 = (progress: request.agent.Progress) => { + console.info('upload task completed.'); +}; +request.agent.create(getContext(), config).then((task: request.agent.Task) => { + task.on('completed', createOffCallback1); + task.on('completed', createOffCallback2); + // Unsubscribe from createOffCallback1. + task.off('completed', createOffCallback1); + // Unsubscribe from all callbacks of the foreground task completion event. + task.off('completed'); + console.info(`Succeeded in creating a upload task. result: ${task.tid}`); +}).catch((err: BusinessError) => { + console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); +}); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +### off('failed')10+ + +off(event: 'failed', callback?: (progress: Progress) => void): void + +Unsubscribes from the foreground task failure event. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | -------- | --------- | ------------------------------------------------------------ | +| event | string | Yes | Type of the event to subscribe to.
The value is **'failed'**, indicating task failure. | +| callback | function | No | Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered. | + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | ---------------- | +| 21900005 | task mode error. | + +**Example** + + ```ts +let attachments: Array = [{ + name: "taskOffTest", + value: { + filename: "taskOffTest.avi", + mimeType: "application/octet-stream", + path: "./taskOffTest.avi", + } +}]; +let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', + title: 'taskOffTest', + description: 'Sample code for event listening', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" +}; +let createOffCallback1 = (progress: request.agent.Progress) => { + console.info('upload task failed.'); +}; +let createOffCallback2 = (progress: request.agent.Progress) => { + console.info('upload task failed.'); +}; +request.agent.create(getContext(), config).then((task: request.agent.Task) => { + task.on('failed', createOffCallback1); + task.on('failed', createOffCallback2); + // Unsubscribe from createOffCallback1. + task.off('failed', createOffCallback1); + // Unsubscribe from all callbacks of the foreground task failure event. + task.off('failed'); + console.info(`Succeeded in creating a upload task. result: ${task.tid}`); +}).catch((err: BusinessError) => { + console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); +}); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +### off('response')20+ + +off(event: 'response', callback?: Callback<HttpResponse>): void + +Unsubscribes from task response headers. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| event | string | Yes| Type of the event to unsubscribe from.
- **response**: task response.| +| callback | Callback<[HttpResponse](#httpresponse12)> | No| Callback to unregister. If this parameter is not specified, all callbacks of the current type will be unregistered.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message| +| -------- | -------- | +| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. | + +**Example** + + ```ts + import { BusinessError } from '@kit.BasicServicesKit'; + import { common } from '@kit.AbilityKit'; + + // Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. + let context = this.getUIContext().getHostContext() as common.UIAbilityContext; + let attachments: Array = [{ + name: "taskOffTest", + value: { + filename: "taskOffTest.avi", + path: "./taskOffTest.avi", + } + }]; + let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', // Replace the URL with the HTTP address of the real server. + title: 'taskOffTest', + description: 'Sample code for event listening', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" + }; + let createOffCallback1 = (progress: request.agent.HttpResponse) => { + console.info('upload task response.'); + }; + let createOffCallback2 = (progress: request.agent.HttpResponse) => { + console.info('upload task response.'); + }; + request.agent.create(context, config).then((task: request.agent.Task) => { + task.on('response', createOffCallback1); + task.on('response', createOffCallback2); + // Unsubscribe from createOffCallback1. + task.off('response', createOffCallback1); + // Unsubscribe from all callbacks of the task removal event. + task.off('response'); + console.info(`Succeeded in creating a upload task. result: ${task.tid}`); + task.start(); + }).catch((err: BusinessError) => { + console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); + }); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +### off('pause')20+ + +off(event: 'pause', callback?: (progress: [Progress](#progress10)) => void): void + +Unsubscribes from the foreground task pause event. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| event | string | Yes| Type of the event to unsubscribe from.
- **'pause'**: task pause.| +| callback | function | No| Callback used to return the data structure of the task progress.| + +Parameters of the callback function + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| progress | [Progress](#progress10) | Yes| Task progress.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message| +| -------- | -------- | +| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. | + +**Example** + + ```ts + import { BusinessError } from '@kit.BasicServicesKit'; + import { common } from '@kit.AbilityKit'; + + // Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. + let context = this.getUIContext().getHostContext() as common.UIAbilityContext; + let attachments: Array = [{ + name: "taskOffTest", + value: { + filename: "taskOffTest.avi", + path: "./taskOffTest.avi", + } + }]; + let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', // Replace the URL with the HTTP address of the real server. + title: 'taskOffTest', + description: 'Sample code for event listening', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" + }; + let createOffCallback1 = (progress: request.agent.Progress) => { + console.info('upload task pause.'); + }; + let createOffCallback2 = (progress: request.agent.Progress) => { + console.info('upload task pause.'); + }; + request.agent.create(context, config).then((task: request.agent.Task) => { + task.on('pause', createOffCallback1); + task.on('pause', createOffCallback2); + // Unsubscribe from createOffCallback1. + task.off('pause', createOffCallback1); + // Unsubscribe from all callbacks of the foreground task pause event. + task.off('pause'); + console.info(`Succeeded in creating a upload task. result: ${task.tid}`); + task.start(); + }).catch((err: BusinessError) => { + console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); + }); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +### off('resume')20+ + +off(event: 'resume', callback?: (progress: [Progress](#progress10)) => void): void + +Unsubscribes from the foreground task resume event. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| event | string | Yes| Type of the event to unsubscribe from.
- **'resume'**: task resume.| +| callback | function | No| Callback used to return the data structure of the task progress.| + +Parameters of the callback function + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| progress | [Progress](#progress10) | Yes| Task progress.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message| +| -------- | -------- | +| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. | + +**Example** + + ```ts + import { BusinessError } from '@kit.BasicServicesKit'; + import { common } from '@kit.AbilityKit'; + + // Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. + let context = this.getUIContext().getHostContext() as common.UIAbilityContext; + let attachments: Array = [{ + name: "taskOffTest", + value: { + filename: "taskOffTest.avi", + path: "./taskOffTest.avi", + } + }]; + let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', // Replace the URL with the HTTP address of the real server. + title: 'taskOffTest', + description: 'Sample code for event listening', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" + }; + let createOffCallback1 = (progress: request.agent.Progress) => { + console.info('upload task resume.'); + }; + let createOffCallback2 = (progress: request.agent.Progress) => { + console.info('upload task resume.'); + }; + request.agent.create(context, config).then((task: request.agent.Task) => { + task.on('resume', createOffCallback1); + task.on('resume', createOffCallback2); + // Unsubscribe from createOffCallback1. + task.off('resume', createOffCallback1); + // Unsubscribe from all callbacks of the foreground task resume event. + task.off('resume'); + console.info(`Succeeded in creating a upload task. result: ${task.tid}`); + task.start(); + }).catch((err: BusinessError) => { + console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); + }); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +### off('remove')20+ + +off(event: 'remove', callback?: (progress: [Progress](#progress10)) => void): void + +Unsubscribes from the task removal event. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| event | string | Yes| Type of the event to unsubscribe from.
- **'remove'**: task removal.| +| callback | function | No| Callback used to return the data structure of the task progress.| + +Parameters of the callback function + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| progress | [Progress](#progress10) | Yes| Task progress.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message| +| -------- | -------- | +| 401 | Parameter error. Possible causes: 1. Missing mandatory parameters. 2. Incorrect parameter type. 3. Parameter verification failed. | + +**Example** + + ```ts + import { BusinessError } from '@kit.BasicServicesKit'; + import { common } from '@kit.AbilityKit'; + + // Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. + let context = this.getUIContext().getHostContext() as common.UIAbilityContext; + let attachments: Array = [{ + name: "taskOffTest", + value: { + filename: "taskOffTest.avi", + path: "./taskOffTest.avi", + } + }]; + let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', // Replace the URL with the HTTP address of the real server. + title: 'taskOffTest', + description: 'Sample code for event listening', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" + }; + let createOffCallback1 = (progress: request.agent.Progress) => { + console.info('upload task remove.'); + }; + let createOffCallback2 = (progress: request.agent.Progress) => { + console.info('upload task remove.'); + }; + request.agent.create(context, config).then((task: request.agent.Task) => { + task.on('remove', createOffCallback1); + task.on('remove', createOffCallback2); + // Unsubscribe from createOffCallback1. + task.off('remove', createOffCallback1); + // Unsubscribe from all callbacks of the task removal event. + task.off('remove'); + console.info(`Succeeded in creating a upload task. result: ${task.tid}`); + task.start(); + }).catch((err: BusinessError) => { + console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); + }); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +### start10+ + +start(callback: AsyncCallback<void>): void + +Starts this task. This API cannot be used to start an initialized task. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | -------- | --------- | ------------------------------------------------------------ | +| callback | function | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. | + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | --------------------------- | +| 13400003 | task service ability error. | +| 21900007 | task state error. | + +**Example** + + ```ts +let config: request.agent.Config = { + action: request.agent.Action.DOWNLOAD, + url: 'http://127.0.0.1', + title: 'taskStartTest', + description: 'Sample code for start the download task', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "GET", + data: "", + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" +}; +request.agent.create(getContext(), config).then((task: request.agent.Task) => { + task.start((err: BusinessError) => { + if (err) { + console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in starting a download task.`); + }); + console.info(`Succeeded in creating a download task. result: ${task.tid}`); +}).catch((err: BusinessError) => { + console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); +}); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +### start10+ + +start(): Promise<void> + +Starts this task. This API cannot be used to start an initialized task. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Return value** + +| Type | Description | +| ------------------- | ------------------------------ | +| Promise<void> | Promise that returns no value. | + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | --------------------------- | +| 13400003 | task service ability error. | +| 21900007 | task state error. | + +**Example** + + ```ts +let config: request.agent.Config = { + action: request.agent.Action.DOWNLOAD, + url: 'http://127.0.0.1', + title: 'taskStartTest', + description: 'Sample code for start the download task', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "GET", + data: "", + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" +}; +request.agent.create(getContext(), config).then((task: request.agent.Task) => { + task.start().then(() => { + console.info(`Succeeded in starting a download task.`); + }).catch((err: BusinessError) => { + console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`); + }); + console.info(`Succeeded in creating a download task. result: ${task.tid}`); +}).catch((err: BusinessError) => { + console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); +}); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +### pause20+ + +pause(callback: AsyncCallback<void>): void + +Pauses a task that is waiting, running, or retrying. A paused task can be resumed by [resume](#resume10). This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](errorcode-request.md). + +| ID| Error Message| +| -------- | -------- | +| 13400003 | Task service ability error. | +| 21900007 | Operation with wrong task state. | + +**Example** + + ```ts + import { BusinessError } from '@kit.BasicServicesKit'; + import { common } from '@kit.AbilityKit'; + + // Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. + let context = this.getUIContext().getHostContext() as common.UIAbilityContext; + let config: request.agent.Config = { + action: request.agent.Action.DOWNLOAD, + url: 'http://127.0.0.1', // Replace the URL with the HTTP address of the real server. + title: 'taskPauseTest', + description: 'Sample code for pause the download task', + mode: request.agent.Mode.BACKGROUND, + overwrite: false, + method: "GET", + data: "", + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" + }; + request.agent.create(context, config).then((task: request.agent.Task) => { + task.start(); + for(let t = Date.now(); Date.now() - t <= 1000;); // To prevent asynchronous out-of-order, wait for 1 second before performing the next operation. + task.pause((err: BusinessError) => { + if (err) { + console.error(`Failed to pause the download task, Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in pausing a download task. `); + }); + console.info(`Succeeded in creating a download task. result: ${task.tid}`); + }).catch((err: BusinessError) => { + console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); + }); + ``` + +### pause20+ + +pause(): Promise<void> + +Pauses a task that is waiting, running, or retrying. A paused task can be resumed by [resume](#resume10). This API uses a promise to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Return value** + +| Type | Description | +| ------------------- | ------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](errorcode-request.md). + +| ID| Error Message| +| -------- | -------- | +| 13400003 | Task service ability error. | +| 21900007 | Operation with wrong task state. | + +**Example** + + ```ts + import { BusinessError } from '@kit.BasicServicesKit'; + import { common } from '@kit.AbilityKit'; + + // Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. + let context = this.getUIContext().getHostContext() as common.UIAbilityContext; + let config: request.agent.Config = { + action: request.agent.Action.DOWNLOAD, + url: 'http://127.0.0.1', // Replace the URL with the HTTP address of the real server. + title: 'taskPauseTest', + description: 'Sample code for pause the download task', + mode: request.agent.Mode.BACKGROUND, + overwrite: false, + method: "GET", + data: "", + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" + }; + request.agent.create(context, config).then((task: request.agent.Task) => { + task.start(); + for(let t = Date.now(); Date.now() - t <= 1000;); // To prevent asynchronous out-of-order, wait for 1 second before performing the next operation. + task.pause().then(() => { + console.info(`Succeeded in pausing a download task. `); + }).catch((err: BusinessError) => { + console.error(`Failed to pause the download task, Code: ${err.code}, message: ${err.message}`); + }); + console.info(`Succeeded in creating a download task. result: ${task.tid}`); + }).catch((err: BusinessError) => { + console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); + }); + ``` +### resume20+ + +resume(callback: AsyncCallback<void>): void + +Resumes a paused task. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](errorcode-request.md) and [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message| +| -------- | -------- | +| 201 | Permission denied. | +| 13400003 | Task service ability error. | +| 21900007 | Operation with wrong task state. | + +**Example** + + ```ts + import { BusinessError } from '@kit.BasicServicesKit'; + import { common } from '@kit.AbilityKit'; + + // Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. + let context = this.getUIContext().getHostContext() as common.UIAbilityContext; + let config: request.agent.Config = { + action: request.agent.Action.DOWNLOAD, + url: 'http://127.0.0.1', // Replace the URL with the HTTP address of the real server. + title: 'taskResumeTest', + description: 'Sample code for resume the download task', + mode: request.agent.Mode.BACKGROUND, + overwrite: false, + method: "GET", + data: "", + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" + }; + request.agent.create(context, config).then((task: request.agent.Task) => { + task.start(); + for(let t = Date.now(); Date.now() - t <= 1000;); // To prevent asynchronous out-of-order, wait for 1 second before performing the next operation. + task.pause(); + for(let t = Date.now(); Date.now() - t <= 1000;); // To prevent asynchronous out-of-order, wait for 1 second before performing the next operation. + task.resume((err: BusinessError) => { + if (err) { + console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in resuming a download task. `); + }); + console.info(`Succeeded in creating a download task. result: ${task.tid}`); + }).catch((err: BusinessError) => { + console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); + }); + ``` + +### resume20+ + +resume(): Promise<void> + +Resumes a paused task. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Return value** + +| Type | Description | +| ------------------- | ------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](errorcode-request.md) and [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message| +| -------- | -------- | +| 201 | Permission denied. | +| 13400003 | Task service ability error. | +| 21900007 | Operation with wrong task state. | + +**Example** + + ```ts + import { BusinessError } from '@kit.BasicServicesKit'; + import { common } from '@kit.AbilityKit'; + + // Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext. + let context = this.getUIContext().getHostContext() as common.UIAbilityContext; + let config: request.agent.Config = { + action: request.agent.Action.DOWNLOAD, + url: 'http://127.0.0.1', // Replace the URL with the HTTP address of the real server. + title: 'taskResumeTest', + description: 'Sample code for resume the download task', + mode: request.agent.Mode.BACKGROUND, + overwrite: false, + method: "GET", + data: "", + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" + }; + request.agent.create(context, config).then((task: request.agent.Task) => { + task.start(); + for(let t = Date.now(); Date.now() - t <= 1000;); // To prevent asynchronous out-of-order, wait for 1 second before performing the next operation. + task.pause(); + for(let t = Date.now(); Date.now() - t <= 1000;); // To prevent asynchronous out-of-order, wait for 1 second before performing the next operation. + task.resume().then(() => { + console.info(`Succeeded in resuming a download task. `); + }).catch((err: BusinessError) => { + console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`); + }); + console.info(`Succeeded in creating a download task. result: ${task.tid}`); + }).catch((err: BusinessError) => { + console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); + }); + ``` + +### stop10+ + +stop(callback: AsyncCallback<void>): void + +Stops this task. This API can be used to stop a running, waiting, or retrying task. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | -------- | --------- | ------------------------------------------------------------ | +| callback | function | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. | + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | --------------------------- | +| 13400003 | task service ability error. | +| 21900007 | task state error. | + +**Example** + + ```ts +let config: request.agent.Config = { + action: request.agent.Action.DOWNLOAD, + url: 'http://127.0.0.1', + title: 'taskStopTest', + description: 'Sample code for stop the download task', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "GET", + data: "", + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" +}; +request.agent.create(getContext(), config).then((task: request.agent.Task) => { + task.stop((err: BusinessError) => { + if (err) { + console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in stopping a download task. `); + }); + console.info(`Succeeded in creating a download task. result: ${task.tid}`); +}).catch((err: BusinessError) => { + console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); +}); + ``` + + +### stop10+ + +stop(): Promise<void> + +Stops this task. This API can be used to stop a running, waiting, or retrying task. This API uses a promise to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Return value** + +| Type | Description | +| ------------------- | ------------------------------ | +| Promise<void> | Promise that returns no value. | + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | --------------------------- | +| 13400003 | task service ability error. | +| 21900007 | task state error. | + +**Example** + + ```ts +let config: request.agent.Config = { + action: request.agent.Action.DOWNLOAD, + url: 'http://127.0.0.1', + title: 'taskStopTest', + description: 'Sample code for stop the download task', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "GET", + data: "", + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" +}; +request.agent.create(getContext(), config).then((task: request.agent.Task) => { + task.stop().then(() => { + console.info(`Succeeded in stopping a download task. `); + }).catch((err: BusinessError) => { + console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`); + }); + console.info(`Succeeded in creating a download task. result: ${task.tid}`); +}).catch((err: BusinessError) => { + console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); +}); + ``` + +## request.agent.create10+ + +create(context: BaseContext, config: Config, callback: AsyncCallback<Task>): void + +Creates an upload or download task and adds it to the queue. An application can create a maximum of 10 unfinished tasks. This API uses an asynchronous callback to return the result. + + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ------------------------------------------------------- | --------- | ------------------------------------------------------------ | +| config | [Config](#config10) | Yes | Task configuration. | +| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes | Application-based context. | +| callback | AsyncCallback<[Task](#task10)> | Yes | Callback used to return the configuration about the created task. | + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | ---------------------------------- | +| 13400001 | file operation error. | +| 13400003 | task service ability error. | +| 21900004 | application task queue full error. | +| 21900005 | task mode error. | + +**Example** + + ```ts +let attachments: Array = [{ + name: "createTest", + value: { + filename: "createTest.avi", + mimeType: "application/octet-stream", + path: "./createTest.avi", + } +}]; +let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', + title: 'createTest', + description: 'Sample code for create task', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" +}; +request.agent.create(getContext(), config, (err: BusinessError, task: request.agent.Task) => { + if (err) { + console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in creating a download task. result: ${task.config}`); +}); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +## request.agent.create10+ + +create(context: BaseContext, config: Config): Promise<Task> + +Creates an upload or download task and adds it to the queue. An application can create a maximum of 10 unfinished tasks. This API uses a promise to return the result. + + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------------------------------------------------------- | --------- | -------------------------- | +| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes | Application-based context. | +| config | [Config](#config10) | Yes | Task configuration. | + +**Return value** + +| Type | Description | +| ------------------------------ | ------------------------------------------------------------ | +| Promise<[Task](#task10)> | Promise used to return the configuration about the created task. | + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | ---------------------------------- | +| 13400001 | file operation error. | +| 13400003 | task service ability error. | +| 21900004 | application task queue full error. | +| 21900005 | task mode error. | + +**Example** + + ```ts +let attachments: Array = [{ + name: "createTest", + value: { + filename: "createTest.avi", + mimeType: "application/octet-stream", + path: "./createTest.avi", + } +}]; +let config: request.agent.Config = { + action: request.agent.Action.UPLOAD, + url: 'http://127.0.0.1', + title: 'createTest', + description: 'Sample code for create task', + mode: request.agent.Mode.FOREGROUND, + overwrite: false, + method: "PUT", + data: attachments, + saveas: "./", + network: request.agent.Network.CELLULAR, + metered: false, + roaming: true, + retry: true, + redirect: true, + index: 0, + begins: 0, + ends: -1, + gauge: false, + precise: false, + token: "it is a secret" +}; +request.agent.create(getContext(), config).then((task: request.agent.Task) => { + console.info(`Succeeded in creating a download task. result: ${task.config}`); +}).catch((err) => { + console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); +}); + ``` + +> **NOTE** +> +> For details about how to obtain the context in the example, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability). + +## request.agent.remove10+ + +remove(id: string, callback: AsyncCallback<void>): void + +Removes a specified task of the invoker. If the task is being executed, the task is forced to stop. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ------------------------- | --------- | ------------------------------------------------------------ | +| id | string | Yes | Task ID. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. | + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | --------------------------- | +| 13400003 | task service ability error. | +| 21900006 | task not found error. | + +**Example** + + ```ts +request.agent.remove("123456", (err: BusinessError) => { + if (err) { + console.error(`Failed to removing a download task, Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in creating a download task.`); +}); + ``` + + +## request.agent.remove10+ + +remove(id: string): Promise<void> + +Removes a specified task of the invoker. If the task is being executed, the task is forced to stop. This API uses a promise to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| ---- | ------ | --------- | ----------- | +| id | string | Yes | Task ID. | + +**Return value** + +| Type | Description | +| ------------------- | ------------------------------ | +| Promise<void> | Promise that returns no value. | + +**Error codes** + +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | --------------------------- | +| 13400003 | task service ability error. | +| 21900006 | task not found error. | + +**Example** + + ```ts +request.agent.remove("123456").then(() => { + console.info(`Succeeded in removing a download task. `); +}).catch((err: BusinessError) => { + console.error(`Failed to remove a download task, Code: ${err.code}, message: ${err.message}`); +}); + ``` + + +## request.agent.show10+ + +show(id: string, callback: AsyncCallback<TaskInfo>): void + +Shows the task details based on the task ID. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | -------------------------------------------- | --------- | ------------------------------------- | +| id | string | Yes | Task ID. | +| callback | AsyncCallback<[TaskInfo](#taskinfo10)> | Yes | Callback used to return task details. | + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | --------------------------- | +| 13400003 | task service ability error. | +| 21900006 | task not found error. | + +**Example** + + ```ts +request.agent.show("123456", (err: BusinessError, taskInfo: request.agent.TaskInfo) => { + if (err) { + console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in showing a upload task.`); +}); + ``` + + +## request.agent.show10+ + +show(id: string): Promise<TaskInfo> + +Queries a task details based on the task ID. This API uses a promise to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| ---- | ------ | --------- | ----------- | +| id | string | Yes | Task ID. | + +**Return value** + +| Type | Description | +| -------------------------------------- | -------------------------------------------- | +| Promise<[TaskInfo](#taskinfo10)> | Promise Promise used to return task details. | + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | --------------------------- | +| 13400003 | task service ability error. | +| 21900006 | task not found error. | + +**Example** + + ```ts +request.agent.show("123456").then((taskInfo: request.agent.TaskInfo) => { + console.info(`Succeeded in showing the upload task.`); +}).catch((err: BusinessError) => { + console.error(`Failed to show the upload task. Code: ${err.code}, message: ${err.message}`); +}); + ``` + + +## request.agent.touch10+ + +touch(id: string, token: string, callback: AsyncCallback<TaskInfo>): void + +Queries the task details based on the task ID and token. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | -------------------------------------------- | --------- | ------------------------------------- | +| id | string | Yes | Task ID. | +| token | string | Yes | Token for task query. | +| callback | AsyncCallback<[TaskInfo](#taskinfo10)> | Yes | Callback used to return task details. | + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | --------------------------- | +| 13400003 | task service ability error. | +| 21900006 | task not found error. | + +**Example** + + ```ts +request.agent.touch("123456", "token", (err: BusinessError, taskInfo: request.agent.TaskInfo) => { + if (err) { + console.error(`Failed to touch an upload task. Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in touching an upload task.`); +}); + ``` + + +## request.agent.touch10+ + +touch(id: string, token: string): Promise<TaskInfo> + +Queries the task details based on the task ID and token. This API uses a promise to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----- | ------ | --------- | --------------------- | +| id | string | Yes | Task ID. | +| token | string | Yes | Token for task query. | + +**Return value** + +| Type | Description | +| -------------------------------------- | -------------------------------------------- | +| Promise<[TaskInfo](#taskinfo10)> | Promise Promise used to return task details. | + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | --------------------------- | +| 13400003 | task service ability error. | +| 21900006 | task not found error. | + +**Example** + + ```ts +request.agent.touch("123456", "token").then((taskInfo: request.agent.TaskInfo) => { + console.info(`Succeeded in touching a upload task. `); +}).catch((err: BusinessError) => { + console.error(`Failed to touch an upload task. Code: ${err.code}, message: ${err.message}`); +}); + ``` + +## request.agent.search10+ + +search(callback: AsyncCallback<Array<string>>): void + +Searches for task IDs based on [Filter](#filter10). This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | --------- | ---------------------------------------- | +| callback | AsyncCallback<Array<string>> | Yes | Callback used to return task ID matches. | + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | --------------------------- | +| 13400003 | task service ability error. | + +**Example** + + ```ts +request.agent.search((err: BusinessError, data: Array) => { + if (err) { + console.error(`Upload task search failed. Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Upload task search succeeded. `); +}); + ``` + + +## request.agent.search10+ + +search(filter?: Filter): Promise<Array<string>> + +Searches for task IDs based on [Filter](#filter10). This API uses a promise to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------ | ------------------- | --------- | ---------------- | +| filter | [Filter](#filter10) | No | Filter criteria. | + +**Return value** + +| Type | Description | +| ---------------------------------- | ----------------------------------------------- | +| Promise<Array<string>> | Promise Promise used to return task ID matches. | + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + +| ID | Error Message | +| -------- | --------------------------- | +| 13400003 | task service ability error. | + +**Example** + + ```ts +let filter: request.agent.Filter = { + bundle: "com.example.myapplication", + action: request.agent.Action.UPLOAD, + mode: request.agent.Mode.FOREGROUND +} +request.agent.search(filter).then((data: Array) => { + console.info(`Upload task search succeeded. `); +}).catch((err: BusinessError) => { + console.error(`Upload task search failed. Code: ${err.code}, message: ${err.message}`); +}); + ``` + + \ No newline at end of file -- Gitee