diff --git a/en/application-dev/reference/apis/js-apis-request.md b/en/application-dev/reference/apis/js-apis-request.md index 50c50f574bbcad706077725e3b4c6f69f3334b1c..b2ff6a8bc7ca45e255a57c9ebe414d12f87157e7 100644 --- a/en/application-dev/reference/apis/js-apis-request.md +++ b/en/application-dev/reference/apis/js-apis-request.md @@ -17,9 +17,9 @@ import request from '@ohos.request'; ## Constraints -HTTPS is supported by default. To support HTTP, you need to add **network** to the **config.json** file and set the **cleartextTraffic** attribute to **true**. +HTTPS is supported by default in the FA model. To support HTTP, add **network** to the **config.json** file and set the **cleartextTraffic** attribute to **true**. -``` +```js var config = { "deviceConfig": { "default": { @@ -32,6 +32,9 @@ var config = { } ``` +The **cleartextTraffic** attribute is not involved during the development of applications in the stage model. + + ## Constants @@ -39,28 +42,28 @@ var config = { **System capability**: SystemCapability.MiscServices.Download -| Name | Type | Readable | Writable | Description | +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| NETWORK_MOBILE | number | Yes | No | Whether download is allowed when the cellular network is used. | -| NETWORK_WIFI | number | Yes | No | Whether download is allowed on a WLAN. | -| ERROR_CANNOT_RESUME7+ | number | Yes | No | Failure to resume the download due to an error. | -| ERROR_DEVICE_NOT_FOUND7+ | number | Yes | No | Failure to find a storage device such as a memory card. | -| ERROR_FILE_ALREADY_EXISTS7+ | number | Yes | No | Failure to download the file because it already exists. | -| ERROR_FILE_ERROR7+ | number | Yes | No | File operation failure. | -| ERROR_HTTP_DATA_ERROR7+ | number | Yes | No | HTTP transmission failure. | -| ERROR_INSUFFICIENT_SPACE7+ | number | Yes | No | Insufficient storage space. | -| ERROR_TOO_MANY_REDIRECTS7+ | number | Yes | No | Error caused by too many network redirections. | -| ERROR_UNHANDLED_HTTP_CODE7+ | number | Yes | No | Unidentified HTTP code. | -| ERROR_UNKNOWN7+ | number | Yes | No | Unknown error. | -| PAUSED_QUEUED_FOR_WIFI7+ | number | Yes | No | Download paused and queuing for a WLAN connection, because the file size exceeds the maximum value allowed by a cellular network session. | -| PAUSED_UNKNOWN7+ | number | Yes | No | Download paused due to unknown reasons. | -| PAUSED_WAITING_FOR_NETWORK7+ | number | Yes | No | Download paused due to a network connection problem, for example, network disconnection. | -| PAUSED_WAITING_TO_RETRY7+ | number | Yes | No | Download paused and then retried. | -| SESSION_FAILED7+ | number | Yes | No | Download failure without retry. | -| SESSION_PAUSED7+ | number | Yes | No | Download paused. | -| SESSION_PENDING7+ | number | Yes | No | Download pending. | -| SESSION_RUNNING7+ | number | Yes | No | Download in progress. | -| SESSION_SUCCESSFUL7+ | number | Yes | No | Successful download. | +| NETWORK_MOBILE | number | Yes| No| Whether download is allowed on a mobile network.| +| NETWORK_WIFI | number | Yes| No| Whether download is allowed on a WLAN.| +| ERROR_CANNOT_RESUME7+ | number | Yes| No| Failure to resume the download due to an error.| +| ERROR_DEVICE_NOT_FOUND7+ | number | Yes| No| Failure to find a storage device such as a memory card.| +| ERROR_FILE_ALREADY_EXISTS7+ | number | Yes| No| Failure to download the file because it already exists.| +| ERROR_FILE_ERROR7+ | number | Yes| No| File operation failure.| +| ERROR_HTTP_DATA_ERROR7+ | number | Yes| No| HTTP transmission failure.| +| ERROR_INSUFFICIENT_SPACE7+ | number | Yes| No| Insufficient storage space.| +| ERROR_TOO_MANY_REDIRECTS7+ | number | Yes| No| Error caused by too many network redirections.| +| ERROR_UNHANDLED_HTTP_CODE7+ | number | Yes| No| Unidentified HTTP code.| +| ERROR_UNKNOWN7+ | number | Yes| No| Unknown error.| +| PAUSED_QUEUED_FOR_WIFI7+ | number | Yes| No| Download paused and queuing for a WLAN connection, because the file size exceeds the maximum value allowed by a mobile network session.| +| PAUSED_UNKNOWN7+ | number | Yes| No| Download paused due to unknown reasons.| +| PAUSED_WAITING_FOR_NETWORK7+ | number | Yes| No| Download paused due to a network connection problem, for example, network disconnection.| +| PAUSED_WAITING_TO_RETRY7+ | number | Yes| No| Download paused and then retried.| +| SESSION_FAILED7+ | number | Yes| No| Download failure without retry.| +| SESSION_PAUSED7+ | number | Yes| No| Download paused.| +| SESSION_PENDING7+ | number | Yes| No| Download pending.| +| SESSION_RUNNING7+ | number | Yes| No| Download in progress.| +| SESSION_SUCCESSFUL7+ | number | Yes| No| Successful download.| ## request.upload @@ -69,30 +72,36 @@ upload(config: UploadConfig): Promise<UploadTask> Uploads files. This API uses a promise to return the result. +This API can be used only in the FA model. + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Upload **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| config | [UploadConfig](#uploadconfig) | Yes | Configurations of the upload. | +| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| **Return value** -| Type | Description | +| Type| Description| | -------- | -------- | -| Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object. | +| Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object.| **Example** ```js - let file1 = { filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }; - let data = { name: "name123", value: "123" }; - let header = { key1: "value1", key2: "value2" }; let uploadTask; - request.upload({ url: 'https://patch', header: header, method: "POST", files: [file1], data: [data] }).then((data) => { + let uploadConfig = { + url: 'https://patch', + header: { key1: "value1", key2: "value2" }, + method: "POST", + files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], + data: [{ name: "name123", value: "123" }], + }; + request.upload(uploadConfig).then((data) => { uploadTask = data; }).catch((err) => { console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); @@ -106,25 +115,31 @@ upload(config: UploadConfig, callback: AsyncCallback<UploadTask>): void Uploads files. This API uses an asynchronous callback to return the result. +This API can be used only in the FA model. + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Upload **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| config | [UploadConfig](#uploadconfig) | Yes | Configurations of the upload. | -| callback | AsyncCallback<[UploadTask](#uploadtask)> | No | Callback used to return the **UploadTask** object. | +| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| +| callback | AsyncCallback<[UploadTask](#uploadtask)> | No| Callback used to return the **UploadTask** object.| **Example** ```js - let file1 = { filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }; - let data = { name: "name123", value: "123" }; - let header = { key1: "value1", key2: "value2" }; let uploadTask; - request.upload({ url: 'https://patch', header: header, method: "POST", files: [file1], data: [data] }, (err, data) => { + let uploadConfig = { + url: 'https://patch', + header: { key1: "value1", key2: "value2" }, + method: "POST", + files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], + data: [{ name: "name123", value: "123" }], + }; + request.upload(uploadConfig, (err, data) => { if (err) { console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); return; @@ -132,8 +147,87 @@ Uploads files. This API uses an asynchronous callback to return the result. uploadTask = data; }); ``` +## request.upload9+ + +upload(context: BaseContext, config: UploadConfig): Promise<UploadTask> + +Uploads files. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Upload + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| context | BaseContext | Yes| Application-based context.| +| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| + + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object.| + +**Example** + + ```js + let uploadTask; + let uploadConfig = { + url: 'https://patch', + header: { key1: "value1", key2: "value2" }, + method: "POST", + files: { filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }, + data: { name: "name123", value: "123" }, + }; + request.upload(globalThis.abilityContext, uploadConfig).then((data) => { + uploadTask = data; + }).catch((err) => { + console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); + }); + ``` +## request.upload9+ + +upload(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void + +Uploads files. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Upload + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| context | BaseContext | Yes| Application-based context.| +| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| +| callback | AsyncCallback<[UploadTask](#uploadtask)> | No| Callback used to return the **UploadTask** object.| + +**Example** + + ```js + let uploadTask; + let uploadConfig = { + url: 'https://patch', + header: { key1: "value1", key2: "value2" }, + method: "POST", + files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], + data: [{ name: "name123", value: "123" }], + }; + request.upload(globalThis.abilityContext, uploadConfig, (err, data) => { + if (err) { + console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); + return; + } + uploadTask = data; + }); + ``` + ## UploadTask Implements file uploads. Before using any APIs of this class, you must obtain an **UploadTask** object. @@ -143,7 +237,7 @@ Implements file uploads. Before using any APIs of this class, you must obtain an on(type: 'progress', callback:(uploadedSize: number, totalSize: number) => void): void -Subscribes to the upload progress event. This API uses an asynchronous callback to return the result. +Subscribes to an upload event. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERNET @@ -151,17 +245,17 @@ Subscribes to the upload progress event. This API uses an asynchronous callback **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Type of the event to subscribe to. The value is **progress** (upload progress). | -| callback | function | Yes | Callback for the upload progress event. | +| type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (upload progress).| +| callback | function | Yes| Callback for the upload progress event.| -**callback** parameters +Parameters of the callback function -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| uploadedSize | number | Yes | Size of the uploaded files, in KB. | -| totalSize | number | Yes | Total size of the files to upload, in KB. | +| uploadedSize | number | Yes| Size of the uploaded files, in KB.| +| totalSize | number | Yes| Total size of the files to upload, in KB.| **Example** @@ -177,7 +271,7 @@ Subscribes to the upload progress event. This API uses an asynchronous callback on(type: 'headerReceive', callback: (header: object) => void): void -Subscribes to the **headerReceive** event, which is triggered when an HTTP response header is received. This API uses an asynchronous callback to return the result. +Subscribes to an upload event. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERNET @@ -185,16 +279,16 @@ Subscribes to the **headerReceive** event, which is triggered when an HTTP respo **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Type of the event to subscribe to. The value is **'headerReceive'** (response header). | -| callback | function | Yes | Callback for the HTTP Response Header event. | +| type | string | Yes| Type of the event to subscribe to. The value is **'headerReceive'** (response header).| +| callback | function | Yes| Callback for the HTTP Response Header event.| -**callback** parameters +Parameters of the callback function -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| header | object | Yes | HTTP Response Header. | +| header | object | Yes| HTTP Response Header.| **Example** @@ -210,7 +304,7 @@ Subscribes to the **headerReceive** event, which is triggered when an HTTP respo off(type: 'progress', callback?: (uploadedSize: number, totalSize: number) => void): void -Unsubscribes from the upload progress event. This API uses an asynchronous callback to return the result. +Unsubscribes from an upload event. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERNET @@ -218,17 +312,17 @@ Unsubscribes from the upload progress event. This API uses an asynchronous callb **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Type of the event to unsubscribe from. The value is **'progress'** (upload progress). | -| callback | function | No | Callback for the upload progress event. | +| type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (upload progress).| +| callback | function | No| Callback for the upload progress event.| -**callback** parameters +Parameters of the callback function -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| uploadedSize | number | Yes | Size of the uploaded files, in KB. | -| totalSize | number | Yes | Total size of the files to upload, in KB. | +| uploadedSize | number | Yes| Size of the uploaded files, in KB.| +| totalSize | number | Yes| Total size of the files to upload, in KB.| **Example** @@ -244,7 +338,7 @@ Unsubscribes from the upload progress event. This API uses an asynchronous callb off(type: 'headerReceive', callback?: (header: object) => void): void -Unsubscribes from the **headerReceive** event. This API uses an asynchronous callback to return the result. +Unsubscribes from an upload event. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERNET @@ -252,16 +346,16 @@ Unsubscribes from the **headerReceive** event. This API uses an asynchronous cal **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Type of the event to unsubscribe from. The value is **'headerReceive'** (response header). | -| callback | function | No | Callback for the HTTP Response Header event. | +| type | string | Yes| Type of the event to unsubscribe from. The value is **'headerReceive'** (response header).| +| callback | function | No| Callback for the HTTP Response Header event.| -**callback** parameters +Parameters of the callback function -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| header | object | Yes | HTTP Response Header. | +| header | object | Yes| HTTP Response Header.| **Example** @@ -277,7 +371,7 @@ Unsubscribes from the **headerReceive** event. This API uses an asynchronous cal remove(): Promise<boolean> -Removes this upload task. This API uses a promise to return the result. +Removes this upload task. This API uses a promise to return the result. **Required permissions**: ohos.permission.INTERNET @@ -285,9 +379,9 @@ Removes this upload task. This API uses a promise to return the result. **Return value** -| Type | Description | +| Type| Description| | -------- | -------- | -| Promise<boolean> | Promise used to return the task removal result. If **true** is returned, the task is removed. If **false** is returned, the task fails to be removed. | +| Promise<boolean> | Promise used to return the task removal result. If **true** is returned, the task is removed. If **false** is returned, the task fails to be removed.| **Example** @@ -308,7 +402,7 @@ Removes this upload task. This API uses a promise to return the result. remove(callback: AsyncCallback<boolean>): void -Removes this upload task. This API uses an asynchronous callback to return the result. +Removes this upload task. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERNET @@ -316,9 +410,9 @@ Removes this upload task. This API uses an asynchronous callback to return the r **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. | +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| **Example** @@ -339,37 +433,42 @@ Removes this upload task. This API uses an asynchronous callback to return the r ## UploadConfig +**Required permissions**: ohos.permission.INTERNET + **System capability**: SystemCapability.MiscServices.Upload -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| url | string | Yes | Resource URL. | -| header | object | Yes | HTTP or HTTPS header added to an upload request. | -| method | string | Yes | Request method, which can be **POST** or **PUT**. The default value is **POST**. | -| files | Array<[File](#file)> | Yes | List of files to upload, which is submitted through **multipart/form-data**. | -| data | Array<[RequestData](#requestdata)> | Yes | Form data in the request body. | +| url | string | Yes| Resource URL.| +| header | object | Yes| HTTP or HTTPS header added to an upload request.| +| method | string | Yes| Request method, which can be **'POST'** or **'PUT'**. The default value is **'POST'**.| +| files | Array<[File](#file)> | Yes| List of files to upload, which is submitted through **multipart/form-data**.| +| data | Array<[RequestData](#requestdata)> | Yes| Form data in the request body.| ## File -**System capability**: SystemCapability.MiscServices.Upload +**Required permissions**: ohos.permission.INTERNET -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.MiscServices.Download + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| filename | string | No | File name in the header when **multipart** is used. | -| name | string | No | Name of a form item when **multipart** is used. The default value is **file**. | -| uri | string | Yes | Local path for storing files.
The **dataability** and **internal** protocol types are supported. However, the **internal** protocol type supports only temporary directories. Below are examples:
dataability:///com.domainname.dataability.persondata/person/10/file.txt
internal://cache/path/to/file.txt | -| type | string | No | Type of the file content. By default, the type is obtained based on the extension of the file name or URI. | +| filename | string | No| File name in the header when **multipart** is used.| +| name | string | No| Name of a form item when **multipart** is used. The default value is **file**.| +| uri | string | Yes| Local path for storing files.
The **dataability** and **internal** protocol types are supported. However, the **internal** protocol type supports only temporary directories. Below are examples:
dataability:///com.domainname.dataability.persondata/person/10/file.txt

internal://cache/path/to/file.txt | +| type | string | No| Type of the file content. By default, the type is obtained based on the extension of the file name or URI.| ## RequestData -**System capability**: SystemCapability.MiscServices.Upload +**Required permissions**: ohos.permission.INTERNET -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.MiscServices.Download +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| name | string | Yes | Name of a form element. | -| value | string | Yes | Value of a form element. | +| name | string | Yes| Name of a form element.| +| value | string | Yes| Value of a form element.| ## request.download @@ -378,21 +477,23 @@ download(config: DownloadConfig): Promise<DownloadTask> Downloads files. This API uses a promise to return the result. +This API can be used only in the FA model. + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Download **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| config | [DownloadConfig](#downloadconfig) | Yes | Configurations of the download. | +| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| **Return value** -| Type | Description | +| Type| Description| | -------- | -------- | -| Promise<[DownloadTask](#downloadtask)> | Promise used to return the result. | +| Promise<[DownloadTask](#downloadtask)> | Promise used to return the result.| **Example** @@ -412,16 +513,18 @@ download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): v Downloads files. This API uses an asynchronous callback to return the result. +This API can be used only in the FA model. + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Download **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| config | [DownloadConfig](#downloadconfig) | Yes | Configurations of the download. | -| callback | AsyncCallback<[DownloadTask](#downloadtask)> | No | Callback used to return the result. | +| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| +| callback | AsyncCallback<[DownloadTask](#downloadtask)> | No| Callback used to return the result.| **Example** @@ -437,7 +540,72 @@ Downloads files. This API uses an asynchronous callback to return the result. }); ``` +## request.download9+ + +download(context: BaseContext, config: DownloadConfig): Promise<DownloadTask> + +Downloads files. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| context | BaseContext | Yes| Application-based context.| +| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<[DownloadTask](#downloadtask)> | Promise used to return the result.| + +**Example** + + ```js + let downloadTask; + request.download(globalThis.abilityContext, { url: 'https://xxxx/xxxx.hap' }).then((data) => { + downloadTask = data; + }).catch((err) => { + console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); + }) + ``` + + +## request.download9+ +download(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void; + +Downloads files. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERNET + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| context | BaseContext | Yes| Application-based context.| +| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| +| callback | AsyncCallback<[DownloadTask](#downloadtask)> | No| Callback used to return the result.| + +**Example** + + ```js + let downloadTask; + request.download(globalThis.abilityContext, { url: 'https://xxxx/xxxxx.hap', + filePath: 'xxx/xxxxx.hap'}, (err, data) => { + if (err) { + console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); + return; + } + downloadTask = data; + }); + ``` ## DownloadTask Implements file downloads. @@ -447,7 +615,7 @@ Implements file downloads. on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void -Subscribes to the download progress event. This API uses an asynchronous callback to return the result. +Subscribes to a download event. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERNET @@ -455,17 +623,17 @@ Subscribes to the download progress event. This API uses an asynchronous callbac **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Type of the event to subscribe to. The value is **'progress'** (download progress). | -| callback | function | Yes | Callback for the download progress event. | +| type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (download progress).| +| callback | function | Yes| Callback for the download progress event.| -**callback** parameters +Parameters of the callback function -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| receivedSize | number | Yes | Size of the downloaded files, in KB. | -| totalSize | number | Yes | Total size of the files to download, in KB. | +| receivedSize | number | Yes| Size of the downloaded files, in KB.| +| totalSize | number | Yes| Total size of the files to download, in KB.| **Example** @@ -481,7 +649,7 @@ Subscribes to the download progress event. This API uses an asynchronous callbac off(type: 'progress', callback?: (receivedSize: number, totalSize: number) => void): void -Unsubscribes from the download progress event. This API uses an asynchronous callback to return the result. +Unsubscribes from a download event. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERNET @@ -489,17 +657,17 @@ Unsubscribes from the download progress event. This API uses an asynchronous cal **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Type of the event to unsubscribe from. The value is **'progress'** (download progress). | -| callback | function | No | Callback for the download progress event. | +| type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (download progress).| +| callback | function | No| Callback for the download progress event.| -**callback** parameters +Parameters of the callback function -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| receivedSize | number | Yes | Size of the downloaded files, in KB. | -| totalSize | number | Yes | Total size of the files to download, in KB. | +| receivedSize | number | Yes| Size of the downloaded files.| +| totalSize | number | Yes| Total size of the files to download.| **Example** @@ -523,10 +691,10 @@ Subscribes to a download event. This API uses an asynchronous callback to return **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type.
- **'complete'**: download task completion event.
- **'pause'**: download task pause event.
- **'remove'**: download task removal event. | -| callback | function | Yes | Callback used to return the result. | +| type | string | Yes| Type of the event to subscribe to.
- **'complete'**: download task completion event.
- **'pause'**: download task pause event.
- **'remove'**: download task removal event.| +| callback | function | Yes| Callback used to return the result.| **Example** @@ -542,7 +710,7 @@ Subscribes to a download event. This API uses an asynchronous callback to return off(type: 'complete'|'pause'|'remove', callback?:() => void): void -Unsubscribes from the download event. This API uses an asynchronous callback to return the result. +Unsubscribes from a download event. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERNET @@ -550,10 +718,10 @@ Unsubscribes from the download event. This API uses an asynchronous callback to **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type.
- **'complete'**: download task completion event.
- **'pause'**: download task pause event.
- **'remove'**: download task removal event. | -| callback | function | No | Callback used to return the result. | +| type | string | Yes| Type of the event to unsubscribe from.
- **'complete'**: download task completion event.
- **'pause'**: download task pause event.
- **'remove'**: download task removal event.| +| callback | function | No| Callback used to return the result.| **Example** @@ -577,16 +745,16 @@ Subscribes to the download task failure event. This API uses an asynchronous cal **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Type of the subscribed event. The value is **'fail'** (download failure). | -| callback | function | Yes | Callback for the download task failure event. | +| type | string | Yes| Type of the event to subscribe to. The value is **'fail'** (download failure).| +| callback | function | Yes| Callback for the download task failure event.| -**callback** parameters +Parameters of the callback function -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| err | number | Yes | Error code of the download failure. For details about the error cause, see [ERROR_*](#constants). | +| err | number | Yes| Error code of the download failure. For details about the error codes, see [ERROR_*](#constants).| **Example** @@ -602,7 +770,7 @@ Subscribes to the download task failure event. This API uses an asynchronous cal off(type: 'fail', callback?: (err: number) => void): void -Unsubscribes from the download task failure event. This API uses an asynchronous callback to return the result. +Unsubscribes from the download task failure event. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERNET @@ -610,16 +778,16 @@ Unsubscribes from the download task failure event. This API uses an asynchronous **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Type of the event to unsubscribe from. The value is **'fail'** (download failure). | -| callback | function | No | Callback for the download task failure event. | +| type | string | Yes| Type of the event to unsubscribe from. The value is **'fail'** (download failure).| +| callback | function | No| Callback for the download task failure event.| -**callback** parameters +Parameters of the callback function -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| err | number | Yes | Error code of the download failure. For details about the error cause, see [ERROR_*](#constants). | +| err | number | Yes| Error code of the download failure. For details about the error codes, see [ERROR_*](#constants).| **Example** @@ -643,9 +811,9 @@ Removes this download task. This API uses a promise to return the result. **Return value** -| Type | Description | +| Type| Description| | -------- | -------- | -| Promise<boolean> | Promise used to return the task removal result. | +| Promise<boolean> | Promise used to return the task removal result.| **Example** @@ -674,9 +842,9 @@ Removes this download task. This API uses an asynchronous callback to return the **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes | Callback used to return the task removal result. | +| callback | AsyncCallback<boolean> | Yes| Callback used to return the task removal result.| **Example** @@ -706,10 +874,9 @@ Queries this download task. This API uses a promise to return the result. **System capability**: SystemCapability.MiscServices.Download **Parameters** - -| Type | Description | -| -------- | -------- | -| Promise<[DownloadInfo](#downloadinfo7)> | Promise used to return the download task information. | + | Type| Description| + | -------- | -------- | + | Promise<[DownloadInfo](#downloadinfo7)> | Promise used to return the download task information.| **Example** @@ -734,9 +901,9 @@ Queries this download task. This API uses an asynchronous callback to return the **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | Yes | Callback used to return the download task information. | +| callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | Yes| Callback used to return the download task information.| **Example** @@ -755,7 +922,7 @@ Queries this download task. This API uses an asynchronous callback to return the queryMimeType(): Promise<string> -Queries **MimeType** of this download task. This API uses a promise to return the result. +Queries the **MimeType** of this download task. This API uses a promise to return the result. **Required permissions**: ohos.permission.INTERNET @@ -763,9 +930,9 @@ Queries **MimeType** of this download task. This API uses a promise to return th **Return value** -| Type | Description | +| Type| Description| | -------- | -------- | -| Promise<string> | Promise used to return **MimeType** of the download task. | +| Promise<string> | Promise used to return the **MimeType** of the download task.| **Example** @@ -782,7 +949,7 @@ Queries **MimeType** of this download task. This API uses a promise to return th queryMimeType(callback: AsyncCallback<string>): void; -Queries **MimeType** of this download task. This API uses an asynchronous callback to return the result. +Queries the **MimeType** of this download task. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERNET @@ -790,9 +957,9 @@ Queries **MimeType** of this download task. This API uses an asynchronous callba **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<string> | Yes | Callback used to return **MimeType** of the download task. | +| callback | AsyncCallback<string> | Yes| Callback used to return the **MimeType** of the download task.| **Example** @@ -819,9 +986,9 @@ Pauses this download task. This API uses a promise to return the result. **Return value** -| Type | Description | +| Type| Description| | -------- | -------- | -| Promise<void> | Promise used to return the download task pause result. | +| Promise<void> | Promise used to return the download task pause result.| **Example** @@ -850,9 +1017,9 @@ Pauses this download task. This API uses an asynchronous callback to return the **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<void> | Yes | Callback used to return the result. | +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Example** @@ -883,9 +1050,9 @@ Resumes this download task. This API uses a promise to return the result. **Parameters** -| Type | Description | +| Type| Description| | -------- | -------- | -| Promise<void> | Promise used to return the result. | +| Promise<void> | Promise used to return the result.| **Example** @@ -915,9 +1082,9 @@ Resumes this download task. This API uses an asynchronous callback to return the **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<void> | Yes | Callback used to return the result. | +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Example** @@ -938,34 +1105,39 @@ Resumes this download task. This API uses an asynchronous callback to return the ## DownloadConfig +**Required permissions**: ohos.permission.INTERNET + **System capability**: SystemCapability.MiscServices.Download -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| url | string | Yes | Resource URL. | -| header | object | No | HTTP or HTTPS header added to a download request. | -| enableMetered | boolean | No | Download allowed in metered connections. | -| enableRoaming | boolean | No | Download allowed on a roaming network. | -| description | string | No | Description of the download session. | -| filePath7+ | string | No | Download path. (The default path is **'internal://cache/'**.
- filePath:'workspace/test.txt': The **workspace** directory is created in the default path to store files.
- filePath:'test.txt': Files are stored in the default path.
- filePath:'workspace/': The **workspace** directory is created in the default path to store files. | -| networkType | number | No | Network type allowed for download. | -| title | string | No | Title of the download session. | +| url | string | Yes| Resource URL.| +| header | object | No| HTTP or HTTPS header added to a download request.| +| enableMetered | boolean | No| Download allowed in metered connections.| +| enableRoaming | boolean | No| Download allowed on a roaming network.| +| description | string | No| Description of the download session.| +| filePath7+ | string | No| Download path. (The default path is **'internal://cache/'**.)
- filePath:'workspace/test.txt': The **workspace** directory is created in the default path to store files.
- filePath:'test.txt': Files are stored in the default path.
- filePath:'workspace/': The **workspace** directory is created in the default path to store files.| +| networkType | number | No| Network type allowed for download.| +| title | string | No| Title of the download session.| +| background | boolean | No| Whether to enable the background task notification. When this parameter is enabled, the download status is displayed in the notification panel.| ## DownloadInfo7+ +**Required permissions**: ohos.permission.INTERNET + **System capability**: SystemCapability.MiscServices.Download -| Name | Type | Mandatory | Description | -| -------- | -------- | -------- | -------- | -| downloadId | number | Yes | ID of the downloaded file. | -| failedReason | number | No | Download failure cause, which can be any constant of [ERROR_*](#constants). | -| fileName | string | Yes | Name of the downloaded file. | -| filePath | string | Yes | URI of the saved file. | -| pausedReason | number | No | Reason for session pause, which can be any constant of [PAUSED_*](#constants). | -| status | number | Yes | Download status code, which can be any constant of [SESSION_*](#constants). | -| targetURI | string | Yes | URI of the downloaded file. | -| downloadTitle | string | Yes | Title of the downloaded file. | -| downloadTotalBytes | number | Yes | Total size of the downloaded file (int bytes). | -| description | string | Yes | Description of the file to download. | -| downloadedBytes | number | Yes | Size of the files downloaded (int bytes). | +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| downloadId | number | Yes| ID of the downloaded file.| +| failedReason | number | No| Download failure cause, which can be any constant of [ERROR_*](#constants).| +| fileName | string | Yes| Name of the downloaded file.| +| filePath | string | Yes| URI of the saved file.| +| pausedReason | number | No| Reason for session pause, which can be any constant of [PAUSED_*](#constants).| +| status | number | Yes| Download status code, which can be any constant of [SESSION_*](#constants).| +| targetURI | string | Yes| URI of the downloaded file.| +| downloadTitle | string | Yes| Title of the downloaded file.| +| downloadTotalBytes | number | Yes| Total size of the files to download (int bytes).| +| description | string | Yes| Description of the file to download.| +| downloadedBytes | number | Yes| Size of the files downloaded (int bytes).|