Struct rusb::DeviceHandle

pub struct DeviceHandle<T: UsbContext> { /* private fields */ }

A handle to an open USB device.

Implementations

impl<T: UsbContext> DeviceHandle<T>

pub fn as_raw(&self) -> *mut libusb_device_handle

Get the raw libusb_device_handle pointer, for advanced use in unsafe code.

This structure tracks claimed interfaces, and will get out if sync if interfaces are manipulated externally. Use only libusb endpoint IO functions.

pub fn into_raw(self) -> *mut libusb_device_handle

Consumes the DeviceHandle, returning the raw libusb_device_handle pointer, for advanced use in unsafe code.

Safety

Panics if you have any claimed interfaces on this handle.

pub fn context(&self) -> &T

Get the context associated with this device

pub fn device(&self) -> Device<T>

Get the device associated to this handle

pub unsafe fn from_libusb( context: T, handle: NonNull<libusb_device_handle> ) -> DeviceHandle<T>

Safety

Converts an existing libusb_device_handle pointer into a DeviceHandle<T>. handle must be a pointer to a valid libusb_device_handle. Rusb assumes ownership of the handle, and will close it on drop.

pub fn active_configuration(&self) -> Result<u8>

Returns the active configuration number.

pub fn set_active_configuration(&self, config: u8) -> Result<()>

Sets the device’s active configuration.

pub fn unconfigure(&self) -> Result<()>

Puts the device in an unconfigured state.

pub fn reset(&self) -> Result<()>

Resets the device.

pub fn clear_halt(&self, endpoint: u8) -> Result<()>

Clear the halt/stall condition for an endpoint.

pub fn kernel_driver_active(&self, iface: u8) -> Result<bool>

Indicates whether the device has an attached kernel driver.

This method is not supported on all platforms.

pub fn detach_kernel_driver(&self, iface: u8) -> Result<()>

Detaches an attached kernel driver from the device.

This method is not supported on all platforms.

pub fn attach_kernel_driver(&self, iface: u8) -> Result<()>

Attaches a kernel driver to the device.

This method is not supported on all platforms.

pub fn set_auto_detach_kernel_driver(&self, auto_detach: bool) -> Result<()>

Enable/disable automatic kernel driver detachment.

When this is enabled rusb will automatically detach the kernel driver on an interface when claiming the interface, and attach it when releasing the interface.

On platforms which do not have support, this function will return Error::NotSupported, and rusb will continue as if this function was never called.

pub fn claim_interface(&self, iface: u8) -> Result<()>

Claims one of the device’s interfaces.

An interface must be claimed before operating on it. All claimed interfaces are released when the device handle goes out of scope.

pub fn release_interface(&self, iface: u8) -> Result<()>

Releases a claimed interface.

pub fn set_alternate_setting(&self, iface: u8, setting: u8) -> Result<()>

Sets an interface’s active setting.

pub fn read_interrupt( &self, endpoint: u8, buf: &mut [u8], timeout: Duration ) -> Result<usize>

Reads from an interrupt endpoint.

This function attempts to read from the interrupt endpoint with the address given by the endpoint parameter and fills buf with any data received from the endpoint. The function blocks up to the amount of time specified by timeout. Minimal timeout is 1 milliseconds, anything smaller will result in an infinite block.

If the return value is Ok(n), then buf is populated with n bytes of data received from the endpoint.

Errors

If this function encounters any form of error while fulfilling the transfer request, an error variant will be returned. If an error variant is returned, no bytes were read.

The errors returned by this function include:

• InvalidParam if the endpoint is not an input endpoint.
• Timeout if the transfer timed out.
• Pipe if the endpoint halted.
• Overflow if the device offered more data.
• NoDevice if the device has been disconnected.
• Io if the transfer encountered an I/O error.

pub fn write_interrupt( &self, endpoint: u8, buf: &[u8], timeout: Duration ) -> Result<usize>

Writes to an interrupt endpoint.

This function attempts to write the contents of buf to the interrupt endpoint with the address given by the endpoint parameter. The function blocks up to the amount of time specified by timeout. Minimal timeout is 1 milliseconds, anything smaller will result in an infinite block.

If the return value is Ok(n), then n bytes of buf were written to the endpoint.

Errors

If this function encounters any form of error while fulfilling the transfer request, an error variant will be returned. If an error variant is returned, no bytes were written.

The errors returned by this function include:

• InvalidParam if the endpoint is not an output endpoint.
• Timeout if the transfer timed out.
• Pipe if the endpoint halted.
• NoDevice if the device has been disconnected.
• Io if the transfer encountered an I/O error.

pub fn read_bulk( &self, endpoint: u8, buf: &mut [u8], timeout: Duration ) -> Result<usize>

Reads from a bulk endpoint.

This function attempts to read from the bulk endpoint with the address given by the endpoint parameter and fills buf with any data received from the endpoint. The function blocks up to the amount of time specified by timeout. Minimal timeout is 1 milliseconds, anything smaller will result in an infinite block.

If the return value is Ok(n), then buf is populated with n bytes of data received from the endpoint.

Errors

If this function encounters any form of error while fulfilling the transfer request, an error variant will be returned. If an error variant is returned, no bytes were read.

The errors returned by this function include:

• InvalidParam if the endpoint is not an input endpoint.
• Timeout if the transfer timed out.
• Pipe if the endpoint halted.
• Overflow if the device offered more data.
• NoDevice if the device has been disconnected.
• Io if the transfer encountered an I/O error.

pub fn write_bulk( &self, endpoint: u8, buf: &[u8], timeout: Duration ) -> Result<usize>

Writes to a bulk endpoint.

This function attempts to write the contents of buf to the bulk endpoint with the address given by the endpoint parameter. The function blocks up to the amount of time specified by timeout. Minimal timeout is 1 milliseconds, anything smaller will result in an infinite block.

If the return value is Ok(n), then n bytes of buf were written to the endpoint.

Errors

If this function encounters any form of error while fulfilling the transfer request, an error variant will be returned. If an error variant is returned, no bytes were written.

The errors returned by this function include:

• InvalidParam if the endpoint is not an output endpoint.
• Timeout if the transfer timed out.
• Pipe if the endpoint halted.
• NoDevice if the device has been disconnected.
• Io if the transfer encountered an I/O error.

pub fn read_control( &self, request_type: u8, request: u8, value: u16, index: u16, buf: &mut [u8], timeout: Duration ) -> Result<usize>

Reads data using a control transfer.

This function attempts to read data from the device using a control transfer and fills buf with any data received during the transfer. The function blocks up to the amount of time specified by timeout. Minimal timeout is 1 milliseconds, anything smaller will result in an infinite block.

The parameters request_type, request, value, and index specify the fields of the control transfer setup packet (bmRequestType, bRequest, wValue, and wIndex respectively). The values for each of these parameters shall be given in host-endian byte order. The value for the request_type parameter can be built with the helper function, request_type(). The meaning of the other parameters depends on the type of control request.

If the return value is Ok(n), then buf is populated with n bytes of data.

Errors

If this function encounters any form of error while fulfilling the transfer request, an error variant will be returned. If an error variant is returned, no bytes were read.

The errors returned by this function include:

• InvalidParam if request_type does not specify a read transfer.
• Timeout if the transfer timed out.
• Pipe if the control request was not supported by the device.
• NoDevice if the device has been disconnected.
• Io if the transfer encountered an I/O error.

pub fn write_control( &self, request_type: u8, request: u8, value: u16, index: u16, buf: &[u8], timeout: Duration ) -> Result<usize>

Writes data using a control transfer.

This function attempts to write the contents of buf to the device using a control transfer. The function blocks up to the amount of time specified by timeout. Minimal timeout is 1 milliseconds, anything smaller will result in an infinite block.

The parameters request_type, request, value, and index specify the fields of the control transfer setup packet (bmRequestType, bRequest, wValue, and wIndex respectively). The values for each of these parameters shall be given in host-endian byte order. The value for the request_type parameter can be built with the helper function, request_type(). The meaning of the other parameters depends on the type of control request.

If the return value is Ok(n), then n bytes of buf were transfered.

Errors

If this function encounters any form of error while fulfilling the transfer request, an error variant will be returned. If an error variant is returned, no bytes were read.

The errors returned by this function include:

• InvalidParam if request_type does not specify a write transfer.
• Timeout if the transfer timed out.
• Pipe if the control request was not supported by the device.
• NoDevice if the device has been disconnected.
• Io if the transfer encountered an I/O error.

pub fn read_languages(&self, timeout: Duration) -> Result<Vec<Language>>

Reads the languages supported by the device’s string descriptors.

This function returns a list of languages that can be used to read the device’s string descriptors.

pub fn read_string_descriptor_ascii(&self, index: u8) -> Result<String>

Reads a ascii string descriptor from the device.

pub fn read_string_descriptor( &self, language: Language, index: u8, timeout: Duration ) -> Result<String>

Reads a string descriptor from the device.

language should be one of the languages returned from read_languages.

pub fn read_manufacturer_string_ascii( &self, device: &DeviceDescriptor ) -> Result<String>

Reads the device’s manufacturer string descriptor (ascii).

pub fn read_manufacturer_string( &self, language: Language, device: &DeviceDescriptor, timeout: Duration ) -> Result<String>

Reads the device’s manufacturer string descriptor.

pub fn read_product_string_ascii( &self, device: &DeviceDescriptor ) -> Result<String>

Reads the device’s product string descriptor (ascii).

pub fn read_product_string( &self, language: Language, device: &DeviceDescriptor, timeout: Duration ) -> Result<String>

Reads the device’s product string descriptor.

pub fn read_serial_number_string_ascii( &self, device: &DeviceDescriptor ) -> Result<String>

Reads the device’s serial number string descriptor (ascii).

pub fn read_serial_number_string( &self, language: Language, device: &DeviceDescriptor, timeout: Duration ) -> Result<String>

Reads the device’s serial number string descriptor.

pub fn read_configuration_string( &self, language: Language, configuration: &ConfigDescriptor, timeout: Duration ) -> Result<String>

Reads the string descriptor for a configuration’s description.

pub fn read_interface_string( &self, language: Language, interface: &InterfaceDescriptor<'_>, timeout: Duration ) -> Result<String>

Reads the string descriptor for a interface’s description.

Trait Implementations

impl<T: UsbContext> Debug for DeviceHandle<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: UsbContext> Drop for DeviceHandle<T>

fn drop(&mut self)

Closes the device.

impl<T: UsbContext + PartialEq> PartialEq for DeviceHandle<T>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: UsbContext + PartialEq> Eq for DeviceHandle<T>

impl<T: UsbContext> Send for DeviceHandle<T>

impl<T: UsbContext> Sync for DeviceHandle<T>