Data Types
/* Truth values. */
#define SANE_FALSE 0
#define SANE_TRUE 1
/* A byte must be big enough to hold 8 bits. */
typedef unsigned char SANE_Byte;
/* A word must be big enough to hold: truth values (SANE_FALSE and
SANE_TRUE), signed integers in the range -2^31..2^31-1, unsigned
integers in the range 0..2^32-1, and fixed point values in the
range -32768..32767.9999 with a resolution of 1/65536, and at least
32 bits. */
typedef int SANE_Word;
typedef SANE_Word SANE_Bool; /* boolean */
typedef SANE_Word SANE_Int; /* integer */
typedef SANE_Word SANE_Fixed; /* fixed point number */
/* Fixed point variables are scaled by 2^16. This allows to express
values in the range -32768..32767.9999 with a resolution of 1.5e-5. */
#define SANE_FIXED_SCALE_SHIFT 16
#define SANE_FIX(v) ((SANE_Word) ((v) * (1 << SANE_FIXED_SCALE_SHIFT)))
#define SANE_UNFIX(v) ((double)(v) / (1 << SANE_FIXED_SCALE_SHIFT))
/* A '\0'-terminated character string. Characters are in the host
native format. For now, characters should be restricted to
iso-latin-1, though eventually this might be expanded to cover UTC. */
typedef char *SANE_String;
typedef const char *SANE_String_Const; /* const SANE_String is NOT the same */
/* An opaque data type that represents a device. A handle may be
anything that fits into a pointer value (e.g., an integer value).
An application must not use a handle in any other way than by
passing it as an argument to other interface functions. */
typedef void *SANE_Handle;
typedef enum
{
SANE_STATUS_GOOD = 0, /* everything A-OK */
SANE_STATUS_UNSUPPORTED, /* operation is not supported */
SANE_STATUS_CANCELLED, /* operation was cancelled */
SANE_STATUS_DEVICE_BUSY, /* device is busy; try again later */
SANE_STATUS_AGAIN, /* currently, no data available; try again */
SANE_STATUS_INVAL, /* data is invalid (includes no dev at open) */
SANE_STATUS_EOF, /* no more data available (end-of-file) */
SANE_STATUS_JAMMED, /* document feeder jammed */
SANE_STATUS_NO_DOCS, /* document feeder out of documents */
SANE_STATUS_COVER_OPEN, /* scanner cover is open */
SANE_STATUS_IO_ERROR, /* error during device I/O */
SANE_STATUS_NO_MEM /* out of memory */
}
SANE_Status;
/* The type of option values is one of the following:
SANE_TYPE_BOOL: A SANE_Word with value SANE_FALSE or SANE_TRUE.
SANE_TYPE_INT: A SANE_Word interpreted as a signed integer.
SANE_TYPE_FIXED: A SANE_Word interpreted as a fixed point value.
SANE_TYPE_STRING: A SANE_String
SANE_TYPE_GROUP: A pseudo-option that is used to label and group
a sequence of options. The group is in effect
for the options that follow up to the point where
another group option is encountered. These pseudo-
options have no value but their name can be used
as a group title.
SANE_TYPE_BUTTON: A pseudo-option that is used to make push-buttons
like "Set Defaults" or "ADF next sheet"
These pseudo-options have no value but their name
should be used as a button-name.
*/
typedef enum
{
SANE_TYPE_BOOL = 0,
SANE_TYPE_INT,
SANE_TYPE_FIXED,
SANE_TYPE_STRING,
SANE_TYPE_GROUP,
SANE_TYPE_BUTTON
}
SANE_Value_Type;
/* Every option value has a unit associated. Note that these are the
units that are used by the SANE interface---what is presented to
the user is entirely up to the application. For example, SANE
lengths are always expressed in millimeters, but an application
should give the user the ability to select some other unit (e.g.,
inches or centimeters). */
typedef enum
{
SANE_UNIT_NONE = 0, /* the value is unit-less (e.g., # of scans) */
SANE_UNIT_PIXEL, /* value is number of pixels */
SANE_UNIT_BIT, /* value is number of bits */
SANE_UNIT_MM, /* value is millimeters */
SANE_UNIT_DPI, /* value is resolution in dots/inch */
SANE_UNIT_PERCENT /* value is a percentage */
}
SANE_Unit;
/* Each device is represented by a structure of the following form.
The structure gives the unique name of the device that can be used
in a call to sane_open(). The rest of the structure provides
additional info on what device the structure represents). The
unique name may be physical (e.g., /dev/scanner or
hostname:/dev/scanner) or logical (e.g., "Flatbed Scanner on host
foobar") but the interpretation is entirely up to the backend.
Unique names should not be overly long (a SANE application must be
able to _cope_ with arbitrarily long names, but it can expect that
most names are relatively short, e.g., less than 32 characters).
VENDOR, MODEL, and TYPE are single-line strings that give
information on the vendor (manufacturer), model, and the type of
the device. For consistency's sake, the following strings should
be used when appropriate (the lists will be expanded as need
arises):
Vendor Strings:
Artec
Connectix
Epson
Hewlett-Packard
Kodak
Logitech
Microtek
Minolta
Mustek
UMAX
None (e.g. for virtual devices)
Model strings:
(vendor specific)
Type Strings:
flatbed scanner
frame grabber
hand-held scanner
still camera
video camera
virtual device
*/
typedef struct
{
SANE_String_Const name; /* unique device name */
SANE_String_Const vendor; /* device vendor string */
SANE_String_Const model; /* device model name */
SANE_String_Const type; /* device type (e.g., "flatbed scanner") */
}
SANE_Device;
/* Options can be supported to a varying degree. The amount of support
is expressed by the capability bitset (member CAP). The meaning of
each possible member is explained below:
SANE_CAP_SOFT_SELECT: The value(s) of the option is
software-controlled.
SANE_CAP_HARD_SELECT: The value(s) of the option is
hardware-controlled. To set the value(s) of such an option,
the application using SANE must prompt the user to set the
option to the selected value before scanning can
start/progress. This bit is mutually exclusive with
SANE_CAP_SOFT_SELECT (either one of them can be set, but not both
simultaneously.
SANE_CAP_SOFT_DETECT: The value of the option can be detected by
software. If SANE_CAP_SOFT_SELECT is set, this bit must be set
too. 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 (it's possible to read out the current
values only).
SANE_CAP_EMULATED: This member is set if an option is not directly
supported by the device and is instead emulated in the backend.
Advanced scanner applications may use their own (presumably
better) emulation in lieu of such an option.
SANE_CAP_AUTOMATIC: If this bit is set then the backend is able to pick
a reasonable option value automatically.
SANE_CAP_INACTIVE: If this bit is set then the option is not
currently active (e.g., because it's meaningful only if another
option is set to some other value).
*/
#define SANE_CAP_SOFT_SELECT (1 << 0)
#define SANE_CAP_HARD_SELECT (1 << 1)
#define SANE_CAP_SOFT_DETECT (1 << 2)
#define SANE_CAP_EMULATED (1 << 3)
#define SANE_CAP_AUTOMATIC (1 << 4)
#define SANE_CAP_INACTIVE (1 << 5)
/* This macro can be used to determine whether an option is currently
active or not. It expects a capability-bitset as its only argument
and returns TRUE if the option is active. */
#define SANE_OPTION_IS_ACTIVE(cap) (((cap) & SANE_CAP_INACTIVE) == 0)
/* This macro can be used to determine whether an option is (software)
settable or not. It expects a capability-bitset as its only
argument and returns TRUE if the option is settable. */
#define SANE_OPTION_IS_SETTABLE(cap) (((cap) & SANE_CAP_SOFT_SELECT) != 0)
/* When operating on options, a bit mask with additional status
information is returned. The following members are possible:
SANE_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, some scanners can set the
resolution in increments of 30dpi only. Setting the resolution
to 307dpi may therefore result in an actual setting of 300dpi.
In such a case, the SANE backend should set this member in the
info return value.
SANE_INFO_RELOAD_OPTIONS: Setting one option may affect the value or
availability of _other_ options. When this happens, the SANE
backend sets this member in the return value to indicate that
the application should reload all options. If you are unsure
about what to return, set this bit to be safe.
SANE_INFO_RELOAD_PARAMS: Setting one option may affect parameter
values. If setting an option affects the parameter values,
bit SANE_INFO_RELOAD_PARAMS will be set. Note that this bit
may be set even if the parameters did not actually change.
However, it is guaranteed that the parameters never change
without this bit being set.
*/
#define SANE_INFO_INEXACT (1 << 0)
#define SANE_INFO_RELOAD_OPTIONS (1 << 1)
#define SANE_INFO_RELOAD_PARAMS (1 << 2)
/* The values of each option may be constrained in one of several
ways. The simplest constraint gives simply a minimum and a maximum
value. Optionally, the range may be quantized by a value Q (which
has the same interpretation as the value; e.g., fixed-point if the
value type is fixed-point). In that case, any value that is an
non-negative integer multiple of Q plus the minimum value is a
legal value---provided the resulting value is not greater than the
maximum value).
XXX Need to say that Range is for fixed-point and integer types
only and that a quantization value of 0 implies no quantization
constraint.
Alternatively, the values can be constrained by explicitly
enumerating the legal values. Depending on the value type,
this list is either a string list or a word list.
Note that a application using SANE does not _have_ to take
constraints into account. However, constraints typically guide the
user and make sure no unreasonable values are entered. It also
allows the application to use more sophisticated graphical elements
to represent options. For example, if the scanner source may be
the flatbed, an automatic document feeder, or a transparency
adapter, then a properly constrained option for the scanner source
could be represented as a set of three radio-buttons. */
typedef enum
{
SANE_CONSTRAINT_NONE = 0,
SANE_CONSTRAINT_RANGE,
SANE_CONSTRAINT_WORD_LIST,
SANE_CONSTRAINT_STRING_LIST
}
SANE_Constraint_Type;
typedef struct
{
SANE_Word min; /* minimum (element) value */
SANE_Word max; /* maximum (element) value */
SANE_Word quant; /* quantization value (0 if none) */
}
SANE_Range;
typedef struct
{
SANE_String_Const name; /* name of this option (command-line name) */
SANE_String_Const title; /* title of this option (single-line) */
SANE_String_Const desc; /* description of this option (multi-line) */
SANE_Value_Type type; /* how are values interpreted? */
SANE_Unit unit; /* what is the (physical) unit? */
/* XXX Number of bytes in option value. For an option of type
SANE_TYPE_STRING, it gives the maximum number of bytes in the
option string (0 means the unbounded). For boolean options,
the size is ignored (but backends should set it to sizeof
(SANE_Word)). For all other types, it implies the option is
a vector of maximum length SIZE/sizeof(SANE_Word). Note that
the size implies the _maximum_ length of a vector. It is
backend-dependent whether setting a vector that is shorter
than the maximum length is admissible or not. */
SANE_Int size;
SANE_Int cap; /* capabilities */
SANE_Constraint_Type constraint_type;
union
{
const SANE_String_Const *string_list; /* NULL-terminated list */
const SANE_Word *word_list; /* first element is list-length */
const SANE_Range *range;
}
constraint;
}
SANE_Option_Descriptor;
typedef enum
{
SANE_ACTION_GET_VALUE = 0, /* get current value */
SANE_ACTION_SET_VALUE, /* get current value */
SANE_ACTION_SET_AUTO /* let backend select value automatically */
}
SANE_Action;
typedef enum
{
SANE_FRAME_GRAY, /* band covering human visual range */
SANE_FRAME_RGB, /* pixel-interleaved red/green/blue bands */
SANE_FRAME_RED, /* red band only */
SANE_FRAME_GREEN, /* green band only */
SANE_FRAME_BLUE /* blue band only */
}
SANE_Frame;
typedef struct
{
/* Format of the current/next frame. */
SANE_Frame format;
/* This is SANE_TRUE if the frame is the first frame of a picture. */
SANE_Bool first_frame;
/* Number of bytes returned per scan line: */
SANE_Int bytes_per_line;
/* Number of pixels per scan line. This value multiplied by the
number of bands and the number of bits per sample must by <=
byte_per_line. */
SANE_Int pixels_per_line;
/* Number of lines for the current scan. If -1, sane_read() should
be called until it returns SANE_STATUS_EOF. */
SANE_Int lines;
/* Number of bits per sample. Each pixel consists of a DEPTH bits
times the number of bands (3 for SANE_BAND_RGB, 1 otherwise). */
SANE_Int depth;
}
SANE_Parameters;