@simplysm/capacitor-plugin-usb-storage 14.0.51 → 14.0.52

package/android/src/main/kotlin/kr/co/simplysm/capacitor/usbstorage/UsbStoragePlugin.kt

@@ -56,7 +56,7 @@ class UsbStoragePlugin : Plugin() {
     }
 
     @PluginMethod
-    fun requestPermissions(call: PluginCall) {
+    override fun requestPermissions(call: PluginCall) {
         val vendorId = call.getInt("vendorId")
         val productId = call.getInt("productId")
 
@@ -115,7 +115,7 @@ class UsbStoragePlugin : Plugin() {
     }
 
     @PluginMethod
-    fun checkPermissions(call: PluginCall) {
+    override fun checkPermissions(call: PluginCall) {
         val vendorId = call.getInt("vendorId")
         val productId = call.getInt("productId")
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/capacitor-plugin-usb-storage",
-  "version": "14.0.51",
+  "version": "14.0.52",
   "description": "심플리즘 패키지 - Capacitor USB 저장소 플러그인",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -18,8 +18,8 @@
     "android"
   ],
   "dependencies": {
-    "@simplysm/core-browser": "14.0.51",
-    "@simplysm/core-common": "14.0.51"
+    "@simplysm/core-browser": "14.0.52",
+    "@simplysm/core-common": "14.0.52"
   },
   "devDependencies": {
     "@capacitor/core": "^7.6.2"

package/README.md

@@ -1,258 +0,0 @@
-# @simplysm/capacitor-plugin-usb-storage
-
-Capacitor USB 저장소 플러그인. Android에서 libaums 라이브러리를 통해 USB Mass Storage 장치를 열거하고 파일을 읽는다. 브라우저에서는 IndexedDB 기반 가상 USB 저장소로 에뮬레이션한다.
-
-## Installation
-
-```bash
-npm install @simplysm/capacitor-plugin-usb-storage
-```
-
-## API Overview
-
-### USB 저장소 - 공개 API
-
-| API | Type | Description |
-|-----|------|-------------|
-| `UsbDeviceInfo` | interface | USB 장치 정보 (이름, 제조사, vendorId 등) |
-| `UsbDeviceFilter` | interface | USB 장치 필터 (vendorId + productId) |
-| `UsbFileInfo` | interface | USB 저장소 내 파일/디렉토리 정보 |
-| `UsbStoragePlugin` | interface | Capacitor 네이티브 플러그인 인터페이스 |
-| `UsbStorage` | abstract class | USB 저장 장치 접근 정적 파사드 |
-
----
-
-## `UsbDeviceInfo`
-
-연결된 USB 장치 정보를 나타내는 인터페이스.
-
-```typescript
-export interface UsbDeviceInfo {
-  deviceName: string;
-  manufacturerName: string;
-  productName: string;
-  vendorId: number;
-  productId: number;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `deviceName` | `string` | 장치 이름 |
-| `manufacturerName` | `string` | 제조사 이름 |
-| `productName` | `string` | 제품 이름 |
-| `vendorId` | `number` | USB Vendor ID |
-| `productId` | `number` | USB Product ID |
-
-## `UsbDeviceFilter`
-
-USB 장치를 식별하기 위한 필터 인터페이스. 모든 장치 접근 메서드의 첫 번째 파라미터로 사용된다.
-
-```typescript
-export interface UsbDeviceFilter {
-  vendorId: number;
-  productId: number;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `vendorId` | `number` | USB Vendor ID |
-| `productId` | `number` | USB Product ID |
-
-## `UsbFileInfo`
-
-USB 저장소 내 파일 또는 디렉토리 정보를 나타내는 인터페이스.
-
-```typescript
-export interface UsbFileInfo {
-  name: string;
-  isDirectory: boolean;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `string` | 파일 또는 디렉토리 이름 |
-| `isDirectory` | `boolean` | 디렉토리 여부 |
-
-## `UsbStoragePlugin`
-
-Capacitor 네이티브 플러그인 인터페이스. 직접 사용하지 않고 `UsbStorage` 파사드를 통해 접근한다.
-
-```typescript
-export interface UsbStoragePlugin {
-  getDevices(): Promise<{ devices: UsbDeviceInfo[] }>;
-  requestPermissions(options: UsbDeviceFilter): Promise<{ granted: boolean }>;
-  checkPermissions(options: UsbDeviceFilter): Promise<{ granted: boolean }>;
-  readdir(options: UsbDeviceFilter & { path: string }): Promise<{ files: UsbFileInfo[] }>;
-  readFile(options: UsbDeviceFilter & { path: string }): Promise<{ data: string | null }>;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getDevices` | 없음 | `Promise<{ devices: UsbDeviceInfo[] }>` | 연결된 USB 장치 목록 조회 |
-| `requestPermissions` | `UsbDeviceFilter` | `Promise<{ granted: boolean }>` | USB 장치 접근 권한 요청 |
-| `checkPermissions` | `UsbDeviceFilter` | `Promise<{ granted: boolean }>` | USB 장치 접근 권한 확인 |
-| `readdir` | `UsbDeviceFilter & { path }` | `Promise<{ files: UsbFileInfo[] }>` | 디렉토리 내용 읽기 |
-| `readFile` | `UsbDeviceFilter & { path }` | `Promise<{ data: string \| null }>` | 파일 읽기 (Base64). 파일이 없으면 `null` |
-
-## `UsbStorage`
-
-USB 저장 장치 접근 정적 파사드 클래스. Android에서는 libaums를 통해 USB Mass Storage에 접근하고, 브라우저에서는 IndexedDB 기반으로 에뮬레이션된다.
-
-`readFile()`의 반환 타입 `Bytes`는 `@simplysm/core-common`의 타입이다 (`Uint8Array` 별칭).
-
-```typescript
-export abstract class UsbStorage {
-  static async getDevices(): Promise<UsbDeviceInfo[]>;
-  static async requestPermissions(filter: UsbDeviceFilter): Promise<boolean>;
-  static async checkPermissions(filter: UsbDeviceFilter): Promise<boolean>;
-  static async readdir(filter: UsbDeviceFilter, dirPath: string): Promise<UsbFileInfo[]>;
-  static async readFile(filter: UsbDeviceFilter, filePath: string): Promise<Bytes | undefined>;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getDevices` | 없음 | `Promise<UsbDeviceInfo[]>` | 연결된 USB Mass Storage 장치 목록 조회 |
-| `requestPermissions` | `filter: UsbDeviceFilter` | `Promise<boolean>` | USB 장치 접근 권한 요청. 승인 여부 반환 |
-| `checkPermissions` | `filter: UsbDeviceFilter` | `Promise<boolean>` | USB 장치 접근 권한 보유 여부 확인 |
-| `readdir` | `filter: UsbDeviceFilter, dirPath: string` | `Promise<UsbFileInfo[]>` | USB 저장 장치의 디렉토리 내용 읽기 |
-| `readFile` | `filter: UsbDeviceFilter, filePath: string` | `Promise<Bytes \| undefined>` | USB 저장 장치에서 파일 읽기. 파일이 없으면 `undefined` 반환. 최대 100MB |
-
-## Browser-Only Testing API (`UsbStorageWeb`)
-
-브라우저 환경에서 테스트 및 개발 목적으로 사용하는 API. `UsbStorage` 정적 파사드로는 접근할 수 없으며, `UsbStorageWeb` 인스턴스를 직접 사용할 때만 호출 가능하다.
-
-### `addVirtualDevice(device)`
-
-가상 USB 장치를 IndexedDB에 등록한다. (테스트/개발용)
-
-```typescript
-async addVirtualDevice(device: {
-  vendorId: number;
-  productId: number;
-  deviceName: string;
-  manufacturerName: string;
-  productName: string;
-}): Promise<void>
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `device.vendorId` | `number` | USB Vendor ID |
-| `device.productId` | `number` | USB Product ID |
-| `device.deviceName` | `string` | 장치 이름 |
-| `device.manufacturerName` | `string` | 제조사 이름 |
-| `device.productName` | `string` | 제품 이름 |
-
-### `addVirtualFile(filter, filePath, data)`
-
-가상 USB 장치에 파일을 추가한다. (테스트/개발용)
-
-```typescript
-async addVirtualFile(
-  filter: UsbDeviceFilter,
-  filePath: string,
-  data: Uint8Array,
-): Promise<void>
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `filter.vendorId` | `number` | 대상 장치의 USB Vendor ID |
-| `filter.productId` | `number` | 대상 장치의 USB Product ID |
-| `filePath` | `string` | 파일 경로 (예: `/updates/config.json`) |
-| `data` | `Uint8Array` | 파일 바이너리 데이터 |
-
-**주의**: 파일이 위치할 부모 디렉토리가 존재하지 않으면 자동으로 생성된다.
-
-### `addVirtualDirectory(filter, dirPath)`
-
-가상 USB 장치에 디렉토리를 추가한다. (테스트/개발용)
-
-```typescript
-async addVirtualDirectory(
-  filter: UsbDeviceFilter,
-  dirPath: string,
-): Promise<void>
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `filter.vendorId` | `number` | 대상 장치의 USB Vendor ID |
-| `filter.productId` | `number` | 대상 장치의 USB Product ID |
-| `dirPath` | `string` | 생성할 디렉토리 경로 (예: `/updates`) |
-
----
-
-## Usage Examples
-
-### USB 장치 열거 및 권한 요청
-
-```typescript
-import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
-
-const devices = await UsbStorage.getDevices();
-if (devices.length > 0) {
-  const device = devices[0];
-  const filter = { vendorId: device.vendorId, productId: device.productId };
-
-  const granted = await UsbStorage.checkPermissions(filter);
-  if (!granted) {
-    await UsbStorage.requestPermissions(filter);
-  }
-}
-```
-
-### USB 저장소 파일 읽기
-
-```typescript
-import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
-import type { UsbDeviceFilter } from "@simplysm/capacitor-plugin-usb-storage";
-
-const filter: UsbDeviceFilter = { vendorId: 1234, productId: 5678 };
-
-// 디렉토리 목록 조회
-const files = await UsbStorage.readdir(filter, "/updates");
-
-// 파일 읽기 (Bytes | undefined 반환)
-const data = await UsbStorage.readFile(filter, "/updates/config.json");
-if (data != null) {
-  const text = new TextDecoder().decode(data);
-}
-```
-
-### 브라우저 테스트 - 가상 USB 장치 설정
-
-브라우저 환경에서 테스트할 때, `UsbStorageWeb`을 직접 import하여 가상 USB 저장소를 설정한다. `UsbStorageWeb`은 패키지 공개 API(`index.ts`)에서 export되지 않으므로, 소스 경로를 직접 참조한다.
-
-```typescript
-import { UsbStorageWeb } from "@simplysm/capacitor-plugin-usb-storage/src/web/UsbStorageWeb";
-import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
-
-const usbStorageWeb = new UsbStorageWeb();
-
-// 가상 장치 등록
-await usbStorageWeb.addVirtualDevice({
-  vendorId: 1234,
-  productId: 5678,
-  deviceName: "Test Device",
-  manufacturerName: "Test Manufacturer",
-  productName: "Test Product",
-});
-
-// 가상 파일 추가
-const fileData = new TextEncoder().encode("Hello, USB!");
-await usbStorageWeb.addVirtualFile(
-  { vendorId: 1234, productId: 5678 },
-  "/updates/config.json",
-  fileData,
-);
-
-// UsbStorage 정적 API로 접근 (Capacitor가 브라우저에서 UsbStorageWeb 인스턴스를 사용)
-const files = await UsbStorage.readdir({ vendorId: 1234, productId: 5678 }, "/updates");
-const data = await UsbStorage.readFile({ vendorId: 1234, productId: 5678 }, "/updates/config.json");
-```

package/android/src/main/java/kr/co/simplysm/capacitor/usbstorage/UsbStoragePlugin.kt

@@ -1,269 +0,0 @@
-package kr.co.simplysm.capacitor.usbstorage
-
-import android.app.PendingIntent
-import android.content.BroadcastReceiver
-import android.content.Context
-import android.content.Intent
-import android.content.IntentFilter
-import android.hardware.usb.UsbManager
-import android.os.Build
-import android.util.Base64
-import android.util.Log
-import com.getcapacitor.JSArray
-import com.getcapacitor.JSObject
-import com.getcapacitor.Plugin
-import com.getcapacitor.PluginCall
-import com.getcapacitor.PluginMethod
-import com.getcapacitor.annotation.CapacitorPlugin
-import me.jahnen.libaums.core.UsbMassStorageDevice
-import me.jahnen.libaums.core.fs.UsbFileInputStream
-import java.nio.ByteBuffer
-
-@CapacitorPlugin(name = "UsbStorage")
-class UsbStoragePlugin : Plugin() {
-
-    companion object {
-        private const val TAG = "UsbStoragePlugin"
-        private const val ACTION_USB_PERMISSION = "kr.co.simplysm.capacitor.usbstorage.USB_PERMISSION"
-        private const val MAX_FILE_SIZE = 100L * 1024 * 1024 // 100MB
-    }
-
-    @PluginMethod
-    fun getDevices(call: PluginCall) {
-        try {
-            val devices = UsbMassStorageDevice.getMassStorageDevices(context)
-
-            val result = JSArray()
-            for (device in devices) {
-                val usbDevice = device.usbDevice
-
-                val deviceObj = JSObject()
-                deviceObj.put("deviceName", usbDevice.deviceName)
-                deviceObj.put("manufacturerName", usbDevice.manufacturerName)
-                deviceObj.put("productName", usbDevice.productName)
-                deviceObj.put("vendorId", usbDevice.vendorId)
-                deviceObj.put("productId", usbDevice.productId)
-                result.put(deviceObj)
-            }
-
-            val ret = JSObject()
-            ret.put("devices", result)
-            call.resolve(ret)
-        } catch (e: Exception) {
-            Log.e(TAG, "getDevices failed", e)
-            call.reject("getDevices failed: ${e.message}")
-        }
-    }
-
-    @PluginMethod
-    fun requestPermissions(call: PluginCall) {
-        val vendorId = call.getInt("vendorId")
-        val productId = call.getInt("productId")
-
-        if (vendorId == null || productId == null) {
-            call.reject("vendorId and productId are required")
-            return
-        }
-
-        try {
-            val device = getDevice(vendorId, productId)
-            val usbDevice = device.usbDevice
-
-            val usbManager = context.getSystemService(Context.USB_SERVICE) as UsbManager
-            if (usbManager.hasPermission(usbDevice)) {
-                val ret = JSObject()
-                ret.put("granted", true)
-                call.resolve(ret)
-                return
-            }
-
-            val receiver = object : BroadcastReceiver() {
-                override fun onReceive(context: Context, intent: Intent) {
-                    try {
-                        context.unregisterReceiver(this)
-                        val granted = intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)
-                        val ret = JSObject()
-                        ret.put("granted", granted)
-                        call.resolve(ret)
-                    } catch (e: Exception) {
-                        Log.e(TAG, "requestPermission callback failed", e)
-                        call.reject("requestPermission failed: ${e.message}")
-                    }
-                }
-            }
-
-            val filter = IntentFilter(ACTION_USB_PERMISSION)
-            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
-                context.registerReceiver(receiver, filter, Context.RECEIVER_NOT_EXPORTED)
-            } else {
-                context.registerReceiver(receiver, filter)
-            }
-
-            val flags = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
-                PendingIntent.FLAG_MUTABLE
-            } else {
-                0
-            }
-            val permissionIntent = PendingIntent.getBroadcast(
-                context, 0, Intent(ACTION_USB_PERMISSION), flags
-            )
-            usbManager.requestPermission(usbDevice, permissionIntent)
-        } catch (e: Exception) {
-            Log.e(TAG, "requestPermission failed", e)
-            call.reject("requestPermission failed: ${e.message}")
-        }
-    }
-
-    @PluginMethod
-    fun checkPermissions(call: PluginCall) {
-        val vendorId = call.getInt("vendorId")
-        val productId = call.getInt("productId")
-
-        if (vendorId == null || productId == null) {
-            call.reject("vendorId and productId are required")
-            return
-        }
-
-        try {
-            val device = getDevice(vendorId, productId)
-            val usbManager = context.getSystemService(Context.USB_SERVICE) as UsbManager
-            val hasPermission = usbManager.hasPermission(device.usbDevice)
-
-            val ret = JSObject()
-            ret.put("granted", hasPermission)
-            call.resolve(ret)
-        } catch (e: Exception) {
-            Log.e(TAG, "hasPermission failed", e)
-            call.reject("hasPermission failed: ${e.message}")
-        }
-    }
-
-    @PluginMethod
-    fun readdir(call: PluginCall) {
-        val vendorId = call.getInt("vendorId")
-        val productId = call.getInt("productId")
-        val path = call.getString("path")
-
-        if (vendorId == null || productId == null || path == null) {
-            call.reject("vendorId, productId, and path are required")
-            return
-        }
-
-        try {
-            val device = getDevice(vendorId, productId)
-
-            val usbManager = context.getSystemService(Context.USB_SERVICE) as UsbManager
-            if (!usbManager.hasPermission(device.usbDevice)) {
-                call.reject("No permission for this USB device")
-                return
-            }
-
-            device.init()
-            try {
-                val fs = device.partitions[0].fileSystem
-                val root = fs.rootDirectory
-                val dir = root.search(path)
-
-                if (dir == null || !dir.isDirectory) {
-                    call.reject("Directory not found: $path")
-                    return
-                }
-
-                val files = dir.listFiles()
-
-                val result = JSArray()
-                for (file in files) {
-                    val info = JSObject()
-                    info.put("name", file.name)
-                    info.put("isDirectory", file.isDirectory)
-                    result.put(info)
-                }
-
-                val ret = JSObject()
-                ret.put("files", result)
-                call.resolve(ret)
-            } finally {
-                device.close()
-            }
-        } catch (e: Exception) {
-            Log.e(TAG, "readdir failed", e)
-            call.reject("readdir failed: ${e.message}")
-        }
-    }
-
-    @PluginMethod
-    fun readFile(call: PluginCall) {
-        val vendorId = call.getInt("vendorId")
-        val productId = call.getInt("productId")
-        val path = call.getString("path")
-
-        if (vendorId == null || productId == null || path == null) {
-            call.reject("vendorId, productId, and path are required")
-            return
-        }
-
-        try {
-            val device = getDevice(vendorId, productId)
-
-            val usbManager = context.getSystemService(Context.USB_SERVICE) as UsbManager
-            if (!usbManager.hasPermission(device.usbDevice)) {
-                call.reject("No permission for this USB device")
-                return
-            }
-
-            device.init()
-            try {
-                val fs = device.partitions[0].fileSystem
-                val root = fs.rootDirectory
-                val usbFile = root.search(path)
-
-                if (usbFile == null) {
-                    val ret = JSObject()
-                    ret.put("data", null as String?)
-                    call.resolve(ret)
-                    return
-                }
-
-                if (usbFile.isDirectory) {
-                    call.reject("Path is a directory: $path")
-                    return
-                }
-
-                val fileLength = usbFile.length
-                if (fileLength > MAX_FILE_SIZE) {
-                    call.reject("File too large: $fileLength bytes (max $MAX_FILE_SIZE)")
-                    return
-                }
-                val buffer = ByteBuffer.allocate(fileLength.toInt())
-
-                val inputStream = UsbFileInputStream(usbFile)
-                val tmpBuf = ByteArray(fs.chunkSize)
-                var count: Int
-                while (inputStream.read(tmpBuf).also { count = it } != -1) {
-                    buffer.put(tmpBuf, 0, count)
-                }
-                inputStream.close()
-
-                val base64Data = Base64.encodeToString(buffer.array(), Base64.NO_WRAP)
-
-                val ret = JSObject()
-                ret.put("data", base64Data)
-                call.resolve(ret)
-            } finally {
-                device.close()
-            }
-        } catch (e: Exception) {
-            Log.e(TAG, "readFile failed", e)
-            call.reject("readFile failed: ${e.message}")
-        }
-    }
-
-    @Throws(Exception::class)
-    private fun getDevice(vendorId: Int, productId: Int): UsbMassStorageDevice {
-        val devices = UsbMassStorageDevice.getMassStorageDevices(context)
-        return devices.firstOrNull { device ->
-            val usbDevice = device.usbDevice
-            usbDevice.vendorId == vendorId && usbDevice.productId == productId
-        } ?: throw Exception("USB device not found: vendorId=$vendorId, productId=$productId")
-    }
-}