138 lines
5.4 KiB
C
138 lines
5.4 KiB
C
//---
|
|
// fxlink:usb - libusb functions
|
|
//---
|
|
|
|
#ifndef FXLINK_USB_H
|
|
#define FXLINK_USB_H
|
|
|
|
#include "util.h"
|
|
#include "properties.h"
|
|
#include "filter.h"
|
|
#include <libusb.h>
|
|
|
|
/* usb_properties(): Determine as many properties of the device as possible
|
|
|
|
If the device can be opened, an open handle should be supplied as (dh). This
|
|
is used to determine the serial number; if the device cannot be opened, the
|
|
serial number is omitted from the device properties.
|
|
|
|
@dc Device descriptor
|
|
@dh Open handle if the device can be opened, or NULL
|
|
-> Returns detected properties of the device. */
|
|
properties_t usb_properties(struct libusb_device_descriptor *dc,
|
|
libusb_device_handle *dh);
|
|
|
|
/* usb_unique_matching(): Device that matches the provided filter, if unique
|
|
|
|
This function runs through the list of devices provided by libusb and
|
|
determines whether there is exactly one device matching the filter. If so,
|
|
a pointer to this device is set in (*dev) and FILTER_UNIQUE is returned. The
|
|
device is referenced and should be un-referenced after use for the data to
|
|
be freed. If (dev) is NULL, the pointer is not recorded and not referenced.
|
|
|
|
If there are no devices matching the filter, (*dev) is unchanged and this
|
|
function returns FILTER_NONE. If several devices match the filter, (*dev) is
|
|
unchanged and FILTER_MULTIPLE is returned. If an error occurs and the
|
|
function cannot complete, an error is printed and FILTER_ERROR is returned.
|
|
|
|
@filter Device filter to refine the search
|
|
@context Previously-initialized libusb context
|
|
@dev Output: unique device matching the filter (may be NULL)
|
|
-> Returns one of FILTER_{UNIQUE,NONE,MULTIPLE,ERROR}. */
|
|
int usb_unique_matching(filter_t const *filter, libusb_context *context,
|
|
libusb_device **dev);
|
|
|
|
/* usb_unique_wait(): Wait for a device matching the provided filter to connect
|
|
|
|
This function waits up to the provided delay for a device matching the
|
|
specified filter to be connected. It calls usb_unique_matching() several
|
|
times per second to check for new devices being attached and initialized.
|
|
|
|
If several devices are connected when usb_unique_wait() is first called, or
|
|
several devices are connected between two calls to usb_unique_matching(),
|
|
this function returns FILTER_MULTIPLE. As soon as a unique matching device
|
|
is found, the pointer is referenced and set in (*dev) if (dev) is not NULL,
|
|
and FILTER_UNIQUE is returned, regardless of whether other matching devices
|
|
are attached before the end of the wait period.
|
|
|
|
If no matching device is attached during the specified period, this function
|
|
returns FILTER_NONE. If an error occurs during scanning, it returns
|
|
FILTER_ERROR.
|
|
|
|
@filter Device filter to refine the search
|
|
@delay Time resource to use delay from
|
|
@context Previously-initialized libusb context
|
|
@dev Output: unique device matching the filter (can be NULL)
|
|
-> Returns one of FILTER_{UNIQUE,NONE,MULTIPLE,ERROR}. */
|
|
int usb_unique_wait(filter_t const *filter, delay_t *delay,
|
|
libusb_context *context, libusb_device **dev);
|
|
|
|
//---
|
|
// Iteration on libusb devices
|
|
//---
|
|
|
|
typedef struct {
|
|
/* Current device and its device descriptor */
|
|
libusb_device *dev;
|
|
struct libusb_device_descriptor dc;
|
|
/* If the device can be opened, its open handle, otherwise NULL */
|
|
libusb_device_handle *dh;
|
|
/* Device properties */
|
|
properties_t props;
|
|
/* Whether the iteration has finished */
|
|
bool done;
|
|
|
|
/* Internal indicators: list of devices and current index */
|
|
libusb_device **devices;
|
|
int device_count;
|
|
int index;
|
|
|
|
} usb_iterator_t;
|
|
|
|
/* usb_iter_start(): Start an iteration on libusb devices
|
|
If the first step fails, returns an iterator with (done = true) and sets
|
|
(*error) to true; otherwise, sets (*error) to false. */
|
|
usb_iterator_t usb_iter_start(libusb_context *context, bool *error);
|
|
|
|
/* usb_iter_next(): Iterate to the next libusb device */
|
|
void usb_iter_next(usb_iterator_t *it);
|
|
|
|
/* Convenience for-loop macro for iteration */
|
|
#define for_libusb_devices(NAME, context, error) \
|
|
for(usb_iterator_t NAME = usb_iter_start(context, error); \
|
|
!NAME.done; usb_iter_next(&NAME)) if(!NAME.done)
|
|
|
|
//---
|
|
// Miscellaneous
|
|
//---
|
|
|
|
/* usb_id(): Printable address-based identifier for error messages
|
|
This function is used in error messages to describe the device on which an
|
|
error occurred in a useful way. The pointer returned is to a static buffer
|
|
that changes at every call to this function, and should only be used briefly
|
|
to generate messages. */
|
|
char const *usb_id(libusb_device *dev);
|
|
|
|
/* usb_serial_number(): Serial number advertised by the device
|
|
|
|
This function returns the serial number (as presented with iSerialNumber in
|
|
the device descriptor) of the provided device, which may or may not be
|
|
present.
|
|
|
|
Serial numbers for CASIO calculators normally have 8 letters. The LINK
|
|
application presents a 12-character code with "0000" prepended. This
|
|
function detects this quirk and only returns the last 8 characters. gint's
|
|
driver doesn't send to "0000" prefix.
|
|
|
|
This function requires the device to be open in order to send the request
|
|
for the STRING descriptor, and cannot be used if the process user doesn't
|
|
have write access to the device.
|
|
|
|
@dh Open device handle
|
|
-> Returns a freshly-allocated copy of the serial number string, to be
|
|
free()'d after use, or NULL if the serial number is unspecified or cannot
|
|
be retrieved. */
|
|
char *usb_serial_number(libusb_device_handle *dh);
|
|
|
|
#endif /* FXLINK_USB_H */
|