The **request** module provides applications with basic upload, download, and background transmission agent capabilities.
> **NOTE**<br>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.
> **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
...
...
@@ -17,14 +20,16 @@ import request from '@ohos.request';
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**.
```
var config = {
"deviceConfig": {
"default": {
"network": {
"cleartextTraffic": true
}
...
//...
}
}
}
```
...
...
@@ -37,9 +42,9 @@ HTTPS is supported by default. To support HTTP, you need to add **network** to t
| 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 when the WLAN is used. |
| NETWORK_WIFI | number | Yes | No | Whether download is allowed on a WLAN. |
| ERROR_CANNOT_RESUME<sup>7+</sup> | number | Yes | No | Failure to resume the download due to an error. |
| ERROR_DEVICE_NOT_FOUND<sup>7+</sup> | number | Yes | No | Failure to find a storage device such as an SD card. |
| ERROR_DEVICE_NOT_FOUND<sup>7+</sup> | number | Yes | No | Failure to find a storage device such as a memory card. |
| ERROR_FILE_ALREADY_EXISTS<sup>7+</sup> | number | Yes | No | Failure to download the file because it already exists. |
| ERROR_FILE_ERROR<sup>7+</sup> | number | Yes | No | File operation failure. |
| ERROR_HTTP_DATA_ERROR<sup>7+</sup> | number | Yes | No | HTTP transmission failure. |
...
...
@@ -47,7 +52,7 @@ HTTPS is supported by default. To support HTTP, you need to add **network** to t
| ERROR_TOO_MANY_REDIRECTS<sup>7+</sup> | number | Yes | No | Error caused by too many network redirections. |
| ERROR_UNHANDLED_HTTP_CODE<sup>7+</sup> | number | Yes | No | Unidentified HTTP code. |
| ERROR_UNKNOWN<sup>7+</sup> | number | Yes | No | Unknown error. |
| PAUSED_QUEUED_FOR_WIFI<sup>7+</sup> | number | Yes | No | Download paused and queuing for WLAN connection, because the file size exceeds the maximum value allowed by a cellular network session. |
| PAUSED_QUEUED_FOR_WIFI<sup>7+</sup> | 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_UNKNOWN<sup>7+</sup> | number | Yes | No | Download paused due to unknown reasons. |
| PAUSED_WAITING_FOR_NETWORK<sup>7+</sup> | number | Yes | No | Download paused due to a network connection problem, for example, network disconnection. |
| PAUSED_WAITING_TO_RETRY<sup>7+</sup> | number | Yes | No | Download paused and then retried. |
...
...
@@ -151,7 +156,7 @@ Subscribes to the upload progress event. This API uses an asynchronous callback
| 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
**callback** parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
...
...
@@ -182,10 +187,10 @@ Subscribes to the **headerReceive** event, which is triggered when an HTTP respo
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to subscribe to. The value is **headerReceive** (response header). |
| 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
**callback** parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
...
...
@@ -215,10 +220,10 @@ Unsubscribes from the upload progress event. This API uses an asynchronous callb
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to unsubscribe from. The value is **progress** (upload progress). |
| 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. |
Parameters of the callback function
**callback** parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
...
...
@@ -249,10 +254,10 @@ Unsubscribes from the **headerReceive** event. This API uses an asynchronous cal
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to unsubscribe from. The value is **headerReceive** (response header). |
| 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. |
Parameters of the callback function
**callback** parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
...
...
@@ -340,7 +345,7 @@ Removes this upload task. This API uses an asynchronous callback to return the r
| -------- | -------- | -------- | -------- |
| url | string | Yes | Resource URL. |
| header | object | Yes | HTTP or HTTPS header added to an upload request. |
| method | string | Yes | Request methods available: **POST** and**PUT**. The default value is **POST**. |
| 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. |
...
...
@@ -452,10 +457,10 @@ Subscribes to the download progress event. This API uses an asynchronous callbac
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to subscribe to. The value is **progress** (download progress). |
| 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. |
Parameters of the callback function
**callback** parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
...
...
@@ -465,11 +470,10 @@ Parameters of the callback function
| callback | function | No | Callback used to return the result. |
**Example**
```js
downloadTask.off('complete',functioncallback(){
console.info('Download task completed.');
}
downloadTask.off('complete',functioncallback(){
console.info('Download task completed.');
}
);
});
```
...
...
@@ -578,10 +579,10 @@ Subscribes to the download task failure event. This API uses an asynchronous cal
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the subscribed event. The value is **fail** (download failure). |
| type | string | Yes | Type of the subscribed event. The value is **'fail'** (download failure). |
| callback | function | Yes | Callback for the download task failure event. |
Parameters of the callback function
**callback** parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
...
...
@@ -590,11 +591,10 @@ Parameters of the callback function
**Example**
```js
downloadTask.on('fail',functioncallBack(err){
console.info('Download task failed. Cause:'+err);
}
downloadTask.on('fail',functioncallBack(err){
console.info('Download task failed. Cause:'+err);
}
);
});
```
...
...
@@ -612,10 +612,10 @@ Unsubscribes from the download task failure event. This API uses an asynchronous
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| type | string | Yes | Type of the event to unsubscribe from. The value is **fail** (download failure). |
| 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. |
Parameters of the callback function
**callback** parameters
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
...
...
@@ -624,11 +624,10 @@ Parameters of the callback function
**Example**
```js
downloadTask.off('fail',functioncallBack(err){
console.info('Download task failed. Cause:'+err);
}
downloadTask.off('fail',functioncallBack(err){
console.info('Download task failed. Cause:'+err);
}
);
});
```
...
...
@@ -948,7 +947,7 @@ Resumes this download task. This API uses an asynchronous callback to return the
| 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. |
| filePath<sup>7+</sup> | string | No | Download path. (The default path is [ERROR:Invalid link:en-us_topic_0000001135742582.xml#xref8132147102215,link:en-us_topic_0000001127125012.xml#section1856519365229](en-us_topic_0000001127125012.xml#section1856519365229)).<br/>- filePath:'workspace/test.txt': The **workspace** directory is created in the default path to store files.<br/>- filePath:'test.txt': Files are stored in the default path.<br/>- filePath:'workspace/': The **workspace** directory is created in the default path to store files. |
| filePath<sup>7+</sup> | string | No | Download path. (The default path is **'internal://cache/'**.<br/>- filePath:'workspace/test.txt': The **workspace** directory is created in the default path to store files.<br/>- filePath:'test.txt': Files are stored in the default path.<br/>- 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. |