view release on metacpan or  search on metacpan

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

                        ($^O eq 'MSWin32' ? ' -llibusb -L\"$ENV{WINDDK}\\lib\\crt\\i386\" -lmsvcrt ' : '-lusb') )
            : ( LIBS => '-lusb', )
        ),
        ($ENV{LIBUSB_INCDIR} ? ( INC => "-I\"$ENV{LIBUSB_INCDIR}\"" ) : () ),
        NAME => 'Device::USB::Win32Async',
        VERSION => '0.36',
   );

Inline->init();


=head1 NAME

Device::USB::Win32Async - Add async functions to Device::USB

=head1 VERSION

Version 0.36

=head1 SYNOPSIS

Device::USB provides a Perl wrapper around the libusb library.

Device::USB::Win32Async adds the async functions from libusb-win32 to Device::USB.
This is only available for Win32 systems.

    use Device::USB;
    use Device::USB::Win32Async;

    my $usb = Device::USB->new();
    my $dev = $usb->find_device( $VENDOR, $PRODUCT );

    ...

    my $Context;                # Context variable for asynch I/O
    my $Buffer;                 # Buffer for results (input) or to transmit (output)
    my $NumBytes = 5000;        # of bytes to transfer

    $dev->bulk_setup_async($Context,$Endpoint);
    $Status = $dev->submit_async($Context,$Buffer,$NumBytes);   # Start the transfer

    while( 1 ) {
        $Response = $dev->reap_async_nocancel($Context,50);     # 50 mS wait time

        last
            if $Response != Device::USB::Device::ETIMEDOUT;
        #
        # Do other tasks while waiting, such as update the GUI
        #
        # For example, a TK program might call $MainWindow->update();
        #
        <Other Task code>
        }

See the libusb-win32 manual for more information about the methods. The
functionality is the same as the libusb function whose name is
the method name prepended with "usb_".

Generally, define a $Context variable which the library will use to keep track of
the asynchronous call. Activate the transfer (read or write, depending on the
endpoint) using submit_async() as shown, then loop calling reap_async_nocancel()
while checking the return code.

You can have any number of async operations pending on different endpoints - just
define multiple context variables as needed (ie - $Context1, $Context2, &c).

=cut


##########################################################################################
#
# Version 0.34 - Added support for asynchronous I/O
#
# The caller supplies a scalar $Context which we use to keep opaque (from the caller)
#   information about the I/O operation.
#
# The libusb driver will malloc some data and pass back a pointer to use as the context,
#   but we need to keep track of the buffer as well as this malloc'd context.
#
# So in the caller's $Context we store a ref to an anonymous array with two elements:
#   [0] => the libusb context, and [1] => ref to the user's buffer.
#
# We do this using $_[1], which is an alias to the user's var.
#
=over

=item isochronous_setup_async($Context,$Endpoint,$Packetsize)

Setup a Context for use in subsequent asynchronous operations

=over 4

=item Context

A scalar to store opaque information about the operation

=item Endpoint

The endpoint the asynchronous operation will use

=item Packetsize

The size of the isochronous packets

=back

Returns 0 on success, < 0 on error (consult errno.h for explanation)

=cut

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

    #
    # ($Context,$Endpoint,$Packetsize) = @_;
    #
    $_[0] = [ 0, "" ];      # User's var is now anonymous array

    return libusb_isochronous_setup_async($self->{handle},$_[0][0],$_[1],$_[2]);
    }

=item bulk_setup_async($Context,$Endpoint)

Setup a Context for use in subsequent asynchronous operations

=over 4

=item Context

A scalar to store opaque information about the operation

=item Endpoint

The endpoint the asynchronous operation will use

=back

Returns 0 on success, < 0 on error (consult errno.h for explanation)

=cut

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

    #
    # ($Context,$Endpoint) = @_;
    #
    $_[0] = [ 0, "" ];      # User's var is now anonymous array

    return libusb_bulk_setup_async($self->{handle},$_[0][0],$_[1]);
    }

=item interrupt_setup_async($Context,$Endpoint)

Setup a Context for use in subsequent asynchronous operations

=over 4

=item Context

A scalar to store opaque information about the operation

=item Endpoint

The endpoint the asynchronous operation will use

=back

Returns 0 on success, < 0 on error (consult errno.h for explanation)

=cut

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

    #
    # ($Context,$Endpoint) = @_;
    #
    $_[0] = [ 0, "" ];      # User's var is now anonymous array

    return libusb_interrupt_setup_async($self->{handle},$_[0][0],$_[1]);
    }

=item submit_async($Context,$Buffer,$Size)

Start an asynchronous I/O operation

=over 4

=item Context

A previously prepared context generated by one of the xxx_setup_async functions above

=item Buffer

A string buffer to receive the resulting data

=item Size

The number of bytes to pre-allocate to hold the incoming data.

=back

Returns 0 on success, < 0 on error (consult errno.h for explanation)

=cut

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

    #
    # ($Context,$Buffer,$Size) = @_;
    #
    $_[0][1] = \$_[1];      # Save user's buffer for reap (below)

    return libusb_submit_async($_[0][0],$_[1],$_[2]);
    }

=item reap_async($Context,$Timeout)

Get the results of an asynchronous operation and cancel if not complete.

=over 4