diff --git a/en/application-dev/reference/apis/js-apis-system-request.md b/en/application-dev/reference/apis/js-apis-system-request.md index 18b94b676942abb856fa9bd709c1898a6f98588d..a2b939bf7d0983a25202fe11b7c5dd4ddd9d3665 100644 --- a/en/application-dev/reference/apis/js-apis-system-request.md +++ b/en/application-dev/reference/apis/js-apis-system-request.md @@ -1,9 +1,11 @@ -# Uploading and Downloading +# @system.request -> ![icon-note.gif](public_sys-resources/icon-note.gif) **Noteļ¼š** -> - The APIs of this module are no longer maintained since API version 6. It is recommended that you use [`@ohos.request`](js-apis-request.md) instead. +The **system.request** module provides applications with basic upload and download capabilities. + +> **NOTE** +> - The APIs of this module are deprecated since API version 9. You are advised to use [`@ohos.request`](js-apis-request.md) instead. > -> - The initial APIs of this module are supported since API version 4. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import @@ -13,179 +15,245 @@ import request from '@system.request'; ``` -## Required Permissions +## request.upload -ohos.permission.INTERNET. +upload(options: UploadRequestOptions): void +Uploads a file. This API returns no value. -## request.upload +**System capability**: SystemCapability.MiscServices.Upload -upload(Object): void +**Parameters** -Uploads files. + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | options | [UploadRequestOptions](#uploadrequestoptions) | Yes| Upload configurations.| -**Parameters** +**Example** -| Name | Type | Mandatory | Description | -| -------- | -------- | -------- | -------- | -| url | string | Yes | URL of the upload server. | -| header | Object | No | Request header. | -| method | string | No | Request methods available: **POST** and **PUT**. The default value is **POST**. | -| files | Array<File> | Yes | List of files to upload, which is submitted through **multipart/form-data**. | -| data | Array<RequestData> | No | Form data in the request body. | -| success | Function | No | Called when the download task is complete. | -| fail | Function | No | Called when downloading fails or the task does not exist. | -| complete | Function | No | Called when the execution is complete. | + ```js + let uploadRequestOptions = { + url: 'http://www.path.com', + method: 'POST', + files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], + data: [{ name: "name123", value: "123" }], + success: function(data) { + console.info(' upload success, code:' + JSON.stringify(data)); + }, + fail: function(data, code) { + console.info(' upload fail data: ' + data + 'code: ' + code); + }, + complete: function (){ + console.info(' upload complete'); + } + } + try { + request.upload(uploadRequestOptions); + console.info('upload start '); + } catch(err) { + console.info(' upload err:' + err); + } + ``` -**Table 1** File -| 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 storage path of a file. | -| type | string | No | Type of the file content. By default, the type is obtained based on the suffix of the file name or URI. | +## UploadRequestOptions -**Table 2** RequestData +**System capability**: SystemCapability.MiscServices.Upload -| Name | Type | Mandatory | Description | -| -------- | -------- | -------- | -------- | -| name | string | Yes | Name of the form element | -| value | string | Yes | Value of the form element | -When the files are successfully uploaded, the following values will be returned. + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | url | string | Yes| URL of the upload server.| + | data | Array<[RequestData](#requestdata)> | No| Form data in the request body.| + | files | Array<[RequestFile](#requestfile)> | Yes| List of files to upload, which is submitted through **multipart/form-data**.| + | header | Object | No| Request header.| + | method | string | No| Request method, which can be **'POST'** or **'PUT'**. The default value is **POST**.| + | success | Function | No| Called when API call is successful.| + | fail | Function | No| Called when API call has failed.| + | complete | Function | No| Called when API call is complete.| -| Name | Type | Description | -| -------- | -------- | -------- | -| code | number | HTTP status code returned by the server. | -| data | string | Content returned by the server. The value type is determined by the type in the returned headers. | -| headers | Object | Headers returned by the server. | +**success parameter** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | data | [UploadResponse](#uploadresponse) | Yes| Information returned when the upload task is successful.| -When the files fail to be uploaded, an HTTP status code is returned in **code** of **data**. +**fail parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | data | any | Yes| Header information returned when the upload task fails.| + | code | number | Yes| HTTP status code returned when the upload task fails.| -**Example** -``` -export default { - upLoad() { - request.upload({ - url: 'http://www.path.com', - files: [ - { - uri: 'internal://cache/path/to/file.txt', - name: 'file', - filename: 'file.txt', - }, - ], - data:[ - { - name: 'name1', - value: 'value', - }, - ], - success: function(data) { - console.log('upload success, code:' + data.code); - }, - fail: function() { - console.log('upload fail'); - }, - }); - } -} -``` +## UploadResponse -## request.download +**System capability**: SystemCapability.MiscServices.Upload -download(Object): void + | Name| Type| Description| + | -------- | -------- | -------- | + | code | number | HTTP status code returned by the server.| + | data | string | Content returned by the server. The value type is determined by the type in the returned headers.| + | headers | Object | Headers returned by the server.| -Downloads files. -**Parameters** +## RequestFile + +**System capability**: SystemCapability.MiscServices.Upload + + | 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.| + | 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 -| Name | Type | Mandatory | Description | -| -------- | -------- | -------- | -------- | -| url | string | Yes | Resource URL. | -| header | Object | No | Request header. | -| description | string | No | Download description. The default value is the file name. | -| filename | string | No | Name of the file to download. The value is obtained from the current request or resource URL by default. | -| success | Function | No | Called when the download task is complete. | -| fail | Function | No | Called when downloading fails or the task does not exist. | -| complete | Function | No | Called when the execution is complete. | + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | name | string | Yes| Name of the form element.| + | value | string | Yes| Value of the form element.| -Return values of the **success** callback -| Name | Type | Description | -| -------- | -------- | -------- | -| token | string | Download token, which is used to obtain the download status. | -One of the following error codes will be returned if the operation fails. +## request.download + +download(options: DownloadRequestOptions): void + +Downloads a file. This API returns no value. + +**System capability**: SystemCapability.MiscServices.Download + +**Parameters** -| Error Code | Description | -| -------- | -------- | -| 400 | Download task failed | + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | options | [DownloadRequestOptions](#downloadrequestoptions) | Yes| Download configurations.| **Example** -``` -export default { - downLoad() { - request.download({ - url: 'http://www.path.com', - success: function(data) { - console.log('call success callback success: ' + data.token); - }, - fail: function(data, code) { - console.log('handling fail'); - }, - }); + ```js + let downloadRequestOptions = { + url: 'http://www.path.com', + filename: 'requestSystenTest', + header: '', + description: 'this is requeSystem download response', + success: function(data) { + console.info(' download success, code:' + JSON.stringify(data)); + }, + fail: function(data, code) { + console.info(' download fail data: ' + data + 'code: ' + code); + }, + complete: function (){ + console.info(' download complete'); + } } -} -``` + try { + request.download(downloadRequestOptions); + console.info('download start '); + } catch(err) { + console.info(' download err:' + err); + } + ``` -## request.onDownloadComplete +## DownloadRequestOptions -onDownloadComplete(Object): void +**System capability**: SystemCapability.MiscServices.Download -Listens to download task status. + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | url | string | Yes| Resource URL.| + | filename | string | No| Name of the file to download. The value is obtained from the current request or resource URL by default.| + | header | Object | No| Request header.| + | description | string | No| Download description. The default value is the file name.| + | success | Function | No| Called when API call is successful.| + | fail | Function | No| Called when API call has failed.| + | complete | Function | No| Called when API call is complete.| -**Parameters** +**success parameter** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | data | [DownloadResponse](#downloadresponse) | Yes| Information returned when the download task is successful.| + +**fail parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | data | any | Yes| Header information returned when the download task fails.| + | code | number | Yes| HTTP status code returned when the download task fails.| + +## DownloadResponse + +**System capability**: SystemCapability.MiscServices.Download + + | Name| Type| Description| + | -------- | -------- | -------- | + | token | string | Download token, which is used to obtain the download status| + + +## request.onDownloadComplete -| Name | Type | Mandatory | Description | -| -------- | -------- | -------- | -------- | -| token | string | Yes | Token of the result returned by the download method | -| success | Function | No | Called when the download task is complete. | -| fail | Function | No | Called when downloading fails or the task does not exist. | -| complete | Function | No | Called when the execution is complete. | +onDownloadComplete(options: OnDownloadCompleteOptions): void -Return values of the **success** callback +Listens for download task status. This API returns no value. -| Name | Type | Description | -| -------- | -------- | -------- | -| uri | string | URI of the download file | +**System capability**: SystemCapability.MiscServices.Download -One of the following error codes will be returned if the listening fails. +**Parameters** -| Error Code | Description | -| -------- | -------- | -| 400 | Download task failed | -| 401 | Download task not exist | + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | options | [OnDownloadCompleteOptions](#ondownloadcompleteoptions) | Yes| Configurations of the download task.| **Example** -``` -export default { - onDownloadComplete() { - request.onDownloadComplete({ - token: 'token-index', - success: function(data) { - console.log('download success, uri:' + data.uri); - }, - fail: function(data, code) { - console.log('download fail'); - }, - }); + ```js + let onDownloadCompleteOptions = { + token: 'token-index', + success: function(data) { + console.info(' download success, code:' + JSON.stringify(data)); + }, + fail: function(data, code) { + console.info(' download fail data: ' + data + 'code: ' + code); + }, + complete: function (){ + console.info(' download complete'); + } } -} -``` \ No newline at end of file + request.onDownloadComplete(onDownloadCompleteOptions); + ``` + + +## OnDownloadCompleteOptions + +**System capability**: SystemCapability.MiscServices.Download + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | token | string | Yes| Result token returned by the download API.| + | success | Function | No| Called when API call is successful.| + | fail | Function | No| Called when API call has failed.| + | complete | Function | No| Called when API call is complete.| + +**success parameter** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | data | [OnDownloadCompleteResponse](#ondownloadcompleteresponse) | Yes| Information returned when the download task is successful.| + +**fail parameters** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | data | any | Yes| Header information returned when the download task fails.| + | code | number | Yes| HTTP status code returned when the download task fails.| + + +## OnDownloadCompleteResponse + +**System capability**: SystemCapability.MiscServices.Download + + | Name| Type| Description| + | -------- | -------- | -------- | + | uri | string | URI of the download file.|