diff --git a/en/application-dev/reference/apis/js-apis-request.md b/en/application-dev/reference/apis/js-apis-request.md index 45f0882a2cf0c151f04528c9e45271bf22ea1656..65e8c2708c98748ba55a734e8095228233d90b9a 100644 --- a/en/application-dev/reference/apis/js-apis-request.md +++ b/en/application-dev/reference/apis/js-apis-request.md @@ -3,6 +3,7 @@ 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')7+)](#onfail7). ## Constants @@ -53,6 +55,8 @@ The **cleartextTraffic** attribute is not involved during the development of app | 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_OFFLINE9+ | number | Yes| No| No network connection.| +| ERROR_UNSUPPORTED_NETWORK_TYPE9+ | number | Yes| No| Network type mismatch.| | 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.| @@ -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**
This API is deprecated since API version 9. You are advised to use [request.uploadFile9+](#requestuploadfile9). + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Upload **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| **Return value** -| Type| Description| -| -------- | -------- | -| Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object.| + | Type| Description| + | -------- | -------- | + | Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object.| **Example** - + ```js let uploadTask; let uploadConfig = { @@ -116,19 +122,23 @@ Uploads files. This API uses an asynchronous callback to return the result. This API can be used only in the FA model. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [request.uploadFile9+](#requestuploadfile9-1). + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Upload **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| -| callback | AsyncCallback<[UploadTask](#uploadtask)> | No| Callback used to return the **UploadTask** object.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| + | callback | AsyncCallback<[UploadTask](#uploadtask)> | Yes| Callback used to return the **UploadTask** object.| **Example** - + ```js let uploadTask; let uploadConfig = { @@ -152,6 +162,96 @@ upload(context: BaseContext, config: UploadConfig): Promise<UploadTask> Uploads files. This API uses a promise to return the result. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [request.uploadFile9+](#requestuploadfile9). + +**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. + +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [request.uploadFile9+](#requestuploadfile9-1). + +**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)> | Yes| 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; + }); + ``` + + +## request.uploadFile9+ + +uploadFile(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 @@ -159,7 +259,7 @@ Uploads files. This API uses a promise to return the result. **Parameters** | Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | + | -------- | -------- | -------- | -------- | | context | BaseContext | Yes| Application-based context.| | config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| @@ -167,9 +267,16 @@ Uploads files. This API uses a promise to return the result. **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 @@ -178,10 +285,10 @@ Uploads files. This API uses a promise to return the result. 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" }, + files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], + data: [{ name: "name123", value: "123" }], }; - request.upload(globalThis.abilityContext, uploadConfig).then((data) => { + request.uploadFile(globalThis.abilityContext, uploadConfig).then((data) => { uploadTask = data; }).catch((err) => { console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); @@ -189,9 +296,9 @@ Uploads files. This API uses a promise to return the result. ``` -## request.upload9+ +## request.uploadFile9+ -upload(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void +uploadFile(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void Uploads files. This API uses an asynchronous callback to return the result. @@ -202,10 +309,17 @@ Uploads files. This API uses an asynchronous callback to return the result. **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.| +| 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** @@ -218,7 +332,7 @@ Uploads files. This API uses an asynchronous callback to return the result. files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], data: [{ name: "name123", value: "123" }], }; - request.upload(globalThis.abilityContext, uploadConfig, (err, data) => { + request.uploadFile(globalThis.abilityContext, uploadConfig, (err, data) => { if (err) { console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); return; @@ -227,6 +341,7 @@ Uploads files. This API uses an asynchronous callback to return the result. }); ``` + ## UploadTask Implements file uploads. Before using any APIs of this class, you must obtain an **UploadTask** object. @@ -244,12 +359,12 @@ 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 is **'progress'** (upload progress).| -| callback | function | Yes| Callback for the upload progress event.| + | 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 + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | @@ -257,8 +372,9 @@ Parameters of the callback function | totalSize | number | Yes| Total size of the files to upload, in KB.| **Example** - + ```js + let uploadTask; uploadTask.on('progress', function callback(uploadedSize, totalSize) { console.info("upload totalSize:" + totalSize + " uploadedSize:" + uploadedSize); } @@ -278,20 +394,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 is **'headerReceive'** (response header).| -| callback | function | Yes| Callback for the HTTP Response Header event.| + | 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 + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | header | object | Yes| HTTP Response Header.| **Example** - + ```js + let uploadTask; uploadTask.on('headerReceive', function callback(headers){ console.info("upOnHeader headers:" + JSON.stringify(headers)); } @@ -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.| -Parameters of the callback function + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | taskstates | Array<[TaskState](#taskstate9)> | Yes| Upload result.| **Example** - + ```js + let uploadTask; uploadTask.on('complete', function callback(taskStates) { for (let i = 0; i < taskStates.length; i++ ) { console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i])); @@ -353,12 +471,12 @@ 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 unsubscribe from. The value is **'progress'** (upload progress).| -| callback | function | No| Callback for the upload progress event.| + | 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.| -Parameters of the callback function + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | @@ -366,8 +484,9 @@ Parameters of the callback function | totalSize | number | Yes| Total size of the files to upload, in KB.| **Example** - + ```js + let uploadTask; uploadTask.off('progress', function callback(uploadedSize, totalSize) { console.info('uploadedSize: ' + uploadedSize, 'totalSize: ' + totalSize); } @@ -387,20 +506,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 unsubscribe from. The value is **'headerReceive'** (response header).| -| callback | function | No| Callback for the HTTP Response Header event.| + | 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.| -Parameters of the callback function + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | header | object | Yes| HTTP Response Header.| **Example** - + ```js + let uploadTask; uploadTask.off('headerReceive', function callback(headers) { console.info("upOnHeader headers:" + JSON.stringify(headers)); } @@ -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.| -Parameters of the callback function + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | taskstates | Array<[TaskState](#taskstate9)> | Yes| Upload result.| **Example** - + ```js + let uploadTask; uploadTask.off('complete', function callback(taskStates) { for (let i = 0; i < taskStates.length; i++ ) { console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i])); @@ -455,19 +576,24 @@ remove(): Promise<boolean> Removes this upload task. This API uses a promise to return the result. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [delete9+](#delete9). + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Upload **Return value** -| 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.| + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Promise used to return the result. It returns **true** if the operation is successful and returns **false** otherwise.| **Example** - + ```js + let uploadTask; uploadTask.remove().then((result) => { if (result) { console.info('Upload task removed successfully. '); @@ -486,6 +612,76 @@ remove(callback: AsyncCallback<boolean>): void Removes this upload task. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [delete9+](#delete9-1). + +**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 + let uploadTask; + uploadTask.remove((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.'); + } + }); + ``` + + +### 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 deletion result. It returns **true** if the operation is successful and returns **false** otherwise.| + +**Example** + + ```js + let uploadTask; + 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 @@ -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) => { + let uploadTask; + 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.
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 | 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.
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 | Yes| Type of the file content. By default, the type is obtained based on the extension of the file name or URI.| ## RequestData @@ -571,6 +768,10 @@ download(config: DownloadConfig): Promise<DownloadTask> Downloads files. This API uses a promise to return the result. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [request.downloadFile9+](#requestdownloadfile9). + This API can be used only in the FA model. **Required permissions**: ohos.permission.INTERNET @@ -579,18 +780,18 @@ This API can be used only in the FA model. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| **Return value** -| Type| Description| -| -------- | -------- | -| Promise<[DownloadTask](#downloadtask)> | Promise used to return the result.| + | Type| Description| + | -------- | -------- | + | Promise<[DownloadTask](#downloadtask)> | Promise used to return the result.| **Example** - + ```js let downloadTask; request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => { @@ -607,6 +808,10 @@ download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): v Downloads files. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [request.downloadFile9+](#requestdownloadfile9-1). + This API can be used only in the FA model. **Required permissions**: ohos.permission.INTERNET @@ -615,13 +820,13 @@ This API can be used only in the FA model. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| -| callback | AsyncCallback<[DownloadTask](#downloadtask)> | No| Callback used to return the result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| + | callback | AsyncCallback<[DownloadTask](#downloadtask)> | Yes| Callback used to return the result.| **Example** - + ```js let downloadTask; request.download({ url: 'https://xxxx/xxxxx.hap', @@ -640,25 +845,29 @@ download(context: BaseContext, config: DownloadConfig): Promise<DownloadTask& Downloads files. This API uses a promise to return the result. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [request.downloadFile9+](#requestdownloadfile9). + **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.| + | 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.| + | 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) => { @@ -675,20 +884,24 @@ download(context: BaseContext, config: DownloadConfig, callback: AsyncCallback&l Downloads files. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [request.downloadFile9+](#requestdownloadfile9-1). + **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.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | context | BaseContext | Yes| Application-based context.| + | config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| + | callback | AsyncCallback<[DownloadTask](#downloadtask)> | Yes| Callback used to return the result.| **Example** - + ```js let downloadTask; request.download(globalThis.abilityContext, { url: 'https://xxxx/xxxxx.hap', @@ -700,16 +913,13 @@ Downloads files. This API uses an asynchronous callback to return the result. downloadTask = data; }); ``` -## DownloadTask - -Implements file downloads. -### on('progress') +## request.downloadFile9+ -on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void +downloadFile(context: BaseContext, config: DownloadConfig): Promise<DownloadTask> -Subscribes to a download event. This API uses an asynchronous callback to return the result. +Downloads files. This API uses a promise to return the result. **Required permissions**: ohos.permission.INTERNET @@ -718,24 +928,116 @@ Subscribes to a download 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 is **'progress'** (download progress).| -| callback | function | Yes| Callback for the download progress event.| + | -------- | -------- | -------- | -------- | +| context | BaseContext | Yes| Application-based context.| +| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| -Parameters of the callback function +**Return value** -| 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.| +| 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 - downloadTask.on('progress', function download_callback(receivedSize, totalSize) { - console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); - } - ); + let downloadTask; + 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)); + }) + ``` + + +## request.downloadFile9+ + +downloadFile(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)> | 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; + 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; + }); + ``` + + +## DownloadTask + +Implements file downloads. + + +### on('progress') + +on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void + +Subscribes to a download event. 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| + | -------- | -------- | -------- | -------- | + | 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 + +| 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.| + +**Example** + + ```js + let downloadTask; + downloadTask.on('progress', function download_callback(receivedSize, totalSize) { + console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); + } + ); ``` @@ -751,12 +1053,12 @@ Unsubscribes from a download event. This API uses an asynchronous callback to re **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 for the download progress event.| + | 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.| -Parameters of the callback function + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | @@ -764,7 +1066,7 @@ Parameters of the callback function | totalSize | number | Yes| Total size of the files to download.| **Example** - + ```js downloadTask .off('progress', function download_callback(receivedSize, totalSize) { console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); @@ -785,14 +1087,15 @@ Subscribes to a download event. This API uses an asynchronous callback to return **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.| + | 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 downloadTask; downloadTask.on('complete', function callback() { console.info('Download task completed.'); } @@ -812,14 +1115,15 @@ Unsubscribes from a download event. This API uses an asynchronous callback to re **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.| + | 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 downloadTask; downloadTask.off('complete', function callback() { console.info('Download task completed.'); } @@ -839,20 +1143,21 @@ Subscribes to the download task failure event. This API uses an asynchronous cal **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.| + | 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 + 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 [ERROR_*](#constants).| **Example** - + ```js + let downloadTask; downloadTask.on('fail', function callBack(err) { console.info('Download task failed. Cause:' + err); } @@ -872,20 +1177,21 @@ Unsubscribes from the download task failure event. This API uses an asynchronous **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 for the download task failure event.| + | 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.| -Parameters of the callback function + 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 [ERROR_*](#constants).| **Example** - + ```js + let downloadTask; downloadTask.off('fail', function callBack(err) { console.info('Download task failed. Cause:' + err); } @@ -899,19 +1205,24 @@ remove(): Promise<boolean> Removes this download task. This API uses a promise to return the result. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [delete9+](#delete9-2). + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Download **Return value** -| Type| Description| -| -------- | -------- | -| Promise<boolean> | Promise used to return the task removal result.| + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Promise used to return the task removal result.| **Example** - + ```js + let downloadTask; downloadTask.remove().then((result) => { if (result) { console.info('Download task removed.'); @@ -930,19 +1241,24 @@ remove(callback: AsyncCallback<boolean>): void Removes this download task. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [delete9+](#delete9-3). + **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 removal result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | Yes| Callback used to return the task removal result.| **Example** - + ```js + let downloadTask; downloadTask.remove((err, result)=>{ if(err) { console.error('Failed to remove the download task.'); @@ -963,18 +1279,24 @@ query(): Promise<DownloadInfo> Queries this download task. This API uses a promise to return the result. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [getTaskInfo9+](#gettaskinfo9). + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Download -**Parameters** - | Type| Description| +**Return value** + + | Type| Description| | -------- | -------- | | Promise<[DownloadInfo](#downloadinfo7)> | Promise used to return the download task information.| **Example** - + ```js + let downloadTask; downloadTask.query().then((downloadInfo) => { console.info('Download task queried. Data:' + JSON.stringify(downloadInfo)) }) .catch((err) => { @@ -989,19 +1311,24 @@ query(callback: AsyncCallback<DownloadInfo>): void Queries this download task. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [getTaskInfo9+](#gettaskinfo9-1). + **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.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | Yes| Callback used to return the download task information.| **Example** - + ```js + let downloadTask; downloadTask.query((err, downloadInfo)=>{ if(err) { console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); @@ -1018,19 +1345,24 @@ queryMimeType(): Promise<string> Queries the **MimeType** of this download task. This API uses a promise to return the result. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [getTaskMimeType9+](#gettaskmimetype9). + **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.| + | Type| Description| + | -------- | -------- | + | Promise<string> | Promise used to return the **MimeType** of the download task.| **Example** - + ```js + let downloadTask; downloadTask.queryMimeType().then((data) => { console.info('Download task queried. Data:' + JSON.stringify(data)); }).catch((err) => { @@ -1045,19 +1377,24 @@ queryMimeType(callback: AsyncCallback<string>): void; Queries the **MimeType** of this download task. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [getTaskMimeType9+](#gettaskmimetype9-1). + **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.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<string> | Yes| Callback used to return the **MimeType** of the download task.| **Example** - + ```js + let downloadTask; downloadTask.queryMimeType((err, data)=>{ if(err) { console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); @@ -1074,19 +1411,24 @@ pause(): Promise<void> Pauses this download task. This API uses a promise to return the result. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [suspend9+](#suspend9). + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Download **Return value** -| Type| Description| -| -------- | -------- | -| Promise<void> | Promise used to return the download task pause result.| + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the download task pause result.| **Example** - + ```js + let downloadTask; downloadTask.pause().then((result) => { if (result) { console.info('Download task paused. '); @@ -1103,6 +1445,10 @@ Pauses this download task. This API uses a promise to return the result. pause(callback: AsyncCallback<void>): void +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [suspend9+](#suspend9-1). + Pauses this download task. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERNET @@ -1111,13 +1457,14 @@ Pauses 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.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Example** - + ```js + let downloadTask; downloadTask.pause((err, result)=>{ if(err) { console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); @@ -1138,20 +1485,344 @@ resume(): Promise<void> Resumes this download task. This API uses a promise to return the result. +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [restore9+](#restore9). + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +**Example** + + ```js + let downloadTask; + downloadTask.resume().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); + }); + ``` + + +### resume7+ + +resume(callback: AsyncCallback<void>): void + +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [restore9+](#restore9-1). + +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<void> | Yes| Callback used to return the result.| + +**Example** + + ```js + let downloadTask; + downloadTask.resume((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.'); + } + }); + ``` + + +### delete9+ + +delete(): Promise<boolean> + +Deletes 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 + let downloadTask; + 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 result.| + +**Example** + + ```js + let downloadTask; + 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> + +Queries 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<void> | Promise used to return the result.| +| Promise<[DownloadInfo](#downloadinfo7)> | Promise used to return the download task information.| **Example** ```js - downloadTask.resume().then((result) => { + let downloadTask; + 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+ + +query(callback: AsyncCallback<DownloadInfo>): void + +Queries 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 + let downloadTask; + 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 + let downloadTask; + 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 + let downloadTask; + 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 + let downloadTask; + 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 + let downloadTask; + 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 + let downloadTask; + downloadTask.restore().then((result) => { if (result) { console.info('Download task resumed.') } else { @@ -1164,9 +1835,9 @@ Resumes this download task. This API uses a promise to return the result. ``` -### resume7+ +### restore9+ -resume(callback: AsyncCallback<void>): void +restore(callback: AsyncCallback<boolean>): void 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)=>{ + let downloadTask; + 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.
- **true**: yes
**false**: no| -| enableRoaming | boolean | No| Whether download is allowed on a roaming network.
- **true**: yes
**false**: no| +| 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.
- **true**: yes
- **false**: no| +| enableRoaming | boolean | No| Whether download is allowed on a roaming network.
- **true**: yes
- **false**: no| | 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.
- NETWORK_MOBILE: 0x00000001
- NETWORK_WIFI: 0x00010000| diff --git a/en/application-dev/reference/apis/js-apis-system-parameterV9.md b/en/application-dev/reference/apis/js-apis-system-parameterV9.md index 5e725ca92b1138a2ebc579036748343c50417b32..23ad27a04596da4b52bc254c931670845f39fb5f 100644 --- a/en/application-dev/reference/apis/js-apis-system-parameterV9.md +++ b/en/application-dev/reference/apis/js-apis-system-parameterV9.md @@ -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. ## Modules to Import diff --git a/en/application-dev/reference/errorcodes/errorcode-request.md b/en/application-dev/reference/errorcodes/errorcode-request.md new file mode 100644 index 0000000000000000000000000000000000000000..20de2eeb4639a8e85da7b916b6524c427ca23537 --- /dev/null +++ b/en/application-dev/reference/errorcodes/errorcode-request.md @@ -0,0 +1,55 @@ +# Upload and Download Error Codes + +## 13400001 File Operation Error + +**Error Message** + +File operation error. + +**Description** + +This error code is reported when a file operation error occurs in invoking the **uploadFile** or **downloadFile** API. + +**Possible Causes** + +The file permission is insufficient. + +**Solution** + +Make sure you have the required permission on the target files. + +## 13400002 File Path Error + +**Error Message** + +Bad file path. + +**Description** + +This error code is reported when a file path error occurs in invoking the **uploadFile** or **downloadFile** API. + +**Possible Causes** + +The file path is incorrect. + +**Solution** + +Verify the file path. + +## 13400003 Service Error + +**Error Message** + +Task manager service error. + +**Description** + +This error code is reported when a task manager service error occurs in invoking the **downloadFile** API. + +**Possible Causes** + +The task fails to be created. + +**Solution** + +Verify the task settings. diff --git a/en/application-dev/reference/errorcodes/errorcode-system-parameterV9.md b/en/application-dev/reference/errorcodes/errorcode-system-parameterV9.md new file mode 100644 index 0000000000000000000000000000000000000000..f959417bd8b1bef207591ce1178366791e202a01 --- /dev/null +++ b/en/application-dev/reference/errorcodes/errorcode-system-parameterV9.md @@ -0,0 +1,74 @@ +# System Parameter Error Codes + +## 14700101 Failure to Query the System Parameter + +**Error Message** + +System parameter can not be found. + +**Description** + +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.