com.tuneology.sane
Class Sane

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

public class Sane

extends java.lang.Object

SANE is an application programming interface (API) that provides standardized access to any raster image scanner hardware. The standardized interface allows to write just one driver for each scanner device instead of one driver for each scanner and application. The reduction in the number of required drivers provides significant savings in development time. More importantly, SANE raises the level at which applications can work. As such, it will enable applications that were previously unheard of in the UNIX world. While SANE is primarily targeted at a UNIX environment, the standard has been carefully designed to make it possible to implement the API on virtually any hardware or operating system.

SANE is an acronym for 'Scanner Access Now Easy'. Also, the hope is that SANE is sane in the sense that it will allow easy implementation of the API while accommodating all features required by today's scanner hardware and applications. Specifically, SANE should be broad enough to accommodate devices such as scanners, digital still and video cameras, as well as virtual devices like image file filters.

Version:

$Id$

Author:

Fran Taylor

Field Summary

static int	CAP_ADVANCED If set, this capability indicates that the option should be considered an advanced user option.
static int	CAP_ALWAYS_SETTABLE
static int	CAP_AUTOMATIC If set, this capability indicates that the backend (or the device) is capable to picking a reasonable option value automatically.
static int	CAP_EMULATED If set, this capability indicates that an option is not directly supported by the device and is instead emulated in the backend.
static int	CAP_HARD_SELECT The option value can be set by user-intervention (e.g., by flipping a switch).
static int	CAP_INACTIVE If set, this capability indicates that the option is not currently active (e.g., because it's meaningful only if another option is set to some other value).
static int	CAP_SOFT_DETECT The option value can be detected by software.
static int	CAP_SOFT_SELECT The option value can be set by a call to setValues().
static int	FRAME_BLUE Blue band of a red/green/blue image.
static int	FRAME_GRAY Band covering human visual range.
static int	FRAME_GREEN Green band of a red/green/blue image.
static int	FRAME_RED Red band of a red/green/blue image.
static int	FRAME_RGB Pixel-interleaved red/green/blue bands.
static int	INFO_INEXACT This value is returned when setting an option value resulted in a value being selected that does not exactly match the requested value.
static int	INFO_RELOAD_OPTIONS The setting of an option may affect the value or availability of one or more other options.
static int	INFO_RELOAD_PARAMS The setting of an option may affect the parameter values (see sane_get_parameters()).
static int	STATUS_ACCESS_DENIED Access to resource has been denied.
static int	STATUS_CANCELLED Operation was cancelled.
static int	STATUS_COVER_OPEN Scanner cover is open.
static int	STATUS_DEVICE_BUSY Device is busy---retry later.
static int	STATUS_EOF No more data available (end-of-file).
static int	STATUS_GOOD Operation completed succesfully.
static int	STATUS_INVAL Data or argument is invalid.
static int	STATUS_IO_ERROR Error during device I/O.
static int	STATUS_JAMMED Document feeder jammed.
static int	STATUS_NO_DOCS Document feeder out of documents.
static int	STATUS_NO_MEM Out of memory.
static int	STATUS_UNSUPPORTED Operation is not supported.
static int	TYPE_BOOL Option value is of type boolean.
static int	TYPE_BUTTON An option of this type has no value.
static int	TYPE_FIXED Option value is of type int with 16 bits of integer value and 16 bits of fractional value.
static int	TYPE_GROUP An option of this type has no value.
static int	TYPE_INT Option value is of type int.
static int	TYPE_STRING Option value is of type String.
static int	UNIT_BIT
static int	UNIT_DPI
static int	UNIT_MICROSECOND
static int	UNIT_MM
static int	UNIT_NONE
static int	UNIT_PERCENT
static int	UNIT_PIXEL

Method Summary

static void	exit() This function must be called to terminate use of a backend.
static SaneDevice[]	getDevices(boolean local_only) This function can be used to query the list of devices that are available.
static int	getVersionCode() Returns the version code of the backend.
static void	init() This function must be called before any other SANE function can be called.
static SaneScanner	open(java.lang.String deviceName) This function is used to establish a connection to a particular device.
static void	setAuthorizer(SaneAuthorization a) The authorization function may be called by a backend in response to any of the following calls: open, setValue(s), getValue(s), setAutomatic, SaneScanner.start.
static java.lang.String	strstatus(int status) This function can be used to translate a SANE status code into a printable string.

Methods inherited from class java.lang.Object

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

Field Detail

STATUS_GOOD

public static final int STATUS_GOOD

Operation completed succesfully.

See Also:

Constant Field Values

STATUS_UNSUPPORTED

public static final int STATUS_UNSUPPORTED

Operation is not supported.

See Also:

Constant Field Values

STATUS_CANCELLED

public static final int STATUS_CANCELLED

Operation was cancelled.

See Also:

Constant Field Values

STATUS_DEVICE_BUSY

public static final int STATUS_DEVICE_BUSY

Device is busy---retry later.

See Also:

Constant Field Values

STATUS_INVAL

public static final int STATUS_INVAL

Data or argument is invalid.

See Also:

Constant Field Values

STATUS_EOF

public static final int STATUS_EOF

No more data available (end-of-file).

See Also:

Constant Field Values

STATUS_JAMMED

public static final int STATUS_JAMMED

Document feeder jammed.

See Also:

Constant Field Values

STATUS_NO_DOCS

public static final int STATUS_NO_DOCS

Document feeder out of documents.

See Also:

Constant Field Values

STATUS_COVER_OPEN

public static final int STATUS_COVER_OPEN

Scanner cover is open.

See Also:

Constant Field Values

STATUS_IO_ERROR

public static final int STATUS_IO_ERROR

Error during device I/O.

See Also:

Constant Field Values

STATUS_NO_MEM

public static final int STATUS_NO_MEM

Out of memory.

See Also:

Constant Field Values

STATUS_ACCESS_DENIED

public static final int STATUS_ACCESS_DENIED

Access to resource has been denied.

See Also:

Constant Field Values

UNIT_NONE

public static final int UNIT_NONE

See Also:

Constant Field Values

UNIT_PIXEL

public static final int UNIT_PIXEL

See Also:

Constant Field Values

UNIT_BIT

public static final int UNIT_BIT

See Also:

Constant Field Values

UNIT_MM

public static final int UNIT_MM

See Also:

Constant Field Values

UNIT_DPI

public static final int UNIT_DPI

See Also:

Constant Field Values

UNIT_PERCENT

public static final int UNIT_PERCENT

See Also:

Constant Field Values

UNIT_MICROSECOND

public static final int UNIT_MICROSECOND

See Also:

Constant Field Values

CAP_SOFT_SELECT

public static final int CAP_SOFT_SELECT

The option value can be set by a call to setValues().

See Also:

Constant Field Values

CAP_HARD_SELECT

public static final int CAP_HARD_SELECT

The option value can be set by user-intervention (e.g., by flipping a switch). The user-interface should prompt the user to execute the appropriate action to set such an option. This capability is mutually exclusive with SANE_CAP_SOFT_SELECT (either one of them can be set, but not both simultaneously).

See Also:

Constant Field Values

CAP_SOFT_DETECT

public static final int CAP_SOFT_DETECT

The option value can be detected by software. If SANE_CAP_SOFT_SELECT is set, this capability must be set. If SANE_CAP_HARD_SELECT is set, this capability may or may not be set. If this capability is set but neither SANE_CAP_SOFT_SELECT nor SANE_CAP_HARD_SELECT are, then there is no way to control the option. That is, the option provides read-out of the current value only.

See Also:

Constant Field Values

CAP_EMULATED

public static final int CAP_EMULATED

If set, this capability indicates that an option is not directly supported by the device and is instead emulated in the backend. A sophisticated frontend may elect to use its own (presumably better) emulation in lieu of an emulated option.

See Also:

Constant Field Values

CAP_AUTOMATIC

public static final int CAP_AUTOMATIC

If set, this capability indicates that the backend (or the device) is capable to picking a reasonable option value automatically. For such options, it is possible to select automatic operation by calling sane_control_option() with an action value of SANE_ACTION_SET_AUTO.

See Also:

Constant Field Values

CAP_INACTIVE

public static final int CAP_INACTIVE

If set, this capability indicates that the option is not currently active (e.g., because it's meaningful only if another option is set to some other value).

See Also:

Constant Field Values

CAP_ADVANCED

public static final int CAP_ADVANCED

If set, this capability indicates that the option should be considered an advanced user option. A frontend typically displays such options in a less conspicuous way than regular options (e.g., a command line interface may list such options last or a graphical interface may make them available in a seperate advanced settings dialog).

See Also:

Constant Field Values

CAP_ALWAYS_SETTABLE

public static final int CAP_ALWAYS_SETTABLE

See Also:

Constant Field Values

TYPE_BOOL

public static final int TYPE_BOOL

Option value is of type boolean.

See Also:

Constant Field Values

TYPE_INT

public static final int TYPE_INT

Option value is of type int.

See Also:

Constant Field Values

TYPE_FIXED

public static final int TYPE_FIXED

Option value is of type int with 16 bits of integer value and 16 bits of fractional value.

See Also:

Constant Field Values

TYPE_STRING

public static final int TYPE_STRING

Option value is of type String.

See Also:

Constant Field Values

TYPE_BUTTON

public static final int TYPE_BUTTON

An option of this type has no value. For example, a button-typed option could be used by a backend to provide a means to select default values or to the tell an automatic document feeder to advance to the next sheet of paper.

See Also:

Constant Field Values

TYPE_GROUP

public static final int TYPE_GROUP

An option of this type has no value. This type is used to group logically related options. A group option is in effect up to the point where another group option is encountered (or up to the end of the option list, if there are no other group options). For group options, only members title and type are valid in the option descriptor.

See Also:

Constant Field Values

FRAME_GRAY

public static final int FRAME_GRAY

Band covering human visual range.

See Also:

Constant Field Values

FRAME_RGB

public static final int FRAME_RGB

Pixel-interleaved red/green/blue bands.

See Also:

Constant Field Values

FRAME_RED

public static final int FRAME_RED

Red band of a red/green/blue image.

See Also:

Constant Field Values

FRAME_GREEN

public static final int FRAME_GREEN

Green band of a red/green/blue image.

See Also:

Constant Field Values

FRAME_BLUE

public static final int FRAME_BLUE

Blue band of a red/green/blue image.

See Also:

Constant Field Values

INFO_INEXACT

public static final int INFO_INEXACT

This value is returned when setting an option value resulted in a value being selected that does not exactly match the requested value. For example, if a scanner can adjust the resolution in increments of 30dpi only, setting the resolution to 307dpi may result in an actual setting of 300dpi. When this happens, the bitset returned in *i has this member set. In addition, the option value is modified to reflect the actual (rounded) value that was used by the backend. Note that inexact values are admissible for strings as well. A backend may choose to ``round'' a string to the closest matching legal string for a constrained string value.

See Also:

Constant Field Values

INFO_RELOAD_OPTIONS

public static final int INFO_RELOAD_OPTIONS

The setting of an option may affect the value or availability of one or more other options. When this happens, the SANE backend returns this to indicate that the application should reload all options. This member may be set if and only if at least one option changed.

See Also:

Constant Field Values

INFO_RELOAD_PARAMS

public static final int INFO_RELOAD_PARAMS

The setting of an option may affect the parameter values (see sane_get_parameters()). If setting an option affects the parameter values, this bit will be set in the return value. Note that this member may be set even if the parameters did not actually change. However, it is guaranteed that the parameters never change without this member being set.

See Also:

Constant Field Values

Method Detail

init

public static void init()
                 throws SaneException

This function must be called before any other SANE function can be called. The behavior of a SANE backend is undefined if this function is not called first.

Throws:

SaneException

setAuthorizer

public static void setAuthorizer(SaneAuthorization a)

The authorization function may be called by a backend in response to any of the following calls: open, setValue(s), getValue(s), setAutomatic, SaneScanner.start. If a backend was initialized without authorization function, then authorization requests that cannot be handled by the backend itself will fail automatically and the user may be prevented from accessing protected resources. Backends are encouraged to implement means of authentication that do not require user assistance. E.g., on a multi-user system that authenticates users through a login process a backend could automatically lookup the apporpriate password based on resource- and user-name.

Parameters:

a -

getVersionCode

public static int getVersionCode()

Returns the version code of the backend.

Returns:

the version code of the backend.

getDevices

public static SaneDevice[] getDevices(boolean local_only)
                               throws SaneException

This function can be used to query the list of devices that are available. If the function executes successfully, it returns a reference to an array of SANE_Device objectsq. The returned array is guaranteed to remain unchanged and valid until (a) another call to this function is performed or (b) a call to exit() is performed. This function can be called repeatedly to detect when new devices become available. If argument local_only is true, only local devices are returned (devices directly attached to the machine that SANE is running on). If it is false, the device list includes all remote devices that are accessible to the SANE library.

This function may fail with SANE_STATUS_NO_MEM if an insufficient amount of memory is available.

Parameters:

local_only -

Returns:

an array of available devices.

Throws:

SaneException

open

public static SaneScanner open(java.lang.String deviceName)
                        throws SaneException

This function is used to establish a connection to a particular device. The name of the device to be opened is passed in argument name. If the call completes successfully, a reference to the device is returned. As a special case, specifying a zero-length string as the device requests opening the first available device (if there is such a device).

This function may fail with one of the following SaneExceptions:

STATUS_DEVICE_BUSY: The device is currently busy (in use by somebody else).
SANE_STATUS_INVAL: The device name is not valid.
SANE_STATUS_IO_ERROR An error occured while communicating with the device.
SANE_STATUS_NO_MEM: An insufficent amount of memory is available.
SANE_STATUS_ACCESS_DENIED: Access to the device has been denied due to insufficient or invalid authentication.

Parameters:

deviceName -

Returns:

A scanner object.

Throws:

SaneException

strstatus

public static java.lang.String strstatus(int status)

This function can be used to translate a SANE status code into a printable string. The returned string is a single line of text that forms a complete sentence, but without the trailing period (full-stop).

Parameters:

status - the SANE status code.

Returns:

the string associated with the status.

exit

public static void exit()

This function must be called to terminate use of a backend. The function will first close all device handles that still might be open (it is recommended to close device handles explicitly through a call to close(), but backends are required to release all resources upon a call to this function). After this function returns, no function other than init() may be called. Neglecting to call this function may result in some resources not being released properly.