Skip to content

Commit 8d6903a

Browse files
OS-pedrogustavobilroOS-pedrogustavobilro
authored
docs: Clarify input options + add examples (#29)
* docs: Explicitly document which paramters of `HttpOptions` are used. References: https://outsystemsrd.atlassian.net/browse/IONIC-52 * docs: Notes on `HttpOptions` and error codes * docs: Add example usage section * docs: mention Filesystem plugin for getting path References: https://outsystemsrd.atlassian.net/browse/IONIC-52 * docs: Add note about chunkedMode and http headers References: #10 * chore: minor update on example code * chore: fix lint issues
1 parent 0b2f319 commit 8d6903a

File tree

3 files changed

+280
-13
lines changed

3 files changed

+280
-13
lines changed

‎README.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,68 @@ npm install @capacitor/file-transfer
2626
npx cap sync
2727
```
2828

29+
## Example
30+
31+
### Download
32+
33+
```typescript
34+
import { FileTransfer } from '@capacitor/file-transfer';
35+
import { Filesystem, Directory } from '@capacitor/filesystem';
36+
37+
// First get the full file path using Filesystem
38+
const fileInfo = await Filesystem.getUri({
39+
directory: Directory.Data,
40+
path: 'downloaded-file.pdf'
41+
});
42+
43+
try {
44+
// Then use the FileTransfer plugin to download
45+
await FileTransfer.downloadFile({
46+
url: 'https://example.com/file.pdf',
47+
path: fileInfo.uri,
48+
progress: true
49+
});
50+
} catch(error) {
51+
// handle error - see `FileTransferError` interface for what error information is returned
52+
}
53+
54+
// Progress events
55+
FileTransfer.addListener('progress', (progress) => {
56+
console.log(`Downloaded ${progress.bytes} of ${progress.contentLength}`);
57+
});
58+
```
59+
60+
### Upload
61+
62+
```typescript
63+
import { FileTransfer } from '@capacitor/file-transfer';
64+
import { Filesystem, Directory } from '@capacitor/filesystem';
65+
66+
// First get the full file path using Filesystem
67+
const fileInfo = await Filesystem.getUri({
68+
directory: Directory.Cache,
69+
path: 'image_upload.png'
70+
});
71+
72+
try {
73+
// Then use the FileTransfer plugin to upload
74+
const result = await FileTransfer.downloadFile({
75+
url: 'https://example.com/upload_api',
76+
path: fileInfo.uri,
77+
chunkedMode: true,
78+
headers: {
79+
// Upload uses `multipart/form-data` by default.
80+
// If you want to avoid that, you can set the 'Content-Type' header explicitly.
81+
'Content-Type': 'application/octet-stream',
82+
},
83+
progress: false
84+
});
85+
// get server response and other info from result - see `UploadFileResult` interface
86+
} catch(error) {
87+
// handle error - see `FileTransferError` interface for what error information is returned
88+
}
89+
```
90+
2991
## Documentation
3092

3193
Refer to [this page](packages/capacitor-plugin/README.md).

‎packages/capacitor-plugin/README.md‎

Lines changed: 101 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,69 @@ npm install @capacitor/file-transfer
99
npx cap sync
1010
```
1111

12+
## Example
13+
14+
### Download
15+
16+
```typescript
17+
import { FileTransfer } from '@capacitor/file-transfer';
18+
import { Filesystem, Directory } from '@capacitor/filesystem';
19+
20+
// First get the full file path using Filesystem
21+
const fileInfo = await Filesystem.getUri({
22+
directory: Directory.Data,
23+
path: 'downloaded-file.pdf'
24+
});
25+
26+
try {
27+
// Then use the FileTransfer plugin to download
28+
await FileTransfer.downloadFile({
29+
url: 'https://example.com/file.pdf',
30+
path: fileInfo.uri,
31+
progress: true
32+
});
33+
} catch(error) {
34+
// handle error - see `FileTransferError` interface for what error information is returned
35+
}
36+
37+
// Progress events
38+
FileTransfer.addListener('progress', (progress) => {
39+
console.log(`Downloaded ${progress.bytes} of ${progress.contentLength}`);
40+
});
41+
```
42+
43+
### Upload
44+
45+
```typescript
46+
import { FileTransfer } from '@capacitor/file-transfer';
47+
import { Filesystem, Directory } from '@capacitor/filesystem';
48+
49+
// First get the full file path using Filesystem
50+
const fileInfo = await Filesystem.getUri({
51+
directory: Directory.Cache,
52+
path: 'image_upload.png'
53+
});
54+
55+
try {
56+
// Then use the FileTransfer plugin to upload
57+
const result = await FileTransfer.downloadFile({
58+
url: 'https://example.com/upload_api',
59+
path: fileInfo.uri,
60+
chunkedMode: true,
61+
headers: {
62+
// Upload uses `multipart/form-data` by default.
63+
// If you want to avoid that, you can set the 'Content-Type' header explicitly.
64+
'Content-Type': 'application/octet-stream',
65+
},
66+
progress: false
67+
});
68+
// get server response and other info from result - see `UploadFileResult` interface
69+
} catch(error) {
70+
// handle error - see `FileTransferError` interface for what error information is returned
71+
}
72+
```
73+
74+
1275
## API
1376

1477
<docgen-index>
@@ -21,6 +84,10 @@ npx cap sync
2184

2285
</docgen-index>
2386

87+
Note: Some of the input options come from `HttpOptions` in `@capacitor/core`, but the plugin does not use all parameters from `HttpOptions`. The ones that are used are documented below.
88+
89+
For list of existing error codes, see [Errors](#errors).
90+
2491
<docgen-api>
2592
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
2693

@@ -108,10 +175,24 @@ Remove all listeners for this plugin.
108175

109176
#### DownloadFileOptions
110177

111-
| Prop | Type | Description | Since |
112-
| -------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
113-
| **`path`** | <code>string</code> | The full file path the downloaded file should be moved to. | 1.0.0 |
114-
| **`progress`** | <code>boolean</code> | If true, progress event will be dispatched on every chunk received. See addListener() for more information. Chunks are throttled to every 100ms on Android/iOS to avoid slowdowns. | 1.0.0 |
178+
| Prop | Type | Description | Since |
179+
| --------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
180+
| **`url`** | <code>string</code> | The URL to download the file from. | 1.0.0 |
181+
| **`path`** | <code>string</code> | The full file path the downloaded file should be moved to. You may use a plugin like `@capacitor/filesystem` to get a complete file path. | 1.0.0 |
182+
| **`progress`** | <code>boolean</code> | If true, progress event will be dispatched on every chunk received. See addListener() for more information. Chunks are throttled to every 100ms on Android/iOS to avoid slowdowns. Default is `false`. | 1.0.0 |
183+
| **`method`** | <code>string</code> | The Http Request method to run. (Default is GET) | 1.0.0 |
184+
| **`params`** | <code><a href="#httpparams">HttpParams</a></code> | URL parameters to append to the request. This <a href="#httpparams">`HttpParams`</a> interface comes from `@capacitor/core`. | 1.0.0 |
185+
| **`headers`** | <code><a href="#httpheaders">HttpHeaders</a></code> | Http Request headers to send with the request. This <a href="#httpheaders">`HttpHeaders`</a> interface comes from `@capacitor/core`. | 1.0.0 |
186+
| **`readTimeout`** | <code>number</code> | How long to wait to read additional data in milliseconds. Resets each time new data is received. Default is 60,000 milliseconds (1 minute). Not supported on web. | 1.0.0 |
187+
| **`connectTimeout`** | <code>number</code> | How long to wait for the initial connection in milliseconds. Default is 60,000 milliseconds (1 minute). In iOS, there's no real distinction between `connectTimeout`and `readTimeout`. Plugin tries to use `connectTimeout`, if not uses `readTimeout`, if not uses default | 1.0.0 |
188+
| **`disableRedirects`** | <code>boolean</code> | Sets whether automatic HTTP redirects should be disabled | 1.0.0 |
189+
| **`shouldEncodeUrlParams`** | <code>boolean</code> | Use this option if you need to keep the URL unencoded in certain cases (already encoded, azure/firebase testing, etc.). The default is `true`. Not supported on web. | 1.0.0 |
190+
191+
192+
#### HttpParams
193+
194+
195+
#### HttpHeaders
115196

116197

117198
#### UploadFileResult
@@ -126,14 +207,22 @@ Remove all listeners for this plugin.
126207

127208
#### UploadFileOptions
128209

129-
| Prop | Type | Description | Since |
130-
| ----------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
131-
| **`path`** | <code>string</code> | Full file path of the file to upload. | 1.0.0 |
132-
| **`blob`** | <code>Blob</code> | Blob data to upload. Will use this instead of path if provided. This is only available on web. | 1.0.0 |
133-
| **`chunkedMode`** | <code>boolean</code> | Whether to upload data in a chunked streaming mode. Not supported on web. | 1.0.0 |
134-
| **`mimeType`** | <code>string</code> | Mime type of the data to upload. Only used if "Content-Type" header was not provided. | 1.0.0 |
135-
| **`fileKey`** | <code>string</code> | Type of form element. The default is set to "file". Only used if "Content-Type" header was not provided. | 1.0.0 |
136-
| **`progress`** | <code>boolean</code> | If true, progress event will be dispatched on every chunk received. See addListener() for more information. Chunks are throttled to every 100ms on Android/iOS to avoid slowdowns. | 1.0.0 |
210+
| Prop | Type | Description | Since |
211+
| --------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
212+
| **`url`** | <code>string</code> | The URL to upload the file to. | 1.0.0 |
213+
| **`path`** | <code>string</code> | Full file path of the file to upload. You may use a plugin like `@capacitor/filesystem` to get a complete file path. | 1.0.0 |
214+
| **`blob`** | <code>Blob</code> | Blob data to upload. Will use this instead of path if provided. This is only available on web. | 1.0.0 |
215+
| **`chunkedMode`** | <code>boolean</code> | Whether to upload data in a chunked streaming mode. Not supported on web. Note: The upload uses `Content-Type: multipart/form-data`, when `chunkedMode` is `true`. Depending on your backend server, this can cause the upload to fail. If your server expects a raw stream (e.g. `application/octet-stream`), you must explicitly set the `Content-Type` header in `headers`. | 1.0.0 |
216+
| **`mimeType`** | <code>string</code> | Mime type of the data to upload. Only used if "Content-Type" header was not provided. | 1.0.0 |
217+
| **`fileKey`** | <code>string</code> | Type of form element. The default is set to "file". Only used if "Content-Type" header was not provided. | 1.0.0 |
218+
| **`progress`** | <code>boolean</code> | If true, progress event will be dispatched on every chunk received. See addListener() for more information. Chunks are throttled to every 100ms on Android/iOS to avoid slowdowns. Default is `false`. | 1.0.0 |
219+
| **`method`** | <code>string</code> | The Http Request method to run. (Default is POST) | 1.0.0 |
220+
| **`params`** | <code><a href="#httpparams">HttpParams</a></code> | URL parameters to append to the request. This <a href="#httpparams">`HttpParams`</a> interface comes from `@capacitor/core`. | 1.0.0 |
221+
| **`headers`** | <code><a href="#httpheaders">HttpHeaders</a></code> | Http Request headers to send with the request. This <a href="#httpheaders">`HttpHeaders`</a> interface comes from `@capacitor/core`. | 1.0.0 |
222+
| **`readTimeout`** | <code>number</code> | How long to wait to read additional data in milliseconds. Resets each time new data is received. Default is 60,000 milliseconds (1 minute). Not supported on web. | 1.0.0 |
223+
| **`connectTimeout`** | <code>number</code> | How long to wait for the initial connection in milliseconds. Default is 60,000 milliseconds (1 minute). Not supported on web. In iOS, there's no real distinction between `connectTimeout`and `readTimeout`. Plugin tries to use `connectTimeout`, if not uses `readTimeout`, if not uses default | 1.0.0 |
224+
| **`disableRedirects`** | <code>boolean</code> | Sets whether automatic HTTP redirects should be disabled. Not supported on web. | 1.0.0 |
225+
| **`shouldEncodeUrlParams`** | <code>boolean</code> | Use this option if you need to keep the URL unencoded in certain cases (already encoded, azure/firebase testing, etc.). The default is `true`. Not supported on web. | 1.0.0 |
137226

138227

139228
#### PluginListenerHandle

0 commit comments

Comments
 (0)