From 9e4ad2dcc98035702238a9d88f7454410ad63f43 Mon Sep 17 00:00:00 2001 From: Henning Geinitz Date: Wed, 3 Jul 2002 19:48:45 +0000 Subject: [PATCH] Used dn (device number) instead of fd (file descriptor) to avoid confusion. Updated doxygen documentation. Henning Meier-Geinitz --- include/sane/sanei_usb.h | 101 +++++++++++++++++++------------ sanei/sanei_usb.c | 124 +++++++++++++++++++-------------------- 2 files changed, 127 insertions(+), 98 deletions(-) diff --git a/include/sane/sanei_usb.h b/include/sane/sanei_usb.h index d43013856..3a9703a7d 100644 --- a/include/sane/sanei_usb.h +++ b/include/sane/sanei_usb.h @@ -27,6 +27,10 @@ * detection and control messages aren't supported on these platforms. * - Access using libusb (where available). * + * A general remark: Do not mix sanei_usb functions with "normal" file-related + * libc functions like open() or close. The device numbers used in sanei_usb + * are not file descriptors. + * * @sa sanei_lm983x.h, sanei_pa4s2.h, sanei_pio.h, sanei_scsi.h, and man sane-usb(5) * for user-oriented documentation @@ -41,7 +45,8 @@ /* USB spec defines */ #ifndef USB_CLASS_PER_INTERFACE /* Also defined in libusb */ -/* Device and/or interface class codes */ +/** @name Device and/or interface class codes */ +/* @{ */ #define USB_CLASS_PER_INTERFACE 0x00 #define USB_CLASS_AUDIO 0x01 #define USB_CLASS_COMM 0x02 @@ -51,38 +56,44 @@ #define USB_CLASS_HUB 0x09 #define USB_CLASS_DATA 0x0a #define USB_CLASS_VENDOR_SPEC 0xff +/* @} */ -/* USB descriptor types */ +/** @name USB descriptor types */ +/* @{ */ #define USB_DT_DEVICE 0x01 #define USB_DT_CONFIG 0x02 #define USB_DT_STRING 0x03 #define USB_DT_INTERFACE 0x04 #define USB_DT_ENDPOINT 0x05 - #define USB_DT_HID 0x21 #define USB_DT_REPORT 0x22 #define USB_DT_PHYSICAL 0x23 #define USB_DT_HUB 0x29 +/* @} */ -/* Descriptor sizes per descriptor type */ +/** @name Descriptor sizes per descriptor type */ +/* @{ */ #define USB_DT_DEVICE_SIZE 18 #define USB_DT_CONFIG_SIZE 9 #define USB_DT_INTERFACE_SIZE 9 #define USB_DT_ENDPOINT_SIZE 7 #define USB_DT_ENDPOINT_AUDIO_SIZE 9 #define USB_DT_HUB_NONVAR_SIZE 7 +/* @} */ -/* Endpoint descriptor values */ +/** @name Endpoint descriptors */ +/* @{ */ #define USB_ENDPOINT_ADDRESS_MASK 0x0f #define USB_ENDPOINT_DIR_MASK 0x80 - #define USB_ENDPOINT_TYPE_MASK 0x03 #define USB_ENDPOINT_TYPE_CONTROL 0 #define USB_ENDPOINT_TYPE_ISOCHRONOUS 1 #define USB_ENDPOINT_TYPE_BULK 2 #define USB_ENDPOINT_TYPE_INTERRUPT 3 +/* @} */ -/* Standard requests */ +/** @name Standard requests */ +/* @{ */ #define USB_REQ_GET_STATUS 0x00 #define USB_REQ_CLEAR_FEATURE 0x01 #define USB_REQ_SET_FEATURE 0x03 @@ -94,28 +105,38 @@ #define USB_REQ_GET_INTERFACE 0x0A #define USB_REQ_SET_INTERFACE 0x0B #define USB_REQ_SYNCH_FRAME 0x0C +/* @} */ -/* USB types */ +/** @name USB types */ +/* @{ */ #define USB_TYPE_STANDARD (0x00 << 5) #define USB_TYPE_CLASS (0x01 << 5) #define USB_TYPE_VENDOR (0x02 << 5) #define USB_TYPE_RESERVED (0x03 << 5) +/* @} */ -/* USB recipients */ +/** @name USB recipients */ +/* @{ */ #define USB_RECIP_DEVICE 0x00 #define USB_RECIP_INTERFACE 0x01 #define USB_RECIP_ENDPOINT 0x02 #define USB_RECIP_OTHER 0x03 +/* @} */ #endif /* not USB_CLASS_PER_INTERFACE */ /* Not defined in libsub */ +/** @name USB Masks */ +/* @{ */ #define USB_TYPE_MASK (0x03 << 5) #define USB_RECIP_MASK 0x1f +/* @} */ -/* USB directions */ +/** @name USB directions */ +/* @{ */ #define USB_DIR_OUT 0 #define USB_DIR_IN 0x80 +/* @} */ /** Initialize sanei_usb. * @@ -125,10 +146,11 @@ extern void sanei_usb_init (void); /** Get the vendor and product ids. * - * Currently, only scanners supported by the Linux USB scanner module can be - * found. The Linux version must be 2.4.8 or higher. + * Currently, only libusb devices and scanners supported by the Linux USB + * scanner module can be found. For the latter method, the Linux version + * must be 2.4.8 or higher. * - * @param fd device file descriptor + * @param dn device number of an already sanei_usb_opened device * @param vendor vendor id * @param product product id * @@ -137,7 +159,7 @@ extern void sanei_usb_init (void); * - SANE_STATUS_UNSUPPORTED - if the OS doesn't support detection of ids */ extern SANE_Status -sanei_usb_get_vendor_product (SANE_Int fd, SANE_Word * vendor, +sanei_usb_get_vendor_product (SANE_Int dn, SANE_Word * vendor, SANE_Word * product); /** Find devices that match given vendor and product ids. @@ -157,11 +179,17 @@ sanei_usb_find_devices (SANE_Int vendor, SANE_Int product, /** Open a USB device. * - * The device is opened by its filename devname and the file descriptor is - * returned in fd on success. + * The device is opened by its name devname and the device number is + * returned in dn on success. * - * @param devname filename of the device file - * @param fd device file descriptor + * Device names can be either device file names for direct access over + * kernel drivers (like /dev/usb/scanner) or libusb names. The libusb format + * looks like this: "libusb:bus-id:device-id". Bus-id and device-id are + * platform-dependent. An example could look like this: "libusb:001:002" + * (Linux). + * + * @param devname name of the device to open + * @param dn device number * * @return * - SANE_STATUS_GOOD - on success @@ -169,20 +197,20 @@ sanei_usb_find_devices (SANE_Int vendor, SANE_Int product, * permissions * - SANE_STATUS_INVAL - on every other error */ -extern SANE_Status sanei_usb_open (SANE_String_Const devname, SANE_Int * fd); +extern SANE_Status sanei_usb_open (SANE_String_Const devname, SANE_Int * dn); /** Close a USB device. * - * @param fd file descriptor of the device + * @param dn device number */ -extern void sanei_usb_close (SANE_Int fd); +extern void sanei_usb_close (SANE_Int dn); /** Initiate a bulk transfer read. * * Read up to size bytes from the device to buffer. After the read, size * contains the number of bytes actually read. * - * @param fd file descriptor of the device + * @param dn device number * @param buffer buffer to store read data in * @param size size of the data * @@ -194,14 +222,14 @@ extern void sanei_usb_close (SANE_Int fd); * */ extern SANE_Status -sanei_usb_read_bulk (SANE_Int fd, SANE_Byte * buffer, size_t * size); +sanei_usb_read_bulk (SANE_Int dn, SANE_Byte * buffer, size_t * size); /** Initiate a bulk transfer write. * * Write up to size bytes from buffer to the device. After the write size * contains the number of bytes actually written. * - * @param fd file descriptor of the device + * @param dn device number * @param buffer buffer to write to device * @param size size of the data * @@ -211,25 +239,25 @@ sanei_usb_read_bulk (SANE_Int fd, SANE_Byte * buffer, size_t * size); * - SANE_STATUS_INVAL - on every other error */ extern SANE_Status -sanei_usb_write_bulk (SANE_Int fd, SANE_Byte * buffer, size_t * size); +sanei_usb_write_bulk (SANE_Int dn, SANE_Byte * buffer, size_t * size); /** Send/receive a control message to/from a USB device. * - * This function is only supported for Linux 2.4.13 and newer. - * The arguments rtype, req, value, and index are passed directly to - * usb_control_msg (see the Linux - * USB project and - * www.usb.org developers information for documentation). + * This function is only supported for libusb devices and kernel acces with + * Linux 2.4.13 and newer. + * For a detailed explanation of the parameters, have a look at the USB + * specification at the + * www.usb.org developers information page. * - * @param fd file descriptor of the device file - * @param data buffer to send/receive data - * @param len length of data to send/receive + * @param dn device number * @param rtype specifies the characteristics of the request (e.g. data * direction) * @param req actual request * @param value parameter specific to the request * @param index parameter specific to the request (often used to select * endpoint) + * @param len length of data to send/receive + * @param data buffer to send/receive data * * @return * - SANE_STATUS_GOOD - on success @@ -238,14 +266,15 @@ sanei_usb_write_bulk (SANE_Int fd, SANE_Byte * buffer, size_t * size); * SANE. */ extern SANE_Status -sanei_usb_control_msg (SANE_Int fd, SANE_Int rtype, SANE_Int req, +sanei_usb_control_msg (SANE_Int dn, SANE_Int rtype, SANE_Int req, SANE_Int value, SANE_Int index, SANE_Int len, SANE_Byte * data); /** Expand device name patterns into a list of devices. * - * Apart from a normal device name (such as /dev/usb/scanner0), this - * function currently supports USB device specifications of the form: + * Apart from a normal device name (such as /dev/usb/scanner0 or + * libusb:002:003), this function currently supports USB device + * specifications of the form: * * usb VENDOR PRODUCT * diff --git a/sanei/sanei_usb.c b/sanei/sanei_usb.c index 3502b61f7..5e6669581 100644 --- a/sanei/sanei_usb.c +++ b/sanei/sanei_usb.c @@ -86,7 +86,7 @@ device_list_type; #define MAX_DEVICES 100 -/* per-device information, using the functions fd as index */ +/* per-device information, using the functions' parameters dn as index */ static device_list_type devices[MAX_DEVICES]; #ifdef HAVE_LIBUSB @@ -185,45 +185,45 @@ sanei_usb_attach_matching_devices (const char *name, } SANE_Status -sanei_usb_get_vendor_product (SANE_Int fd, SANE_Word * vendor, +sanei_usb_get_vendor_product (SANE_Int dn, SANE_Word * vendor, SANE_Word * product) { SANE_Word vendorID = 0; SANE_Word productID = 0; - if (fd >= MAX_DEVICES || fd < 0) + if (dn >= MAX_DEVICES || dn < 0) { - DBG (1, "sanei_usb_get_vendor_product: fd >= MAX_DEVICES || fd < 0\n"); + DBG (1, "sanei_usb_get_vendor_product: dn >= MAX_DEVICES || dn < 0\n"); return SANE_STATUS_INVAL; } - if (devices[fd].method == sanei_usb_method_scanner_driver) + if (devices[dn].method == sanei_usb_method_scanner_driver) { #if defined (__linux__) /* read the vendor and product IDs via the IOCTLs */ - if (ioctl (devices[fd].fd, SCANNER_IOCTL_VENDOR, &vendorID) == -1) + if (ioctl (devices[dn].fd, SCANNER_IOCTL_VENDOR, &vendorID) == -1) { - if (ioctl (devices[fd].fd, SCANNER_IOCTL_VENDOR_OLD, &vendorID) + if (ioctl (devices[dn].fd, SCANNER_IOCTL_VENDOR_OLD, &vendorID) == -1) DBG (3, "sanei_usb_get_vendor_product: ioctl (vendor) " - "of device %d failed: %s\n", fd, strerror (errno)); + "of device %d failed: %s\n", dn, strerror (errno)); } - if (ioctl (devices[fd].fd, SCANNER_IOCTL_PRODUCT, &productID) == -1) + if (ioctl (devices[dn].fd, SCANNER_IOCTL_PRODUCT, &productID) == -1) { - if (ioctl (devices[fd].fd, SCANNER_IOCTL_PRODUCT_OLD, + if (ioctl (devices[dn].fd, SCANNER_IOCTL_PRODUCT_OLD, &productID) == -1) DBG (3, "sanei_usb_get_vendor_product: ioctl (product) " - "of device %d failed: %s\n", fd, strerror (errno)); + "of device %d failed: %s\n", dn, strerror (errno)); } #endif /* defined (__linux__) */ /* put more os-dependant stuff ... */ } - else if (devices[fd].method == sanei_usb_method_libusb) + else if (devices[dn].method == sanei_usb_method_libusb) { #ifdef HAVE_LIBUSB - vendorID = usb_device (devices[fd].libusb_handle)->descriptor.idVendor; + vendorID = usb_device (devices[dn].libusb_handle)->descriptor.idVendor; productID = - usb_device (devices[fd].libusb_handle)->descriptor.idProduct; + usb_device (devices[dn].libusb_handle)->descriptor.idProduct; #else DBG (1, "sanei_usb_get_vendor_product: libusb support missing\n"); return SANE_STATUS_UNSUPPORTED; @@ -232,7 +232,7 @@ sanei_usb_get_vendor_product (SANE_Int fd, SANE_Word * vendor, else { DBG (1, "sanei_usb_get_vendor_product: access method %d not " - "implemented\n", devices[fd].method); + "implemented\n", devices[dn].method); return SANE_STATUS_INVAL; } @@ -244,13 +244,13 @@ sanei_usb_get_vendor_product (SANE_Int fd, SANE_Word * vendor, if (!vendorID || !productID) { DBG (3, "sanei_usb_get_vendor_product: device %d: Your OS doesn't " - "seem to support detection of vendor+product ids\n", fd); + "seem to support detection of vendor+product ids\n", dn); return SANE_STATUS_UNSUPPORTED; } else { DBG (3, "sanei_usb_get_vendor_product: device %d: vendorID: 0x%04x, " - "productID: 0x%04x\n", fd, vendorID, productID); + "productID: 0x%04x\n", dn, vendorID, productID); return SANE_STATUS_GOOD; } } @@ -263,14 +263,14 @@ check_vendor_product (SANE_String_Const devname, SANE_Word vendor, { SANE_Status status; SANE_Word devvendor, devproduct; - SANE_Int fd; + SANE_Int dn; - status = sanei_usb_open (devname, &fd); + status = sanei_usb_open (devname, &dn); if (status != SANE_STATUS_GOOD) return status; - status = sanei_usb_get_vendor_product (fd, &devvendor, &devproduct); - sanei_usb_close (fd); + status = sanei_usb_get_vendor_product (dn, &devvendor, &devproduct); + sanei_usb_close (dn); if (status == SANE_STATUS_GOOD) { if (devvendor == vendor && devproduct == product) @@ -356,13 +356,13 @@ sanei_usb_find_devices (SANE_Int vendor, SANE_Int product, } SANE_Status -sanei_usb_open (SANE_String_Const devname, SANE_Int * fd) +sanei_usb_open (SANE_String_Const devname, SANE_Int * dn) { int devcount; - if (!fd) + if (!dn) { - DBG (1, "sanei_usb_open: can't open `%s': fd == NULL\n", devname); + DBG (1, "sanei_usb_open: can't open `%s': dn == NULL\n", devname); return SANE_STATUS_INVAL; } @@ -542,35 +542,35 @@ sanei_usb_open (SANE_String_Const devname, SANE_Int * fd) devices[devcount].method = sanei_usb_method_scanner_driver; } devices[devcount].open = SANE_TRUE; - *fd = devcount; - DBG (3, "sanei_usb_open: opened usb device `%s' (*fd=%d)\n", + *dn = devcount; + DBG (3, "sanei_usb_open: opened usb device `%s' (*dn=%d)\n", devname, devcount); return SANE_STATUS_GOOD; } void -sanei_usb_close (SANE_Int fd) +sanei_usb_close (SANE_Int dn) { - DBG (5, "sanei_usb_close: closing device %d\n", fd); - if (fd >= MAX_DEVICES || fd < 0) + DBG (5, "sanei_usb_close: closing device %d\n", dn); + if (dn >= MAX_DEVICES || dn < 0) { - DBG (1, "sanei_usb_close: fd >= MAX_DEVICES || fd < 0\n"); + DBG (1, "sanei_usb_close: dn >= MAX_DEVICES || dn < 0\n"); return; } - if (devices[fd].method == sanei_usb_method_scanner_driver) - close (devices[fd].fd); + if (devices[dn].method == sanei_usb_method_scanner_driver) + close (devices[dn].fd); else #ifdef HAVE_LIBUSB - usb_close (devices[fd].libusb_handle); + usb_close (devices[dn].libusb_handle); #else DBG (1, "sanei_usb_close: libusb support missing\n"); #endif - devices[fd].open = SANE_FALSE; + devices[dn].open = SANE_FALSE; return; } SANE_Status -sanei_usb_read_bulk (SANE_Int fd, SANE_Byte * buffer, size_t * size) +sanei_usb_read_bulk (SANE_Int dn, SANE_Byte * buffer, size_t * size) { ssize_t read_size = 0; @@ -580,19 +580,19 @@ sanei_usb_read_bulk (SANE_Int fd, SANE_Byte * buffer, size_t * size) return SANE_STATUS_INVAL; } - if (fd >= MAX_DEVICES || fd < 0) + if (dn >= MAX_DEVICES || dn < 0) { - DBG (1, "sanei_usb_read_bulk: fd >= MAX_DEVICES || fd < 0\n"); + DBG (1, "sanei_usb_read_bulk: dn >= MAX_DEVICES || dn < 0\n"); return SANE_STATUS_INVAL; } - if (devices[fd].method == sanei_usb_method_scanner_driver) - read_size = read (devices[fd].fd, buffer, *size); - else if (devices[fd].method == sanei_usb_method_libusb) + if (devices[dn].method == sanei_usb_method_scanner_driver) + read_size = read (devices[dn].fd, buffer, *size); + else if (devices[dn].method == sanei_usb_method_libusb) #ifdef HAVE_LIBUSB { - if (devices[fd].bulk_in_ep) - read_size = usb_bulk_read (devices[fd].libusb_handle, - devices[fd].bulk_in_ep, (char *) buffer, + if (devices[dn].bulk_in_ep) + read_size = usb_bulk_read (devices[dn].libusb_handle, + devices[dn].bulk_in_ep, (char *) buffer, (int) *size, libusb_timeout); else { @@ -610,7 +610,7 @@ sanei_usb_read_bulk (SANE_Int fd, SANE_Byte * buffer, size_t * size) else { DBG (1, "sanei_usb_read_bulk: access method %d not implemented\n", - devices[fd].method); + devices[dn].method); return SANE_STATUS_INVAL; } @@ -633,7 +633,7 @@ sanei_usb_read_bulk (SANE_Int fd, SANE_Byte * buffer, size_t * size) } SANE_Status -sanei_usb_write_bulk (SANE_Int fd, SANE_Byte * buffer, size_t * size) +sanei_usb_write_bulk (SANE_Int dn, SANE_Byte * buffer, size_t * size) { ssize_t write_size = 0; @@ -643,20 +643,20 @@ sanei_usb_write_bulk (SANE_Int fd, SANE_Byte * buffer, size_t * size) return SANE_STATUS_INVAL; } - if (fd >= MAX_DEVICES || fd < 0) + if (dn >= MAX_DEVICES || dn < 0) { - DBG (1, "sanei_usb_write_bulk: fd >= MAX_DEVICES || fd < 0\n"); + DBG (1, "sanei_usb_write_bulk: dn >= MAX_DEVICES || dn < 0\n"); return SANE_STATUS_INVAL; } - if (devices[fd].method == sanei_usb_method_scanner_driver) - write_size = write (devices[fd].fd, buffer, *size); - else if (devices[fd].method == sanei_usb_method_libusb) + if (devices[dn].method == sanei_usb_method_scanner_driver) + write_size = write (devices[dn].fd, buffer, *size); + else if (devices[dn].method == sanei_usb_method_libusb) #ifdef HAVE_LIBUSB { - if (devices[fd].bulk_in_ep) - write_size = usb_bulk_write (devices[fd].libusb_handle, - devices[fd].bulk_out_ep, (char *) buffer, + if (devices[dn].bulk_in_ep) + write_size = usb_bulk_write (devices[dn].libusb_handle, + devices[dn].bulk_out_ep, (char *) buffer, (int) *size, libusb_timeout); else { @@ -674,7 +674,7 @@ sanei_usb_write_bulk (SANE_Int fd, SANE_Byte * buffer, size_t * size) else { DBG (1, "sanei_usb_read_bulk: access method %d not implemented\n", - devices[fd].method); + devices[dn].method); return SANE_STATUS_INVAL; } @@ -691,17 +691,17 @@ sanei_usb_write_bulk (SANE_Int fd, SANE_Byte * buffer, size_t * size) } SANE_Status -sanei_usb_control_msg (SANE_Int fd, SANE_Int rtype, SANE_Int req, +sanei_usb_control_msg (SANE_Int dn, SANE_Int rtype, SANE_Int req, SANE_Int value, SANE_Int index, SANE_Int len, SANE_Byte * data) { - if (fd >= MAX_DEVICES || fd < 0) + if (dn >= MAX_DEVICES || dn < 0) { - DBG (1, "sanei_usb_control_msg: fd >= MAX_DEVICES || fd < 0\n"); + DBG (1, "sanei_usb_control_msg: dn >= MAX_DEVICES || dn < 0\n"); return SANE_STATUS_INVAL; } - if (devices[fd].method == sanei_usb_method_scanner_driver) + if (devices[dn].method == sanei_usb_method_scanner_driver) { #if defined(__linux__) struct ctrlmsg_ioctl c; @@ -716,7 +716,7 @@ sanei_usb_control_msg (SANE_Int fd, SANE_Int rtype, SANE_Int req, DBG (5, "sanei_usb_control_msg: rtype = 0x%02x, req = %d, value = %d, " "index = %d, len = %d\n", rtype, req, value, index, len); - if (ioctl (devices[fd].fd, SCANNER_IOCTL_CTRLMSG, &c) < 0) + if (ioctl (devices[dn].fd, SCANNER_IOCTL_CTRLMSG, &c) < 0) { DBG (5, "sanei_usb_control_msg: SCANNER_IOCTL_CTRLMSG error - %s\n", strerror (errno)); @@ -728,12 +728,12 @@ sanei_usb_control_msg (SANE_Int fd, SANE_Int rtype, SANE_Int req, return SANE_STATUS_UNSUPPORTED; #endif /* not __linux__ */ } - else if (devices[fd].method == sanei_usb_method_libusb) + else if (devices[dn].method == sanei_usb_method_libusb) #ifdef HAVE_LIBUSB { int result; - result = usb_control_msg (devices[fd].libusb_handle, rtype, req, + result = usb_control_msg (devices[dn].libusb_handle, rtype, req, value, index, (char *) data, len, libusb_timeout); if (result < 0) @@ -753,7 +753,7 @@ sanei_usb_control_msg (SANE_Int fd, SANE_Int rtype, SANE_Int req, else { DBG (1, "sanei_usb_read_bulk: access method %d not implemented\n", - devices[fd].method); + devices[dn].method); return SANE_STATUS_UNSUPPORTED; } }