com.tuneology.sane
Class SaneScanner

java.lang.Object
  |
  +--com.tuneology.sane.SaneScanner

public class SaneScanner

extends java.lang.Object

Represents a connection to a hardware scanner device.

Version:

$Id$

Author:

Fran Taylor

Method Summary

void	cancel() This function is used to immediately or as quickly as possible cancel the currently pending operation of the device.
void	close() This function terminates the association between the scanner object and the device it represents.
OptionDescriptor[]	get_option_descriptors() This function is used to access option descriptors.
SaneParameters	get_parameters() This function is used to obtain the current scan parameters.
int	read(java.lang.Object buf, int off, int len) This function is used to read image data from the device.
void	set_io_mode(boolean m) This function is used to set the I/O mode of the scanner.
void	start() This function initiates aquisition of an image from the scanner.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

get_option_descriptors

public OptionDescriptor[] get_option_descriptors()

This function is used to access option descriptors.

Returns:

the option descriptors for the scanner.

get_parameters

public SaneParameters get_parameters()

This function is used to obtain the current scan parameters. The returned parameters are guaranteed to be accurate between the time a scan has been started (start() has been called) and the completion of that request. Outside of that window, the returned values are best-effort estimates of what the parameters will be when start() gets invoked. Calling this function before a scan has actually started allows, for example, to get an estimate of how big the scanned image will be.

Returns:

the set of parameters for the scanner.

start

public void start()
           throws SaneException

This function initiates aquisition of an image from the scanner.

This function may fail with one of the following status codes:

STATUS_CANCELLED: The operation was cancelled through a call to sane_cancel.
STATUS_DEVICE_BUSY: The device is busy. The operation should be retried later.
STATUS_JAMMED: The document feeder is jammed.
STATUS_NO_DOCS: The document feeder is out of documents.
STATUS_COVER_OPEN: The scanner cover is open.
STATUS_IO_ERROR: An error occurred while communicating with the device.
STATUS_NO_MEM: An insufficent amount of memory is available.

Throws:

SaneException

read

public int read(java.lang.Object buf,
                int off,
                int len)
         throws SaneException

This function is used to read image data from the device. If this function is called when no data is available, one of two things may happen, depending on the I/O mode that is in effect.

1. If the device is in blocking I/O mode (the default mode), the call blocks until at least one data byte is available (or until some error occurs).

2. If the device is in non-blocking I/O mode, the call returns zero immediately.

The I/O mode can be set via a call to set_io_mode().

This function may fail by throwing one of the following SaneException values.

STATUS_CANCELLED: The operation was cancelled through a call to cancel().
STATUS_EOF: No more data is available for the current frame.
STATUS_JAMMED: The document feeder is jammed.
STATUS_NO_DOCS: The document feeder is out of documents.
STATUS_COVER_OPEN: The scanner cover is open.
STATUS_IO_ERROR: An error occurred while communicating with the device.
STATUS_NO_MEM: An insufficent amount of memory is available.
STATUS_ACCESS_DENIED: Access to the device has been denied due to insufficient or invalid authentication.

Parameters:

buf -

off -

len -

Throws:

SaneException

cancel

public void cancel()

This function is used to immediately or as quickly as possible cancel the currently pending operation of the device. This function can be called at any time, but usually affects long-running operations only (such as image is acquisition). It is important to note that completion of this operaton does not imply that the currently pending operation has been cancelled. It only guarantees that cancellation has been initiated. Cancellation completes only when the cancelled call returns. Since the SANE API does not require any other operations to be re-entrant, this implies that a frontend must not call any other operation until the cancelled operation has returned.

set_io_mode

public void set_io_mode(boolean m)
                 throws SaneException

This function is used to set the I/O mode of the scanner. The I/O mode can be either blocking or non-blocking. If argument m is true, the mode is set to non-blocking mode, otherwise it's set to blocking mode. By default, newly opened handles operate in blocking mode. A backend may elect not to support non-blocking I/O mode. In such a case set_io_mode() throws STATUS_UNSUPPORTED. Blocking I/O must be supported by all backends, so calling this function with argument m set to false is guaranteed to complete successfully.

Parameters:

m -

Throws:

SaneException

close

public void close()

This function terminates the association between the scanner object and the device it represents. If the device is presently active, a call to cancel() is performed first. After this function returns, the scanner object must not be used anymore.