NAME

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

VERSION

Version 0.31

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).

isochronous_setup_async($Context,$Endpoint,$Packetsize)

Setup a Context for use in subsequent asynchronous operations

Context

A scalar to store opaque information about the operation

Endpoint

The endpoint the asynchronous operation will use

Packetsize

The size of the isochronous packets

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

bulk_setup_async($Context,$Endpoint)

Setup a Context for use in subsequent asynchronous operations

Context

A scalar to store opaque information about the operation

Endpoint

The endpoint the asynchronous operation will use

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

interrupt_setup_async($Context,$Endpoint)

Setup a Context for use in subsequent asynchronous operations

Context

A scalar to store opaque information about the operation

Endpoint

The endpoint the asynchronous operation will use

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

submit_asynch($Context,$Buffer,$Size)

Start an asynchronous I/O operation

Context

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

Buffer

A string buffer to receive the resulting data

Size

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

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

reap_asynch($Context,$Timeout)

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

Context

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

Timeout

Number of milliseconds to wait before timeout

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

reap_asynch_nocancel($Context,$Timeout)

Get the results of an asynchronous operation, but continue request (return Device::USB::Device::ETIMEDOUT => -116) if not complete yet.

Context

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

Timeout

Number of milliseconds to wait before timeout

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

cancel_async($Context)

Cancel an asynchronous operation in progress

Context

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

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

free_async($Context)

Free up resources allocated for the asynchrounous context

Context

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

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

DEPENDENCIES

Carp, Inline::C, and Device::USB.

Also depends on the libusb-win32 library.

AUTHOR

Rajstennaj Barrabas wrote the code.

The module is maintained by G. Wade Johnson (wade at anomaly dot org).

BUGS

Please report any bugs or feature requests to bug-device-usb-win32async@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Device::USB::Win32Async. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

LIMITATIONS

This module depends on extensions to the libusb library added in the LibUsb-Win32 library. As such, the module is only expected to work on a Win32-based system.

COPYRIGHT & LICENSE

Copyright 2009 Rajstennaj Barrabas

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0.