SANEI  1.0.27-170-g1a2a8ee7-dirty
Macros | Functions
sanei_usb.h File Reference

This file provides a generic USB interface. More...

Go to the source code of this file.

Macros

#define HAVE_SANEI_USB_SET_TIMEOUT
 Check if sanei_usb_set_timeout() is available.
 
#define HAVE_SANEI_USB_CLEAR_HALT
 Check if sanei_usb_clear_halt() is available.
 
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
 
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
#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 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
#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
 
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
#define USB_RECIP_DEVICE   0x00
 
#define USB_RECIP_INTERFACE   0x01
 
#define USB_RECIP_ENDPOINT   0x02
 
#define USB_RECIP_OTHER   0x03
 
USB Masks
#define USB_TYPE_MASK   (0x03 << 5)
 
#define USB_RECIP_MASK   0x1f
 
USB directions
#define USB_DIR_OUT   0x00
 
#define USB_DIR_IN   0x80
 

Functions

void sanei_usb_init (void)
 Initialize sanei_usb. More...
 
void sanei_usb_exit (void)
 End sanei_usb use, freeing resources when needed. More...
 
void sanei_usb_scan_devices (void)
 Search for USB devices. More...
 
SANE_Status sanei_usb_get_vendor_product_byname (SANE_String_Const devname, SANE_Word *vendor, SANE_Word *product)
 Get the vendor and product ids by device name. More...
 
SANE_Status sanei_usb_get_vendor_product (SANE_Int dn, SANE_Word *vendor, SANE_Word *product)
 Get the vendor and product ids. More...
 
SANE_Status sanei_usb_find_devices (SANE_Int vendor, SANE_Int product, SANE_Status(*attach)(SANE_String_Const devname))
 Find devices that match given vendor and product ids. More...
 
SANE_Status sanei_usb_open (SANE_String_Const devname, SANE_Int *dn)
 Open a USB device. More...
 
void sanei_usb_set_endpoint (SANE_Int dn, SANE_Int ep_type, SANE_Int ep)
 Set the endpoint for the USB communication. More...
 
SANE_Int sanei_usb_get_endpoint (SANE_Int dn, SANE_Int ep_type)
 Retrieve the endpoint used for the USB communication. More...
 
void sanei_usb_close (SANE_Int dn)
 Close a USB device. More...
 
void sanei_usb_set_timeout (SANE_Int timeout)
 Set the libusb timeout for bulk and interrupt reads. More...
 
SANE_Status sanei_usb_clear_halt (SANE_Int dn)
 Clear halt condition on bulk endpoints. More...
 
SANE_Status sanei_usb_reset (SANE_Int dn)
 Reset device. More...
 
SANE_Status sanei_usb_read_bulk (SANE_Int dn, SANE_Byte *buffer, size_t *size)
 Initiate a bulk transfer read. More...
 
SANE_Status sanei_usb_write_bulk (SANE_Int dn, const SANE_Byte *buffer, size_t *size)
 Initiate a bulk transfer write. More...
 
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)
 Send/receive a control message to/from a USB device. More...
 
SANE_Status sanei_usb_read_int (SANE_Int dn, SANE_Byte *buffer, size_t *size)
 Initiate a interrupt transfer read. More...
 
void sanei_usb_attach_matching_devices (const char *name, SANE_Status(*attach)(const char *dev))
 Expand device name patterns into a list of devices. More...
 
SANE_Status sanei_usb_set_configuration (SANE_Int dn, SANE_Int configuration)
 Initiate set configuration. More...
 
SANE_Status sanei_usb_claim_interface (SANE_Int dn, SANE_Int interface_number)
 Initiate claim interface. More...
 
SANE_Status sanei_usb_release_interface (SANE_Int dn, SANE_Int interface_number)
 Initiate release interface. More...
 
SANE_Status sanei_usb_set_altinterface (SANE_Int dn, SANE_Int alternate)
 Initiate a set altinterface. More...
 
SANE_Status sanei_usb_get_descriptor (SANE_Int dn, struct sanei_usb_dev_descriptor *desc)
 Get some information from the device descriptor. More...
 

Detailed Description

This file provides a generic USB interface.

Currently, two access methods to USB devices are provided:

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.

See also
sanei_lm983x.h, sanei_pa4s2.h, sanei_pio.h, sanei_scsi.h, and man sane-usb(5) for user-oriented documentation

Function Documentation

◆ sanei_usb_init()

void sanei_usb_init ( void  )

Initialize sanei_usb.

Call this before any other sanei_usb function.

◆ sanei_usb_exit()

void sanei_usb_exit ( void  )

End sanei_usb use, freeing resources when needed.

When the use count of sanei_usb reach 0, free resources and end sanei_usb use.

◆ sanei_usb_scan_devices()

void sanei_usb_scan_devices ( void  )

Search for USB devices.

Search USB busses for scanner devices.

◆ sanei_usb_get_vendor_product_byname()

SANE_Status sanei_usb_get_vendor_product_byname ( SANE_String_Const  devname,
SANE_Word *  vendor,
SANE_Word *  product 
)

Get the vendor and product ids by device name.

Parameters
devname
vendorvendor id
productproduct id
Returns
  • SANE_STATUS_GOOD - if the ids could be determined
  • SANE_STATUS_INVAL - if the device is not found
  • SANE_STATUS_UNSUPPORTED - if this method is not supported with the current access method

◆ sanei_usb_get_vendor_product()

SANE_Status sanei_usb_get_vendor_product ( SANE_Int  dn,
SANE_Word *  vendor,
SANE_Word *  product 
)

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.

Parameters
dndevice number of an already sanei_usb_opened device
vendorvendor id
productproduct id
Returns
  • SANE_STATUS_GOOD - if the ids could be determined
  • SANE_STATUS_UNSUPPORTED - if the OS doesn't support detection of ids

◆ sanei_usb_find_devices()

SANE_Status sanei_usb_find_devices ( SANE_Int  vendor,
SANE_Int  product,
SANE_Status(*)(SANE_String_Const devname)  attach 
)

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.

Parameters
vendorvendor id
productproduct id
attachattach function
Returns
SANE_STATUS_GOOD - on success (even if no scanner was found)

◆ sanei_usb_open()

SANE_Status sanei_usb_open ( SANE_String_Const  devname,
SANE_Int *  dn 
)

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).

Parameters
devnamename of the device to open
dndevice number
Returns
  • 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

◆ sanei_usb_set_endpoint()

void sanei_usb_set_endpoint ( SANE_Int  dn,
SANE_Int  ep_type,
SANE_Int  ep 
)

Set the endpoint for the USB communication.

Allows to switch to a different endpoint for the USB communication than the default (auto-detected) endpoint. This function can only be called after sanei_usb_open.

Parameters
dndevice number
ep_typetype of endpoint to set (bitwise or of USB_DIR_IN/OUT and USB_ENDPOINT_TYPE_BULK/CONTROL/INTERRUPT/ISOCHRONOUS
ependpoint to use for the given type

◆ sanei_usb_get_endpoint()

SANE_Int sanei_usb_get_endpoint ( SANE_Int  dn,
SANE_Int  ep_type 
)

Retrieve the endpoint used for the USB communication.

Returns the endpoint used for the USB communication of the given type. This function can only be called after sanei_usb_open.

Parameters
dndevice number
ep_typetype of endpoint to retrieve (bitwise or of USB_DIR_IN/OUT and USB_ENDPOINT_TYPE_BULK/CONTROL/INTERRUPT/ISOCHRONOUS
Returns
endpoint used for the given type

◆ sanei_usb_close()

void sanei_usb_close ( SANE_Int  dn)

Close a USB device.

Parameters
dndevice number

◆ sanei_usb_set_timeout()

void sanei_usb_set_timeout ( SANE_Int  timeout)

Set the libusb timeout for bulk and interrupt reads.

Parameters
timeoutthe new timeout in ms

◆ sanei_usb_clear_halt()

SANE_Status sanei_usb_clear_halt ( SANE_Int  dn)

Clear halt condition on bulk endpoints.

Parameters
dndevice number

◆ sanei_usb_reset()

SANE_Status sanei_usb_reset ( SANE_Int  dn)

Reset device.

Parameters
dndevice number

◆ sanei_usb_read_bulk()

SANE_Status sanei_usb_read_bulk ( SANE_Int  dn,
SANE_Byte *  buffer,
size_t *  size 
)

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.

Parameters
dndevice number
bufferbuffer to store read data in
sizesize of the data
Returns
  • 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

◆ sanei_usb_write_bulk()

SANE_Status sanei_usb_write_bulk ( SANE_Int  dn,
const 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.

Parameters
dndevice number
bufferbuffer to write to device
sizesize of the data
Returns
  • SANE_STATUS_GOOD - on succes
  • SANE_STATUS_IO_ERROR - if an error occured during the write
  • SANE_STATUS_INVAL - on every other error

◆ sanei_usb_control_msg()

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 
)

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 www.usb.org developers information page.

Parameters
dndevice number
rtypespecifies the characteristics of the request (e.g. data direction)
reqactual request
valueparameter specific to the request
indexparameter specific to the request (often used to select endpoint)
lenlength of data to send/receive
databuffer to send/receive data
Returns
  • 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.

◆ sanei_usb_read_int()

SANE_Status sanei_usb_read_int ( SANE_Int  dn,
SANE_Byte *  buffer,
size_t *  size 
)

Initiate a interrupt transfer read.

Read up to size bytes from the interrupt endpoint from the device to buffer. After the read, size contains the number of bytes actually read.

Parameters
dndevice number
bufferbuffer to store read data in
sizesize of the data
Returns
  • 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

◆ sanei_usb_attach_matching_devices()

void sanei_usb_attach_matching_devices ( const char *  name,
SANE_Status(*)(const char *dev)  attach 
)

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.

Parameters
namedevice name pattern
attachattach function

◆ sanei_usb_set_configuration()

SANE_Status sanei_usb_set_configuration ( SANE_Int  dn,
SANE_Int  configuration 
)

Initiate set configuration.

Change set configuration

Parameters
dndevice number
configuration,configurationnummber
Returns
  • 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

◆ sanei_usb_claim_interface()

SANE_Status sanei_usb_claim_interface ( SANE_Int  dn,
SANE_Int  interface_number 
)

Initiate claim interface.

Change claim interface

Parameters
dndevice number
interface_numberinterface number
Returns
  • 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

◆ sanei_usb_release_interface()

SANE_Status sanei_usb_release_interface ( SANE_Int  dn,
SANE_Int  interface_number 
)

Initiate release interface.

Change release interface

Parameters
dndevice number
interface_numberinterface number
Returns
  • 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

◆ sanei_usb_set_altinterface()

SANE_Status sanei_usb_set_altinterface ( SANE_Int  dn,
SANE_Int  alternate 
)

Initiate a set altinterface.

Change set alternate

Parameters
dndevice number
alternate,alternatenummber
Returns
  • 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

◆ sanei_usb_get_descriptor()

SANE_Status sanei_usb_get_descriptor ( SANE_Int  dn,
struct sanei_usb_dev_descriptor *  desc 
)

Get some information from the device descriptor.

Sometimes it's useful to know something about revisions and other stuff reported by the USB system

Parameters
dndevice number
descwhere to put the information to
Returns
  • SANE_STATUS_GOOD - on succes
  • SANE_STATUS_UNSUPPORTED - if the feature is not supported by the OS or SANE.
  • SANE_STATUS_INVAL - on every other error