diff --git a/en/application-dev/reference/apis/js-apis-request.md b/en/application-dev/reference/apis/js-apis-request.md index 98ff862ea6932d76bed8ba8a8de4a9b452e54a11..50c50f574bbcad706077725e3b4c6f69f3334b1c 100644 --- a/en/application-dev/reference/apis/js-apis-request.md +++ b/en/application-dev/reference/apis/js-apis-request.md @@ -1,7 +1,10 @@ # Upload and Download +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 **Example** ```js - downloadTask.on('progress', function download_callback(receivedSize, totalSize) { + downloadTask.on('progress', function download_callback(receivedSize, totalSize) { console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); } ); - }); ``` @@ -487,10 +491,10 @@ Unsubscribes from the download progress event. This API uses an asynchronous cal | Name | Type | Mandatory | Description | | -------- | -------- | -------- | -------- | -| type | string | Yes | Type of the event to unsubscribe from. The value is **progress** (download progress). | +| 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. | -Parameters of the callback function +**callback** parameters | Name | Type | Mandatory | Description | | -------- | -------- | -------- | -------- | @@ -500,11 +504,10 @@ Parameters of the callback function **Example** ```js - downloadTask .off('progress', function download_callback(receivedSize, totalSize) { - console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); - } + downloadTask .off('progress', function download_callback(receivedSize, totalSize) { + console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); + } ); - }); ``` @@ -522,17 +525,16 @@ Subscribes to a download event. This API uses an asynchronous callback to return | Name | Type | Mandatory | Description | | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type.<br/>- **complete**: download task completion event.<br/>- **pause**: download task pause event.<br/>- **remove**: download task removal event. | +| type | string | Yes | Event type.<br/>- **'complete'**: download task completion event.<br/>- **'pause'**: download task pause event.<br/>- **'remove'**: download task removal event. | | callback | function | Yes | Callback used to return the result. | **Example** ```js - downloadTask.on('complete', function callback() { - console.info('Download task completed.'); - } + downloadTask.on('complete', function callback() { + console.info('Download task completed.'); + } ); - }); ``` @@ -550,17 +552,16 @@ Unsubscribes from the download event. This API uses an asynchronous callback to | Name | Type | Mandatory | Description | | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type.<br/>- **complete**: download task completion event.<br/>- **pause**: download task pause event.<br/>- **remove**: download task removal event. | +| type | string | Yes | Event type.<br/>- **'complete'**: download task completion event.<br/>- **'pause'**: download task pause event.<br/>- **'remove'**: download task removal event. | | callback | function | No | Callback used to return the result. | **Example** ```js - downloadTask.off('complete', function callback() { - console.info('Download task completed.'); - } + downloadTask.off('complete', function callback() { + 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', function callBack(err) { - console.info('Download task failed. Cause:' + err); - } + downloadTask.on('fail', function callBack(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', function callBack(err) { - console.info('Download task failed. Cause:' + err); - } + downloadTask.off('fail', function callBack(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. |