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