Version 0.2.2

Author: wuwbobo2021

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changes
+
+## 0.2.2
+* Fixed support for newest Android versions: `check_attached_intent()` does not work, `PermissionRequest` never returns the result of being permitted, both are caused by the bad implementation of `PartialEq` for `DeviceInfo`.
+* Added `UsbSerial` trait to prepare for driver implementations of non-CDC serial adapters.
+* The serial handler can be turned into `nusb` transfer queues for asynchronous operations, this can be done after serial configuration.
+
+## 0.2.1
+* Added `HotplugWatch`;
+* `DeviceInfo::request_permission()` now returns a result of `Option<PermissionRequest>` instead of `()`.
+
+## 0.2.0
+* Switched to `nusb` for USB data transfering, instead of calling Java methods for reading and writing.
+* `serialport` became a required dependency; the optional feature for `rusb` (which may not work on some Android devices) is removed.
+
+## 0.1.1
+* Fixed doc.rs build problem.
+
+## 0.1.0
+* Initial release.

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "android-usbser"
-version = "0.2.1"
+version = "0.2.2"
 authors = ["wuwbobo2021 <wuwbobo@outlook.com>"]
 edition = "2021"
 license = "MIT OR Apache-2.0"
@@ -32,7 +32,7 @@ nusb = "0.1.12"
 serialport = "4.6"
 futures-core = "0.3"
 futures-lite = "2.5"
-jni-min-helper = { version = "0.2.2", features = ["futures"] }
+jni-min-helper = { version = "0.2.6", features = ["futures"] }
 
 [lib]
 name = "android_usbser"

lib.rs

@@ -54,9 +54,27 @@ pub mod usb {
     }
 }
 
+use nusb::transfer::{Queue, RequestBuffer};
+
+/// Serial driver implementations inside this crate should implement this trait.
+///
+/// TODO: add crate-level functions `probe() -> Result<Vec<DeviceInfo>, Error>`
+/// and `open(dev_info: &DeviceInfo, timeout: Duration) -> Result<Box<dyn UsbSerial>, Error>`.
+pub trait UsbSerial: serialport::SerialPort {
+    /// Sets baudrate, parity check mode, data bits and stop bits.
+    fn configure(&mut self, conf: &SerialConfig) -> std::io::Result<()>;
+
+    /// Takes `nusb` transfer queues of the read endpoint and the write endpoint.
+    /// This can be called after serial configuration to do asynchronous operations.
+    fn into_queues(self) -> (Queue<RequestBuffer>, Queue<Vec<u8>>);
+
+    #[doc(hidden)]
+    fn sealer(_: private::Internal);
+}
+
 use serialport::{DataBits, Parity, StopBits};
 
-/// Sets baudrate, parity check mode, data bits and stop bits.
+/// Serial parameters including baudrate, parity check mode, data bits and stop bits.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 pub struct SerialConfig {
     pub baud_rate: u32,
@@ -156,3 +174,9 @@ impl std::fmt::Display for SerialConfig {
         write!(f, "{baud_rate},{parity},{data_bits},{stop_bits}")
     }
 }
+
+mod private {
+    /// Used as a parameter of the hidden function in sealed traits.
+    #[derive(Debug)]
+    pub struct Internal;
+}

ser_cdc.rs

@@ -3,9 +3,12 @@ use std::{
     time::Duration,
 };
 
-use crate::usb::{self, DeviceInfo, InterfaceInfo, SyncReader, SyncWriter};
 use crate::SerialConfig;
-use nusb::transfer::{Control, ControlType, Direction, Recipient};
+use crate::{
+    usb::{self, DeviceInfo, InterfaceInfo, SyncReader, SyncWriter},
+    UsbSerial,
+};
+use nusb::transfer::{Control, ControlType, Direction, Queue, Recipient, RequestBuffer};
 
 use serialport::{DataBits, Parity, SerialPort, StopBits};
 
@@ -354,3 +357,15 @@ impl SerialPort for CdcSerial {
         Err(err_unsupported_op())
     }
 }
+
+impl UsbSerial for CdcSerial {
+    fn configure(&mut self, conf: &SerialConfig) -> std::io::Result<()> {
+        self.set_config(*conf)
+    }
+
+    fn into_queues(self) -> (Queue<RequestBuffer>, Queue<Vec<u8>>) {
+        (self.reader.into(), self.writer.into())
+    }
+
+    fn sealer(_: crate::private::Internal) {}
+}

usb_conn.rs

@@ -14,7 +14,7 @@ const EXTRA_DEVICE: &str = "device";
 const ACTION_USB_PERMISSION: &str = "rust.android_usbser.USB_PERMISSION"; // custom
 const EXTRA_PERMISSION_GRANTED: &str = "permission";
 
-/// Gets a gloabal reference of `android.hardware.usb.UsbManager`.
+/// Gets a global reference of `android.hardware.usb.UsbManager`.
 #[inline(always)]
 pub(crate) fn usb_manager() -> Result<&'static jni::objects::JObject<'static>, Error> {
     use std::sync::OnceLock;
@@ -50,7 +50,7 @@ fn get_usb_manager() -> Result<jni::objects::GlobalRef, Error> {
     }
 }
 
-/// Checks if the Android application is opened by an intent with
+/// Checks if the Android context is an activity opened by an intent of
 /// `android.hardware.usb.action.USB_DEVICE_ATTACHED`. If so, it takes the `DeviceInfo`
 /// for the caller to open the device.
 ///
@@ -84,7 +84,7 @@ pub fn check_attached_intent() -> Result<DeviceInfo, Error> {
     }
     let dev_info = get_extra_device(&intent_startup)?;
     if dev_info.check_connection() {
-        Ok(dev_info) 
+        Ok(dev_info)
     } else {
         Err(Error::from(ErrorKind::NotConnected))
     }
@@ -124,19 +124,19 @@ pub fn watch_devices() -> Result<HotplugWatch, Error> {
 /// Stream of device connection / disconnection events.
 #[derive(Debug)]
 pub struct HotplugWatch {
-    waiter: BroadcastWaiter
+    waiter: BroadcastWaiter,
 }
 
 /// Event returned from the `HotplugWatch` stream.
 #[derive(Clone, Debug)]
 pub enum HotplugEvent {
     Connected(DeviceInfo),
-    Disconnected(DeviceInfo)
+    Disconnected(DeviceInfo),
 }
 
 #[derive(Debug)]
 struct HotplugWatchFuture<'a> {
-    watch: &'a mut HotplugWatch
+    watch: &'a mut HotplugWatch,
 }
 
 impl HotplugWatch {
@@ -217,7 +217,7 @@ impl DeviceInfo {
         let usb_man = usb_manager()?;
         let env = &mut jni_attach_vm().map_err(jerr)?;
         env.call_method(
-            &usb_man,
+            usb_man,
             "hasPermission",
             "(Landroid/hardware/usb/UsbDevice;)Z",
             &[self.internal.as_obj().into()],
@@ -235,10 +235,10 @@ impl DeviceInfo {
     }
 
     /// Performs a permission request for the device.
-    /// 
+    ///
     /// Returns `Ok(None)` if the permission is already granted. Otherwise it returns a
     /// `PermissionRequest` handler.
-    /// 
+    ///
     /// The activity might be paused by `requestPermission()` here, but resumed on receving result.
     /// The state of `PermissionRequest` can be checked on `android_activity::MainEvent::Resume`,
     /// Otherwise block in a background thread (it wouldn't be paused/resumed automatically).
@@ -279,7 +279,7 @@ impl DeviceInfo {
             .map_err(jerr)?;
 
         env.call_method(
-            &usb_man,
+            usb_man,
             "requestPermission",
             "(Landroid/hardware/usb/UsbDevice;Landroid/app/PendingIntent;)V",
             &[(&self.internal).into(), (&pending).into()],
@@ -291,7 +291,12 @@ impl DeviceInfo {
             return Ok(None); // almost impossible
         }
         BroadcastWaiter::build([ACTION_USB_PERMISSION])
-            .map(|waiter| Some(PermissionRequest { dev_info: self.clone(), waiter }))
+            .map(|waiter| {
+                Some(PermissionRequest {
+                    dev_info: self.clone(),
+                    waiter,
+                })
+            })
             .map_err(jerr)
     }
 
@@ -305,7 +310,7 @@ impl DeviceInfo {
             let env = &mut jni_attach_vm().map_err(jerr)?;
             let conn = env
                 .call_method(
-                    &usb_man,
+                    usb_man,
                     "openDevice",
                     "(Landroid/hardware/usb/UsbDevice;)Landroid/hardware/usb/UsbDeviceConnection;",
                     &[(&self.internal).into()],
@@ -331,15 +336,15 @@ impl DeviceInfo {
 #[derive(Debug)]
 pub struct PermissionRequest {
     dev_info: DeviceInfo,
-    waiter: BroadcastWaiter
+    waiter: BroadcastWaiter,
 }
 
 impl PermissionRequest {
     /// Returns a reference of the associated `DeviceInfo` which can be cloned.
     pub fn device_info(&self) -> &DeviceInfo {
         &self.dev_info
     }
-    
+
     /// Checks if the request has completed.
     pub fn responsed(&self) -> bool {
         self.waiter.count_received() > 0

usb_info.rs

@@ -9,7 +9,7 @@ pub fn list_devices() -> Result<Vec<DeviceInfo>, Error> {
     let env = &mut jni_attach_vm().map_err(jerr)?;
     let mut devices = Vec::new();
     let ref_dev_list = env
-        .call_method(&usb_man, "getDeviceList", "()Ljava/util/HashMap;", &[])
+        .call_method(usb_man, "getDeviceList", "()Ljava/util/HashMap;", &[])
         .get_object(env)
         .map_err(jerr)?;
     let map_dev = env.get_map(&ref_dev_list).map_err(jerr)?;
@@ -56,7 +56,9 @@ pub struct DeviceInfo {
     /// USB protocol version.
     #[getset(get = "pub")]
     version: Option<String>,
-    /// Device serial ID string.
+    /// Device serial ID string. FIXME: On Android 10 and above, this is always `None`
+    /// if this struct is created before gaining permission for the device. To read it,
+    /// call `list_devices()` and find the device again after the permission is granted.
     #[getset(get = "pub")]
     serial_number: Option<String>,
 
@@ -112,7 +114,16 @@ impl DeviceInfo {
             info.version = Some(get_string_field(env, dev, "getVersion")?);
             info.manufacturer_string = get_string_field(env, dev, "getManufacturerName").ok();
             info.product_string = get_string_field(env, dev, "getProductName").ok();
-            info.serial_number = get_string_field(env, dev, "getSerialNumber").ok();
+            info.serial_number = if android_api_level() < 29 {
+                get_string_field(env, dev, "getSerialNumber").ok()
+            } else {
+                // Avoid printing `java.lang.SecurityException: User has not given permission...`
+                env.call_method(dev, "getSerialNumber", "()Ljava/lang/String;", &[])
+                    .map_err(jni_clear_ex_silent)
+                    .get_object(env)
+                    .and_then(|o| o.get_string(env))
+                    .ok()
+            }
         }
         Ok(info)
     }
@@ -150,10 +161,16 @@ impl PartialEq for DeviceInfo {
     fn eq(&self, other: &Self) -> bool {
         // Check `android.hardware.usb.UsbDevice.equals()` source code:
         // it may compare both `UsbDevice` only by name (`path_name`).
+        if let (Some(self_ser), Some(other_ser)) =
+            (self.serial_number.as_ref(), other.serial_number.as_ref())
+        {
+            if self_ser != other_ser {
+                return false;
+            }
+        }
         self.vendor_id == other.vendor_id
             && self.product_id == other.product_id
             && self.path_name == other.path_name
-            && self.serial_number == other.serial_number
     }
 }
 

usb_sync.rs

@@ -74,6 +74,18 @@ impl SyncReader {
     }
 }
 
+impl From<ReadQueue> for SyncReader {
+    fn from(value: ReadQueue) -> Self {
+        Self::new(value)
+    }
+}
+
+impl From<SyncReader> for ReadQueue {
+    fn from(value: SyncReader) -> Self {
+        value.queue
+    }
+}
+
 /// Synchronous wrapper of a `nusb` OUT transfer queue.
 pub struct SyncWriter {
     queue: WriteQueue,
@@ -135,3 +147,15 @@ impl SyncWriter {
         result
     }
 }
+
+impl From<WriteQueue> for SyncWriter {
+    fn from(value: WriteQueue) -> Self {
+        Self::new(value)
+    }
+}
+
+impl From<SyncWriter> for WriteQueue {
+    fn from(value: SyncWriter) -> Self {
+        value.queue
+    }
+}