diff --git a/arkuix/js-apis-request.md b/arkuix/js-apis-request.md
new file mode 100644
index 0000000000000000000000000000000000000000..97d4616967b5f22078478296f38a10de9c732830
--- /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