sanei_scsi.h File Reference

Generic interface to SCSI drivers. More...

Go to the source code of this file.

Macros
#define	HAVE_SANEI_SCSI_OPEN_EXTENDED
	Do we have sanei_scsi_open_extended()? More...

Typedefs
typedef SANE_Status(*	SANEI_SCSI_Sense_Handler) (int fd, u_char *sense_buffer, void *arg)
	Sense handler. More...

Functions
void	sanei_scsi_find_devices (const char *vendor, const char *model, const char *type, int bus, int channel, int id, int lun, SANE_Status(*attach)(const char *dev))
	Find SCSI devices. More...
SANE_Status	sanei_scsi_open (const char *device_name, int *fd, SANEI_SCSI_Sense_Handler sense_handler, void *sense_arg)
	Open a SCSI device. More...
SANE_Status	sanei_scsi_open_extended (const char *device_name, int *fd, SANEI_SCSI_Sense_Handler sense_handler, void *sense_arg, int *buffersize)
	Open a SCSI device and set the buffer size. More...
SANE_Status	sanei_scsi_req_enter (int fd, const void *src, size_t src_size, void *dst, size_t *dst_size, void **idp)
	Enqueue SCSI command. More...
SANE_Status	sanei_scsi_req_enter2 (int fd, const void *cmd, size_t cmd_size, const void *src, size_t src_size, void *dst, size_t *dst_size, void **idp)
	Enqueue SCSI command and separated data. More...
SANE_Status	sanei_scsi_req_wait (void *id)
	Wait for SCSI command. More...
SANE_Status	sanei_scsi_cmd (int fd, const void *src, size_t src_size, void *dst, size_t *dst_size)
	Send SCSI command. More...
SANE_Status	sanei_scsi_cmd2 (int fd, const void *cmd, size_t cmd_size, const void *src, size_t src_size, void *dst, size_t *dst_size)
	Send SCSI command and separated data. More...
void	sanei_scsi_req_flush_all (void)
	Flush queue. More...
void	sanei_scsi_req_flush_all_extended (int fd)
	Flush queue for handle. More...
void	sanei_scsi_close (int fd)
	Close a SCSI device. More...

Variables
int	sanei_scsi_max_request_size
	Maximum size of a SCSI request.

Detailed Description

Generic interface to SCSI drivers.

See also

sanei_usb.h, sanei_ab306.h,sanei_lm983x.h, sanei_pa4s2.h, sanei_pio.h, and man sane-scsi(5) for user-oriented documentation

Macro Definition Documentation

HAVE_SANEI_SCSI_OPEN_EXTENDED

#define HAVE_SANEI_SCSI_OPEN_EXTENDED

Do we have sanei_scsi_open_extended()?

Let backends decide, which open call to use: if HAVE_SANEI_SCSI_OPEN_EXTENDED is defined, sanei_scsi_open_extended may be used. May also be used to decide, if sanei_scsi_req_flush_all or sanei_scsi_req_flush_all_extended() should be used.

See also

sanei_scsi_open(), sanei_scsi_open_extended()

Typedef Documentation

SANEI_SCSI_Sense_Handler

typedef SANE_Status(* SANEI_SCSI_Sense_Handler) (int fd, u_char *sense_buffer, void *arg)

Sense handler.

The sense handler can be implemented in backends. It's for deciding which sense codes should be considered an error and which shouldn't.

Parameters

fd	file descriptor
sense_buffer	pointer to buffer containing sense codes
arg	pointer to data buffer

Returns

• SANE_STATUS_GOOD - on success (sense isn't regarded as error)
• any other status if sense code is regarded as error

Function Documentation

sanei_scsi_find_devices()

void sanei_scsi_find_devices	(	const char *	vendor,
		const char *	model,
		const char *	type,
		int	bus,
		int	channel,
		int	id,
		int	lun,
		SANE_Status(*)(const char *dev)	attach
	)

Find SCSI devices.

Find each SCSI device that matches the pattern specified by the arguments. String arguments can be "omitted" by passing NULL, integer arguments can be "omitted" by passing -1.

Example: vendor="HP" model=NULL, type=NULL, bus=3, id=-1, lun=-1 would attach all HP devices on SCSI bus 3.

Parameters

vendor
model
type
bus
channel
id
lun
attach	callback invoked once for each device, dev is the real devicename (passed to attach callback)

sanei_scsi_open()

SANE_Status sanei_scsi_open	(	const char *	device_name,
		int *	fd,
		SANEI_SCSI_Sense_Handler	sense_handler,
		void *	sense_arg
	)

Open a SCSI device.

Opens a SCSI device by its device filename and returns a file descriptor. If it's necessary to adjust the SCSI buffer size, use sanei_scsi_open_extended().

Parameters

device_name	name of the devicefile, e.g. "/dev/sg0"
fd	file descriptor
sense_handler	called whenever the SCSI driver returns a sense buffer
sense_arg	pointer to data for the sense handler

Returns

• SANE_STATUS_GOOD - on success
• SANE_STATUS_ACCESS_DENIED - if the file couldn't be accessed due to permissions
• SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
• SANE_STATUS_INVAL - if the filename was invalid or an unknown error occurred

See also

sanei_scsi_open_extended(), HAVE_SANEI_SCSI_OPEN_EXTENDED

sanei_scsi_open_extended()

SANE_Status sanei_scsi_open_extended	(	const char *	device_name,
		int *	fd,
		SANEI_SCSI_Sense_Handler	sense_handler,
		void *	sense_arg,
		int *	buffersize
	)

Open a SCSI device and set the buffer size.

The extended open call allows a backend to ask for a specific buffer size. sanei_scsi_open_extended() tries to allocate a buffer of the size given by *buffersize upon entry to this function. If sanei_scsi_open_extended returns successfully, *buffersize contains the available buffer size. This value may be both smaller or larger than the value requested by the backend; it can even be zero. The backend must decide, if it got enough buffer memory to work.

Note that the value of *buffersize may differ for different files.

Parameters

device_name	name of the devicefile, e.g. "/dev/sg0"
fd	file descriptor
sense_handler	called whenever the SCSI driver returns a sense buffer
sense_arg	pointer to data for the sense handler
buffersize	size of the SCAI request buffer (in bytes)

Returns

• SANE_STATUS_GOOD - on success
• SANE_STATUS_ACCESS_DENIED - if the file couldn't be accessed due to permissions
• SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
• SANE_STATUS_INVAL - if the filename was invalid or an unknown error occurred

See also

sanei_scsi_open(), HAVE_SANEI_SCSI_OPEN_EXTENDED

sanei_scsi_req_enter()

SANE_Status sanei_scsi_req_enter	(	int	fd,
		const void *	src,
		size_t	src_size,
		void *	dst,
		size_t *	dst_size,
		void **	idp
	)

Enqueue SCSI command.

One or more scsi commands can be enqueued by calling sanei_scsi_req_enter().

NOTE: Some systems may not support multiple outstanding commands. On such systems, sanei_scsi_req_enter() may block. In other words, it is not proper to assume that enter() is a non-blocking routine.

Parameters

fd	file descriptor
src	pointer to the SCSI command and associated write data (if any)
src_size	length of the command and data
dst	pointer to a buffer in which data is returned; NULL if no data is returned
dst_size	on input, the size of the buffer pointed to by dst, on exit, set to the number of bytes returned in the buffer (which is less than or equal to the buffer size; may be NULL if no data is expected
idp	pointer to a void* that uniquely identifies the entered request

Returns

• SANE_STATUS_GOOD - on success
• SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver
• SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
• SANE_STATUS_INVAL - if a locking or an unknown error occurred

See also

sanei_scsi_req_enter2()

sanei_scsi_req_enter2()

SANE_Status sanei_scsi_req_enter2	(	int	fd,
		const void *	cmd,
		size_t	cmd_size,
		const void *	src,
		size_t	src_size,
		void *	dst,
		size_t *	dst_size,
		void **	idp
	)

Enqueue SCSI command and separated data.

Same as sanei_scsi_req_enter(), but with separate buffers for the SCSI command and for the data to be sent to the device.

With sanei_scsi_req_enter(), the length of the SCSI command block must be guessed. While that works in most cases, Canon scanners for example use the vendor specific commands 0xd4, 0xd5 and 0xd6. The Canon scanners want to get 6 byte command blocks for these commands, but sanei_scsi_req_enter() and sanei_scsi_cmd() send 12 bytes.

If dst_size and *dst_size are non-zero, a "read command" (ie, data transfer from the device to the host) is assumed.

Parameters

fd	file descriptor
cmd	pointer to SCSI command
cmd_size	size of the command
src	pointer to the buffer with data to be sent to the scanner
src_size	size of src buffer
dst	pointer to a buffer in which data is returned; NULL if no data is returned
dst_size	on input, the size of the buffer pointed to by dst, on exit, set to the number of bytes returned in the buffer (which is less than or equal to the buffer size; may be NULL if no data is expected
idp	pointer to a void* that uniquely identifies the entered request

Returns

• SANE_STATUS_GOOD - on success
• SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver
• SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
• SANE_STATUS_INVAL - if a locking or an unknown error occurred

See also

sanei_scsi_req_enter()

sanei_scsi_req_wait()

SANE_Status sanei_scsi_req_wait

(

void *

id

)

Wait for SCSI command.

Wait for the completion of the SCSI command with id ID.

Parameters

id	id used in sanei_scsi_req_enter()

Returns

• SANE_STATUS_GOOD - on success
• SANE_STATUS_DEVICE_BUSY - if the device is busy (try again later)
• SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver

sanei_scsi_cmd()

SANE_Status sanei_scsi_cmd	(	int	fd,
		const void *	src,
		size_t	src_size,
		void *	dst,
		size_t *	dst_size
	)

Send SCSI command.

This is a convenience function that is equivalent to a pair of sanei_scsi_req_enter()/sanei_scsi_req_wait() calls.

Parameters

fd	file descriptor
src	pointer to the SCSI command and associated write data (if any)
src_size	length of the command and data
dst	pointer to a buffer in which data is returned; NULL if no data is returned
dst_size	on input, the size of the buffer pointed to by dst, on exit, set to the number of bytes returned in the buffer (which is less than or equal to the buffer size; may be NULL if no data is expected

Returns

• SANE_STATUS_GOOD - on success
• SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver
• SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
• SANE_STATUS_INVAL - if a locking or an unknown error occurred

See also

sanei_scsi_cmd2(), sanei_scsi_req_enter(), sanei_scsi_req_wait()

sanei_scsi_cmd2()

SANE_Status sanei_scsi_cmd2	(	int	fd,
		const void *	cmd,
		size_t	cmd_size,
		const void *	src,
		size_t	src_size,
		void *	dst,
		size_t *	dst_size
	)

Send SCSI command and separated data.

This is a convenience function that is equivalent to a pair of sanei_scsi_req_enter2()/sanei_scsi_req_wait() calls.

Parameters

fd	file descriptor
cmd	pointer to SCSI command
cmd_size	size of the command
src	pointer to the buffer with data to be sent to the scanner
src_size	size of src buffer
dst	pointer to a buffer in which data is returned; NULL if no data is returned
dst_size	on input, the size of the buffer pointed to by dst, on exit, set to the number of bytes returned in the buffer (which is less than or equal to the buffer size; may be NULL if no data is expected

Returns

• SANE_STATUS_GOOD - on success
• SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver
• SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
• SANE_STATUS_INVAL - if a locking or an unknown error occurred

See also

sanei_scsi_cmd(), sanei_scsi_req_enter(), sanei_scsi_req_wait()

sanei_scsi_req_flush_all()

void sanei_scsi_req_flush_all

(

void

)

Flush queue.

Flush all pending SCSI commands. This function work only, if zero or one SCSI file handles are open.

See also

sanei_scsi_req_flush_all_extended()

sanei_scsi_req_flush_all_extended()

void sanei_scsi_req_flush_all_extended

(

int

fd

)

Flush queue for handle.

Flush all SCSI commands pending for one handle

Parameters

fd	file descriptor

See also

sanei_scsi_req_flush_all()

sanei_scsi_close()

void sanei_scsi_close

(

int

fd

)

Close a SCSI device.

Parameters

fd	file descriptor