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.
...
...
@@ -31,8 +32,9 @@ var config = {
}
```
The **cleartextTraffic** attribute is not involved during the development of applications in the stage model.
The **cleartextTraffic** attribute is not involved during application development in the stage model.
The download server must support the HTTP HEAD method so that the size of the data to download can be obtained through **content-length**. Otherwise, the download task fails. If this is the case, you can check the failure cause through [on('fail')<sup>7+</sup>)](#onfail7).
## Constants
...
...
@@ -53,6 +55,8 @@ The **cleartextTraffic** attribute is not involved during the development of app
| ERROR_INSUFFICIENT_SPACE<sup>7+</sup> | number | Yes| No| Insufficient storage space.|
| 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_OFFLINE<sup>9+</sup> | number | Yes| No| No network connection.|
| ERROR_UNSUPPORTED_NETWORK_TYPE<sup>9+</sup> | number | Yes| No| Network type mismatch.|
| 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 a WLAN connection, because the file size exceeds the maximum value allowed by a mobile network session.|
| PAUSED_UNKNOWN<sup>7+</sup> | number | Yes| No| Download paused due to unknown reasons.|
...
...
@@ -73,24 +77,26 @@ Uploads files. This API uses a promise to return the result.
This API can be used only in the FA model.
> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [request.uploadFile<sup>9+</sup>](#requestuploadfile9).
@@ -311,20 +428,21 @@ Subscribes to an upload event. This API uses an asynchronous callback to return
**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 | function | Yes| Callback used to return the result.|
| 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.|
@@ -419,20 +539,21 @@ Unsubscribes from an upload event. This API uses an asynchronous callback to ret
**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 | function | No| Callback used to return the result.|
| 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.|
| 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.|
| Type| Description|
| -------- | -------- |
| Promise<boolean> | Promise used to return the result. It returns **true** if the operation is successful and returns **false** otherwise.|
| Promise<boolean> | Promise used to return the task deletion result. It returns **true** if the operation is successful and returns **false** otherwise.|
@@ -493,13 +689,14 @@ Removes this upload task. This API uses an asynchronous callback to return the r
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.|
**Example**
```js
uploadTask.remove((err,result)=>{
letuploadTask;
uploadTask.delete((err,result)=>{
if(err){
console.error('Failed to remove the upload task. Cause: '+JSON.stringify(err));
return;
...
...
@@ -522,7 +719,7 @@ Removes this upload task. This API uses an asynchronous callback to return the r
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| url | string | Yes| Resource URL.|
| header | object | Yes| HTTP or HTTPS header added to an upload request.|
| 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.|
...
...
@@ -547,10 +744,10 @@ Removes this upload task. This API uses an asynchronous callback to return the r
| 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.<br>The **dataability** and **internal** protocol types are supported. However, the **internal** protocol type supports only temporary directories. Below are examples:<br>dataability:///com.domainname.dataability.persondata/person/10/file.txt<br><br>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 | 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.<br>The **dataability** and **internal** protocol types are supported. However, the **internal** protocol type supports only temporary directories. Below are examples:<br>dataability:///com.domainname.dataability.persondata/person/10/file.txt<br>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.|
Resumes this download task. This API uses an asynchronous callback to return the result.
...
...
@@ -1177,13 +1848,14 @@ Resumes this download task. This API uses an asynchronous callback to return the
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback<void> | Yes| Callback used to return the result.|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.|
**Example**
```js
downloadTask.resume((err,result)=>{
letdownloadTask;
downloadTask.restore((err,result)=>{
if(err){
console.error('Failed to resume the download task. Cause:'+err);
return;
...
...
@@ -1206,9 +1878,9 @@ Resumes this download task. This API uses an asynchronous callback to return the
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| url | string | Yes| Resource URL.|
| header | object | No| HTTP or HTTPS header added to a download request.|
| enableMetered | boolean | No| Whether download is allowed on a metered connection.<br>- **true**: yes<br>**false**: no|
| enableRoaming | boolean | No| Whether download is allowed on a roaming network.<br>- **true**: yes<br>**false**: no|
| header | Object | No| HTTPS flag header to be included in the download request.<br>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:<br>CURL_SSLVERSION_TLSv1_0<br>CURL_SSLVERSION_TLSv1_1<br>CURL_SSLVERSION_TLSv1_2<br>CURL_SSLVERSION_TLSv1_3<br>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:<br>- The TLS 1.2 cipher suite list includes the following ciphers:<br>TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,<br>TLS_DHE_DSS_WITH_AES_128_GCM_SHA256,TLS_DSS_RSA_WITH_AES_256_GCM_SHA384,<br>TLS_PSK_WITH_AES_256_GCM_SHA384,TLS_DHE_PSK_WITH_AES_128_GCM_SHA256,<br>TLS_DHE_PSK_WITH_AES_256_GCM_SHA384,TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256,<br>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,<br>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,<br>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256,<br>TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256,TLS_ECDHE_PSK_WITH_AES_256_GCM_SHA384,<br>TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_CCM,<br>TLS_DHE_RSA_WITH_AES_256_CCM,TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256,<br>TLS_PSK_WITH_AES_256_CCM,TLS_DHE_PSK_WITH_AES_128_CCM,<br>TLS_DHE_PSK_WITH_AES_256_CCM,TLS_ECDHE_ECDSA_WITH_AES_128_CCM,<br>TLS_ECDHE_ECDSA_WITH_AES_256_CCM,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256<br>- The TLS 1.3 cipher suite list includes the following ciphers:<br>TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_CCM_SHA256<br>- The TLS 1.3 cipher suite list adds the Chinese national cryptographic algorithm:<br>TLS_SM4_GCM_SM3,TLS_SM4_CCM_SM3 |
| enableMetered | boolean | No| Whether download is allowed on a metered connection.<br>- **true**: yes<br>-**false**: no|
| enableRoaming | boolean | No| Whether download is allowed on a roaming network.<br>- **true**: yes<br>-**false**: no|
| description | string | No| Description of the download session.|
| 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.<br>- NETWORK_MOBILE: 0x00000001<br>- NETWORK_WIFI: 0x00010000|
@@ -7,7 +7,7 @@ For details about the system parameter design principles and definitions, see
> **NOTE**
> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The APIs provided by this module are system APIs.
> - Third-party applications cannot use the APIs provided by this module, because system parameters each require specific discretionary access control (DAC) and MAC permissions.
> - Third-party applications cannot use the APIs provided by this module, because system parameters each require specific discretionary access control (DAC) and mandatory access control (MAC) permissions.
This error code is reported when the parameter does not exist in the workspace or no key has been set for the parameter.
**Possible Causes**
The parameter is not set or fails to be set.
**Solution**
Set the parameter correctly.
## 14700102 Invalid System Parameter Value
**Error Message**
System parameter value is invalid.
**Description**
This error code is reported when the value of the system parameter is invalid.
**Possible Causes**
The value of the system parameter is empty, is out of range, or contains special characters, for example, "const..param.xxx".
**Solution**
Set the value to a valid string.
## 14700103 Permission Denial for the Operation on the System Permission
**Error Message**
System permission operation permission denied.
**Description**
This error code is reported when the system parameter does not have the discretionary access control (DAC) or mandatory access control (MAC) permission.
**Possible Causes**
The DAC or MAC permission is not configured.
**Solution**
Add the DAC or MAC permission as needed.
## 14700104 Internal System Error, Including Out of Memory and Deadlock
**Error Message**
System internal error including out of memory, deadlock etc.
**Description**
This error code is reported when the attempt to modify the **const** attribute settings, the socket connection, or the memory copy fails.
**Possible Causes**
The socket connection is abnormal, or the node fails to be added or obtained.
**Solution**
1. Analyze the memory usage of the entire process and eliminate memory leak.
2. If you are in a multi-thread scenario, check the error stack for deadlock.
