kopia lustrzana https://gitlab.com/sane-project/backends
294 wiersze
9.5 KiB
C
294 wiersze
9.5 KiB
C
/* sane - Scanner Access Now Easy.
|
|
Copyright (C) 2001, 2002 Henning Meier-Geinitz
|
|
This file is part of the SANE package.
|
|
|
|
SANE is free software; you can redistribute it and/or modify it
|
|
under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation; either version 2 of the License, or
|
|
(at your option) any later version.
|
|
|
|
SANE is distributed in the hope that it will be useful, but WITHOUT
|
|
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
|
|
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
|
|
License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with sane; see the file COPYING. If not, write to the Free
|
|
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|
|
*/
|
|
|
|
/** @file sanei_usb.h
|
|
* This file provides a generic USB interface.
|
|
*
|
|
* Currently, two access methods to USB devices are provided:
|
|
* - Access to device
|
|
* files as used by the Linux kernel USB scanner driver is supported. FreeBSD
|
|
* and OpenBSD with their uscanner drivers also work this way. However,
|
|
* 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 <a
|
|
* href="http://www.mostang.com/sane/man/sane-usb.5.html">man sane-usb(5)</a>
|
|
* for user-oriented documentation
|
|
*/
|
|
|
|
#ifndef sanei_usb_h
|
|
#define sanei_usb_h
|
|
|
|
#include "../include/sane/config.h"
|
|
#include "../include/sane/sane.h"
|
|
|
|
/* USB spec defines */
|
|
#ifndef USB_CLASS_PER_INTERFACE
|
|
/* Also defined in libusb */
|
|
/** @name Device and/or interface class codes */
|
|
/* @{ */
|
|
#define USB_CLASS_PER_INTERFACE 0x00
|
|
#define USB_CLASS_AUDIO 0x01
|
|
#define USB_CLASS_COMM 0x02
|
|
#define USB_CLASS_HID 0x03
|
|
#define USB_CLASS_PRINTER 0x07
|
|
#define USB_CLASS_MASS_STORAGE 0x08
|
|
#define USB_CLASS_HUB 0x09
|
|
#define USB_CLASS_DATA 0x0a
|
|
#define USB_CLASS_VENDOR_SPEC 0xff
|
|
/* @} */
|
|
|
|
/** @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
|
|
/* @} */
|
|
|
|
/** @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
|
|
/* @} */
|
|
|
|
/** @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
|
|
/* @} */
|
|
|
|
/** @name Standard requests */
|
|
/* @{ */
|
|
#define USB_REQ_GET_STATUS 0x00
|
|
#define USB_REQ_CLEAR_FEATURE 0x01
|
|
#define USB_REQ_SET_FEATURE 0x03
|
|
#define USB_REQ_SET_ADDRESS 0x05
|
|
#define USB_REQ_GET_DESCRIPTOR 0x06
|
|
#define USB_REQ_SET_DESCRIPTOR 0x07
|
|
#define USB_REQ_GET_CONFIGURATION 0x08
|
|
#define USB_REQ_SET_CONFIGURATION 0x09
|
|
#define USB_REQ_GET_INTERFACE 0x0A
|
|
#define USB_REQ_SET_INTERFACE 0x0B
|
|
#define USB_REQ_SYNCH_FRAME 0x0C
|
|
/* @} */
|
|
|
|
/** @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)
|
|
/* @} */
|
|
|
|
/** @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
|
|
/* @} */
|
|
|
|
/** @name USB directions */
|
|
/* @{ */
|
|
#define USB_DIR_OUT 0
|
|
#define USB_DIR_IN 0x80
|
|
/* @} */
|
|
|
|
/** Initialize sanei_usb.
|
|
*
|
|
* Call this before any other sanei_usb function.
|
|
*/
|
|
extern void sanei_usb_init (void);
|
|
|
|
/** Get the vendor and product ids.
|
|
*
|
|
* 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 dn device number of an already sanei_usb_opened device
|
|
* @param vendor vendor id
|
|
* @param product product id
|
|
*
|
|
*@return
|
|
* - SANE_STATUS_GOOD - if the ids could be determinded
|
|
* - SANE_STATUS_UNSUPPORTED - if the OS doesn't support detection of ids
|
|
*/
|
|
extern SANE_Status
|
|
sanei_usb_get_vendor_product (SANE_Int dn, SANE_Word * vendor,
|
|
SANE_Word * product);
|
|
|
|
/** Find devices that match given vendor and product ids.
|
|
*
|
|
* For limitations, see function sanei_usb_get_vendor_product().
|
|
* The function attach is called for every device which has been found.
|
|
*
|
|
* @param vendor vendor id
|
|
* @param product product id
|
|
* @param attach attach function
|
|
*
|
|
* @return SANE_STATUS_GOOD - on success (even if no scanner was found)
|
|
*/
|
|
extern SANE_Status
|
|
sanei_usb_find_devices (SANE_Int vendor, SANE_Int product,
|
|
SANE_Status (*attach) (SANE_String_Const devname));
|
|
|
|
/** Open a USB device.
|
|
*
|
|
* The device is opened by its name devname and the device number is
|
|
* returned in dn on success.
|
|
*
|
|
* 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
|
|
* - SANE_STATUS_ACCESS_DENIED - if the file couldn't be accessed due to
|
|
* permissions
|
|
* - SANE_STATUS_INVAL - on every other error
|
|
*/
|
|
extern SANE_Status sanei_usb_open (SANE_String_Const devname, SANE_Int * dn);
|
|
|
|
/** Close a USB device.
|
|
*
|
|
* @param dn device number
|
|
*/
|
|
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 dn device number
|
|
* @param buffer buffer to store read data in
|
|
* @param size size of the data
|
|
*
|
|
* @return
|
|
* - SANE_STATUS_GOOD - on succes
|
|
* - SANE_STATUS_EOF - if zero bytes have been read
|
|
* - SANE_STATUS_IO_ERROR - if an error occured during the read
|
|
* - SANE_STATUS_INVAL - on every other error
|
|
*
|
|
*/
|
|
extern SANE_Status
|
|
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 dn device number
|
|
* @param buffer buffer to write to device
|
|
* @param size size of the data
|
|
*
|
|
* @return
|
|
* - SANE_STATUS_GOOD - on succes
|
|
* - SANE_STATUS_IO_ERROR - if an error occured during the write
|
|
* - SANE_STATUS_INVAL - on every other error
|
|
*/
|
|
extern SANE_Status
|
|
sanei_usb_write_bulk (SANE_Int dn, const SANE_Byte * buffer, size_t * size);
|
|
|
|
/** Send/receive a control message to/from a USB device.
|
|
*
|
|
* 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 <a href="http://www.usb.org/developers/docs.html">
|
|
* www.usb.org developers information page</a>.
|
|
*
|
|
* @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
|
|
* - SANE_STATUS_IO_ERROR - on error
|
|
* - SANE_STATUS_UNSUPPORTED - if the feature is not supported by the OS or
|
|
* SANE.
|
|
*/
|
|
extern SANE_Status
|
|
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 or
|
|
* libusb:002:003), this function currently supports USB device
|
|
* specifications of the form:
|
|
*
|
|
* usb VENDOR PRODUCT
|
|
*
|
|
* VENDOR and PRODUCT are non-negative integer numbers in decimal or
|
|
* hexadecimal format. A similar function for SCSI devices can be found
|
|
* in include/sane/config.h.
|
|
*
|
|
* @param name device name pattern
|
|
* @param attach attach function
|
|
*
|
|
*/
|
|
extern void
|
|
sanei_usb_attach_matching_devices (const char *name,
|
|
SANE_Status (*attach) (const char *dev));
|
|
|
|
#endif /* sanei_usb_h */
|