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

Macros
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
	Check if sanei_usb_set_timeout() is available.

#define	USB_DIR_IN 0x80
	Check if sanei_usb_set_timeout() is available.

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

SANE_Status	sanei_usb_testing_enable_replay (SANE_String_Const path, int development_mode)
	Initialize sanei_usb for replay testing. More...

SANE_Status	sanei_usb_testing_enable_record (SANE_String_Const path, SANE_String_Const be_name)
	Initialize sanei_usb for recording. More...

SANE_String	sanei_usb_testing_get_backend (void)
	Returns backend name for testing. More...

SANE_Bool	sanei_usb_is_replay_mode_enabled (void)
	Returns SANE_TRUE if replay testing mode is enabled, i.e. More...

void	sanei_usb_testing_record_clear (void)
	Clears currently recorded data. More...

void	sanei_usb_testing_record_message (SANE_String_Const message)
	Records a debug message in the captured USB data if testing mode is enabled. More...

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:

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.

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_testing_enable_replay()

SANE_Status sanei_usb_testing_enable_replay	(	SANE_String_Const	path,
		int	development_mode
	)

Initialize sanei_usb for replay testing.

Initializes sanei_usb for testing by mocking whole USB stack. This function must be called before sanei_usb_init().

The sanei_usb subsystem also implements a "development mode". It modifies the XML data file with the actual commands of the test run and attempts to proceed testing until a mismatching input command is found for which input data is required.

A <known_commands_end> node in the data XML file will cause sanei_usb not to continue to the subsequent command in the XML file and instead it will prepend all output commands before that node before an output command is encountered.

Parameters

path	Path to the XML data file.
development_mode	Enables development mode.

◆ sanei_usb_testing_enable_record()

SANE_Status sanei_usb_testing_enable_record	(	SANE_String_Const	path,
		SANE_String_Const	be_name
	)

Initialize sanei_usb for recording.

Initializes sanei_usb for recording communication with the scanner. This function must be called before sanei_usb_init().

Parameters

path	Path to the XML data file.
be_name	The name of the backend to enable recording for.

◆ sanei_usb_testing_get_backend()

SANE_String sanei_usb_testing_get_backend ( void )

Returns backend name for testing.

Returns backend name for the file registered in sanei_usb_testing_enable. The caller is responsible for freeing it.

◆ sanei_usb_is_replay_mode_enabled()

SANE_Bool sanei_usb_is_replay_mode_enabled ( void )

Returns SANE_TRUE if replay testing mode is enabled, i.e.

whether we are working with fake scan data.

◆ sanei_usb_testing_record_clear()

void sanei_usb_testing_record_clear ( void )

Clears currently recorded data.

This is useful on certain backends to clear the currently recorded data if it relates to other devices than the one that the scan will be performed on. On these backends all devices that the backend supports are opened multiple times. Recording this interaction to XML file makes it impossible to replay it, as the existence of these devices is not mocked currently.

This function may only be called when no USB devices are open, otherwise the behavior is unpredictable.

◆ sanei_usb_testing_record_message()

void sanei_usb_testing_record_message ( SANE_String_Const message )

Records a debug message in the captured USB data if testing mode is enabled.

If testing mode is not enabled, this function does nothing.

Parameters

msg	Message to record

◆ 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 buses 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
vendor	vendor id
product	product 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

dn	device number of an already sanei_usb_opened device
vendor	vendor id
product	product 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

vendor	vendor id
product	product id
attach	attach 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

devname	name of the device to open
dn	device 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

dn	device number
ep_type	type of endpoint to set (bitwise or of USB_DIR_IN/OUT and USB_ENDPOINT_TYPE_BULK/CONTROL/INTERRUPT/ISOCHRONOUS
ep	endpoint 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

dn	device number
ep_type	type 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

dn	device number

◆ sanei_usb_set_timeout()

void sanei_usb_set_timeout ( SANE_Int timeout )

Set the libusb timeout for bulk and interrupt reads.

Parameters

timeout the new timeout in ms

◆ sanei_usb_clear_halt()

SANE_Status sanei_usb_clear_halt ( SANE_Int dn )

Clear halt condition on bulk endpoints.

Parameters

dn	device number

◆ sanei_usb_reset()

SANE_Status sanei_usb_reset ( SANE_Int dn )

Reset device.

Parameters

dn	device 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

dn	device number
buffer	buffer to store read data in
size	size of the data

Returns

SANE_STATUS_GOOD - on success
SANE_STATUS_EOF - if zero bytes have been read
SANE_STATUS_IO_ERROR - if an error occurred 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

dn	device number
buffer	buffer to write to device
size	size of the data

Returns

SANE_STATUS_GOOD - on success
SANE_STATUS_IO_ERROR - if an error occurred 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 access 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

dn	device number
rtype	specifies the characteristics of the request (e.g. data direction)
req	actual request
value	parameter specific to the request
index	parameter specific to the request (often used to select endpoint)
len	length of data to send/receive
data	buffer 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

dn	device number
buffer	buffer to store read data in
size	size of the data

Returns

SANE_STATUS_GOOD - on success
SANE_STATUS_EOF - if zero bytes have been read
SANE_STATUS_IO_ERROR - if an error occurred 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

name	device name pattern
attach	attach function

◆ sanei_usb_set_configuration()

SANE_Status sanei_usb_set_configuration	(	SANE_Int	dn,
		SANE_Int	configuration
	)

Initiate set configuration.

Change set configuration

Parameters

dn	device number
configuration,configuration	nummber

Returns

SANE_STATUS_GOOD - on success
SANE_STATUS_EOF - if zero bytes have been read
SANE_STATUS_IO_ERROR - if an error occurred 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

dn	device number
interface_number	interface number

Returns

SANE_STATUS_GOOD - on success
SANE_STATUS_EOF - if zero bytes have been read
SANE_STATUS_IO_ERROR - if an error occurred 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

dn	device number
interface_number	interface number

Returns

SANE_STATUS_GOOD - on success
SANE_STATUS_EOF - if zero bytes have been read
SANE_STATUS_IO_ERROR - if an error occurred 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

dn	device number
alternate,alternate	nummber

Returns

SANE_STATUS_GOOD - on success
SANE_STATUS_EOF - if zero bytes have been read
SANE_STATUS_IO_ERROR - if an error occurred 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

dn	device number
desc	where to put the information to

Returns

SANE_STATUS_GOOD - on success
SANE_STATUS_UNSUPPORTED - if the feature is not supported by the OS or SANE.
SANE_STATUS_INVAL - on every other error

Macros

USB directions

Detailed Description

Function Documentation

◆ sanei_usb_testing_enable_replay()

◆ sanei_usb_testing_enable_record()

◆ sanei_usb_testing_get_backend()

◆ sanei_usb_is_replay_mode_enabled()

◆ sanei_usb_testing_record_clear()

◆ sanei_usb_testing_record_message()

◆ sanei_usb_init()

◆ sanei_usb_exit()

◆ sanei_usb_scan_devices()

◆ sanei_usb_get_vendor_product_byname()

◆ sanei_usb_get_vendor_product()

◆ sanei_usb_find_devices()

◆ sanei_usb_open()

◆ sanei_usb_set_endpoint()

◆ sanei_usb_get_endpoint()

◆ sanei_usb_close()

◆ sanei_usb_set_timeout()

◆ sanei_usb_clear_halt()

◆ sanei_usb_reset()

◆ sanei_usb_read_bulk()

◆ sanei_usb_write_bulk()

◆ sanei_usb_control_msg()

◆ sanei_usb_read_int()

◆ sanei_usb_attach_matching_devices()

◆ sanei_usb_set_configuration()

◆ sanei_usb_claim_interface()

◆ sanei_usb_release_interface()

◆ sanei_usb_set_altinterface()

◆ sanei_usb_get_descriptor()