pub struct Device { /* private fields */ }
Expand description
An opened USB device.
Obtain a Device
by calling DeviceInfo::open
:
use nusb;
let device_info = nusb::list_devices().unwrap()
.find(|dev| dev.vendor_id() == 0xAAAA && dev.product_id() == 0xBBBB)
.expect("device not connected");
let device = device_info.open().expect("failed to open device");
let interface = device.claim_interface(0);
This type is reference-counted with an Arc
internally, and can be cloned cheaply for
use in multiple places in your program. The device is closed when all clones and all
associated Interface
s are dropped.
Use .claim_interface(i)
to open an interface to submit
transfers.
Implementations§
source§impl Device
impl Device
sourcepub fn claim_interface(&self, interface: u8) -> Result<Interface, Error>
pub fn claim_interface(&self, interface: u8) -> Result<Interface, Error>
Open an interface of the device and claim it for exclusive use.
sourcepub fn detach_and_claim_interface(
&self,
interface: u8
) -> Result<Interface, Error>
pub fn detach_and_claim_interface( &self, interface: u8 ) -> Result<Interface, Error>
Detach kernel drivers and open an interface of the device and claim it for exclusive use.
§Platform notes
This function can only detach kernel drivers on Linux. Calling on other platforms has
the same effect as claim_interface
.
sourcepub fn active_configuration(
&self
) -> Result<Configuration<'_>, ActiveConfigurationError>
pub fn active_configuration( &self ) -> Result<Configuration<'_>, ActiveConfigurationError>
Get information about the active configuration.
This returns cached data and does not perform IO. However, it can fail if the device is unconfigured, or if it can’t find a configuration descriptor for the configuration reported as active by the OS.
sourcepub fn configurations(&self) -> impl Iterator<Item = Configuration<'_>>
pub fn configurations(&self) -> impl Iterator<Item = Configuration<'_>>
Get an iterator returning information about each configuration of the device.
This returns cached data and does not perform IO.
sourcepub fn set_configuration(&self, configuration: u8) -> Result<(), Error>
pub fn set_configuration(&self, configuration: u8) -> Result<(), Error>
Set the device configuration.
The argument is the desired configuration’s bConfigurationValue
descriptor field from Configuration::configuration_value
or 0
to
unconfigure the device.
§Platform-specific notes
- Not supported on Windows
sourcepub fn get_descriptor(
&self,
desc_type: u8,
desc_index: u8,
language_id: u16,
timeout: Duration
) -> Result<Vec<u8>, Error>
pub fn get_descriptor( &self, desc_type: u8, desc_index: u8, language_id: u16, timeout: Duration ) -> Result<Vec<u8>, Error>
Request a descriptor from the device.
The language_id
should be 0
unless you are requesting a string descriptor.
§Platform-specific details
- On Windows, the timeout argument is ignored, and an OS-defined timeout is used.
- On Windows, this does not wake suspended devices. Reading their descriptors will return an error.
sourcepub fn get_string_descriptor_supported_languages(
&self,
timeout: Duration
) -> Result<impl Iterator<Item = u16>, Error>
pub fn get_string_descriptor_supported_languages( &self, timeout: Duration ) -> Result<impl Iterator<Item = u16>, Error>
Request the list of supported languages for string descriptors.
§Platform-specific details
See notes on get_descriptor
.
sourcepub fn get_string_descriptor(
&self,
desc_index: u8,
language_id: u16,
timeout: Duration
) -> Result<String, Error>
pub fn get_string_descriptor( &self, desc_index: u8, language_id: u16, timeout: Duration ) -> Result<String, Error>
Request a string descriptor from the device.
Almost all devices support only the language ID US_ENGLISH
.
Unpaired UTF-16 surrogates will be replaced with �
, like String::from_utf16_lossy
.
§Platform-specific details
See notes on get_descriptor
.
sourcepub fn reset(&self) -> Result<(), Error>
pub fn reset(&self) -> Result<(), Error>
Reset the device, forcing it to re-enumerate.
This Device
will no longer be usable, and you should drop it and call
super::list_devices
to find and re-open it again.
§Platform-specific notes
- Not supported on Windows
sourcepub fn control_in_blocking(
&self,
control: Control,
data: &mut [u8],
timeout: Duration
) -> Result<usize, TransferError>
pub fn control_in_blocking( &self, control: Control, data: &mut [u8], timeout: Duration ) -> Result<usize, TransferError>
Synchronously perform a single IN (device-to-host) transfer on the default control endpoint.
§Platform-specific notes
- Not supported on Windows. You must claim an interface and use the interface handle to submit transfers.
- On Linux, this takes a device-wide lock, so if you have multiple threads, you are better off using the async methods.
sourcepub fn control_out_blocking(
&self,
control: Control,
data: &[u8],
timeout: Duration
) -> Result<usize, TransferError>
pub fn control_out_blocking( &self, control: Control, data: &[u8], timeout: Duration ) -> Result<usize, TransferError>
Synchronously perform a single OUT (host-to-device) transfer on the default control endpoint.
§Platform-specific notes
- Not supported on Windows. You must claim an interface and use the interface handle to submit transfers.
- On Linux, this takes a device-wide lock, so if you have multiple threads, you are better off using the async methods.
sourcepub fn control_in(&self, data: ControlIn) -> TransferFuture<ControlIn> ⓘ
pub fn control_in(&self, data: ControlIn) -> TransferFuture<ControlIn> ⓘ
Asynchronously submit a single IN (device-to-host) transfer on the default control endpoint.
§Example
use futures_lite::future::block_on;
use nusb::transfer::{ ControlIn, ControlType, Recipient };
let data: Vec<u8> = block_on(device.control_in(ControlIn {
control_type: ControlType::Vendor,
recipient: Recipient::Device,
request: 0x30,
value: 0x0,
index: 0x0,
length: 64,
})).into_result()?;
§Platform-specific notes
- Not supported on Windows. You must claim an interface and use the interface handle to submit transfers.
sourcepub fn control_out(
&self,
data: ControlOut<'_>
) -> TransferFuture<ControlOut<'_>> ⓘ
pub fn control_out( &self, data: ControlOut<'_> ) -> TransferFuture<ControlOut<'_>> ⓘ
Submit a single OUT (host-to-device) transfer on the default control endpoint.
§Example
use futures_lite::future::block_on;
use nusb::transfer::{ ControlOut, ControlType, Recipient };
block_on(device.control_out(ControlOut {
control_type: ControlType::Vendor,
recipient: Recipient::Device,
request: 0x32,
value: 0x0,
index: 0x0,
data: &[0x01, 0x02, 0x03, 0x04],
})).into_result()?;
§Platform-specific notes
- Not supported on Windows. You must claim an interface and use the interface handle to submit transfers.