libaums：开源库，用于访问Android上的USB Mass Storage设备，而无需植根设备

libaums ======= [](https://www.javadoc.io/doc/me.jahnen/libaums) [ ](https://travis-ci.org/magnusja/libaums)[ ](https://codecov.io/gh/magnusja/libaums)[ ](https://www.codacy.com/manual/magnusja/libaums?utm_source=github.com&utm_medium=referral&utm_content=magnusja/libaums&utm_campaign=Badge_Grade)[  ](https://bintray.com/magnusja/maven/libaums/_latestVersion) [ ](https://gitter.im/libaums) A library to access USB mass storage devices (pen drives, external HDDs, card readers) using the Android USB Host API. Currently it supports the SCSI command set and the FAT32 file system. ## How to use ### Install The library can be included into your project like this: ```ruby implementation 'me.jahnen:libaums:0.7.6' ``` If you need the HTTP or the storage provider module: ```ruby implementation 'me.jahnen:libaums-httpserver:0.5.3' implementation 'me.jahnen:libaums-storageprovider:0.5.1' ``` ### Basics #### Query available mass storage devices #### Java ```java UsbMassStorageDevice[] devices = UsbMassStorageDevice.getMassStorageDevices(this /* Context or Activity */); for(UsbMassStorageDevice device: devices) { // before interacting with a device you need to call init()! device.init(); // Only uses the first partition on the device FileSystem currentFs = device.getPartitions().get(0).getFileSystem(); Log.d(TAG, "Capacity: " + currentFs.getCapacity()); Log.d(TAG, "Occupied Space: " + currentFs.getOccupiedSpace()); Log.d(TAG, "Free Space: " + currentFs.getFreeSpace()); Log.d(TAG, "Chunk size: " + currentFs.getChunkSize()); } ``` #### Kotlin ```kotlin val devices = UsbMassStorageDevice.getMassStorageDevices(this /* Context or Activity */) for (device in devices) { // before interacting with a device you need to call init()! device.init() // Only uses the first partition on the device val currentFs = device.partitions[0].fileSystem Log.d(TAG, "Capacity: " + currentFs.capacity) Log.d(TAG, "Occupied Space: " + currentFs.occupiedSpace) Log.d(TAG, "Free Space: " + currentFs.freeSpace) Log.d(TAG, "Chunk size: " + currentFs.chunkSize) } ``` #### Permissions Your app needs to get permission from the user at run time to be able to communicate the device. From a `UsbMassStorageDevice` you can get the underlying `android.usb.UsbDevice` to do so. #### Java ```java PendingIntent permissionIntent = PendingIntent.getBroadcast(this, 0, new Intent(ACTION_USB_PERMISSION), 0); usbManager.requestPermission(device.getUsbDevice(), permissionIntent); ```` #### Kotlin ```kotlin val permissionIntent = PendingIntent.getBroadcast(this, 0, Intent(ACTION_USB_PERMISSION), 0); usbManager.requestPermission(device.usDevice, permissionIntent); ``` For more information regarding permissions please check out the Android documentation: https://developer.android.com/guide/topics/connectivity/usb/host.html#permission-d #### Working with files and folders ##### Java ```java UsbFile root = currentFs.getRootDirectory(); UsbFile[] files = root.listFiles(); for(UsbFile file: files) { Log.d(TAG, file.getName()); if(file.isDirectory()) { Log.d(TAG, file.getLength()); } } UsbFile newDir = root.createDirectory("foo"); UsbFile file = newDir.createFile("bar.txt"); // write to a file OutputStream os = new UsbFileOutputStream(file); os.write("hello".getBytes()); os.close(); // read from a file InputStream is = new UsbFileInputStream(file); byte[] buffer = new byte[currentFs.getChunkSize()]; is.read(buffer); ``` ##### Kotlin ```kotlin val root = currentFs.rootDirectory val files = root.listFiles() for (file in files) { Log.d(TAG, file.name) if (file.isDirectory) { Log.d(TAG, file.length) } } val newDir = root.createDirectory("foo") val file = newDir.createFile("bar.txt") // write to a file val os = UsbFileOutputStream(file) os.write("hello".toByteArray()) os.close() // read from a file val ins = UsbFileInputStream(file) val buffer = ByteArray(currentFs.chunkSize) ins.read(buffer) ``` #### Using buffered streams for more efficency ```java OutputStream os = UsbFileStreamFactory.createBufferedOutputStream(file, currentFs); InputStream is = UsbFileStreamFactory.createBufferedInputStream(file, currentFs); ``` #### Cleaning up ```java // Don't forget to call UsbMassStorageDevice.close() when you are finished device.close(); ``` #### Troubleshooting If you get the following error fairly often (mostly under Android 9.0 Pie): ``` java.io.IOException: Could not write to device, result == -1 errno 0 null ``` or something similar, you might want to try the [libusb module](https://github.com/magnusja/libaums/tree/develop/libusbcommunication). This uses, instead of the Android USB host API, the [libusb](https://github.com/libusb/libusb) library for low level communication with the USB mass storage device. see discussions: https://github.com/magnusja/libaums/issues/209 https://github.com/magnusja/libaums/issues/237 https://github.com/magnusja/libaums/pull/242 __Note__, that libusb is licensed under LGPL, which is different from the license this project is licensed under! This might come with some drawbacks or extra work for closed source applications, see here: https://xebia.com/blog/the-lgpl-on-android/ ## Provide access to external apps Usually third party apps do not have access to the files on a mass storage device if the Android system does mount (this is usually supported on newer devices, back in 2014 there was no support for that) the device or this app integrates this library itself. To solve this issue there are two additional modules to provide access to other app. One uses the Storage Access Framework feature of Android (API level >= 19) and the other one spins up an HTTP server to allow downloading or streaming of videos or images for instance. ### HTTP server [](https://www.javadoc.io/doc/com.github.mjdev/libaums-httpserver) libaums currently supports two different HTTP server libraries. 1. [NanoHTTPD](https://github.com/NanoHttpd/nanohttpd) 2. [AsyncHttpServer](https://github.com/koush/AndroidAsync/blob/master/AndroidAsync/src/com/koushikdutta/async/http/server/AsyncHttpServer.java) You can spin up a server pretty easy, you just have to decide for a HTTP server implementation. If you do not have special requirements, you can just go for one, it should not make much of a difference. #### Java ```java UsbFile file = ... // can be directory or file HttpServer server = AsyncHttpServer(8000); // port 8000 // or HttpServer server = NanoHttpdServer(8000); // port 8000 UsbFileHttpServer fileServer = new UsbFileHttpServer(file, server); fileServer.start(); ``` #### Kotlin ```kotlin val file: UsbFile // can be directory or file val server = AsyncHttpServer(8000) // port 8000 // or val server = NanoHttpdServer(8000) // port 8000 val fileServer = UsbFileHttpServer(file, server) fileServer.start() ``` The file you provide can either be an actual file or a directory: 1. File: Accessible either via "/" or "/FILE_NAME" 2. Directory: All files in this directory und sub directories are accessable via their names. Directory listing is not supported! If you want to be able to access these files when your app is in background, you should implement a service for that. There is an example available in the `httpserver` module. You can use it, but should subclass it or create your own to adapt it to your needs. #### Java `