SANEI: sanei_usb.h File Reference

Go to the source code of this file.


Defines
#define	HAVE_SANEI_USB_SET_TIMEOUT
	Check if sanei_usb_set_timeout() is available.
Device and/or interface class codes
USB descriptor types
Descriptor sizes per descriptor type
Endpoint descriptors
Standard requests
USB types
USB recipients
USB Masks
USB directions
Functions
void	sanei_usb_init (void)
	Initialize sanei_usb.
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.
SANE_Status	sanei_usb_get_vendor_product (SANE_Int dn, SANE_Word vendor, SANE_Word product)
	Get the vendor and product ids.
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.
SANE_Status	sanei_usb_open (SANE_String_Const devname, SANE_Int *dn)
	Open a USB device.
void	sanei_usb_close (SANE_Int dn)
	Close a USB device.
void	sanei_usb_set_timeout (SANE_Int timeout)
	Set the libusb timeout for bulk and interrupt reads.
SANE_Status	sanei_usb_read_bulk (SANE_Int dn, SANE_Byte buffer, size_t size)
	Initiate a bulk transfer read.
SANE_Status	sanei_usb_write_bulk (SANE_Int dn, const SANE_Byte buffer, size_t size)
	Initiate a bulk transfer write.
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.
SANE_Status	sanei_usb_read_int (SANE_Int dn, SANE_Byte buffer, size_t size)
	Initiate a interrupt transfer read.
void	sanei_usb_attach_matching_devices (const char name, SANE_Status(attach)(const char *dev))
	Expand device name patterns into a list of devices.
SANE_Status	sanei_usb_set_configuration (SANE_Int dn, SANE_Int configuration)
	Initiate set configuration.
SANE_Status	sanei_usb_claim_interface (SANE_Int dn, SANE_Int interface_number)
	Initiate claim interface.
SANE_Status	sanei_usb_release_interface (SANE_Int dn, SANE_Int interface_number)
	Initiate release interface.
SANE_Status	sanei_usb_set_altinterface (SANE_Int dn, SANE_Int alternate)
	Initiate a set altinterface.
SANE_Status	sanei_usb_get_descriptor (SANE_Int dn, struct sanei_usb_dev_descriptor *desc)
	Get some information from the device descriptor.

Detailed Description

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.

Function Documentation

void sanei_usb_init ( void )

Initialize sanei_usb.

Call this before any other sanei_usb function.

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

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

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)

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

void sanei_usb_close ( SANE_Int dn )

Close a USB device.

Parameters:

device number

void sanei_usb_set_timeout ( SANE_Int timeout )

Set the libusb timeout for bulk and interrupt reads.

Parameters:

timeout

the new timeout in ms

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

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 succes
SANE_STATUS_IO_ERROR - if an error occured during the write
SANE_STATUS_INVAL - on every other error

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:

	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.

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

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

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

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

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

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

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 succes
SANE_STATUS_UNSUPPORTED - if the feature is not supported by the OS or SANE.
SANE_STATUS_INVAL - on every other error

sanei_usb.h File Reference

Defines

Functions

Detailed Description

Function Documentation