The SANE standard is based on just two SANE-specific base types: the SANE byte and word.
typedef some-scalar-type SANE_Byte;SANE_Byte must correspond to some scalar C type that is capable of holding values in the range 0 to 255. SANE_Word must be capable of holding any of the following:
typedef some-scalar-type SANE_Word;
SANE_Bool is used for variables that can take one of
the two truth values SANE_FALSE and
SANE_TRUE. The former value is defined to be 0,
whereas the latter is 1.
Note that SANE_Bool is simply an alias of SANE_Word. It is therefore always legal to use the latter type in place of the former. However, for clarity, it is recommended to use SANE_Bool whenever a given variable or formal argument has a fixed interpretation as a boolean object.#define SANE_FALSE 0 #define SANE_TRUE 1 typedef SANE_Word SANE_Bool;
SANE_Int is used for variables that can take integer values in the range -232 to 231-1. Its C declaration is given below.
Note that SANE_Int is simply an alias of SANE_Word. It is therefore always legal to use the latter type in place of the former. However, for clarity, it is recommended to use SANE_Int whenever a given variable or formal argument has a fixed interpretation as an integer object.typedef SANE_Word SANE_Int;
SANE_Fixed is used for variables that can take fixed point values in the range -32768 to 32767.9999 with a resolution of 1/65535. The C declarations relating to this type are given below.
The macro SANE_FIXED_SCALE_SHIFT gives the location of the fixed binary point. This standard defines that value to be 16, which yields a resolution of 1/65536.#define SANE_FIXED_SCALE_SHIFT 16 typedef SANE_Word SANE_Fixed;
SANE does not require that the following two expressions hold true (even if the values of w and d are in range):
In other words, conversion between fixed and double values may be lossy. It is therefore recommended to avoid repeated conversions between the two representations.SANE_UNFIX(SANE_FIX(d)) == d SANE_FIX(SANE_UNFIX(w)) == w
Type SANE_Char represents a single text character or symbol. At present, this type maps directly to the underlying C char type (typically one byte). The encoding for such characters is currently fixed as ISO LATIN-1. Future versions of this standard may map this type to a wider type and allow multi-byte encodings to support internationalization. As a result of this, care should be taken to avoid the assumption that sizeof(SANE_Char)==sizeof(char).
typedef char SANE_Char;
Type SANE_String represents a text string as a sequence of C char values. The end of the sequence is indicated by a '\0' (NUL) character.
The type SANE_String_Const is provided by SANE to enable declaring strings whose contents is unchangable. Note that in ANSI C, the declarationtypedef SANE_Char *SANE_String; typedef const SANE_Char *SANE_String_Const;
declares a string pointer that is constant (not a string pointer that points to a constant value).const SANE_String str;
Access to a scanner is provided through an opaque type called SANE_Handle. The C declaration of this type is given below.
While this type is declared to be a void pointer, an application must not attempt to interpret the value of a SANE_Handle. In particular, SANE does not require that a value of this type is a legal pointer value.typedef void *SANE_Handle;
Most SANE operations return a value of type SANE_Status to indicate whether the completion status of the operation. If an operation completes successfully, SANE_STATUS_GOOD is returned. In case of an error, a value is returned that indicates the nature of the problem. The complete list of available status codes is listed in Table 1. It is recommended to use function sane_strstatus() to convert status codes into a legible string.
Each SANE device is represented by a structure of type SANE_Device. The C declaration of this type is given below.
The structure provides the unique name of the scanner in member name. It is this unique name that should be passed in a call to sane_open(). The format of this name is completely up to the backend. The only constraints are that the name is unique among all devices supported by the backend and that the name is a legal SANE text string. To simplify presentation of unique names, their length should not be excessive. It is recommended that backends keep unique names below 32 characters in length. However, applications must be able to cope with arbitrary length unique names.typedef struct { SANE_String_Const name; SANE_String_Const vendor; SANE_String_Const model; SANE_String_Const type; } SANE_Device;
Vendor Strings | |
AGFA | Logitech |
Artec | Microtek |
Connectix | Minolta |
Epson | Mustek |
Hewlett-Packard | UMAX |
Kodak | Noname |
Type Strings |
flatbed scanner |
frame grabber |
handheld scanner |
still camera |
video camera |
virtual device |
Note that vendor string Noname can be used for virtual devices that have no physical vendor associated. Also, there are no predefined model name strings since those are vendor specific and therefore completely under control of the respective backends.
Option descriptors are at the same time the most intricate and powerful type in the SANE standard. Options are used to control virtually all aspects of device operation. Much of the power of the SANE API stems from the fact that most device controls are completely described by their respective option descriptor. Thus, a frontend can control a scanner abstractly, without requiring knowledge as to what the purpose of any given option is. Conversely, a scanner can describe its controls without requiring knowledge of how the frontend operates. The C declaration of the SANE_Option_Descriptor type is given below.
typedef struct { SANE_String_Const name; SANE_String_Const title; SANE_String_Const desc; SANE_Value_Type type; SANE_Unit unit; SANE_Int size; SANE_Int cap; SANE_Constraint_Type constraint_type; union { const SANE_String_Const *string_list; const SANE_Word *word_list; const SANE_Range *range; } constraint; } SANE_Option_Descriptor;
Member name is a string that uniquely identifies the option. The name must be unique for a given device (i.e., the option names across different backends or devices need not be unique). The option name must consist of lower-case ASCII letters (a--z), digits (0--9), or the dash character (-) only. The first character must be a lower-case ASCII character (i.e., not a digit or a dash).
Member title is a single-line string that can be used by the frontend as a title string. This should typically be a short (one or two-word) string that is chosen based on the function of the option.
Member desc is a (potentially very) long string that can be used as a help text to describe the option. It is the responsibility of the frontend to break the string into managable-length lines. Newline characters in this string should be interpreted as paragraph breaks.
Member type specifies the type of the option value. The possible values for type SANE_Value_Type are described in Table 3.
Symbol | Code | Description |
0 | Option value is of type SANE_Bool. | |
1 | Option value is of type SANE_Int. | |
2 | Option value is of type SANE_Fixed. | |
3 | Option value is of type SANE_String. | |
4 | An option of this type has no value. Instead, setting an option of this type has an option-specific side-effect. 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. | |
5 | 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. | |
|
Member unit specifies what the physical unit of the option value is. The possible values for type SANE_U-nit are described in Table 4. Note that the specified unit is what the SANE backend expects. It is entirely up to a frontend as to how these units a presented to the user. For example, SANE expresses all lengths in millimeters. A frontend is generally expected to provide appropriate conversion routines so that a user can express quantities in a customary unit (e.g., inches or centimeters).
Member size specifies the size of the option value (in bytes). This member has a slightly different interpretation depending on the type of the option value:
- SANE_TYPE_STRING:
- The size is the maximum size of the string. For the purpose of string size calcuations, the terminating NUL character is considered to be part of the string. Note that the terminating NUL character must always be present in string option values.
- SANE_TYPE_INT, SANE_TYPE_FIXED:
- The size must be a positive integer multiple of the size of a SANE_Word. The option value is a vector of length
[Eq.
size/sizeof(SANE_Word). ]
- SANE_TYPE_BOOL:
- The size must be set to sizeof(SANE_Word).
- SANE_TYPE_BUTTON, SANE_TYPE_GROUP:
- The option size is ignored.
Member cap describes what capabilities the option posseses. This is a bitset that is formed as the inclusive logical OR of the capabilities described in Table 5. The SANE API provides the following to macros to test certain features of a given capability bitset:
Symbol | Code | Description |
1 | The option value can be set by a call to sane_con-trol_opt-ion(). | |
2 | 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). | |
4 | The option value can be detected by software. If SANE_-CAP_-SO-FT_SEL-ECT 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_SO-FT_SEL-ECT nor SANE_CAP_HA-RD_SEL-ECT are, then there is no way to control the option. That is, the option provides read-out of the current value only. | |
8 | 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. | |
16 | 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. | |
32 | 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). | |
64 | 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). | |
|
It is often useful to constrain the values that an option can take. For example, constraints can be used by a frontend to determine how to represent a given option. Member constraint_type indicates what constraint is in effect for the option. The constrained values that are allowed for the option are described by one of the union members of member constraint. The possible values of type SANE_Constraint_Type and the interpretation of the constraint union is described in Table 6.
Symbol | Code | Description |
|
0 | The value is unconstrained. The option can take any of the values possible for the option's type. |
1 | This constraint is
applicable to integer and fixed-point valued options only. It
constrains the option value to a possibly quantized range of
numbers. Option descriptor member constraint.range points to
a range of the type SANE_Range. This type is illustrated
below:
All three members in this structure are interpreted according to the option value type (SANE_TYPE_INT or SANE_TYPE_FIXED). Members min and max specify the minimum and maximum values, respectively. If member quant is non-zero, it specifies the quantization value. If l is the minimum value, u the maximum value and q the (non-zero) quantization of a range, then the legal values are v=k*q+l for all non-negative integer values of k such that v<=u.typedef struct { SANE_Word min; SANE_Word max; SANE_Word quant; } SANE_Range; | |
2 | This constraint is applicable to integer and fixed-point valued options only. It constrains the option value to a list of numeric values. Option descriptor member constraint.word_list points to a list of words that enumerates the legal values. The first element in that list is an integer (SANE_Int) that specifies the length of the list (not counting the length itself). The remaining elements in the list are interpreted according to the type of the option value (SANE_TYPE_INT or SANE_TYPE_FIXED). | |
3 | This constraint is applicable to string-valued options only. It constrains the option value to a list of strings. The option descriptor member con-strai-nt.str-ing_list points to a NULL terminated list of strings that enumerate the legal values for the option value. | |