@simplysm/capacitor-plugin-usb-storage 12.16.29 → 12.16.31
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +152 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
# @simplysm/capacitor-plugin-usb-storage
|
|
2
|
+
|
|
3
|
+
Capacitor plugin for accessing USB Mass Storage devices. Uses the [libaums](https://github.com/magnusja/libaums) library on Android to read files and directories from USB storage.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @simplysm/capacitor-plugin-usb-storage
|
|
9
|
+
npx cap sync
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
### Requirements
|
|
13
|
+
|
|
14
|
+
- `@capacitor/core` ^7.0.0
|
|
15
|
+
|
|
16
|
+
### Platform Support
|
|
17
|
+
|
|
18
|
+
| Platform | Supported |
|
|
19
|
+
|----------|-----------|
|
|
20
|
+
| Android | Yes |
|
|
21
|
+
| Web | Stub only (shows alert) |
|
|
22
|
+
|
|
23
|
+
## API
|
|
24
|
+
|
|
25
|
+
### `UsbStorage`
|
|
26
|
+
|
|
27
|
+
Static utility class for interacting with USB Mass Storage devices.
|
|
28
|
+
|
|
29
|
+
#### `UsbStorage.getDevices()`
|
|
30
|
+
|
|
31
|
+
Returns a list of connected USB Mass Storage devices.
|
|
32
|
+
|
|
33
|
+
**Returns:** `Promise<IUsbDeviceInfo[]>`
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
|
|
37
|
+
|
|
38
|
+
const devices = await UsbStorage.getDevices();
|
|
39
|
+
for (const device of devices) {
|
|
40
|
+
console.log(device.productName, device.vendorId, device.productId);
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
#### `UsbStorage.requestPermission(filter)`
|
|
45
|
+
|
|
46
|
+
Requests access permission for a specific USB device. If permission is already granted, resolves immediately.
|
|
47
|
+
|
|
48
|
+
| Parameter | Type | Description |
|
|
49
|
+
|--------------------|----------|--------------------------|
|
|
50
|
+
| `filter.vendorId` | `number` | USB vendor ID |
|
|
51
|
+
| `filter.productId` | `number` | USB product ID |
|
|
52
|
+
|
|
53
|
+
**Returns:** `Promise<boolean>` -- whether permission was granted.
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
const granted = await UsbStorage.requestPermission({
|
|
57
|
+
vendorId: 1234,
|
|
58
|
+
productId: 5678,
|
|
59
|
+
});
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
#### `UsbStorage.hasPermission(filter)`
|
|
63
|
+
|
|
64
|
+
Checks whether the app already has permission to access a specific USB device.
|
|
65
|
+
|
|
66
|
+
| Parameter | Type | Description |
|
|
67
|
+
|--------------------|----------|--------------------------|
|
|
68
|
+
| `filter.vendorId` | `number` | USB vendor ID |
|
|
69
|
+
| `filter.productId` | `number` | USB product ID |
|
|
70
|
+
|
|
71
|
+
**Returns:** `Promise<boolean>` -- whether permission is held.
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
const hasPerm = await UsbStorage.hasPermission({
|
|
75
|
+
vendorId: 1234,
|
|
76
|
+
productId: 5678,
|
|
77
|
+
});
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
#### `UsbStorage.readdir(filter, dirPath)`
|
|
81
|
+
|
|
82
|
+
Reads the contents of a directory on the USB storage device.
|
|
83
|
+
|
|
84
|
+
| Parameter | Type | Description |
|
|
85
|
+
|--------------------|----------|------------------------------------|
|
|
86
|
+
| `filter.vendorId` | `number` | USB vendor ID |
|
|
87
|
+
| `filter.productId` | `number` | USB product ID |
|
|
88
|
+
| `dirPath` | `string` | Path to the directory to list |
|
|
89
|
+
|
|
90
|
+
**Returns:** `Promise<string[]>` -- file and folder names in the directory.
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
const files = await UsbStorage.readdir(
|
|
94
|
+
{ vendorId: 1234, productId: 5678 },
|
|
95
|
+
"/Documents",
|
|
96
|
+
);
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
#### `UsbStorage.read(filter, filePath)`
|
|
100
|
+
|
|
101
|
+
Reads a file from the USB storage device. The file data is transferred as base64 from the native layer and returned as a `Buffer`.
|
|
102
|
+
|
|
103
|
+
| Parameter | Type | Description |
|
|
104
|
+
|--------------------|----------|------------------------------------|
|
|
105
|
+
| `filter.vendorId` | `number` | USB vendor ID |
|
|
106
|
+
| `filter.productId` | `number` | USB product ID |
|
|
107
|
+
| `filePath` | `string` | Path to the file to read |
|
|
108
|
+
|
|
109
|
+
**Returns:** `Promise<Buffer | undefined>` -- file contents as a Buffer, or `undefined` if the file was not found.
|
|
110
|
+
|
|
111
|
+
```ts
|
|
112
|
+
const data = await UsbStorage.read(
|
|
113
|
+
{ vendorId: 1234, productId: 5678 },
|
|
114
|
+
"/Documents/report.csv",
|
|
115
|
+
);
|
|
116
|
+
if (data != null) {
|
|
117
|
+
const text = data.toString("utf-8");
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### `IUsbDeviceInfo`
|
|
122
|
+
|
|
123
|
+
Device information returned by `getDevices`.
|
|
124
|
+
|
|
125
|
+
| Property | Type | Description |
|
|
126
|
+
|--------------------|----------|--------------------------|
|
|
127
|
+
| `deviceName` | `string` | Android device path |
|
|
128
|
+
| `manufacturerName` | `string` | Manufacturer name |
|
|
129
|
+
| `productName` | `string` | Product name |
|
|
130
|
+
| `vendorId` | `number` | USB vendor ID |
|
|
131
|
+
| `productId` | `number` | USB product ID |
|
|
132
|
+
|
|
133
|
+
### `IUsbDeviceFilter`
|
|
134
|
+
|
|
135
|
+
Filter used to identify a specific USB device.
|
|
136
|
+
|
|
137
|
+
| Property | Type | Description |
|
|
138
|
+
|-------------|----------|----------------|
|
|
139
|
+
| `vendorId` | `number` | USB vendor ID |
|
|
140
|
+
| `productId` | `number` | USB product ID |
|
|
141
|
+
|
|
142
|
+
### `IUsbStoragePlugin`
|
|
143
|
+
|
|
144
|
+
Low-level plugin interface registered via `registerPlugin`. Use the `UsbStorage` class instead for a simpler API.
|
|
145
|
+
|
|
146
|
+
| Method | Signature |
|
|
147
|
+
|---------------------|----------------------------------------------------------------------------------------|
|
|
148
|
+
| `getDevices` | `() => Promise<{ devices: IUsbDeviceInfo[] }>` |
|
|
149
|
+
| `requestPermission` | `(options: IUsbDeviceFilter) => Promise<{ granted: boolean }>` |
|
|
150
|
+
| `hasPermission` | `(options: IUsbDeviceFilter) => Promise<{ granted: boolean }>` |
|
|
151
|
+
| `readdir` | `(options: IUsbDeviceFilter & { path: string }) => Promise<{ files: string[] }>` |
|
|
152
|
+
| `read` | `(options: IUsbDeviceFilter & { path: string }) => Promise<{ data: string \| null }>` |
|