1# @system.request (Upload and Download) 2 3The **system.request** module provides applications with basic upload and download capabilities. 4 5> **NOTE** 6> - The APIs of this module are deprecated since API version 9. You are advised to use [@ohos.request](js-apis-request.md) instead. 7> 8> - 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. 9 10 11## Modules to Import 12 13 14``` 15import request from '@system.request'; 16``` 17 18## request.upload 19 20upload(options: UploadRequestOptions): void 21 22Uploads a file. This API returns no value. 23 24**System capability**: SystemCapability.MiscServices.Upload 25 26**Parameters** 27 28| Name| Type| Mandatory| Description| 29| -------- | -------- | -------- | -------- | 30| options | [UploadRequestOptions](#uploadrequestoptions) | Yes| Upload configurations.| 31 32**Example** 33 34 ```js 35 let uploadRequestOptions = { 36 url: 'http://www.path.com', 37 method: 'POST', 38 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 39 data: [{ name: "name123", value: "123" }], 40 success: function(data) { 41 console.info(' upload success, code:' + JSON.stringify(data)); 42 }, 43 fail: function(data, code) { 44 console.info(' upload fail data: ' + data + 'code: ' + code); 45 }, 46 complete: function (){ 47 console.info(' upload complete'); 48 } 49 } 50 try { 51 request.upload(uploadRequestOptions); 52 console.info('upload start '); 53 } catch(err) { 54 console.info(' upload err:' + err); 55 } 56 ``` 57 58 59## UploadRequestOptions 60 61**System capability**: SystemCapability.MiscServices.Upload 62 63 64| Name| Type| Mandatory| Description| 65| -------- | -------- | -------- | -------- | 66| url | string | Yes| URL of the upload server.| 67| data | Array<[RequestData](#requestdata)> | No| Form data in the request body.| 68| files | Array<[RequestFile](#requestfile)> | Yes| List of files to upload, which is submitted through **multipart/form-data**.| 69| header | Object | No| Request header.| 70| method | string | No| Request method, which can be **'POST'** or **'PUT'**. The default value is **POST**.| 71| success | Function | No| Called when API call is successful.| 72| fail | Function | No| Called when API call has failed.| 73| complete | Function | No| Called when API call is complete.| 74 75**success parameter** 76| Name| Type| Mandatory| Description| 77| -------- | -------- | -------- | -------- | 78| data | [UploadResponse](#uploadresponse) | Yes| Information returned when the upload task is successful.| 79 80**fail parameters** 81| Name| Type| Mandatory| Description| 82| -------- | -------- | -------- | -------- | 83| data | any | Yes| Header information returned when the upload task fails.| 84| code | number | Yes| HTTP status code returned when the upload task fails.| 85 86 87 88## UploadResponse 89 90**System capability**: SystemCapability.MiscServices.Upload 91 92| Name| Type| Mandatory| Description| 93| -------- | -------- | -------- | -------- | 94| code | number | Yes| HTTP status code returned by the server.| 95| data | string | Yes| Content returned by the server. The value type is determined by the type in the returned headers.| 96| headers | Object | Yes| Headers returned by the server.| 97 98 99## RequestFile 100 101**System capability**: SystemCapability.MiscServices.Upload 102 103| Name| Type| Mandatory| Description| 104| -------- | -------- | -------- | -------- | 105| filename | string | No| File name in the header when **multipart** is used.| 106| name | string | No| Name of a form item when **multipart** is used. The default value is **file**.| 107| uri | string | Yes| Local path for storing files.| 108| type | string | No| Type of the file content. By default, the type is obtained based on the extension of the file name or URI.| 109 110 111## RequestData 112 113**System capability**: SystemCapability.MiscServices.Upload 114 115| Name| Type| Mandatory| Description| 116| -------- | -------- | -------- | -------- | 117| name | string | Yes| Name of the form element.| 118| value | string | Yes| Value of the form element.| 119 120 121 122## request.download 123 124download(options: DownloadRequestOptions): void 125 126Downloads a file. This API returns no value. 127 128**System capability**: SystemCapability.MiscServices.Download 129 130**Parameters** 131 132| Name| Type| Mandatory| Description| 133| -------- | -------- | -------- | -------- | 134| options | [DownloadRequestOptions](#downloadrequestoptions) | Yes| Download configurations.| 135 136**Example** 137 138 ```js 139 let downloadRequestOptions = { 140 url: 'http://www.path.com', 141 filename: 'requestSystenTest', 142 header: '', 143 description: 'this is requeSystem download response', 144 success: function(data) { 145 console.info(' download success, code:' + JSON.stringify(data)); 146 }, 147 fail: function(data, code) { 148 console.info(' download fail data: ' + data + 'code: ' + code); 149 }, 150 complete: function (){ 151 console.info(' download complete'); 152 } 153 } 154 try { 155 request.download(downloadRequestOptions); 156 console.info('download start '); 157 } catch(err) { 158 console.info(' download err:' + err); 159 } 160 ``` 161 162 163## DownloadRequestOptions 164 165**System capability**: SystemCapability.MiscServices.Download 166 167| Name| Type| Mandatory| Description| 168| -------- | -------- | -------- | -------- | 169| url | string | Yes| Resource URL.| 170| filename | string | No| Name of the file to download. The value is obtained from the current request or resource URL by default.| 171| header | Object | No| Request header.| 172| description | string | No| Download description. The default value is the file name.| 173| success | Function | No| Called when API call is successful.| 174| fail | Function | No| Called when API call has failed.| 175| complete | Function | No| Called when API call is complete.| 176 177**success parameter** 178| Name| Type| Mandatory| Description| 179| -------- | -------- | -------- | -------- | 180| data | [DownloadResponse](#downloadresponse) | Yes| Information returned when the download task is successful.| 181 182**fail parameters** 183| Name| Type| Mandatory| Description| 184| -------- | -------- | -------- | -------- | 185| data | any | Yes| Header information returned when the download task fails.| 186| code | number | Yes| HTTP status code returned when the download task fails.| 187 188## DownloadResponse 189 190**System capability**: SystemCapability.MiscServices.Download 191 192| Name| Type| Mandatory| Description| 193| -------- | -------- | -------- | -------- | 194| token | string | Yes| Download token, which is used to obtain the download status| 195 196 197## request.onDownloadComplete 198 199onDownloadComplete(options: OnDownloadCompleteOptions): void 200 201Listens for download task status. This API returns no value. 202 203**System capability**: SystemCapability.MiscServices.Download 204 205**Parameters** 206 207| Name| Type| Mandatory| Description| 208| -------- | -------- | -------- | -------- | 209| options | [OnDownloadCompleteOptions](#ondownloadcompleteoptions) | Yes| Configurations of the download task.| 210 211**Example** 212 213 ```js 214 let onDownloadCompleteOptions = { 215 token: 'token-index', 216 success: function(data) { 217 console.info(' download success, code:' + JSON.stringify(data)); 218 }, 219 fail: function(data, code) { 220 console.info(' download fail data: ' + data + 'code: ' + code); 221 }, 222 complete: function (){ 223 console.info(' download complete'); 224 } 225 } 226 request.onDownloadComplete(onDownloadCompleteOptions); 227 ``` 228 229 230## OnDownloadCompleteOptions 231 232**System capability**: SystemCapability.MiscServices.Download 233 234| Name| Type| Mandatory| Description| 235| -------- | -------- | -------- | -------- | 236| token | string | Yes| Result token returned by the download API.| 237| success | Function | No| Called when API call is successful.| 238| fail | Function | No| Called when API call has failed.| 239| complete | Function | No| Called when API call is complete.| 240 241**success parameter** 242| Name| Type| Mandatory| Description| 243| -------- | -------- | -------- | -------- | 244| data | [OnDownloadCompleteResponse](#ondownloadcompleteresponse) | Yes| Information returned when the download task is successful.| 245 246**fail parameters** 247| Name| Type| Mandatory| Description| 248| -------- | -------- | -------- | -------- | 249| data | any | Yes| Header information returned when the download task fails.| 250| code | number | Yes| HTTP status code returned when the download task fails.| 251 252 253## OnDownloadCompleteResponse 254 255**System capability**: SystemCapability.MiscServices.Download 256 257| Name| Type| Mandatory| Description| 258| -------- | -------- | -------- | -------- | 259| uri | string | Yes| URI of the download file.| 260
