view release on metacpan or  search on metacpan

lib/Device/USB/Device.pm  view on Meta::CPAN

    return 0 == $!;
}

=item set_configuration

Sets the active configuration of the device.

=over 4

=item configuration

the integer specified in the descriptor field bConfigurationValue.

=back

returns 0 on success or <0 on error

When using libusb-win32 under Windows, it is important to call
C<set_configuration()> after the C<open()> but before any other method calls.
Without this call, other methods may not work. This call is not required under
Linux.

=cut

sub set_configuration
{
    my $self = shift;
    my $configuration = shift;
    $self->_assert_open();

    return Device::USB::libusb_set_configuration( $self->{handle}, $configuration );
}

=item set_altinterface

Sets the active alternative setting of the current interface for the device.

=over 4

=item alternate

the integer specified in the descriptor field bAlternateSetting.

=back

returns 0 on success or <0 on error

=cut

sub set_altinterface
{
    my $self = shift;
    my $alternate = shift;
    $self->_assert_open();

    return Device::USB::libusb_set_altinterface( $self->{handle}, $alternate );
}

=item clear_halt

Clears any halt status on the supplied endpoint.

=over 4

=item alternate

the integer specified bEndpointAddress descriptor field.

=back

returns 0 on success or <0 on error

=cut

sub clear_halt
{
    my $self = shift;
    my $ep = shift;
    $self->_assert_open();

    return Device::USB::libusb_clear_halt( $self->{handle}, $ep );
}

=item reset

Resets the device. This also closes the handle and invalidates this device.
This device will be unusable.

=cut

sub reset  ## no critic (ProhibitBuiltinHomonyms)
{
    my $self = shift;

    return 0 unless defined $self->{handle};

    my $ret = Device::USB::libusb_reset( $self->{handle} );
    delete $self->{handle} unless $ret;

    return $ret;
}

=item claim_interface

Claims the specified interface with the operating system.

=over 4

=item interface

The interface value listed in the descriptor field bInterfaceNumber.

=back

Returns 0 on success, <0 on failure.

=cut

sub claim_interface
{
    my $self = shift;

lib/Device/USB/Device.pm  view on Meta::CPAN

=cut

sub get_string_simple
{
    my $self = shift;
    my $index = shift;
    $self->_assert_open();

    my $buf = "\0" x MAX_BUFFER_SIZE;

    my $retlen = Device::USB::libusb_get_string_simple(
        $self->{handle}, $index, $buf, MAX_BUFFER_SIZE
    );

    return if $retlen < 0;

    return substr( $buf, 0, $retlen );
}

=item get_descriptor

Retrieve a descriptor from the device

=over 4

=item type

The type of descriptor to retrieve.

=item index

The index of that descriptor in the list of descriptors of that type.

=back

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.      

=cut

sub get_descriptor
{
    my $self = shift;
    my $type = shift;
    my $index = shift;
    $self->_assert_open();

    my $buf = "\0" x MAX_BUFFER_SIZE;

    my $retlen = Device::USB::libusb_get_descriptor(
        $self->{handle}, $type, $index, $buf, MAX_BUFFER_SIZE
    );

    return if $retlen < 0;

    return substr( $buf, 0, $retlen );
}

=item get_descriptor_by_endpoint

Retrieve an endpoint-specific descriptor from the device

=over 4

=item ep

Endpoint to query.

=item type

The type of descriptor to retrieve.

=item index

The index of that descriptor in the list of descriptors.

=item buf

Buffer into which to write the requested descriptor

=item size

Max size to read into the buffer.

=back

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.      

=cut

sub get_descriptor_by_endpoint
{
    my $self = shift;
    my $ep = shift;
    my $type = shift;
    my $index = shift;

    $self->_assert_open();

    my $buf = "\0" x MAX_BUFFER_SIZE;

    my $retlen = Device::USB::libusb_get_descriptor_by_endpoint(
        $self->{handle}, $ep, $type, $index, $buf, MAX_BUFFER_SIZE
    );

    return if $retlen < 0;

    return substr( $buf, 0, $retlen );
}

=item bulk_read

Perform a bulk read request from the specified endpoint.

=over 4

=item ep

The number of the endpoint to read

=item bytes

Buffer into which to write the requested data.

=item size

Max size to read into the buffer.

=item timeout

Maximum time to wait (in milliseconds)

=back

The function returns the number of bytes returned or <0 on error.

USB is packet based, not stream based. So using C<bulk_read()> to read part
of the packet acts like a I<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 C<bulk_read()> with the total packet size.

=cut

sub bulk_read
{
    my $self = shift;
    # Don't change to shifts, I need to write back to $bytes.
    my ($ep, $bytes, $size, $timeout) = @_;
    $bytes = q{} unless defined $bytes;

    $self->_assert_open();

    if(length $bytes < $size)
    {
        $bytes .= "\0" x ($size - length $bytes);
    }

    my $retlen = Device::USB::libusb_bulk_read(
        $self->{handle}, $ep, $bytes, $size, $timeout
    );

    # stick back in the bytes parameter.
    $_[1] = substr( $bytes, 0, $retlen );

    return $retlen;
}

=item interrupt_read

Perform a interrupt read request from the specified endpoint.

=over 4

=item ep

The number of the endpoint to read

=item bytes

Buffer into which to write the requested data.

=item size

Max size to read into the buffer.

=item timeout

Maximum time to wait (in milliseconds)

=back

The function returns the number of bytes returned or <0 on error.

=cut

sub interrupt_read
{
    my $self = shift;
    # Don't change to shifts, I need to write back to $bytes.
    my ($ep, $bytes, $size, $timeout) = @_;
    $bytes = q{} unless defined $bytes;

    $self->_assert_open();

    if(length $bytes < $size)
    {
        $bytes .= "\0" x ($size - length $bytes);
    }

    my $retlen = Device::USB::libusb_interrupt_read(
        $self->{handle}, $ep, $bytes, $size, $timeout
    );

    # stick back in the bytes parameter.
    $_[1] = substr( $bytes, 0, $retlen );

    return $retlen;
}

=item bulk_write

Perform a bulk write request to the specified endpoint.

=over 4

=item ep

The number of the endpoint to write

=item bytes

Buffer from which to write the requested data.

=item timeout

Maximum time to wait (in milliseconds)

=back

The function returns the number of bytes written or <0 on error.

=cut

sub bulk_write
{
    my $self = shift;
    my $ep = shift;
    my $bytes = shift;
    my $timeout = shift;

    $self->_assert_open();

    return Device::USB::libusb_bulk_write(
        $self->{handle}, $ep, $bytes, length $bytes, $timeout
    );
}

=item interrupt_write

Perform a interrupt write request to the specified endpoint.

=over 4

=item ep

The number of the endpoint to write

=item bytes

Buffer from which to write the requested data.

=item timeout

Maximum time to wait (in milliseconds)

=back

The function returns the number of bytes written or <0 on error.

=cut

sub interrupt_write
{
    my $self = shift;
    my $ep = shift;
    my $bytes = shift;
    my $timeout = shift;

    $self->_assert_open();

    return Device::USB::libusb_interrupt_write(
        $self->{handle}, $ep, $bytes, length $bytes, $timeout
    );
}

=item get_driver_np

This function returns the name of the driver bound to the interface
specified by the parameter interface.

=over 4

=item $interface

The interface number of interest.

=back

Returns C<undef> on error.

=cut

sub get_driver_np
{
    my $self = shift;
    my $interface = shift;
    my $name = shift;

    $self->_assert_open();

    my $buf = "\0" x MAX_BUFFER_SIZE;

    my $retlen = Device::USB::libusb_get_driver_np(
        $self->{handle}, $interface, $buf, MAX_BUFFER_SIZE
    );