@simplysm/capacitor-plugin-usb-storage 13.0.85 → 13.0.87

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 +100 -159
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,225 +1,166 @@
1
1
  # @simplysm/capacitor-plugin-usb-storage
2
2
 
3
- Capacitor plugin for reading USB mass storage devices.
3
+ Capacitor USB Mass Storage 플러그인. Android에서 USB 저장장치를 열거하고, 권한을 관리하며, 파일을 읽는다.
4
4
 
5
- - **Android**: USB Mass Storage access via the libaums library
6
- - **Browser**: IndexedDB-based virtual USB storage emulation (for development/testing)
7
-
8
- ## Installation
5
+ ## 설치
9
6
 
10
7
  ```bash
11
8
  npm install @simplysm/capacitor-plugin-usb-storage
12
9
  ```
13
10
 
14
- ### Peer Dependencies
15
-
16
- | Package | Version |
17
- |---------|---------|
18
- | `@capacitor/core` | `^7.4.4` |
19
-
20
- ## API Reference
21
-
22
- ### `UsbStorage` (static class)
23
-
24
- The main entry point. All methods are static and return Promises.
11
+ **의존성:** `@simplysm/core-common` (Bytes, bytes 유틸), `@simplysm/core-browser` (IndexedDbStore, IndexedDbVirtualFs)
12
+ **Peer:** `@capacitor/core` ^7.4.4
13
+ **Android 네이티브:** `me.jahnen:libaums:core:0.9.1` (USB Mass Storage 라이브러리)
25
14
 
26
- #### `UsbStorage.getDevices()`
15
+ ## Export 목록
27
16
 
28
- Get a list of connected USB devices.
29
-
30
- ```ts
31
- const devices: UsbDeviceInfo[] = await UsbStorage.getDevices();
17
+ ```typescript
18
+ // index.ts
19
+ export type { UsbStoragePlugin, UsbDeviceInfo, UsbDeviceFilter, UsbFileInfo } from "./UsbStoragePlugin";
20
+ export { UsbStorage } from "./UsbStorage";
32
21
  ```
33
22
 
34
- **Returns:** `Promise<UsbDeviceInfo[]>`
35
-
36
- ---
23
+ ## 주요 사용법
37
24
 
38
- #### `UsbStorage.requestPermissions(filter)`
25
+ ### 기기 목록 조회
39
26
 
40
- Request access permission for a USB device.
27
+ ```typescript
28
+ import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
41
29
 
42
- ```ts
43
- const granted: boolean = await UsbStorage.requestPermissions({
44
- vendorId: 0x1234,
45
- productId: 0x5678,
46
- });
30
+ const devices = await UsbStorage.getDevices();
31
+ // UsbDeviceInfo[] = [{
32
+ // deviceName: "USB Storage",
33
+ // manufacturerName: "SanDisk",
34
+ // productName: "Ultra",
35
+ // vendorId: 1234,
36
+ // productId: 5678,
37
+ // }]
47
38
  ```
48
39
 
49
- | Parameter | Type | Description |
50
- |-----------|------|-------------|
51
- | `filter` | `UsbDeviceFilter` | Target device vendor/product IDs |
40
+ ### 권한 관리
52
41
 
53
- **Returns:** `Promise<boolean>` -- `true` if permission was granted.
42
+ 기기별로 `vendorId`/`productId` 조합으로 권한을 확인/요청한다.
54
43
 
55
- ---
44
+ ```typescript
45
+ import type { UsbDeviceFilter } from "@simplysm/capacitor-plugin-usb-storage";
56
46
 
57
- #### `UsbStorage.checkPermissions(filter)`
47
+ const filter: UsbDeviceFilter = { vendorId: 1234, productId: 5678 };
58
48
 
59
- Check whether access permission is already granted for a USB device.
60
-
61
- ```ts
62
- const hasPermission: boolean = await UsbStorage.checkPermissions({
63
- vendorId: 0x1234,
64
- productId: 0x5678,
65
- });
49
+ const granted = await UsbStorage.checkPermissions(filter); // boolean
50
+ if (!granted) {
51
+ const result = await UsbStorage.requestPermissions(filter); // boolean
52
+ }
66
53
  ```
67
54
 
68
- | Parameter | Type | Description |
69
- |-----------|------|-------------|
70
- | `filter` | `UsbDeviceFilter` | Target device vendor/product IDs |
71
-
72
- **Returns:** `Promise<boolean>` -- `true` if permission is held.
73
-
74
- ---
55
+ ### 디렉토리 읽기
75
56
 
76
- #### `UsbStorage.readdir(filter, dirPath)`
57
+ ```typescript
58
+ const filter: UsbDeviceFilter = { vendorId: 1234, productId: 5678 };
77
59
 
78
- Read directory contents from a USB storage device.
79
-
80
- ```ts
81
- const files: UsbFileInfo[] = await UsbStorage.readdir(
82
- { vendorId: 0x1234, productId: 0x5678 },
83
- "/Documents",
84
- );
60
+ const files = await UsbStorage.readdir(filter, "/documents");
61
+ // UsbFileInfo[] = [{ name: "report.pdf", isDirectory: false }]
85
62
  ```
86
63
 
87
- | Parameter | Type | Description |
88
- |-----------|------|-------------|
89
- | `filter` | `UsbDeviceFilter` | Target device vendor/product IDs |
90
- | `dirPath` | `string` | Directory path to read |
91
-
92
- **Returns:** `Promise<UsbFileInfo[]>`
64
+ ### 파일 읽기
93
65
 
94
- ---
95
-
96
- #### `UsbStorage.readFile(filter, filePath)`
97
-
98
- Read a file from a USB storage device. Returns the file contents as `Bytes`, or `undefined` if the file was not found.
99
-
100
- ```ts
66
+ ```typescript
101
67
  import type { Bytes } from "@simplysm/core-common";
102
68
 
103
- const data: Bytes | undefined = await UsbStorage.readFile(
104
- { vendorId: 0x1234, productId: 0x5678 },
105
- "/Documents/report.pdf",
106
- );
69
+ const filter: UsbDeviceFilter = { vendorId: 1234, productId: 5678 };
70
+ const data: Bytes | undefined = await UsbStorage.readFile(filter, "/documents/report.pdf");
71
+ // 파일이 없으면 undefined, 있으면 Bytes (Uint8Array)
107
72
  ```
108
73
 
109
- | Parameter | Type | Description |
110
- |-----------|------|-------------|
111
- | `filter` | `UsbDeviceFilter` | Target device vendor/product IDs |
112
- | `filePath` | `string` | File path to read |
113
-
114
- **Returns:** `Promise<Bytes | undefined>`
74
+ Android에서 최대 파일 크기는 100MB이다.
115
75
 
116
- ---
76
+ ## API 레퍼런스
117
77
 
118
- ### Interfaces
78
+ ### `UsbStorage` (abstract class, static 메서드)
119
79
 
120
- #### `UsbDeviceInfo`
80
+ | 메서드 | 시그니처 | 설명 |
81
+ |--------|----------|------|
82
+ | `getDevices` | `() => Promise<UsbDeviceInfo[]>` | 연결된 USB 기기 목록 |
83
+ | `checkPermissions` | `(filter: UsbDeviceFilter) => Promise<boolean>` | 권한 확인 |
84
+ | `requestPermissions` | `(filter: UsbDeviceFilter) => Promise<boolean>` | 권한 요청 (다이얼로그 표시) |
85
+ | `readdir` | `(filter: UsbDeviceFilter, dirPath: string) => Promise<UsbFileInfo[]>` | 디렉토리 목록 |
86
+ | `readFile` | `(filter: UsbDeviceFilter, filePath: string) => Promise<Bytes \| undefined>` | 파일 읽기 (base64 디코딩) |
121
87
 
122
- Information about a connected USB device.
88
+ ### `UsbDeviceFilter` (interface)
123
89
 
124
- ```ts
125
- interface UsbDeviceInfo {
126
- deviceName: string;
127
- manufacturerName: string;
128
- productName: string;
90
+ ```typescript
91
+ interface UsbDeviceFilter {
129
92
  vendorId: number;
130
93
  productId: number;
131
94
  }
132
95
  ```
133
96
 
134
- #### `UsbDeviceFilter`
135
-
136
- Filter used to identify a specific USB device by vendor and product ID.
97
+ ### `UsbDeviceInfo` (interface)
137
98
 
138
- ```ts
139
- interface UsbDeviceFilter {
140
- vendorId: number;
141
- productId: number;
99
+ ```typescript
100
+ interface UsbDeviceInfo {
101
+ deviceName: string; // USB 디바이스 경로명
102
+ manufacturerName: string; // 제조사
103
+ productName: string; // 제품명
104
+ vendorId: number; // USB Vendor ID
105
+ productId: number; // USB Product ID
142
106
  }
143
107
  ```
144
108
 
145
- #### `UsbFileInfo`
109
+ ### `UsbFileInfo` (interface)
146
110
 
147
- Information about a file or directory on the USB device.
148
-
149
- ```ts
111
+ ```typescript
150
112
  interface UsbFileInfo {
151
- name: string;
113
+ name: string; // 파일/디렉토리 이름
152
114
  isDirectory: boolean;
153
115
  }
154
116
  ```
155
117
 
156
- ---
157
-
158
- ### `UsbStoragePlugin` (low-level interface)
118
+ ## 플랫폼 지원
159
119
 
160
- The raw Capacitor plugin interface. Prefer using the `UsbStorage` static class instead.
120
+ | 기능 | Android | Web |
121
+ |------|---------|-----|
122
+ | 기기 열거 | UsbManager + libaums | 가상 기기 (IndexedDB) |
123
+ | 권한 관리 | USB 권한 다이얼로그 (PendingIntent) | 항상 granted |
124
+ | 디렉토리 읽기 | libaums `UsbFile.listFiles()` | IndexedDB 가상 스토리지 |
125
+ | 파일 읽기 | libaums `UsbFileInputStream` (최대 100MB) | IndexedDB base64 데이터 |
161
126
 
162
- ```ts
163
- interface UsbStoragePlugin {
164
- getDevices(): Promise<{ devices: UsbDeviceInfo[] }>;
165
- requestPermissions(options: UsbDeviceFilter): Promise<{ granted: boolean }>;
166
- checkPermissions(options: UsbDeviceFilter): Promise<{ granted: boolean }>;
167
- readdir(options: UsbDeviceFilter & { path: string }): Promise<{ files: UsbFileInfo[] }>;
168
- readFile(options: UsbDeviceFilter & { path: string }): Promise<{ data: string | null }>;
169
- }
170
- ```
171
-
172
- ---
127
+ ## Web 테스트용 가상 기기
173
128
 
174
- ## Web Platform (Virtual USB Storage)
129
+ `UsbStorageWeb` 클래스에는 개발/테스트용 메서드가 있다. Capacitor의 `registerPlugin`을 통해 Web 환경에서 자동으로 사용된다.
175
130
 
176
- On the web platform, the plugin uses an IndexedDB-backed virtual file system for development and testing. The `UsbStorageWeb` class exposes additional helper methods to set up virtual devices and files.
131
+ ```typescript
132
+ import type { UsbDeviceFilter } from "@simplysm/capacitor-plugin-usb-storage";
177
133
 
178
- ### `UsbStorageWeb.addVirtualDevice(device)`
134
+ // Web 환경에서만 UsbStorageWeb 인스턴스의 메서드를 직접 호출해야 함
135
+ // 일반적으로 Capacitor plugin 등록 시 자동으로 Web 구현체가 사용됨
179
136
 
180
- Register a virtual USB device.
181
-
182
- ```ts
183
- await web.addVirtualDevice({
184
- vendorId: 0x1234,
185
- productId: 0x5678,
186
- deviceName: "Virtual USB",
137
+ // 가상 기기 추가
138
+ await usbStorageWeb.addVirtualDevice({
139
+ vendorId: 1234,
140
+ productId: 5678,
141
+ deviceName: "Test USB",
187
142
  manufacturerName: "Test",
188
- productName: "Virtual Drive",
143
+ productName: "Drive",
189
144
  });
190
- ```
191
145
 
192
- ### `UsbStorageWeb.addVirtualFile(filter, filePath, data)`
146
+ // 가상 파일 추가
147
+ const filter: UsbDeviceFilter = { vendorId: 1234, productId: 5678 };
148
+ await usbStorageWeb.addVirtualFile(filter, "/test.txt", new Uint8Array([72, 101, 108, 108, 111]));
193
149
 
194
- Add a file to a virtual USB device.
195
-
196
- ```ts
197
- const content = new TextEncoder().encode("hello");
198
- await web.addVirtualFile(
199
- { vendorId: 0x1234, productId: 0x5678 },
200
- "/docs/readme.txt",
201
- content,
202
- );
150
+ // 가상 디렉토리 추가
151
+ await usbStorageWeb.addVirtualDirectory(filter, "/docs");
203
152
  ```
204
153
 
205
- | Parameter | Type | Description |
206
- |-----------|------|-------------|
207
- | `filter` | `UsbDeviceFilter` | Target virtual device |
208
- | `filePath` | `string` | File path on the virtual device |
209
- | `data` | `Uint8Array` | File contents |
210
-
211
- ### `UsbStorageWeb.addVirtualDirectory(filter, dirPath)`
154
+ Web 가상 스토리지는 `VirtualUsbStorage` 클래스를 사용하며, IndexedDB(`capacitor_usb_virtual_storage`)에 기기와 파일 데이터를 저장한다.
155
+ - 스토어: `devices` (keyPath: `key`, key = `vendorId:productId`), `files` (keyPath: `fullKey`, fullKey = `deviceKey:path`)
212
156
 
213
- Create a directory on a virtual USB device.
214
-
215
- ```ts
216
- await web.addVirtualDirectory(
217
- { vendorId: 0x1234, productId: 0x5678 },
218
- "/docs/reports",
219
- );
220
- ```
157
+ ## Android 네이티브 구현
221
158
 
222
- | Parameter | Type | Description |
223
- |-----------|------|-------------|
224
- | `filter` | `UsbDeviceFilter` | Target virtual device |
225
- | `dirPath` | `string` | Directory path to create |
159
+ - **패키지:** `kr.co.simplysm.capacitor.usbstorage`
160
+ - **플러그인명:** `UsbStorage`
161
+ - **라이브러리:** `me.jahnen:libaums:core:0.9.1`
162
+ - `getDevices`: `UsbMassStorageDevice.getMassStorageDevices(context)`
163
+ - `requestPermissions`: `UsbManager.requestPermission` + BroadcastReceiver 콜백 (Android 13+: `RECEIVER_NOT_EXPORTED`, Android 12+: `PendingIntent.FLAG_MUTABLE`)
164
+ - `readdir`/`readFile`: 기기 init -> 첫 번째 파티션의 FileSystem -> `root.search(path)` -> 작업 -> `device.close()`
165
+ - `readFile`: `UsbFileInputStream`으로 읽고 base64 인코딩, 최대 100MB 제한
166
+ - **퍼미션 액션:** `kr.co.simplysm.capacitor.usbstorage.USB_PERMISSION`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@simplysm/capacitor-plugin-usb-storage",
3
- "version": "13.0.85",
3
+ "version": "13.0.87",
4
4
  "description": "Simplysm Package - Capacitor USB Storage Plugin",
5
5
  "author": "simplysm",
6
6
  "license": "MIT",
@@ -18,8 +18,8 @@
18
18
  "android"
19
19
  ],
20
20
  "dependencies": {
21
- "@simplysm/core-browser": "13.0.85",
22
- "@simplysm/core-common": "13.0.85"
21
+ "@simplysm/core-browser": "13.0.87",
22
+ "@simplysm/core-common": "13.0.87"
23
23
  },
24
24
  "devDependencies": {
25
25
  "@capacitor/core": "^7.6.0"