diff --git a/en/application-dev/reference/apis/js-apis-request.md b/en/application-dev/reference/apis/js-apis-request.md
index 50c50f574bbcad706077725e3b4c6f69f3334b1c..b2ff6a8bc7ca45e255a57c9ebe414d12f87157e7 100644
--- a/en/application-dev/reference/apis/js-apis-request.md
+++ b/en/application-dev/reference/apis/js-apis-request.md
@@ -17,9 +17,9 @@ import request from '@ohos.request';
## Constraints
-HTTPS is supported by default. To support HTTP, you need to add **network** to the **config.json** file and set the **cleartextTraffic** attribute to **true**.
+HTTPS is supported by default in the FA model. To support HTTP, add **network** to the **config.json** file and set the **cleartextTraffic** attribute to **true**.
-```
+```js
var config = {
"deviceConfig": {
"default": {
@@ -32,6 +32,9 @@ var config = {
}
```
+The **cleartextTraffic** attribute is not involved during the development of applications in the stage model.
+
+
## Constants
@@ -39,28 +42,28 @@ var config = {
**System capability**: SystemCapability.MiscServices.Download
-| Name | Type | Readable | Writable | Description |
+| Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
-| NETWORK_MOBILE | number | Yes | No | Whether download is allowed when the cellular network is used. |
-| NETWORK_WIFI | number | Yes | No | Whether download is allowed on a WLAN. |
-| ERROR_CANNOT_RESUME7+ | number | Yes | No | Failure to resume the download due to an error. |
-| ERROR_DEVICE_NOT_FOUND7+ | number | Yes | No | Failure to find a storage device such as a memory card. |
-| ERROR_FILE_ALREADY_EXISTS7+ | number | Yes | No | Failure to download the file because it already exists. |
-| ERROR_FILE_ERROR7+ | number | Yes | No | File operation failure. |
-| ERROR_HTTP_DATA_ERROR7+ | number | Yes | No | HTTP transmission failure. |
-| ERROR_INSUFFICIENT_SPACE7+ | number | Yes | No | Insufficient storage space. |
-| ERROR_TOO_MANY_REDIRECTS7+ | number | Yes | No | Error caused by too many network redirections. |
-| ERROR_UNHANDLED_HTTP_CODE7+ | number | Yes | No | Unidentified HTTP code. |
-| ERROR_UNKNOWN7+ | number | Yes | No | Unknown error. |
-| PAUSED_QUEUED_FOR_WIFI7+ | number | Yes | No | Download paused and queuing for a WLAN connection, because the file size exceeds the maximum value allowed by a cellular network session. |
-| PAUSED_UNKNOWN7+ | number | Yes | No | Download paused due to unknown reasons. |
-| PAUSED_WAITING_FOR_NETWORK7+ | number | Yes | No | Download paused due to a network connection problem, for example, network disconnection. |
-| PAUSED_WAITING_TO_RETRY7+ | number | Yes | No | Download paused and then retried. |
-| SESSION_FAILED7+ | number | Yes | No | Download failure without retry. |
-| SESSION_PAUSED7+ | number | Yes | No | Download paused. |
-| SESSION_PENDING7+ | number | Yes | No | Download pending. |
-| SESSION_RUNNING7+ | number | Yes | No | Download in progress. |
-| SESSION_SUCCESSFUL7+ | number | Yes | No | Successful download. |
+| NETWORK_MOBILE | number | Yes| No| Whether download is allowed on a mobile network.|
+| NETWORK_WIFI | number | Yes| No| Whether download is allowed on a WLAN.|
+| ERROR_CANNOT_RESUME7+ | number | Yes| No| Failure to resume the download due to an error.|
+| ERROR_DEVICE_NOT_FOUND7+ | number | Yes| No| Failure to find a storage device such as a memory card.|
+| ERROR_FILE_ALREADY_EXISTS7+ | number | Yes| No| Failure to download the file because it already exists.|
+| ERROR_FILE_ERROR7+ | number | Yes| No| File operation failure.|
+| ERROR_HTTP_DATA_ERROR7+ | number | Yes| No| HTTP transmission failure.|
+| ERROR_INSUFFICIENT_SPACE7+ | number | Yes| No| Insufficient storage space.|
+| ERROR_TOO_MANY_REDIRECTS7+ | number | Yes| No| Error caused by too many network redirections.|
+| ERROR_UNHANDLED_HTTP_CODE7+ | number | Yes| No| Unidentified HTTP code.|
+| ERROR_UNKNOWN7+ | number | Yes| No| Unknown error.|
+| PAUSED_QUEUED_FOR_WIFI7+ | number | Yes| No| Download paused and queuing for a WLAN connection, because the file size exceeds the maximum value allowed by a mobile network session.|
+| PAUSED_UNKNOWN7+ | number | Yes| No| Download paused due to unknown reasons.|
+| PAUSED_WAITING_FOR_NETWORK7+ | number | Yes| No| Download paused due to a network connection problem, for example, network disconnection.|
+| PAUSED_WAITING_TO_RETRY7+ | number | Yes| No| Download paused and then retried.|
+| SESSION_FAILED7+ | number | Yes| No| Download failure without retry.|
+| SESSION_PAUSED7+ | number | Yes| No| Download paused.|
+| SESSION_PENDING7+ | number | Yes| No| Download pending.|
+| SESSION_RUNNING7+ | number | Yes| No| Download in progress.|
+| SESSION_SUCCESSFUL7+ | number | Yes| No| Successful download.|
## request.upload
@@ -69,30 +72,36 @@ upload(config: UploadConfig): Promise<UploadTask>
Uploads files. This API uses a promise to return the result.
+This API can be used only in the FA model.
+
**Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| config | [UploadConfig](#uploadconfig) | Yes | Configurations of the upload. |
+| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.|
**Return value**
-| Type | Description |
+| Type| Description|
| -------- | -------- |
-| Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object. |
+| Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object.|
**Example**
```js
- let file1 = { filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" };
- let data = { name: "name123", value: "123" };
- let header = { key1: "value1", key2: "value2" };
let uploadTask;
- request.upload({ url: 'https://patch', header: header, method: "POST", files: [file1], data: [data] }).then((data) => {
+ let uploadConfig = {
+ url: 'https://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" }],
+ };
+ request.upload(uploadConfig).then((data) => {
uploadTask = data;
}).catch((err) => {
console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
@@ -106,25 +115,31 @@ upload(config: UploadConfig, callback: AsyncCallback<UploadTask>): void
Uploads files. This API uses an asynchronous callback to return the result.
+This API can be used only in the FA model.
+
**Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Upload
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| config | [UploadConfig](#uploadconfig) | Yes | Configurations of the upload. |
-| callback | AsyncCallback<[UploadTask](#uploadtask)> | No | Callback used to return the **UploadTask** object. |
+| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.|
+| callback | AsyncCallback<[UploadTask](#uploadtask)> | No| Callback used to return the **UploadTask** object.|
**Example**
```js
- let file1 = { filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" };
- let data = { name: "name123", value: "123" };
- let header = { key1: "value1", key2: "value2" };
let uploadTask;
- request.upload({ url: 'https://patch', header: header, method: "POST", files: [file1], data: [data] }, (err, data) => {
+ let uploadConfig = {
+ url: 'https://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" }],
+ };
+ request.upload(uploadConfig, (err, data) => {
if (err) {
console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
return;
@@ -132,8 +147,87 @@ Uploads files. This API uses an asynchronous callback to return the result.
uploadTask = data;
});
```
+## request.upload9+
+
+upload(context: BaseContext, config: UploadConfig): Promise<UploadTask>
+
+Uploads files. This API uses a promise to return the result.
+
+**Required permissions**: ohos.permission.INTERNET
+
+**System capability**: SystemCapability.MiscServices.Upload
+
+**Parameters**
+
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| context | BaseContext | Yes| Application-based context.|
+| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.|
+
+
+**Return value**
+
+| Type| Description|
+| -------- | -------- |
+| Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object.|
+
+**Example**
+
+ ```js
+ let uploadTask;
+ let uploadConfig = {
+ url: 'https://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" },
+ };
+ request.upload(globalThis.abilityContext, uploadConfig).then((data) => {
+ uploadTask = data;
+ }).catch((err) => {
+ console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
+ });
+ ```
+## request.upload9+
+
+upload(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void
+
+Uploads files. 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|
+| -------- | -------- | -------- | -------- |
+| context | BaseContext | Yes| Application-based context.|
+| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.|
+| callback | AsyncCallback<[UploadTask](#uploadtask)> | No| Callback used to return the **UploadTask** object.|
+
+**Example**
+
+ ```js
+ let uploadTask;
+ let uploadConfig = {
+ url: 'https://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" }],
+ };
+ request.upload(globalThis.abilityContext, uploadConfig, (err, data) => {
+ if (err) {
+ console.error('Failed to request the upload. Cause: ' + JSON.stringify(err));
+ return;
+ }
+ uploadTask = data;
+ });
+ ```
+
## UploadTask
Implements file uploads. Before using any APIs of this class, you must obtain an **UploadTask** object.
@@ -143,7 +237,7 @@ Implements file uploads. Before using any APIs of this class, you must obtain an
on(type: 'progress', callback:(uploadedSize: number, totalSize: number) => void): void
-Subscribes to the upload progress event. This API uses an asynchronous callback to return the result.
+Subscribes to an upload event. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET
@@ -151,17 +245,17 @@ Subscribes to the upload progress event. This API uses an asynchronous callback
**Parameters**
-| Name | Type | Mandatory | Description |
+| 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. |
+| 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.|
-**callback** parameters
+Parameters of the callback function
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| uploadedSize | number | Yes | Size of the uploaded files, in KB. |
-| totalSize | number | Yes | Total size of the files to upload, in KB. |
+| uploadedSize | number | Yes| Size of the uploaded files, in KB.|
+| totalSize | number | Yes| Total size of the files to upload, in KB.|
**Example**
@@ -177,7 +271,7 @@ Subscribes to the upload progress event. This API uses an asynchronous callback
on(type: 'headerReceive', callback: (header: object) => void): void
-Subscribes to the **headerReceive** event, which is triggered when an HTTP response header is received. This API uses an asynchronous callback to return the result.
+Subscribes to an upload event. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET
@@ -185,16 +279,16 @@ Subscribes to the **headerReceive** event, which is triggered when an HTTP respo
**Parameters**
-| Name | Type | Mandatory | Description |
+| 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. |
+| 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.|
-**callback** parameters
+Parameters of the callback function
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| header | object | Yes | HTTP Response Header. |
+| header | object | Yes| HTTP Response Header.|
**Example**
@@ -210,7 +304,7 @@ Subscribes to the **headerReceive** event, which is triggered when an HTTP respo
off(type: 'progress', callback?: (uploadedSize: number, totalSize: number) => void): void
-Unsubscribes from the upload progress event. This API uses an asynchronous callback to return the result.
+Unsubscribes from an upload event. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET
@@ -218,17 +312,17 @@ Unsubscribes from the upload progress event. This API uses an asynchronous callb
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| type | string | Yes | Type of the event to unsubscribe from. The value is **'progress'** (upload progress). |
-| callback | function | No | Callback for the upload progress event. |
+| type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (upload progress).|
+| callback | function | No| Callback for the upload progress event.|
-**callback** parameters
+Parameters of the callback function
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| uploadedSize | number | Yes | Size of the uploaded files, in KB. |
-| totalSize | number | Yes | Total size of the files to upload, in KB. |
+| uploadedSize | number | Yes| Size of the uploaded files, in KB.|
+| totalSize | number | Yes| Total size of the files to upload, in KB.|
**Example**
@@ -244,7 +338,7 @@ Unsubscribes from the upload progress event. This API uses an asynchronous callb
off(type: 'headerReceive', callback?: (header: object) => void): void
-Unsubscribes from the **headerReceive** event. This API uses an asynchronous callback to return the result.
+Unsubscribes from an upload event. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET
@@ -252,16 +346,16 @@ Unsubscribes from the **headerReceive** event. This API uses an asynchronous cal
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| type | string | Yes | Type of the event to unsubscribe from. The value is **'headerReceive'** (response header). |
-| callback | function | No | Callback for the HTTP Response Header event. |
+| type | string | Yes| Type of the event to unsubscribe from. The value is **'headerReceive'** (response header).|
+| callback | function | No| Callback for the HTTP Response Header event.|
-**callback** parameters
+Parameters of the callback function
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| header | object | Yes | HTTP Response Header. |
+| header | object | Yes| HTTP Response Header.|
**Example**
@@ -277,7 +371,7 @@ Unsubscribes from the **headerReceive** event. This API uses an asynchronous cal
remove(): Promise<boolean>
-Removes this upload task. This API uses a promise to return the result.
+Removes this upload task. This API uses a promise to return the result.
**Required permissions**: ohos.permission.INTERNET
@@ -285,9 +379,9 @@ Removes this upload task. This API uses a promise to return the result.
**Return value**
-| Type | Description |
+| Type| Description|
| -------- | -------- |
-| Promise<boolean> | Promise used to return the task removal result. If **true** is returned, the task is removed. If **false** is returned, the task fails to be removed. |
+| Promise<boolean> | Promise used to return the task removal result. If **true** is returned, the task is removed. If **false** is returned, the task fails to be removed.|
**Example**
@@ -308,7 +402,7 @@ Removes this upload task. This API uses a promise to return the result.
remove(callback: AsyncCallback<boolean>): void
-Removes this upload task. This API uses an asynchronous callback to return the result.
+Removes this upload task. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET
@@ -316,9 +410,9 @@ Removes this upload task. This API uses an asynchronous callback to return the r
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. |
+| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.|
**Example**
@@ -339,37 +433,42 @@ Removes this upload task. This API uses an asynchronous callback to return the r
## UploadConfig
+**Required permissions**: ohos.permission.INTERNET
+
**System capability**: SystemCapability.MiscServices.Upload
-| Name | Type | Mandatory | Description |
+| 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. |
+| 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.|
## File
-**System capability**: SystemCapability.MiscServices.Upload
+**Required permissions**: ohos.permission.INTERNET
-| Name | Type | Mandatory | Description |
+**System capability**: SystemCapability.MiscServices.Download
+
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| filename | string | No | File name in the header when **multipart** is used. |
-| name | string | No | Name of a form item when **multipart** is used. The default value is **file**. |
-| uri | string | Yes | Local path for storing files.
The **dataability** and **internal** protocol types are supported. However, the **internal** protocol type supports only temporary directories. Below are examples:
dataability:///com.domainname.dataability.persondata/person/10/file.txt
internal://cache/path/to/file.txt |
-| type | string | No | Type of the file content. By default, the type is obtained based on the extension of the file name or URI. |
+| filename | string | No| File name in the header when **multipart** is used.|
+| name | string | No| Name of a form item when **multipart** is used. The default value is **file**.|
+| uri | string | Yes| Local path for storing files.
The **dataability** and **internal** protocol types are supported. However, the **internal** protocol type supports only temporary directories. Below are examples:
dataability:///com.domainname.dataability.persondata/person/10/file.txt
internal://cache/path/to/file.txt |
+| type | string | No| Type of the file content. By default, the type is obtained based on the extension of the file name or URI.|
## RequestData
-**System capability**: SystemCapability.MiscServices.Upload
+**Required permissions**: ohos.permission.INTERNET
-| Name | Type | Mandatory | Description |
+**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. |
+| name | string | Yes| Name of a form element.|
+| value | string | Yes| Value of a form element.|
## request.download
@@ -378,21 +477,23 @@ download(config: DownloadConfig): Promise<DownloadTask>
Downloads files. This API uses a promise to return the result.
+This API can be used only in the FA model.
+
**Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| config | [DownloadConfig](#downloadconfig) | Yes | Configurations of the download. |
+| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.|
**Return value**
-| Type | Description |
+| Type| Description|
| -------- | -------- |
-| Promise<[DownloadTask](#downloadtask)> | Promise used to return the result. |
+| Promise<[DownloadTask](#downloadtask)> | Promise used to return the result.|
**Example**
@@ -412,16 +513,18 @@ download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): v
Downloads files. This API uses an asynchronous callback to return the result.
+This API can be used only in the FA model.
+
**Required permissions**: ohos.permission.INTERNET
**System capability**: SystemCapability.MiscServices.Download
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| config | [DownloadConfig](#downloadconfig) | Yes | Configurations of the download. |
-| callback | AsyncCallback<[DownloadTask](#downloadtask)> | No | Callback used to return the result. |
+| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.|
+| callback | AsyncCallback<[DownloadTask](#downloadtask)> | No| Callback used to return the result.|
**Example**
@@ -437,7 +540,72 @@ Downloads files. This API uses an asynchronous callback to return the result.
});
```
+## request.download9+
+
+download(context: BaseContext, config: DownloadConfig): Promise<DownloadTask>
+
+Downloads files. This API uses a promise to return the result.
+
+**Required permissions**: ohos.permission.INTERNET
+
+**System capability**: SystemCapability.MiscServices.Download
+
+**Parameters**
+
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| context | BaseContext | Yes| Application-based context.|
+| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.|
+
+**Return value**
+
+| Type| Description|
+| -------- | -------- |
+| Promise<[DownloadTask](#downloadtask)> | Promise used to return the result.|
+
+**Example**
+
+ ```js
+ let downloadTask;
+ request.download(globalThis.abilityContext, { url: 'https://xxxx/xxxx.hap' }).then((data) => {
+ downloadTask = data;
+ }).catch((err) => {
+ console.error('Failed to request the download. Cause: ' + JSON.stringify(err));
+ })
+ ```
+
+
+## request.download9+
+download(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void;
+
+Downloads files. 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|
+| -------- | -------- | -------- | -------- |
+| context | BaseContext | Yes| Application-based context.|
+| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.|
+| callback | AsyncCallback<[DownloadTask](#downloadtask)> | No| Callback used to return the result.|
+
+**Example**
+
+ ```js
+ let downloadTask;
+ request.download(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;
+ });
+ ```
## DownloadTask
Implements file downloads.
@@ -447,7 +615,7 @@ Implements file downloads.
on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void
-Subscribes to the download progress event. This API uses an asynchronous callback to return the result.
+Subscribes to a download event. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET
@@ -455,17 +623,17 @@ Subscribes to the download progress event. This API uses an asynchronous callbac
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| type | string | Yes | Type of the event to subscribe to. The value is **'progress'** (download progress). |
-| callback | function | Yes | Callback for the download progress event. |
+| type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (download progress).|
+| callback | function | Yes| Callback for the download progress event.|
-**callback** parameters
+Parameters of the callback function
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| receivedSize | number | Yes | Size of the downloaded files, in KB. |
-| totalSize | number | Yes | Total size of the files to download, in KB. |
+| receivedSize | number | Yes| Size of the downloaded files, in KB.|
+| totalSize | number | Yes| Total size of the files to download, in KB.|
**Example**
@@ -481,7 +649,7 @@ Subscribes to the download progress event. This API uses an asynchronous callbac
off(type: 'progress', callback?: (receivedSize: number, totalSize: number) => void): void
-Unsubscribes from the download progress event. This API uses an asynchronous callback to return the result.
+Unsubscribes from a download event. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET
@@ -489,17 +657,17 @@ Unsubscribes from the download progress event. This API uses an asynchronous cal
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| type | string | Yes | Type of the event to unsubscribe from. The value is **'progress'** (download progress). |
-| callback | function | No | Callback for the download progress event. |
+| type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (download progress).|
+| callback | function | No| Callback for the download progress event.|
-**callback** parameters
+Parameters of the callback function
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| receivedSize | number | Yes | Size of the downloaded files, in KB. |
-| totalSize | number | Yes | Total size of the files to download, in KB. |
+| receivedSize | number | Yes| Size of the downloaded files.|
+| totalSize | number | Yes| Total size of the files to download.|
**Example**
@@ -523,10 +691,10 @@ Subscribes to a download event. This API uses an asynchronous callback to return
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| type | string | Yes | Event type.
- **'complete'**: download task completion event.
- **'pause'**: download task pause event.
- **'remove'**: download task removal event. |
-| callback | function | Yes | Callback used to return the result. |
+| 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**
@@ -542,7 +710,7 @@ Subscribes to a download event. This API uses an asynchronous callback to return
off(type: 'complete'|'pause'|'remove', callback?:() => void): void
-Unsubscribes from the download event. This API uses an asynchronous callback to return the result.
+Unsubscribes from a download event. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET
@@ -550,10 +718,10 @@ Unsubscribes from the download event. This API uses an asynchronous callback to
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| type | string | Yes | Event type.
- **'complete'**: download task completion event.
- **'pause'**: download task pause event.
- **'remove'**: download task removal event. |
-| callback | function | No | Callback used to return the result. |
+| 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**
@@ -577,16 +745,16 @@ Subscribes to the download task failure event. This API uses an asynchronous cal
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| type | string | Yes | Type of the subscribed event. The value is **'fail'** (download failure). |
-| callback | function | Yes | Callback for the download task failure event. |
+| 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.|
-**callback** parameters
+Parameters of the callback function
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| err | number | Yes | Error code of the download failure. For details about the error cause, see [ERROR_*](#constants). |
+| err | number | Yes| Error code of the download failure. For details about the error codes, see [ERROR_*](#constants).|
**Example**
@@ -602,7 +770,7 @@ Subscribes to the download task failure event. This API uses an asynchronous cal
off(type: 'fail', callback?: (err: number) => void): void
-Unsubscribes from the download task failure event. This API uses an asynchronous callback to return the result.
+Unsubscribes from the download task failure event. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET
@@ -610,16 +778,16 @@ Unsubscribes from the download task failure event. This API uses an asynchronous
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| type | string | Yes | Type of the event to unsubscribe from. The value is **'fail'** (download failure). |
-| callback | function | No | Callback for the download task failure event. |
+| type | string | Yes| Type of the event to unsubscribe from. The value is **'fail'** (download failure).|
+| callback | function | No| Callback for the download task failure event.|
-**callback** parameters
+Parameters of the callback function
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| err | number | Yes | Error code of the download failure. For details about the error cause, see [ERROR_*](#constants). |
+| err | number | Yes| Error code of the download failure. For details about the error codes, see [ERROR_*](#constants).|
**Example**
@@ -643,9 +811,9 @@ Removes this download task. This API uses a promise to return the result.
**Return value**
-| Type | Description |
+| Type| Description|
| -------- | -------- |
-| Promise<boolean> | Promise used to return the task removal result. |
+| Promise<boolean> | Promise used to return the task removal result.|
**Example**
@@ -674,9 +842,9 @@ Removes this download task. This API uses an asynchronous callback to return the
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| callback | AsyncCallback<boolean> | Yes | Callback used to return the task removal result. |
+| callback | AsyncCallback<boolean> | Yes| Callback used to return the task removal result.|
**Example**
@@ -706,10 +874,9 @@ Queries this download task. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Download
**Parameters**
-
-| Type | Description |
-| -------- | -------- |
-| Promise<[DownloadInfo](#downloadinfo7)> | Promise used to return the download task information. |
+ | Type| Description|
+ | -------- | -------- |
+ | Promise<[DownloadInfo](#downloadinfo7)> | Promise used to return the download task information.|
**Example**
@@ -734,9 +901,9 @@ Queries this download task. This API uses an asynchronous callback to return the
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | Yes | Callback used to return the download task information. |
+| callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | Yes| Callback used to return the download task information.|
**Example**
@@ -755,7 +922,7 @@ Queries this download task. This API uses an asynchronous callback to return the
queryMimeType(): Promise<string>
-Queries **MimeType** of this download task. This API uses a promise to return the result.
+Queries the **MimeType** of this download task. This API uses a promise to return the result.
**Required permissions**: ohos.permission.INTERNET
@@ -763,9 +930,9 @@ Queries **MimeType** of this download task. This API uses a promise to return th
**Return value**
-| Type | Description |
+| Type| Description|
| -------- | -------- |
-| Promise<string> | Promise used to return **MimeType** of the download task. |
+| Promise<string> | Promise used to return the **MimeType** of the download task.|
**Example**
@@ -782,7 +949,7 @@ Queries **MimeType** of this download task. This API uses a promise to return th
queryMimeType(callback: AsyncCallback<string>): void;
-Queries **MimeType** of this download task. This API uses an asynchronous callback to return the result.
+Queries the **MimeType** of this download task. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.INTERNET
@@ -790,9 +957,9 @@ Queries **MimeType** of this download task. This API uses an asynchronous callba
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| callback | AsyncCallback<string> | Yes | Callback used to return **MimeType** of the download task. |
+| callback | AsyncCallback<string> | Yes| Callback used to return the **MimeType** of the download task.|
**Example**
@@ -819,9 +986,9 @@ Pauses this download task. This API uses a promise to return the result.
**Return value**
-| Type | Description |
+| Type| Description|
| -------- | -------- |
-| Promise<void> | Promise used to return the download task pause result. |
+| Promise<void> | Promise used to return the download task pause result.|
**Example**
@@ -850,9 +1017,9 @@ Pauses this download task. This API uses an asynchronous callback to return the
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
+| callback | AsyncCallback<void> | Yes| Callback used to return the result.|
**Example**
@@ -883,9 +1050,9 @@ Resumes this download task. This API uses a promise to return the result.
**Parameters**
-| Type | Description |
+| Type| Description|
| -------- | -------- |
-| Promise<void> | Promise used to return the result. |
+| Promise<void> | Promise used to return the result.|
**Example**
@@ -915,9 +1082,9 @@ Resumes this download task. This API uses an asynchronous callback to return the
**Parameters**
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
+| callback | AsyncCallback<void> | Yes| Callback used to return the result.|
**Example**
@@ -938,34 +1105,39 @@ Resumes this download task. This API uses an asynchronous callback to return the
## DownloadConfig
+**Required permissions**: ohos.permission.INTERNET
+
**System capability**: SystemCapability.MiscServices.Download
-| Name | Type | Mandatory | Description |
+| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
-| url | string | Yes | Resource URL. |
-| header | object | No | HTTP or HTTPS header added to a download request. |
-| enableMetered | boolean | No | Download allowed in metered connections. |
-| enableRoaming | boolean | No | Download allowed on a roaming network. |
-| description | string | No | Description of the download session. |
-| filePath7+ | string | No | Download path. (The default path is **'internal://cache/'**.
- filePath:'workspace/test.txt': The **workspace** directory is created in the default path to store files.
- filePath:'test.txt': Files are stored in the default path.
- filePath:'workspace/': The **workspace** directory is created in the default path to store files. |
-| networkType | number | No | Network type allowed for download. |
-| title | string | No | Title of the download session. |
+| url | string | Yes| Resource URL.|
+| header | object | No| HTTP or HTTPS header added to a download request.|
+| enableMetered | boolean | No| Download allowed in metered connections.|
+| enableRoaming | boolean | No| Download allowed on a roaming network.|
+| description | string | No| Description of the download session.|
+| filePath7+ | string | No| Download path. (The default path is **'internal://cache/'**.)
- filePath:'workspace/test.txt': The **workspace** directory is created in the default path to store files.
- filePath:'test.txt': Files are stored in the default path.
- filePath:'workspace/': The **workspace** directory is created in the default path to store files.|
+| networkType | number | No| Network type allowed for download.|
+| title | string | No| Title of the download session.|
+| background | boolean | No| Whether to enable the background task notification. When this parameter is enabled, the download status is displayed in the notification panel.|
## DownloadInfo7+
+**Required permissions**: ohos.permission.INTERNET
+
**System capability**: SystemCapability.MiscServices.Download
-| Name | Type | Mandatory | Description |
-| -------- | -------- | -------- | -------- |
-| downloadId | number | Yes | ID of the downloaded file. |
-| failedReason | number | No | Download failure cause, which can be any constant of [ERROR_*](#constants). |
-| fileName | string | Yes | Name of the downloaded file. |
-| filePath | string | Yes | URI of the saved file. |
-| pausedReason | number | No | Reason for session pause, which can be any constant of [PAUSED_*](#constants). |
-| status | number | Yes | Download status code, which can be any constant of [SESSION_*](#constants). |
-| targetURI | string | Yes | URI of the downloaded file. |
-| downloadTitle | string | Yes | Title of the downloaded file. |
-| downloadTotalBytes | number | Yes | Total size of the downloaded file (int bytes). |
-| description | string | Yes | Description of the file to download. |
-| downloadedBytes | number | Yes | Size of the files downloaded (int bytes). |
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| downloadId | number | Yes| ID of the downloaded file.|
+| failedReason | number | No| Download failure cause, which can be any constant of [ERROR_*](#constants).|
+| fileName | string | Yes| Name of the downloaded file.|
+| filePath | string | Yes| URI of the saved file.|
+| pausedReason | number | No| Reason for session pause, which can be any constant of [PAUSED_*](#constants).|
+| status | number | Yes| Download status code, which can be any constant of [SESSION_*](#constants).|
+| targetURI | string | Yes| URI of the downloaded file.|
+| downloadTitle | string | Yes| Title of the downloaded file.|
+| downloadTotalBytes | number | Yes| Total size of the files to download (int bytes).|
+| description | string | Yes| Description of the file to download.|
+| downloadedBytes | number | Yes| Size of the files downloaded (int bytes).|