This module defines a Perl object that represents the data and functionality associated with a USB
device. The object interface provides read-only access to the important data associated with a device. It
also provides methods for almost all of the functions supplied by libusb. Where necessary, the interfaces
to these methods were changed to better match Perl usage. However, most of the methods are straight-
forward wrappers around their libusb counterparts.
METHODS
DESTROY
Close the device connected to the object.
filename
Retrieve the filename associated with the device.
config
In list context, return a list of the configuration structures for this device. In scalar context,
return a reference to that list. This method is deprecated in favor of the two new methods:
configurations and get_configuration.
configurations
In list context, return a list of the configuration structures for this device. In scalar context,
return a reference to that list.
get_configuration
Retrieve the configuration requested by index. The legal values are from 0 to bNumConfigurations() -
1. Negative values access from the back of the list of configurations.
index numeric index of the index to return. If not supplied, use 0.
Returns an object encapsulating the configuration on success, or "undef" on failure.
accessors
There a several accessor methods that return data from the device and device descriptor. Each is
named after the field that they return. All of the BCD fields have been changed to floating point
numbers, so that you don't have to decode them yourself.
The methods include:
bcdUSB
bDeviceClass
bDeviceSubClass
bDeviceProtocol
bMaxPacketSize0
idVendor
idProduct
bcdDevice
iManufacturer
iProduct
iSerialNumber
bNumConfigurations
manufacturer
Retrieve the manufacture name from the device as a string. Return undef if the device read fails.
product
Retrieve the product name from the device as a string. Return undef if the device read fails.
serial_number
Retrieve the serial number from the device as a string. Return undef if the device read fails.
open
Open the device. If the device is already open, close it and reopen it.
If the device fails to open, the reason will be available in $!.
set_configuration
Sets the active configuration of the device.
configuration
the integer specified in the descriptor field bConfigurationValue.
returns 0 on success or <0 on error
When using libusb-win32 under Windows, it is important to call set_configuration() after the open()
but before any other method calls. Without this call, other methods may not work. This call is not
required under Linux.
set_altinterface
Sets the active alternative setting of the current interface for the device.
alternate
the integer specified in the descriptor field bAlternateSetting.
returns 0 on success or <0 on error
clear_halt
Clears any halt status on the supplied endpoint.
alternate
the integer specified bEndpointAddress descriptor field.
returns 0 on success or <0 on error
reset
Resets the device. This also closes the handle and invalidates this device. This device will be
unusable.
claim_interface
Claims the specified interface with the operating system.
interface
The interface value listed in the descriptor field bInterfaceNumber.
Returns 0 on success, <0 on failure.
release_interface
Releases the specified interface back to the operating system.
interface
The interface value listed in the descriptor field bInterfaceNumber.
Returns 0 on success, <0 on failure.
control_msg
Performs a control request to the default control pipe on a device.
requesttype
request
value
index
bytes
Any returned data is placed here. If you don't want any returned data, pass undef.
size
Size of supplied buffer.
timeout
Milliseconds to wait for response.
Returns number of bytes read or written on success, <0 on failure.
get_string
Retrieve a string descriptor from the device.
index
The index of the string in the string list.
langid
The language id used to specify which of the supported languages the string should be encoded in.
Returns a Unicode string. The function returns undef on error.
get_string_simple
Retrieve a string descriptor from the device.
index
The index of the string in the string list.
Returns a C-style string if successful, or undef on error.
get_descriptor
Retrieve a descriptor from the device
type
The type of descriptor to retrieve.
index
The index of that descriptor in the list of descriptors of that type.
TODO: This method needs major rewrite to be Perl-ish. I need to provide a better way to specify the
type (or at least document which are available), and I need to return a Perl data structure, not a
buffer of binary data.
get_descriptor_by_endpoint
Retrieve an endpoint-specific descriptor from the device
ep Endpoint to query.
type
The type of descriptor to retrieve.
index
The index of that descriptor in the list of descriptors.
buf Buffer into which to write the requested descriptor
size
Max size to read into the buffer.
TODO: This method needs major rewrite to be Perl-ish. I need to provide a better way to specify the
type (or at least document which are available), and I need to return a Perl data structure, not a
buffer of binary data.
bulk_read
Perform a bulk read request from the specified endpoint.
ep The number of the endpoint to read
bytes
Buffer into which to write the requested data.
size
Max size to read into the buffer.
timeout
Maximum time to wait (in milliseconds)
The function returns the number of bytes returned or <0 on error.
USB is packet based, not stream based. So using bulk_read() to read part of the packet acts like a
peek. The next time you read, all of the packet is still there.
The data is only removed when you read the entire packet. For this reason, you should always call
bulk_read() with the total packet size.
interrupt_read
Perform a interrupt read request from the specified endpoint.
ep The number of the endpoint to read
bytes
Buffer into which to write the requested data.
size
Max size to read into the buffer.
timeout
Maximum time to wait (in milliseconds)
The function returns the number of bytes returned or <0 on error.
bulk_write
Perform a bulk write request to the specified endpoint.
ep The number of the endpoint to write
bytes
Buffer from which to write the requested data.
timeout
Maximum time to wait (in milliseconds)
The function returns the number of bytes written or <0 on error.
interrupt_write
Perform a interrupt write request to the specified endpoint.
ep The number of the endpoint to write
bytes
Buffer from which to write the requested data.
timeout
Maximum time to wait (in milliseconds)
The function returns the number of bytes written or <0 on error.
get_driver_np
This function returns the name of the driver bound to the interface specified by the parameter
interface.
$interface
The interface number of interest.
Returns "undef" on error.
detach_kernel_driver_np
This function will detach a kernel driver from the interface specified by parameter interface.
Applications using libusb can then try claiming the interface. Returns 0 on success or < 0 on error.
Install Now
PNG Icons
