Helpers for libusb: libfprint Reference Manual

## Helpers for libusb Helpers for libusb — libusb-related helpers |

## Functions

void | (*fpi_usb_transfer_cb_fn) ()
struct libusb_transfer * | fpi_usb_alloc ()
fpi_usb_transfer * | fpi_usb_fill_bulk_transfer ()
int | fpi_usb_submit_transfer ()
int | fpi_usb_cancel_transfer ()

## Types and Values

typedef | fpi_usb_transfer

## 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()`.