.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "USB::LibUSB::XS 3pm"
.TH USB::LibUSB::XS 3pm 2024-03-08 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
USB::LibUSB::XS \- Raw XS bindings to the libusb\-1.0 <http://libusb.info/> API.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  # import all the constants and non\-method subroutines
\&  use USB::LibUSB::XS;
\&
\&  my ($rv, $ctx) = USB::LibUSB::XS\->init();
\&  $ctx\->set_debug(LIBUSB_LOG_LEVEL_WARNING);
\& 
\&  my ($vendor_id, $product_id) = (0x1234, 0x5678);
\&  my $handle = $ctx\->open_device_with_vid_pid($vendor_id, $product_id);
\&
\&  $rv = $handle\->set_auto_detach_kernel_driver(1);
\&  $rv = $handle\->claim_interface($interface);
\&
\&  $rv = $handle\->bulk_transfer_write($endpoint, "some data", $timeout);
\&
\&  ($rv, my $data) = $handle\->bulk_transfer_read($endpoint, $length, $timeout);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
USB::LibUSB::XS provides the raw XS access to the libusb\-1.0 API, which can then be used
by modules like USB::LibUSB, which is a more user frienly interface.
.SH METHODS/FUNCTIONS
.IX Header "METHODS/FUNCTIONS"
The following API is documented in the excellent
libusb documentation <http://libusb.sourceforge.net/api-1.0/>.
.SS "Library initialization/deinitialization"
.IX Subsection "Library initialization/deinitialization"
Implementation status: complete.
.PP
\fIset_debug\fR
.IX Subsection "set_debug"
.PP
.Vb 1
\& $ctx\->set_debug(LIBUSB_LOG_LEVEL_DEBUG);
.Ve
.PP
\fIinit\fR
.IX Subsection "init"
.PP
.Vb 1
\& my ($rv, $ctx) = USB::LibUSB::XS\->init();
.Ve
.PP
\fIexit\fR
.IX Subsection "exit"
.PP
.Vb 1
\& $ctx\->exit();
.Ve
.SS "Device handling and enumeration"
.IX Subsection "Device handling and enumeration"
Implementation status: complete.
.PP
\fIget_device_list\fR
.IX Subsection "get_device_list"
.PP
.Vb 1
\& my ($rv, @device_list) = $ctx\->get_device_list();
.Ve
.PP
\&\f(CW@device_list\fR contains USB::LibUSB::XS::Device objects.
.PP
\fIget_bus_number\fR
.IX Subsection "get_bus_number"
.PP
.Vb 1
\& my $bus_number = $dev\->get_bus_number();
.Ve
.PP
\fIget_port_number\fR
.IX Subsection "get_port_number"
.PP
.Vb 1
\& my $port_number = $dev\->get_port_number();
.Ve
.PP
\fIget_port_numbers\fR
.IX Subsection "get_port_numbers"
.PP
.Vb 1
\& my ($rv, @port_numbers) = $dev\->get_port_numbers();
.Ve
.PP
\fIget_parent\fR
.IX Subsection "get_parent"
.PP
.Vb 1
\& my $parent_dev = $dev\->get_parent();
.Ve
.PP
\fIget_device_address\fR
.IX Subsection "get_device_address"
.PP
.Vb 1
\& my $address = $dev\->get_device_address();
.Ve
.PP
\fIget_device_speed\fR
.IX Subsection "get_device_speed"
.PP
.Vb 1
\& my $speed = $dev\->get_device_speed();
.Ve
.PP
\fIget_max_packet_size\fR
.IX Subsection "get_max_packet_size"
.PP
.Vb 1
\& my $size = $dev\->get_max_packet_size($endpoint);
.Ve
.PP
\fIget_max_iso_packet_size\fR
.IX Subsection "get_max_iso_packet_size"
.PP
.Vb 1
\& my $size = $dev\->get_max_iso_packet_size($endpoint);
.Ve
.PP
\fIref_device\fR
.IX Subsection "ref_device"
.PP
.Vb 1
\& $dev = $dev\->ref_device();
.Ve
.PP
\fIunref_device\fR
.IX Subsection "unref_device"
.PP
.Vb 1
\& $dev\->unref_device();
.Ve
.PP
\fIopen\fR
.IX Subsection "open"
.PP
.Vb 1
\& my ($rv, $handle) = $dev\->open();
.Ve
.PP
Return a USB::LibUSB::XS::Device::Handle object in \f(CW$handle\fR if \f(CW$rv\fR is 0.
.PP
\fIopen_device_with_vid_pid\fR
.IX Subsection "open_device_with_vid_pid"
.PP
.Vb 1
\& my $handle = $ctx\->open_device_with_vid_pid(0x1111, 0x2222);
.Ve
.PP
Return undef on error.
.PP
\fIclose\fR
.IX Subsection "close"
.PP
.Vb 1
\& $handle\->close();
.Ve
.PP
\fIget_device\fR
.IX Subsection "get_device"
.PP
.Vb 1
\& my $dev = $hanlde\->get_device();
.Ve
.PP
\fIget_configuration\fR
.IX Subsection "get_configuration"
.PP
.Vb 1
\& my $config = $handle\->get_configuration();
.Ve
.PP
\fIset_configuration\fR
.IX Subsection "set_configuration"
.PP
.Vb 1
\& my $rv = $handle\->set_configuration($config);
.Ve
.PP
\fIclaim_interface\fR
.IX Subsection "claim_interface"
.PP
.Vb 1
\& my $rv = $handle\->claim_interface($interface_number);
.Ve
.PP
\fIrelease_interface\fR
.IX Subsection "release_interface"
.PP
.Vb 1
\& my $rv = $handle\->release_interface($interface_number);
.Ve
.PP
\fIset_interface_alt_setting\fR
.IX Subsection "set_interface_alt_setting"
.PP
.Vb 1
\& my $rv = $handle\->set_interface_alt_setting($interface_number, $alternate_setting);
.Ve
.PP
\fIclear_halt\fR
.IX Subsection "clear_halt"
.PP
.Vb 1
\& my $rv = $handle\->clear_halt($endpoint);
.Ve
.PP
\fIreset_device\fR
.IX Subsection "reset_device"
.PP
.Vb 1
\& my $rv = $handle\->reset_device();
.Ve
.PP
\fIkernel_driver_active\fR
.IX Subsection "kernel_driver_active"
.PP
.Vb 1
\& my $is_active = $handle\->kernelt_driver_active($interface_number);
.Ve
.PP
\fIdetach_kernel_driver\fR
.IX Subsection "detach_kernel_driver"
.PP
.Vb 1
\& my $rv = $handle\->detach_kernel_driver($interface_number);
.Ve
.PP
\fIattach_kernel_driver\fR
.IX Subsection "attach_kernel_driver"
.PP
.Vb 1
\& my $rv = $handle\->attach_kernel_driver($interface_number);
.Ve
.PP
\fIset_auto_detach_kernel_driver\fR
.IX Subsection "set_auto_detach_kernel_driver"
.PP
.Vb 1
\& my $rv = $handle\->set_auto_detach_kernel_driver($enable);
.Ve
.SS Miscellaneous
.IX Subsection "Miscellaneous"
Implementation status: complete.
.PP
\fIlibusb_has_capability\fR
.IX Subsection "libusb_has_capability"
.PP
.Vb 1
\& my $has_cap = libusb_has_capability($capability);
.Ve
.PP
\fIlibusb_error_name\fR
.IX Subsection "libusb_error_name"
.PP
.Vb 1
\& my $error_name = libusb_error_name($error_code);
.Ve
.PP
\fIlibusb_get_version\fR
.IX Subsection "libusb_get_version"
.PP
.Vb 2
\& my $version_hash = libusb_get_version();
\& my $major = $version_hash\->{major};
.Ve
.PP
\fIlibusb_setlocale\fR
.IX Subsection "libusb_setlocale"
.PP
.Vb 1
\& my $rv = libusb_setlocale($locale);
.Ve
.PP
\fIlibusb_strerror\fR
.IX Subsection "libusb_strerror"
.PP
.Vb 1
\& my $strerror = libusb_strerror($error_code);
.Ve
.SS "USB descriptors"
.IX Subsection "USB descriptors"
Implementation status: complete.
.PP
All descriptors are returned as hash references.
.PP
\fIget_device_descriptor\fR
.IX Subsection "get_device_descriptor"
.PP
.Vb 2
\& my ($rv, $desc) = $dev\->get_device_descriptor();
\& my $iSerialNumber = $desc\->{iSerialNumber};
.Ve
.PP
\fIget_active_config_descriptor\fR
.IX Subsection "get_active_config_descriptor"
.PP
.Vb 2
\& my ($rv, $config) = $dev\->get_active_config_descriptor($ctx);
\& my $iConfiguration = $config\->{iConfiguration};
.Ve
.PP
\fIget_config_descriptor\fR
.IX Subsection "get_config_descriptor"
.PP
.Vb 1
\& my ($rv, $config) = $dev\->get_config_descriptor($ctx, $config_index);
.Ve
.PP
\fIget_config_descriptor_by_value\fR
.IX Subsection "get_config_descriptor_by_value"
.PP
.Vb 1
\& my ($rv, $config) = $dev\->get_config_descriptor_by_value($ctx, $bConfigurationValue);
.Ve
.PP
\fIget_bos_descriptor\fR
.IX Subsection "get_bos_descriptor"
.PP
.Vb 1
\& my ($rv, $bos) = $handle\->get_bos_descriptor($ctx);
.Ve
.PP
\fIget_string_descriptor_ascii\fR
.IX Subsection "get_string_descriptor_ascii"
.PP
.Vb 1
\& my ($rv, $data) = $handle\->get_string_descriptor_ascii($desc_index, $length);
.Ve
.PP
\fIget_descriptor\fR
.IX Subsection "get_descriptor"
.PP
.Vb 1
\& my ($rv, $data) = $handle\->get_descriptor($desc_type, $desc_index, $length);
.Ve
.PP
\fIget_string_descriptor\fR
.IX Subsection "get_string_descriptor"
.PP
.Vb 1
\& my ($rv, $data) = $handle\->get_string_descriptor($desc_index, $langid, $length);
.Ve
.SS "Device hotplug event notification"
.IX Subsection "Device hotplug event notification"
Implementation status: To be implemented.
.SS "Asynchronous device I/O"
.IX Subsection "Asynchronous device I/O"
Implementation status: To be implemented.
.SS "Polling and timing"
.IX Subsection "Polling and timing"
Implementation status: To be implemented.
.SS "Synchronous device I/O"
.IX Subsection "Synchronous device I/O"
Implementation status: complete.
.PP
Timeouts are given in milliseconds.
.PP
\fIcontrol_transfer_write\fR
.IX Subsection "control_transfer_write"
.PP
.Vb 1
\& my $rv = $handle\->control_transfer_write($bmRequestType, $bRequest, $wValue, $wIndex, $data, $timeout);
.Ve
.PP
\fIcontrol_transfer_read\fR
.IX Subsection "control_transfer_read"
.PP
.Vb 1
\& my ($rv, $data) = $handle\->control_transfer_read($bmRequestType, $bRequest, $wValue, $wIndex, $length, $timeout);
.Ve
.PP
\fIbulk_tranfer_write\fR
.IX Subsection "bulk_tranfer_write"
.PP
.Vb 1
\& my $rv = $handle\->bulk_transfer_write($endpoint, $data, $timeout);
.Ve
.PP
\fIbulk_transfer_read\fR
.IX Subsection "bulk_transfer_read"
.PP
.Vb 1
\& my ($rv, $data) = $handle\->bulk_transfer_read($endpoint, $length, $timeout);
.Ve
.PP
\fIinterrupt_transfer_write\fR
.IX Subsection "interrupt_transfer_write"
.PP
.Vb 1
\& my $rv = $handle\->interrupt_transfer_write($endpoint, $data, $timeout);
.Ve
.PP
\fIinterrupt_transfer_read\fR
.IX Subsection "interrupt_transfer_read"
.PP
.Vb 1
\& my ($rv, $data) = $handle\->interrupt_transfer_read($endpoint, $length, $timeout);
.Ve
.SH "REPORTING BUGS"
.IX Header "REPORTING BUGS"
Please report bugs at <https://github.com/lab\-measurement/USB\-LibUSB/issues>.
.SH CONTACT
.IX Header "CONTACT"
Feel free to contact us at the #labmeasurement channel on Freenode IRC.
.SH AUTHOR
.IX Header "AUTHOR"
Simon Reinhardt, <simon.reinhardt@physik.uni\-r.de>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2017 by Simon Reinhardt
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.24.0 or,
at your option, any later version of Perl 5 you may have available.