From 13aca8bea6aabb06b5e363cc2c3e5564cdd40381 Mon Sep 17 00:00:00 2001 From: "ester.zhou" Date: Tue, 21 Feb 2023 12:00:25 +0800 Subject: [PATCH] Update docs (14074) Signed-off-by: ester.zhou --- .../reference/apis/js-apis-request.md | 187 ++---------------- .../changelogs-request.md | 42 ++++ 2 files changed, 53 insertions(+), 176 deletions(-) create mode 100644 en/release-notes/changelogs/OpenHarmony_3.2.10.6/changelogs-request.md diff --git a/en/application-dev/reference/apis/js-apis-request.md b/en/application-dev/reference/apis/js-apis-request.md index ff95e4da7e..ec609543eb 100644 --- a/en/application-dev/reference/apis/js-apis-request.md +++ b/en/application-dev/reference/apis/js-apis-request.md @@ -286,95 +286,6 @@ Uploads files. This API uses an asynchronous callback to return the result. }); ``` -## request.upload(deprecated) - -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 - -**Parameters** - -| 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.| - -**Example** - - ```js - let uploadTask; - let uploadConfig = { - 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) => { - uploadTask = data; - }).catch((err) => { - console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); - }); - ``` - - -## request.upload(deprecated) - -upload(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void - -Uploads files. This API uses an asynchronous callback to return the result. - -> **NOTE** -> -> This API is deprecated since API version 9. You are advised to use [request.uploadFile9+](#requestuploadfile9-1). - -**Required permissions**: ohos.permission.INTERNET - -**System capability**: SystemCapability.MiscServices.Upload - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| context | [BaseContext](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.| - -**Example** - - ```js - let uploadTask; - let uploadConfig = { - 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) => { - 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 through [request.uploadFile9+](#requestuploadfile9) in promise mode or [request.uploadFile9+](#requestuploadfile9-1) in callback mode. @@ -398,7 +309,7 @@ Subscribes to an upload event. This API uses an asynchronous callback to return | type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (upload progress).| | callback | function | Yes| Callback for the upload progress event.| -Parameters of the callback function + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | @@ -432,7 +343,7 @@ Subscribes to an upload event. This API uses an asynchronous callback to return | type | string | Yes| Type of the event to subscribe to. The value is **'headerReceive'** (response header).| | callback | function | Yes| Callback for the HTTP Response Header event.| -Parameters of the callback function + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | @@ -465,7 +376,7 @@ Subscribes to an upload event. This API uses an asynchronous callback to return | type | string | Yes| Type of the event to subscribe to. The value **'complete'** means the upload completion event, and **'fail'** means the upload failure event.| | callback | Callback<Array<TaskState>> | Yes| Callback used to return the result.| -Parameters of the callback function + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | @@ -507,7 +418,7 @@ Unsubscribes from an upload event. This API uses an asynchronous callback to ret | type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (upload progress).| | callback | function | No| Callback for the upload progress event.| -Parameters of the callback function + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | @@ -541,7 +452,7 @@ Unsubscribes from an upload event. This API uses an asynchronous callback to ret | type | string | Yes| Type of the event to unsubscribe from. The value is **'headerReceive'** (response header).| | callback | function | No| Callback for the HTTP Response Header event.| -Parameters of the callback function + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | @@ -573,7 +484,7 @@ Unsubscribes from an upload event. This API uses an asynchronous callback to ret | type | string | Yes| Type of the event to subscribe to. The value **'complete'** means the upload completion event, and **'fail'** means the upload failure event.| | callback | Callback<Array<TaskState>> | No| Callback used to return the result.| -Parameters of the callback function + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | @@ -952,82 +863,6 @@ Downloads files. This API uses an asynchronous callback to return the result. }); ``` -## request.download(deprecated) - -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 - -**Parameters** - -| 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.| - -**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.download(deprecated) - -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 - -**Parameters** - -| 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.| - -**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. 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. @@ -1050,7 +885,7 @@ Subscribes to a download event. This API uses an asynchronous callback to return | 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 + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | @@ -1084,7 +919,7 @@ Unsubscribes from a download event. This API uses an asynchronous callback to re | type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (download progress).| | callback | function | No| Callback for the download progress event.| -Parameters of the callback function + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | @@ -1172,7 +1007,7 @@ Subscribes to the download task failure event. This API uses an asynchronous cal | type | string | Yes| Type of the event to subscribe to. The value is **'fail'** (download failure).| | callback | function | Yes| Callback for the download task failure event.| -Parameters of the callback function + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | @@ -1205,7 +1040,7 @@ Unsubscribes from the download task failure event. This API uses an asynchronous | type | string | Yes| Type of the event to unsubscribe from. The value is **'fail'** (download failure).| | callback | function | No| Callback for the download task failure event.| -Parameters of the callback function + Parameters of the callback function | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | @@ -1265,7 +1100,7 @@ Deletes this download task. This API uses an asynchronous callback to return the | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the task deletion result. | +| callback | AsyncCallback<boolean> | Yes| Callback used to return the task deletion result.| **Example** diff --git a/en/release-notes/changelogs/OpenHarmony_3.2.10.6/changelogs-request.md b/en/release-notes/changelogs/OpenHarmony_3.2.10.6/changelogs-request.md new file mode 100644 index 0000000000..f5d0e2eb98 --- /dev/null +++ b/en/release-notes/changelogs/OpenHarmony_3.2.10.6/changelogs-request.md @@ -0,0 +1,42 @@ +# Upload and Download Subsystem Changelog + + +## cl.request.2 request API Change + +Deleted the beta APIs in API version 9: + +1. function download(context: BaseContext, config: DownloadConfig, callback: AsyncCallback\): void; +2. function download(context: BaseContext, config: DownloadConfig): Promise\; +3. function upload(context: BaseContext, config: UploadConfig, callback: AsyncCallback\): void; +4. function upload(context: BaseContext, config: UploadConfig): Promise\; + +**Change Impact** + +The application developed based on an earlier version in the stage model needs to be adapted to the new APIs. Otherwise, the original service logic will be affected. + +**Key API/Component Changes** + +| Module | Class | Method/Attribute/Enum/Constant | Change Type| +|--------------|--------------|-------------------------------------------------------------------------------------------------------------------|------| +| ohos.request | request | function download(context: BaseContext, config: DownloadConfig, callback: AsyncCallback\): void; | Deleted | +| ohos.request | request | function download(context: BaseContext, config: DownloadConfig): Promise\; | Deleted | +| ohos.request | request | function upload(context: BaseContext, config: UploadConfig, callback: AsyncCallback\): void; | Deleted | +| ohos.request | request | function upload(context: BaseContext, config: UploadConfig): Promise\; | Deleted | + +**Adaptation Guide** + +Call the new APIs. The following uses **downloadFile** as an example to show how it is called in the new version: + +```ts +try { + request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxxx.hap', + filePath: 'xxx/xxxxx.hap'}, (err, data) => { + if (err) { + console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); + return; + } + }); +} catch (err) { + console.log("downloadFile callback fail." + "errCode:" + err.code + ",errMessage:" + err.message); +} +``` -- GitLab