@simplysm/capacitor-plugin-usb-storage 13.0.96 → 13.0.98

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 +64 -123
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,89 +1,48 @@
1
1
  # @simplysm/capacitor-plugin-usb-storage
2
2
 
3
- Capacitor USB Mass Storage 플러그인. Android에서 USB 저장장치를 열거하고, 권한을 관리하며, 파일을 읽는다.
4
- Web 환경에서는 IndexedDB 기반 가상 USB 스토리지를 제공하여 개발/테스트를 지원한다.
3
+ Capacitor USB Storage Plugin -- read files from USB mass storage devices on Android.
5
4
 
6
- ## 설치
5
+ ## Installation
7
6
 
8
7
  ```bash
9
8
  npm install @simplysm/capacitor-plugin-usb-storage
10
9
  ```
11
10
 
12
- **의존성:** `@simplysm/core-common` (Bytes, bytes 유틸), `@simplysm/core-browser` (IndexedDbStore, IndexedDbVirtualFs)
13
- **Peer:** `@capacitor/core` ^7.4.4
14
- **Android 네이티브:** `me.jahnen:libaums:core:0.9.1` (USB Mass Storage 라이브러리)
11
+ ## API Overview
15
12
 
16
- ## 주요 기능
13
+ ### Types
17
14
 
18
- ### 기기 목록 조회
15
+ | API | Type | Description |
16
+ |-----|------|-------------|
17
+ | `UsbDeviceInfo` | interface | USB device info (name, manufacturer, product, vendor/product IDs) |
18
+ | `UsbDeviceFilter` | interface | USB device filter by `vendorId` and `productId` |
19
+ | `UsbFileInfo` | interface | File entry info (`name`, `isDirectory`) |
19
20
 
20
- 연결된 USB Mass Storage 기기 목록을 반환한다.
21
+ ### Interfaces
21
22
 
22
- ```typescript
23
- import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
23
+ | API | Type | Description |
24
+ |-----|------|-------------|
25
+ | `UsbStoragePlugin` | interface | Low-level Capacitor plugin interface for USB storage operations |
24
26
 
25
- const devices = await UsbStorage.getDevices();
26
- // UsbDeviceInfo[] = [{
27
- // deviceName: "USB Storage",
28
- // manufacturerName: "SanDisk",
29
- // productName: "Ultra",
30
- // vendorId: 1234,
31
- // productId: 5678,
32
- // }]
33
- ```
27
+ ### Classes
34
28
 
35
- ### 권한 관리
29
+ | API | Type | Description |
30
+ |-----|------|-------------|
31
+ | `UsbStorage` | abstract class | USB mass storage device access |
36
32
 
37
- 기기별로 `vendorId`/`productId` 조합으로 권한을 확인/요청한다.
38
- Android에서는 시스템 권한 다이얼로그가 표시되며, Web에서는 항상 granted를 반환한다.
33
+ ## `UsbDeviceInfo`
39
34
 
40
35
  ```typescript
41
- import type { UsbDeviceFilter } from "@simplysm/capacitor-plugin-usb-storage";
42
-
43
- const filter: UsbDeviceFilter = { vendorId: 1234, productId: 5678 };
44
-
45
- const granted = await UsbStorage.checkPermissions(filter); // boolean
46
- if (!granted) {
47
- const result = await UsbStorage.requestPermissions(filter); // boolean
36
+ interface UsbDeviceInfo {
37
+ deviceName: string;
38
+ manufacturerName: string;
39
+ productName: string;
40
+ vendorId: number;
41
+ productId: number;
48
42
  }
49
43
  ```
50
44
 
51
- ### 디렉토리 읽기
52
-
53
- USB 저장장치의 지정 경로에 있는 파일/폴더 목록을 반환한다.
54
-
55
- ```typescript
56
- const filter: UsbDeviceFilter = { vendorId: 1234, productId: 5678 };
57
-
58
- const files = await UsbStorage.readdir(filter, "/documents");
59
- // UsbFileInfo[] = [{ name: "report.pdf", isDirectory: false }]
60
- ```
61
-
62
- ### 파일 읽기
63
-
64
- USB 저장장치에서 파일을 읽어 `Bytes`(Uint8Array)로 반환한다. 파일이 없으면 `undefined`를 반환한다.
65
- Android에서 최대 파일 크기는 100MB이다.
66
-
67
- ```typescript
68
- import type { Bytes } from "@simplysm/core-common";
69
-
70
- const filter: UsbDeviceFilter = { vendorId: 1234, productId: 5678 };
71
- const data: Bytes | undefined = await UsbStorage.readFile(filter, "/documents/report.pdf");
72
- ```
73
-
74
- ## API 레퍼런스
75
-
76
- ### `UsbStorage` (abstract class, static 메서드)
77
-
78
- | 메서드 | 시그니처 | 설명 |
79
- |--------|----------|------|
80
- | `getDevices` | `() => Promise<UsbDeviceInfo[]>` | 연결된 USB 기기 목록 |
81
- | `checkPermissions` | `(filter: UsbDeviceFilter) => Promise<boolean>` | 권한 확인 |
82
- | `requestPermissions` | `(filter: UsbDeviceFilter) => Promise<boolean>` | 권한 요청 (다이얼로그 표시) |
83
- | `readdir` | `(filter: UsbDeviceFilter, dirPath: string) => Promise<UsbFileInfo[]>` | 디렉토리 목록 |
84
- | `readFile` | `(filter: UsbDeviceFilter, filePath: string) => Promise<Bytes \| undefined>` | 파일 읽기 (base64 디코딩) |
85
-
86
- ### `UsbDeviceFilter` (interface)
45
+ ## `UsbDeviceFilter`
87
46
 
88
47
  ```typescript
89
48
  interface UsbDeviceFilter {
@@ -92,79 +51,61 @@ interface UsbDeviceFilter {
92
51
  }
93
52
  ```
94
53
 
95
- ### `UsbDeviceInfo` (interface)
54
+ ## `UsbFileInfo`
96
55
 
97
56
  ```typescript
98
- interface UsbDeviceInfo {
99
- deviceName: string; // USB 디바이스 경로명
100
- manufacturerName: string; // 제조사
101
- productName: string; // 제품명
102
- vendorId: number; // USB Vendor ID
103
- productId: number; // USB Product ID
57
+ interface UsbFileInfo {
58
+ name: string;
59
+ isDirectory: boolean;
104
60
  }
105
61
  ```
106
62
 
107
- ### `UsbFileInfo` (interface)
63
+ ## `UsbStoragePlugin`
108
64
 
109
65
  ```typescript
110
- interface UsbFileInfo {
111
- name: string; // 파일/디렉토리 이름
112
- isDirectory: boolean;
66
+ interface UsbStoragePlugin {
67
+ getDevices(): Promise<{ devices: UsbDeviceInfo[] }>;
68
+ requestPermissions(options: UsbDeviceFilter): Promise<{ granted: boolean }>;
69
+ checkPermissions(options: UsbDeviceFilter): Promise<{ granted: boolean }>;
70
+ readdir(options: UsbDeviceFilter & { path: string }): Promise<{ files: UsbFileInfo[] }>;
71
+ readFile(options: UsbDeviceFilter & { path: string }): Promise<{ data: string | null }>;
113
72
  }
114
73
  ```
115
74
 
116
- ## 플랫폼 지원
117
-
118
- | 기능 | Android | Web |
119
- |------|---------|-----|
120
- | 기기 열거 | UsbManager + libaums | 가상 기기 (IndexedDB) |
121
- | 권한 관리 | USB 권한 다이얼로그 (PendingIntent) | 항상 granted |
122
- | 디렉토리 읽기 | libaums `UsbFile.listFiles()` | IndexedDB 가상 스토리지 |
123
- | 파일 읽기 | libaums `UsbFileInputStream` (최대 100MB) | IndexedDB base64 데이터 |
124
-
125
- ## Web 테스트용 가상 기기
75
+ Low-level Capacitor plugin interface. Use `UsbStorage` static methods instead of calling this directly.
126
76
 
127
- `UsbStorageWeb` 클래스에는 개발/테스트용 메서드가 있다. Capacitor의 `registerPlugin`을 통해 Web 환경에서 자동으로 사용된다.
77
+ ## `UsbStorage`
128
78
 
129
79
  ```typescript
130
- import type { UsbDeviceFilter } from "@simplysm/capacitor-plugin-usb-storage";
131
-
132
- // UsbStorageWeb 인스턴스에 직접 접근하여 가상 기기를 구성한다
133
- // 가상 기기 추가
134
- await usbStorageWeb.addVirtualDevice({
135
- vendorId: 1234,
136
- productId: 5678,
137
- deviceName: "Test USB",
138
- manufacturerName: "Test",
139
- productName: "Drive",
140
- });
141
-
142
- // 가상 파일 추가
143
- const filter: UsbDeviceFilter = { vendorId: 1234, productId: 5678 };
144
- await usbStorageWeb.addVirtualFile(filter, "/test.txt", new Uint8Array([72, 101, 108, 108, 111]));
145
-
146
- // 가상 디렉토리 추가
147
- await usbStorageWeb.addVirtualDirectory(filter, "/docs");
80
+ abstract class UsbStorage {
81
+ static async getDevices(): Promise<UsbDeviceInfo[]>;
82
+ static async requestPermissions(filter: UsbDeviceFilter): Promise<boolean>;
83
+ static async checkPermissions(filter: UsbDeviceFilter): Promise<boolean>;
84
+ static async readdir(filter: UsbDeviceFilter, dirPath: string): Promise<UsbFileInfo[]>;
85
+ static async readFile(filter: UsbDeviceFilter, filePath: string): Promise<Bytes | undefined>;
86
+ }
148
87
  ```
149
88
 
150
- ### `UsbStorageWeb` 테스트 전용 메서드
89
+ Plugin for interacting with USB storage devices.
90
+ - Android: USB Mass Storage access via libaums library.
91
+ - Browser: IndexedDB-based virtual USB storage emulation.
151
92
 
152
- | 메서드 | 시그니처 | 설명 |
153
- |--------|----------|------|
154
- | `addVirtualDevice` | `(device: { vendorId, productId, deviceName, manufacturerName, productName }) => Promise<void>` | 가상 USB 기기 추가 |
155
- | `addVirtualFile` | `(filter: UsbDeviceFilter, filePath: string, data: Uint8Array) => Promise<void>` | 가상 파일 추가 |
156
- | `addVirtualDirectory` | `(filter: UsbDeviceFilter, dirPath: string) => Promise<void>` | 가상 디렉토리 추가 |
93
+ ## Usage Examples
157
94
 
158
- Web 가상 스토리지는 `VirtualUsbStorage` 클래스를 사용하며, IndexedDB(`capacitor_usb_virtual_storage`)에 기기와 파일 데이터를 저장한다.
159
- - 스토어: `devices` (keyPath: `key`, key = `vendorId:productId`), `files` (keyPath: `fullKey`, fullKey = `deviceKey:path`)
95
+ ### List USB devices and read files
160
96
 
161
- ## Android 네이티브 구현
97
+ ```typescript
98
+ import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
162
99
 
163
- - **패키지:** `kr.co.simplysm.capacitor.usbstorage`
164
- - **플러그인명:** `UsbStorage`
165
- - **라이브러리:** `me.jahnen.libaums:core:0.9.1`
166
- - `getDevices`: `UsbMassStorageDevice.getMassStorageDevices(context)`
167
- - `requestPermissions`: `UsbManager.requestPermission` + BroadcastReceiver 콜백 (Android 13+: `RECEIVER_NOT_EXPORTED`, Android 12+: `PendingIntent.FLAG_MUTABLE`)
168
- - `readdir`/`readFile`: 기기 init -> 첫 번째 파티션의 FileSystem -> `root.search(path)` -> 작업 -> `device.close()`
169
- - `readFile`: `UsbFileInputStream`으로 읽고 base64 인코딩, 최대 100MB 제한
170
- - **퍼미션 액션:** `kr.co.simplysm.capacitor.usbstorage.USB_PERMISSION`
100
+ const devices = await UsbStorage.getDevices();
101
+ if (devices.length > 0) {
102
+ const device = devices[0];
103
+ const filter = { vendorId: device.vendorId, productId: device.productId };
104
+
105
+ const granted = await UsbStorage.requestPermissions(filter);
106
+ if (granted) {
107
+ const files = await UsbStorage.readdir(filter, "/");
108
+ const data = await UsbStorage.readFile(filter, "/readme.txt");
109
+ }
110
+ }
111
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@simplysm/capacitor-plugin-usb-storage",
3
- "version": "13.0.96",
3
+ "version": "13.0.98",
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.96",
22
- "@simplysm/core-common": "13.0.96"
21
+ "@simplysm/core-browser": "13.0.98",
22
+ "@simplysm/core-common": "13.0.98"
23
23
  },
24
24
  "devDependencies": {
25
25
  "@capacitor/core": "^7.6.0"