@simplysm/capacitor-plugin-usb-storage 12.16.31 → 12.16.36

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.
Files changed (2) hide show
  1. package/README.md +114 -113
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,152 +1,153 @@
1
1
  # @simplysm/capacitor-plugin-usb-storage
2
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.
3
+ Capacitor USB Storage Plugin -- USB mass storage device interaction for Android. Enumerate connected USB devices, manage access permissions, read directories, and read files from USB mass storage devices using the libaums library. Falls back to alert-based stubs on browser.
4
4
 
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
8
  npm install @simplysm/capacitor-plugin-usb-storage
9
- npx cap sync
10
9
  ```
11
10
 
12
- ### Requirements
11
+ ## API Overview
13
12
 
14
- - `@capacitor/core` ^7.0.0
13
+ | API | Type | Description |
14
+ |-----|------|-------------|
15
+ | `UsbStorage` | Abstract class | Static methods for USB mass storage device interaction |
16
+ | `IUsbDeviceInfo` | Interface | USB device information (name, manufacturer, IDs) |
17
+ | `IUsbDeviceFilter` | Interface | Filter to identify a USB device by vendor/product ID |
18
+ | `IUsbStoragePlugin` | Interface | Low-level Capacitor plugin interface for USB storage operations |
15
19
 
16
- ### Platform Support
20
+ ## API Reference
17
21
 
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[]>`
22
+ ### `IUsbDeviceInfo`
34
23
 
35
- ```ts
36
- import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
24
+ Information about a connected USB device.
37
25
 
38
- const devices = await UsbStorage.getDevices();
39
- for (const device of devices) {
40
- console.log(device.productName, device.vendorId, device.productId);
26
+ ```typescript
27
+ export interface IUsbDeviceInfo {
28
+ deviceName: string;
29
+ manufacturerName: string;
30
+ productName: string;
31
+ vendorId: number;
32
+ productId: number;
41
33
  }
42
34
  ```
43
35
 
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.
36
+ | Field | Type | Description |
37
+ |-------|------|-------------|
38
+ | `deviceName` | `string` | System device name |
39
+ | `manufacturerName` | `string` | USB device manufacturer name |
40
+ | `productName` | `string` | USB device product name |
41
+ | `vendorId` | `number` | USB vendor ID |
42
+ | `productId` | `number` | USB product ID |
65
43
 
66
- | Parameter | Type | Description |
67
- |--------------------|----------|--------------------------|
68
- | `filter.vendorId` | `number` | USB vendor ID |
69
- | `filter.productId` | `number` | USB product ID |
44
+ ### `IUsbDeviceFilter`
70
45
 
71
- **Returns:** `Promise<boolean>` -- whether permission is held.
46
+ Filter used to identify a specific USB device by its vendor and product IDs.
72
47
 
73
- ```ts
74
- const hasPerm = await UsbStorage.hasPermission({
75
- vendorId: 1234,
76
- productId: 5678,
77
- });
48
+ ```typescript
49
+ export interface IUsbDeviceFilter {
50
+ vendorId: number;
51
+ productId: number;
52
+ }
78
53
  ```
79
54
 
80
- #### `UsbStorage.readdir(filter, dirPath)`
81
-
82
- Reads the contents of a directory on the USB storage device.
55
+ | Field | Type | Description |
56
+ |-------|------|-------------|
57
+ | `vendorId` | `number` | USB vendor ID to match |
58
+ | `productId` | `number` | USB product ID to match |
83
59
 
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 |
60
+ ### `IUsbStoragePlugin`
89
61
 
90
- **Returns:** `Promise<string[]>` -- file and folder names in the directory.
62
+ Low-level Capacitor plugin interface. Use `UsbStorage` instead for a simplified API.
91
63
 
92
- ```ts
93
- const files = await UsbStorage.readdir(
94
- { vendorId: 1234, productId: 5678 },
95
- "/Documents",
96
- );
64
+ ```typescript
65
+ export interface IUsbStoragePlugin {
66
+ getDevices(): Promise<{ devices: IUsbDeviceInfo[] }>;
67
+ requestPermission(options: IUsbDeviceFilter): Promise<{ granted: boolean }>;
68
+ hasPermission(options: IUsbDeviceFilter): Promise<{ granted: boolean }>;
69
+ readdir(options: IUsbDeviceFilter & { path: string }): Promise<{ files: string[] }>;
70
+ read(options: IUsbDeviceFilter & { path: string }): Promise<{ data: string | null }>;
71
+ }
97
72
  ```
98
73
 
99
- #### `UsbStorage.read(filter, filePath)`
74
+ | Method | Parameters | Returns | Description |
75
+ |--------|------------|---------|-------------|
76
+ | `getDevices` | -- | `Promise<{ devices: IUsbDeviceInfo[] }>` | List connected USB devices |
77
+ | `requestPermission` | `options: IUsbDeviceFilter` | `Promise<{ granted: boolean }>` | Request access permission for a USB device |
78
+ | `hasPermission` | `options: IUsbDeviceFilter` | `Promise<{ granted: boolean }>` | Check if permission is granted for a USB device |
79
+ | `readdir` | `options: IUsbDeviceFilter & { path }` | `Promise<{ files: string[] }>` | List files in a directory on the USB device |
80
+ | `read` | `options: IUsbDeviceFilter & { path }` | `Promise<{ data: string \| null }>` | Read a file from the USB device as base64 |
100
81
 
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.
82
+ ### `UsbStorage`
110
83
 
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");
84
+ Abstract class with static methods for USB mass storage device interaction.
85
+
86
+ - **Android**: Uses libaums library for USB Mass Storage access
87
+ - **Browser**: Shows alert and returns empty values
88
+
89
+ ```typescript
90
+ export abstract class UsbStorage {
91
+ static async getDevices(): Promise<IUsbDeviceInfo[]>;
92
+ static async requestPermission(filter: { vendorId: number; productId: number }): Promise<boolean>;
93
+ static async hasPermission(filter: { vendorId: number; productId: number }): Promise<boolean>;
94
+ static async readdir(
95
+ filter: { vendorId: number; productId: number },
96
+ dirPath: string,
97
+ ): Promise<string[]>;
98
+ static async read(
99
+ filter: { vendorId: number; productId: number },
100
+ filePath: string,
101
+ ): Promise<Buffer | undefined>;
118
102
  }
119
103
  ```
120
104
 
121
- ### `IUsbDeviceInfo`
122
-
123
- Device information returned by `getDevices`.
105
+ | Method | Parameters | Returns | Description |
106
+ |--------|------------|---------|-------------|
107
+ | `getDevices` | -- | `Promise<IUsbDeviceInfo[]>` | Get a list of connected USB storage devices |
108
+ | `requestPermission` | `filter: { vendorId: number; productId: number }` | `Promise<boolean>` | Request access permission for a USB device; returns whether permission was granted |
109
+ | `hasPermission` | `filter: { vendorId: number; productId: number }` | `Promise<boolean>` | Check if access permission is granted for a USB device |
110
+ | `readdir` | `filter: { vendorId, productId }, dirPath: string` | `Promise<string[]>` | List file and directory names in a directory on the USB device |
111
+ | `read` | `filter: { vendorId, productId }, filePath: string` | `Promise<Buffer \| undefined>` | Read a file from the USB device as a Buffer; returns `undefined` if data is null |
124
112
 
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 |
113
+ ## Usage Examples
132
114
 
133
- ### `IUsbDeviceFilter`
115
+ ### List USB devices and read a file
134
116
 
135
- Filter used to identify a specific USB device.
117
+ ```typescript
118
+ import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
136
119
 
137
- | Property | Type | Description |
138
- |-------------|----------|----------------|
139
- | `vendorId` | `number` | USB vendor ID |
140
- | `productId` | `number` | USB product ID |
120
+ // Get connected USB devices
121
+ const devices = await UsbStorage.getDevices();
122
+ if (devices.length === 0) {
123
+ console.log("No USB devices connected");
124
+ return;
125
+ }
141
126
 
142
- ### `IUsbStoragePlugin`
127
+ const device = devices[0];
128
+ console.log(`Found: ${device.productName} by ${device.manufacturerName}`);
143
129
 
144
- Low-level plugin interface registered via `registerPlugin`. Use the `UsbStorage` class instead for a simpler API.
130
+ // Request permission
131
+ const granted = await UsbStorage.requestPermission({
132
+ vendorId: device.vendorId,
133
+ productId: device.productId,
134
+ });
145
135
 
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 }>` |
136
+ if (granted) {
137
+ // List root directory
138
+ const files = await UsbStorage.readdir(
139
+ { vendorId: device.vendorId, productId: device.productId },
140
+ "/",
141
+ );
142
+ console.log("Files:", files);
143
+
144
+ // Read a file
145
+ const data = await UsbStorage.read(
146
+ { vendorId: device.vendorId, productId: device.productId },
147
+ "/data.txt",
148
+ );
149
+ if (data) {
150
+ console.log("Content:", data.toString("utf-8"));
151
+ }
152
+ }
153
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@simplysm/capacitor-plugin-usb-storage",
3
- "version": "12.16.31",
3
+ "version": "12.16.36",
4
4
  "description": "심플리즘 패키지 - Capacitor USB Storage Plugin",
5
5
  "author": "김석래",
6
6
  "repository": {
@@ -18,7 +18,7 @@
18
18
  }
19
19
  },
20
20
  "devDependencies": {
21
- "@capacitor/core": "^7.5.0"
21
+ "@capacitor/core": "^7.6.0"
22
22
  },
23
23
  "peerDependencies": {
24
24
  "@capacitor/core": "^7.0.0"