Merge branch 'upstream'

.github/workflows/rust.yml

@@ -118,3 +118,17 @@ jobs:
       run: cargo build --no-default-features --verbose
     - name: Run tests
       run: cargo test --no-default-features --verbose
+
+  fmt-check:
+    runs-on: ubuntu-latest
+
+    env:
+      DEBIAN_FRONTEND: noninteractive
+
+    steps:
+    - name: checkout repository and submodules
+      uses: actions/checkout@v2
+      with:
+        submodules: recursive
+    - name: fmt check
+      run: cargo fmt --check

examples/dump_descriptors.rs

@@ -6,22 +6,26 @@ fn main() {
     match HidApi::new() {
         Ok(api) => {
             for device in api.device_list() {
-                println!("  {} (Interface {}):",
+                println!(
+                    "  {} (Interface {}):",
                     match device.product_string() {
                         Some(s) => s,
                         _ => "<COULD NOT FETCH>",
                     },
                     device.interface_number()
                 );
                 let mut descriptor = vec![0u8; 2048];
-                match device.open_device(&api).and_then(|dev| dev.get_report_descriptor(&mut descriptor)) {
+                match device
+                    .open_device(&api)
+                    .and_then(|dev| dev.get_report_descriptor(&mut descriptor))
+                {
                     Ok(length) => println!("    {:?}", &mut descriptor[..length]),
-                    Err(err) => println!("    Failed to retrieve descriptor ({:?})", err)
+                    Err(err) => println!("    Failed to retrieve descriptor ({:?})", err),
                 }
             }
         }
         Err(e) => {
             eprintln!("Error: {}", e);
         }
     }
-}
+}

src/ffi.rs

@@ -110,8 +110,8 @@ pub mod macos {
 // For documentation look at the corresponding C header file hidapi_winapi.h
 #[cfg(target_os = "windows")]
 pub mod windows {
-    use windows_sys::core::GUID;
     use super::*;
+    use windows_sys::core::GUID;
 
     extern "C" {
         pub fn hid_winapi_get_container_id(

src/lib.rs

@@ -61,13 +61,13 @@
 mod error;
 mod ffi;
 
+use cfg_if::cfg_if;
 use libc::wchar_t;
 use std::ffi::CStr;
 use std::ffi::CString;
 use std::fmt;
 use std::fmt::Debug;
 use std::sync::Mutex;
-use cfg_if::cfg_if;
 
 pub use error::HidError;
 
@@ -120,7 +120,6 @@ cfg_if! {
     }
 }
 
-
 pub type HidResult<T> = Result<T, HidError>;
 pub const MAX_REPORT_DESCRIPTOR_SIZE: usize = 4096;
 
@@ -234,7 +233,8 @@ impl HidApi {
     /// Indexes devices that match the given VID and PID filters.
     /// 0 indicates no filter.
     pub fn add_devices(&mut self, vid: u16, pid: u16) -> HidResult<()> {
-        self.device_list.append(&mut HidApiBackend::get_hid_device_info_vector(vid, pid)?);
+        self.device_list
+            .append(&mut HidApiBackend::get_hid_device_info_vector(vid, pid)?);
         Ok(())
     }
 
@@ -518,6 +518,8 @@ impl HidDevice {
         self.inner.check_error()
     }
 
+    /// Write an Output report to a HID device.
+    ///
     /// The first byte of `data` must contain the Report ID. For
     /// devices which only support a single report, this must be set
     /// to 0x0. The remaining bytes contain the report data. Since
@@ -530,26 +532,37 @@ impl HidDevice {
     /// `write()` will send the data on the first OUT endpoint, if
     /// one exists. If it does not, it will send the data through
     /// the Control Endpoint (Endpoint 0).
+    ///
+    /// If successful, returns the actual number of bytes written.
     pub fn write(&self, data: &[u8]) -> HidResult<usize> {
         self.inner.write(data)
     }
 
+    /// Read an Input report from a HID device.
+    ///
     /// Input reports are returned to the host through the 'INTERRUPT IN'
     /// endpoint. The first byte will contain the Report number if the device
     /// uses numbered reports.
+    ///
+    /// If successful, returns the actual number of bytes read.
     pub fn read(&self, buf: &mut [u8]) -> HidResult<usize> {
         self.inner.read(buf)
     }
 
+    /// Read an Input report from a HID device with timeout.
+    ///
     /// Input reports are returned to the host through the 'INTERRUPT IN'
     /// endpoint. The first byte will contain the Report number if the device
     /// uses numbered reports. Timeout measured in milliseconds, set -1 for
     /// blocking wait.
+    ///
+    /// If successful, returns the actual number of bytes read.
     pub fn read_timeout(&self, buf: &mut [u8], timeout: i32) -> HidResult<usize> {
         self.inner.read_timeout(buf, timeout)
     }
 
     /// Send a Feature report to the device.
+    ///
     /// Feature reports are sent over the Control endpoint as a
     /// Set_Report transfer.  The first byte of `data` must contain the
     /// 'Report ID'. For devices which only support a single report, this must
@@ -560,13 +573,20 @@ impl HidDevice {
     /// `send_feature_report()`: 'the Report ID' (or 0x0, for devices which
     /// do not use numbered reports), followed by the report data (16 bytes).
     /// In this example, the length passed in would be 17.
+    ///
+    /// If successful, returns the actual number of bytes written.
     pub fn send_feature_report(&self, data: &[u8]) -> HidResult<()> {
         self.inner.send_feature_report(data)
     }
 
+    /// Get a feature report from a HID device.
+    ///
     /// Set the first byte of `buf` to the 'Report ID' of the report to be read.
     /// Upon return, the first byte will still contain the Report ID, and the
     /// report data will start in `buf[1]`.
+    ///
+    /// If successful, returns the number of bytes read plus one for the report ID (which is still
+    /// in the first byte).
     pub fn get_feature_report(&self, buf: &mut [u8]) -> HidResult<usize> {
         self.inner.get_feature_report(buf)
     }

src/windows.rs

@@ -1,5 +1,5 @@
-pub use windows_sys::core::GUID;
 use crate::{HidDevice, HidResult};
+pub use windows_sys::core::GUID;
 
 impl HidDevice {
     /// Get the container ID for a HID device.