Helpers for libusb

Helpers for libusb

Functions

Types and Values

Includes

#include <fpi-usb.h>

Description

A collection of libusb helpers to make driver development easier. Please refer to the libusb API documentation for more information about the original API.

Functions

fpi_usb_transfer_cb_fn ()

void
(*fpi_usb_transfer_cb_fn) (struct libusb_transfer *transfer,
                           struct fp_dev *dev,
                           fpi_ssm *ssm,
                           void *user_data);

This callback will be called in response to a libusb bulk transfer triggered via fpi_usb_fill_bulk_transfer() finishing. Note that the struct libusb_transfer does not need to be freed, as it will be freed after the callback returns, similarly to the LIBUSB_TRANSFER_FREE_TRANSFER flag.

Note that the cancelled status of the transfer should be checked first thing, as the dev , ssm and user_data pointers might not be pointing to valid values anymore. See fpi_usb_cancel_transfer() for more information.

Parameters

transfer

a struct libusb_transfer

 

dev

the struct fp_dev on which the operation was performed

 

ssm

the fpi_ssm state machine

 

user_data

the user data passed to fpi_usb_fill_bulk_transfer()

 

fpi_usb_alloc ()

struct libusb_transfer *
fpi_usb_alloc (void);

Returns a struct libusb_transfer, similar to calling libusb_alloc_transfer(0)[1]. As libfprint uses GLib internally, and memory allocation failures will make applications fail, this helper will assert when the libusb call fails.


fpi_usb_fill_bulk_transfer ()

fpi_usb_transfer *
fpi_usb_fill_bulk_transfer (struct fp_dev *dev,
                            fpi_ssm *ssm,
                            unsigned char endpoint,
                            unsigned char *buffer,
                            int length,
                            fpi_usb_transfer_cb_fn callback,
                            void *user_data,
                            unsigned int timeout);

This function is similar to calling libusb_alloc_transfer(0)] followed by calling libusb_fill_bulk_transfer(). The fpi_usb_transfer_cb_fn callback will however provide more arguments relevant to libfprint drivers, making it a good replacement for the raw libusb calls.

Parameters

dev

a struct fp_dev fingerprint device

 

ssm

the current fpi_ssm state machine

 

endpoint

the USB end point

 

buffer

a buffer allocated with g_malloc() or another GLib function. Note that the returned fpi_usb_transfer will own this buffer, so it should not be freed manually.

 

length

the size of buffer

 

callback

the callback function that will be called once the fpi_usb_submit_transfer() call finishes.

 

user_data

a user data pointer to pass to the callback

 

timeout

timeout for the transfer in milliseconds, or 0 for no timeout

 

Returns

a fpi_usb_transfer transfer struct, to be passed to fpi_usb_submit_transfer().


fpi_usb_submit_transfer ()

int
fpi_usb_submit_transfer (fpi_usb_transfer *transfer);

Start a transfer to the device with the provided fpi_usb_transfer. On error, the fpi_usb_transfer struct will be freed, otherwise it will be freed once the callback provided to fpi_usb_fill_bulk_transfer() has been called.

Parameters

transfer

a fpi_usb_transfer struct

 

Returns

0 on success, or the same errors as libusb_submit_transfer on failure.


fpi_usb_cancel_transfer ()

int
fpi_usb_cancel_transfer (fpi_usb_transfer *transfer);

Cancel a transfer to the device with the provided fpi_usb_transfer. Note that this will not complete the cancellation, as your transfer callback will be called with the LIBUSB_TRANSFER_CANCELLED status, as libusb_cancel_transfer would.

You should not access anything but the given struct libusb_transfer in the callback before checking whether LIBUSB_TRANSFER_CANCELLED has been called, as that might cause memory access violations.

Parameters

transfer

a fpi_usb_transfer struct

 

Returns

0 on success, or the same errors as libusb_cancel_transfer on failure.

Types and Values

fpi_usb_transfer

typedef struct fpi_usb_transfer fpi_usb_transfer;

A structure containing the arguments passed to fpi_usb_fill_bulk_transfer() to be used with fpi_usb_submit_transfer().