diff --git a/en/application-dev/reference/apis/js-apis-request.md b/en/application-dev/reference/apis/js-apis-request.md index 65e8c2708c98748ba55a734e8095228233d90b9a..2220b4bbc02bd9a68fa900138869b6d3f6620675 100644 --- a/en/application-dev/reference/apis/js-apis-request.md +++ b/en/application-dev/reference/apis/js-apis-request.md @@ -1,9 +1,9 @@ -# Upload and Download +# @ohos.request 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. @@ -34,8 +34,9 @@ var config = { 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). +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). +Only HTTP requests are supported. HTTPS requests are not supported. ## Constants @@ -69,86 +70,93 @@ The download server must support the HTTP HEAD method so that the size of the da | SESSION_SUCCESSFUL7+ | number | Yes| No| Successful download.| -## request.upload +## request.uploadFile9+ -upload(config: UploadConfig): Promise<UploadTask> +uploadFile(context: BaseContext, 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. - -> **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| +| -------- | -------- | -------- | -------- | +| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| +| 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.| + +**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 let uploadTask; let uploadConfig = { - url: 'https://patch', + url: 'http://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) => { + request.uploadFile(globalThis.abilityContext, uploadConfig).then((data) => { uploadTask = data; }).catch((err) => { console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); - }) + }); ``` -## request.upload +## request.uploadFile9+ -upload(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. -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)> | Yes| Callback used to return the **UploadTask** object.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| +| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| +| 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** - + ```js let uploadTask; let uploadConfig = { - url: 'https://patch', + url: 'http://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) => { + request.uploadFile(globalThis.abilityContext, uploadConfig, (err, data) => { if (err) { console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); return; @@ -156,15 +164,18 @@ This API can be used only in the FA model. uploadTask = data; }); ``` -## request.upload9+ -upload(context: BaseContext, config: UploadConfig): Promise<UploadTask> +## request.upload(deprecated) + +upload(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). +**Model restriction**: 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 @@ -172,46 +183,46 @@ 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.| - +| 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 = { - url: 'https://patch', + url: 'http://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) => { + request.upload(uploadConfig).then((data) => { uploadTask = data; }).catch((err) => { console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); - }); + }) ``` -## request.upload9+ +## request.upload(deprecated) -upload(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void +upload(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). +**Model restriction**: 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 @@ -219,24 +230,23 @@ 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)> | Yes| 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 = { - url: 'https://patch', + url: 'http://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) => { + request.upload(uploadConfig, (err, data) => { if (err) { console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); return; @@ -245,13 +255,16 @@ Uploads files. This API uses an asynchronous callback to return the result. }); ``` +## request.upload(deprecated) -## request.uploadFile9+ - -uploadFile(context: BaseContext, config: UploadConfig): Promise<UploadTask> +upload(context: BaseContext, config: UploadConfig): Promise<UploadTask> Uploads files. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 9 and is deprecated since API version 9. You are advised to use [request.uploadFile9+](#requestuploadfile9). + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Upload @@ -259,36 +272,29 @@ Uploads files. This API uses a promise to return the result. **Parameters** | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | -| context | BaseContext | Yes| Application-based context.| +| -------- | -------- | -------- | -------- | +| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| | config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| **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. | +| Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object.| **Example** ```js let uploadTask; let uploadConfig = { - url: 'https://patch', + url: 'http://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.uploadFile(globalThis.abilityContext, uploadConfig).then((data) => { + request.upload(globalThis.abilityContext, uploadConfig).then((data) => { uploadTask = data; }).catch((err) => { console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); @@ -296,12 +302,16 @@ For details about the error codes, see [Upload and Download Error Codes](../erro ``` -## request.uploadFile9+ +## request.upload(deprecated) -uploadFile(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void +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 @@ -309,30 +319,23 @@ Uploads files. This API uses an asynchronous callback to return the result. **Parameters** | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | -| context | BaseContext | Yes| Application-based context.| +| -------- | -------- | -------- | -------- | +| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| | config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| | 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** ```js let uploadTask; let uploadConfig = { - url: 'https://patch', + url: 'http://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.uploadFile(globalThis.abilityContext, uploadConfig, (err, data) => { + request.upload(globalThis.abilityContext, uploadConfig, (err, data) => { if (err) { console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); return; @@ -341,10 +344,10 @@ For details about the error codes, see [Upload and Download Error Codes](../erro }); ``` - ## UploadTask -Implements file uploads. Before using any APIs of this class, you must obtain an **UploadTask** object. +Implements file uploads. Before using any APIs of this class, you must obtain an **UploadTask** object through [request.uploadFile9+](#requestuploadfile9) in promise mode or [request.uploadFile9+](#requestuploadfile9-1) in callback mode. + ### on('progress') @@ -359,10 +362,10 @@ 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 @@ -372,9 +375,8 @@ Subscribes to an upload event. This API uses an asynchronous callback to return | 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); } @@ -394,10 +396,10 @@ 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 @@ -406,9 +408,8 @@ Subscribes to an upload event. This API uses an asynchronous callback to return | header | object | Yes| HTTP Response Header.| **Example** - + ```js - let uploadTask; uploadTask.on('headerReceive', function callback(headers){ console.info("upOnHeader headers:" + JSON.stringify(headers)); } @@ -428,10 +429,10 @@ 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 | Callback<Array<TaskState>> | 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 @@ -440,9 +441,8 @@ Subscribes to an upload event. This API uses an asynchronous callback to return | 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])); @@ -471,10 +471,10 @@ 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 @@ -484,9 +484,8 @@ Unsubscribes from an upload event. This API uses an asynchronous callback to ret | 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); } @@ -506,10 +505,10 @@ 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 @@ -518,9 +517,8 @@ Unsubscribes from an upload event. This API uses an asynchronous callback to ret | header | object | Yes| HTTP Response Header.| **Example** - + ```js - let uploadTask; uploadTask.off('headerReceive', function callback(headers) { console.info("upOnHeader headers:" + JSON.stringify(headers)); } @@ -539,10 +537,10 @@ 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 | Callback<Array<TaskState>> | 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 @@ -551,9 +549,8 @@ Unsubscribes from an upload event. This API uses an asynchronous callback to ret | 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])); @@ -569,16 +566,10 @@ Unsubscribes from an upload event. This API uses an asynchronous callback to ret ); ``` +### delete9+ +delete(): Promise<boolean> -### remove - -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). +Deletes this upload task. This API uses a promise to return the result. **Required permissions**: ohos.permission.INTERNET @@ -586,15 +577,14 @@ Removes this upload task. This API uses a promise to return the result. **Return value** - | Type| Description| - | -------- | -------- | - | Promise<boolean> | Promise used to return the result. It returns **true** if the operation is successful and returns **false** otherwise.| +| Type| Description| +| -------- | -------- | +| Promise<boolean> | Promise used to return the task removal result. It returns **true** if the operation is successful and returns **false** otherwise.| **Example** - + ```js - let uploadTask; - uploadTask.remove().then((result) => { + uploadTask.delete().then((result) => { if (result) { console.info('Upload task removed successfully. '); } else { @@ -606,31 +596,26 @@ Removes this upload task. This API uses a promise to return the result. ``` -### remove +### delete9+ -remove(callback: AsyncCallback<boolean>): void +delete(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.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| **Example** - + ```js - let uploadTask; - uploadTask.remove((err, result) => { + uploadTask.delete((err, result) => { if (err) { console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); return; @@ -644,11 +629,15 @@ Removes this upload task. This API uses an asynchronous callback to return the r ``` -### delete9+ +### remove(deprecated) -delete(): Promise<boolean> +remove(): Promise<boolean> -Deletes 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. + +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [delete9+](#delete9). **Required permissions**: ohos.permission.INTERNET @@ -657,14 +646,13 @@ Deletes this upload task. This API uses a promise to return the result. **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.| +| -------- | -------- | +| Promise<boolean> | Promise used to return the task removal result. It returns **true** if the operation is successful and returns **false** otherwise.| **Example** ```js - let uploadTask; - uploadTask.delete().then((result) => { + uploadTask.remove().then((result) => { if (result) { console.info('Upload task removed successfully. '); } else { @@ -676,11 +664,15 @@ Deletes this upload task. This API uses a promise to return the result. ``` -### delete9+ +### remove(deprecated) -delete(callback: AsyncCallback<boolean>): void +remove(callback: AsyncCallback<boolean>): void + +Removes this upload task. This API uses an asynchronous callback to return the result. -Deletes 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 @@ -689,14 +681,13 @@ Deletes 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 - let uploadTask; - uploadTask.delete((err, result) => { + uploadTask.remove((err, result) => { if (err) { console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); return; @@ -709,7 +700,6 @@ Deletes this upload task. This API uses an asynchronous callback to return the r }); ``` - ## UploadConfig **Required permissions**: ohos.permission.INTERNET @@ -746,7 +736,7 @@ Deletes this upload task. This API uses an asynchronous callback to return the r | -------- | -------- | -------- | -------- | | 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 | +| 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.| @@ -761,40 +751,43 @@ Deletes this upload task. This API uses an asynchronous callback to return the r | name | string | Yes| Name of a form element.| | value | string | Yes| Value of a form element.| +## request.downloadFile9+ -## request.download - -download(config: DownloadConfig): Promise<DownloadTask> +downloadFile(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). - -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| - | -------- | -------- | -------- | -------- | - | config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| context | [BaseContext](js-apis-inner-application-baseContext.md) | 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.| + +**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.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => { + 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)); @@ -802,34 +795,38 @@ This API can be used only in the FA model. ``` -## request.download +## request.downloadFile9+ -download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void +downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void; 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 **System capability**: SystemCapability.MiscServices.Download **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| - | callback | AsyncCallback<[DownloadTask](#downloadtask)> | Yes| Callback used to return the result.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| context | [BaseContext](js-apis-inner-application-baseContext.md) | 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.download({ url: 'https://xxxx/xxxxx.hap', + 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)); @@ -839,15 +836,17 @@ This API can be used only in the FA model. }); ``` -## request.download9+ +## request.download(deprecated) -download(context: BaseContext, config: DownloadConfig): Promise<DownloadTask> +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). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [request.downloadFile9+](#requestdownloadfile9). + +**Model restriction**: This API can be used only in the FA model. **Required permissions**: ohos.permission.INTERNET @@ -855,22 +854,21 @@ Downloads files. This API uses a promise to return the result. **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | context | BaseContext | Yes| Application-based context.| - | 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(globalThis.abilityContext, { url: 'https://xxxx/xxxx.hap' }).then((data) => { + request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => { downloadTask = data; }).catch((err) => { console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); @@ -878,15 +876,17 @@ Downloads files. This API uses a promise to return the result. ``` -## request.download9+ +## request.download(deprecated) -download(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void; +download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void 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). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [request.downloadFile9+](#requestdownloadfile9-1). + +**Model restriction**: This API can be used only in the FA model. **Required permissions**: ohos.permission.INTERNET @@ -894,17 +894,16 @@ Downloads files. This API uses an asynchronous callback to return the result. **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.| +| 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(globalThis.abilityContext, { url: 'https://xxxx/xxxxx.hap', + request.download({ url: 'https://xxxx/xxxxx.hap', filePath: 'xxx/xxxxx.hap'}, (err, data) => { if (err) { console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); @@ -914,13 +913,16 @@ Downloads files. This API uses an asynchronous callback to return the result. }); ``` +## request.download(deprecated) -## request.downloadFile9+ - -downloadFile(context: BaseContext, config: DownloadConfig): Promise<DownloadTask> +download(context: BaseContext, config: DownloadConfig): Promise<DownloadTask> Downloads files. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 9 and is deprecated since API version 9. You are advised to use [request.downloadFile9+](#requestdownloadfile9). + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Download @@ -928,30 +930,21 @@ Downloads files. This API uses a promise to return the result. **Parameters** | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | -| context | BaseContext | Yes| Application-based context.| +| -------- | -------- | -------- | -------- | +| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| | config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| **Return value** | 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. | +| Promise<[DownloadTask](#downloadtask)> | Promise used to return the result.| **Example** ```js let downloadTask; - request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxx.hap' }).then((data) => { + 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)); @@ -959,12 +952,16 @@ For details about the error codes, see [Upload and Download Error Codes](../erro ``` -## request.downloadFile9+ +## request.download(deprecated) -downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void; +download(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void; 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 @@ -972,25 +969,16 @@ Downloads files. This API uses an asynchronous callback to return the result. **Parameters** | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | -| context | BaseContext | Yes| Application-based context.| +| -------- | -------- | -------- | -------- | +| context | [BaseContext](js-apis-inner-application-baseContext.md) | 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', + 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)); @@ -1003,7 +991,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro ## DownloadTask -Implements file downloads. +Implements file downloads. Before using any APIs of this class, you must obtain a **DownloadTask** object through [request.downloadFile9+](#requestdownloadfile9) in promise mode or [request.downloadFile9+](#requestdownloadfile9-1) in callback mode. ### on('progress') @@ -1018,10 +1006,10 @@ 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.| +| 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 @@ -1031,9 +1019,8 @@ Subscribes to a download event. This API uses an asynchronous callback to return | 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); } @@ -1053,10 +1040,10 @@ 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 @@ -1066,7 +1053,7 @@ Unsubscribes from a download event. This API uses an asynchronous callback to re | 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); @@ -1087,15 +1074,14 @@ 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.'); } @@ -1115,15 +1101,14 @@ 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.'); } @@ -1143,10 +1128,10 @@ 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 @@ -1155,9 +1140,8 @@ Subscribes to the download task failure event. This API uses an asynchronous cal | 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); } @@ -1177,10 +1161,10 @@ 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 @@ -1189,41 +1173,34 @@ Unsubscribes from the download task failure event. This API uses an asynchronous | 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); } ); ``` + ### delete9+ -### remove - -remove(): Promise<boolean> +delete(): 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) => { + downloadTask.delete().then((result) => { if (result) { console.info('Download task removed.'); } else { @@ -1235,31 +1212,26 @@ Removes this download task. This API uses a promise to return the result. ``` -### remove +### delete9+ -remove(callback: AsyncCallback<boolean>): void +delete(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)=>{ + downloadTask.delete((err, result)=>{ if(err) { console.error('Failed to remove the download task.'); return; @@ -1273,31 +1245,26 @@ Removes this download task. This API uses an asynchronous callback to return the ``` -### query7+ +### getTaskInfo9+ -query(): Promise<DownloadInfo> +getTaskInfo(): 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 **Return value** - | 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** - + ```js - let downloadTask; - downloadTask.query().then((downloadInfo) => { + 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) @@ -1305,31 +1272,26 @@ Queries this download task. This API uses a promise to return the result. ``` -### query7+ +### getTaskInfo9+ -query(callback: AsyncCallback<DownloadInfo>): void +getTaskInfo(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)=>{ + downloadTask.getTaskInfo((err, downloadInfo)=>{ if(err) { console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); } else { @@ -1339,15 +1301,11 @@ Queries this download task. This API uses an asynchronous callback to return the ``` -### queryMimeType7+ - -queryMimeType(): Promise<string> +### getTaskMimeType9+ -Queries the **MimeType** of this download task. This API uses a promise to return the result. +getTaskMimeType(): Promise<string> -> **NOTE** -> -> This API is deprecated since API version 9. You are advised to use [getTaskMimeType9+](#gettaskmimetype9). +Obtains the **MimeType** of this download task. This API uses a promise to return the result. **Required permissions**: ohos.permission.INTERNET @@ -1355,15 +1313,14 @@ Queries the **MimeType** of this download task. This API uses a promise to retur **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) => { + 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)) @@ -1371,15 +1328,11 @@ Queries the **MimeType** of this download task. This API uses a promise to retur ``` -### queryMimeType7+ - -queryMimeType(callback: AsyncCallback<string>): void; +### getTaskMimeType9+ -Queries the **MimeType** of this download task. This API uses an asynchronous callback to return the result. +getTaskMimeType(callback: AsyncCallback<string>): void; -> **NOTE** -> -> This API is deprecated since API version 9. You are advised to use [getTaskMimeType9+](#gettaskmimetype9-1). +Obtains the **MimeType** of this download task. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERNET @@ -1387,15 +1340,14 @@ Queries the **MimeType** of this download task. This API uses an asynchronous ca **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)=>{ + downloadTask.getTaskMimeType((err, data)=>{ if(err) { console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); } else { @@ -1405,31 +1357,26 @@ Queries the **MimeType** of this download task. This API uses an asynchronous ca ``` -### pause7+ +### suspend9+ -pause(): Promise<void> +suspend(): Promise<boolean> 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<boolean> | Promise used to return the download task pause result.| **Example** - + ```js - let downloadTask; - downloadTask.pause().then((result) => { + downloadTask.suspend().then((result) => { if (result) { console.info('Download task paused. '); } else { @@ -1441,13 +1388,9 @@ Pauses this download task. This API uses a promise to return the result. ``` -### pause7+ - -pause(callback: AsyncCallback<void>): void +### suspend9+ -> **NOTE** -> -> This API is deprecated since API version 9. You are advised to use [suspend9+](#suspend9-1). +suspend(callback: AsyncCallback<boolean>): void Pauses this download task. This API uses an asynchronous callback to return the result. @@ -1457,15 +1400,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<boolean> | Yes| Callback used to return the result.| **Example** - + ```js - let downloadTask; - downloadTask.pause((err, result)=>{ + downloadTask.suspend((err, result)=>{ if(err) { console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); return; @@ -1479,31 +1421,26 @@ Pauses this download task. This API uses an asynchronous callback to return the ``` -### resume7+ +### restore9+ -resume(): Promise<void> +restore(): Promise<boolean> 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.| +| Type| Description| +| -------- | -------- | +| Promise<boolean> | Promise used to return the result.| **Example** - + ```js - let downloadTask; - downloadTask.resume().then((result) => { + downloadTask.restore().then((result) => { if (result) { console.info('Download task resumed.') } else { @@ -1516,13 +1453,9 @@ Resumes this download task. This API uses a promise to return the result. ``` -### resume7+ - -resume(callback: AsyncCallback<void>): void +### restore9+ -> **NOTE** -> -> This API is deprecated since API version 9. You are advised to use [restore9+](#restore9-1). +restore(callback: AsyncCallback<boolean>): void Resumes this download task. This API uses an asynchronous callback to return the result. @@ -1532,15 +1465,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.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| **Example** - + ```js - let downloadTask; - downloadTask.resume((err, result)=>{ + downloadTask.restore((err, result)=>{ if (err) { console.error('Failed to resume the download task. Cause:' + err); return; @@ -1554,11 +1486,16 @@ Resumes this download task. This API uses an asynchronous callback to return the ``` -### delete9+ -delete(): Promise<boolean> +### remove(deprecated) -Deletes this download task. This API uses a promise to return the result. +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 @@ -1567,14 +1504,13 @@ Deletes this download task. This API uses a promise to return the result. **Return value** | Type| Description| - | -------- | -------- | -| Promise<boolean> | Promise used to return the result.| +| -------- | -------- | +| Promise<boolean> | Promise used to return the task removal result.| **Example** ```js - let downloadTask; - downloadTask.delete().then((result) => { + downloadTask.remove().then((result) => { if (result) { console.info('Download task removed.'); } else { @@ -1586,11 +1522,15 @@ Deletes this download task. This API uses a promise to return the result. ``` -### delete9+ +### remove(deprecated) -delete(callback: AsyncCallback<boolean>): void +remove(callback: AsyncCallback<boolean>): void -Deletes this download task. This API uses an asynchronous callback to return the result. +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 @@ -1599,14 +1539,13 @@ Deletes this download task. This API uses an asynchronous callback to return the **Parameters** | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<boolean> | Yes| Callback used to return the task removal result.| **Example** ```js - let downloadTask; - downloadTask.delete((err, result)=>{ + downloadTask.remove((err, result)=>{ if(err) { console.error('Failed to remove the download task.'); return; @@ -1620,12 +1559,16 @@ Deletes this download task. This API uses an asynchronous callback to return the ``` -### getTaskInfo9+ +### query(deprecated) -getTaskInfo(): Promise<DownloadInfo> +query(): Promise<DownloadInfo> Queries this download task. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [getTaskInfo9+](#gettaskinfo9). + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Download @@ -1639,8 +1582,7 @@ Queries this download task. This API uses a promise to return the result. **Example** ```js - let downloadTask; - downloadTask.getTaskInfo().then((downloadInfo) => { + downloadTask.query().then((downloadInfo) => { console.info('Download task queried. Data:' + JSON.stringify(downloadInfo)) }) .catch((err) => { console.error('Failed to query the download task. Cause:' + err) @@ -1648,12 +1590,16 @@ Queries this download task. This API uses a promise to return the result. ``` -### getTaskInfo9+ +### query(deprecated) query(callback: AsyncCallback<DownloadInfo>): void Queries this download task. This API uses an asynchronous callback to return the result. +> **NOTE** +> +> This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [getTaskInfo9+](#gettaskinfo9-1). + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Download @@ -1661,14 +1607,13 @@ Queries this download task. This API uses an asynchronous callback to return the **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)=>{ + downloadTask.query((err, downloadInfo)=>{ if(err) { console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); } else { @@ -1678,11 +1623,15 @@ Queries this download task. This API uses an asynchronous callback to return the ``` -### getTaskMimeType9+ +### queryMimeType(deprecated) -getTaskMimeType(): Promise<string> +queryMimeType(): Promise<string> -Obtains the **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. + +> **NOTE** +> +> This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [getTaskMimeType9+](#gettaskmimetype9). **Required permissions**: ohos.permission.INTERNET @@ -1691,14 +1640,13 @@ Obtains the **MimeType** of this download task. This API uses a promise to retur **Return value** | Type| Description| - | -------- | -------- | +| -------- | -------- | | Promise<string> | Promise used to return the **MimeType** of the download task.| **Example** ```js - let downloadTask; - downloadTask.getTaskMimeType().then((data) => { + downloadTask.queryMimeType().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)) @@ -1706,11 +1654,15 @@ Obtains the **MimeType** of this download task. This API uses a promise to retur ``` -### getTaskMimeType9+ +### queryMimeType(deprecated) -getTaskMimeType(callback: AsyncCallback<string>): void; +queryMimeType(callback: AsyncCallback<string>): void; -Obtains the **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. + +> **NOTE** +> +> This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [getTaskMimeType9+](#gettaskmimetype9-1). **Required permissions**: ohos.permission.INTERNET @@ -1719,14 +1671,13 @@ Obtains the **MimeType** of this download task. This API uses an asynchronous ca **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)=>{ + downloadTask.queryMimeType((err, data)=>{ if(err) { console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); } else { @@ -1736,12 +1687,16 @@ Obtains the **MimeType** of this download task. This API uses an asynchronous ca ``` -### suspend9+ +### pause(deprecated) -suspend(): Promise<boolean> +pause(): Promise<void> Pauses this download task. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [suspend9+](#suspend9). + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Download @@ -1749,14 +1704,13 @@ Pauses this download task. This API uses a promise to return the result. **Return value** | Type| Description| - | -------- | -------- | -| Promise<boolean> | Promise used to return the download task pause result.| +| -------- | -------- | +| Promise<void> | Promise used to return the download task pause result.| **Example** ```js - let downloadTask; - downloadTask.suspend().then((result) => { + downloadTask.pause().then((result) => { if (result) { console.info('Download task paused. '); } else { @@ -1768,9 +1722,13 @@ Pauses this download task. This API uses a promise to return the result. ``` -### suspend9+ +### pause(deprecated) -suspend(callback: AsyncCallback<boolean>): void +pause(callback: AsyncCallback<void>): void + +> **NOTE** +> +> This API is supported since API version 7 and 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. @@ -1781,14 +1739,13 @@ Pauses this download task. This API uses an asynchronous callback to return the **Parameters** | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Example** ```js - let downloadTask; - downloadTask.suspend((err, result)=>{ + downloadTask.pause((err, result)=>{ if(err) { console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); return; @@ -1802,12 +1759,16 @@ Pauses this download task. This API uses an asynchronous callback to return the ``` -### restore9+ +### resume(deprecated) -restore(): Promise<boolean> +resume(): Promise<void> Resumes this download task. This API uses a promise to return the result. +> **NOTE** +> +> This API is supported since API version 7 and is deprecated since API version 9. You are advised to use [restore9+](#restore9). + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.MiscServices.Download @@ -1815,14 +1776,13 @@ Resumes this download task. This API uses a promise to return the result. **Return value** | Type| Description| - | -------- | -------- | -| Promise<boolean> | Promise used to return the result.| +| -------- | -------- | +| Promise<void> | Promise used to return the result.| **Example** ```js - let downloadTask; - downloadTask.restore().then((result) => { + downloadTask.resume().then((result) => { if (result) { console.info('Download task resumed.') } else { @@ -1835,9 +1795,13 @@ Resumes this download task. This API uses a promise to return the result. ``` -### restore9+ +### resume(deprecated) -restore(callback: AsyncCallback<boolean>): void +resume(callback: AsyncCallback<void>): void + +> **NOTE** +> +> This API is supported since API version 7 and 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. @@ -1848,14 +1812,13 @@ Resumes this download task. This API uses an asynchronous callback to return the **Parameters** | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Example** ```js - let downloadTask; - downloadTask.restore((err, result)=>{ + downloadTask.resume((err, result)=>{ if (err) { console.error('Failed to resume the download task. Cause:' + err); return;