4.2 Data Types

4.2.1 Base Types

The SANE standard is based on just two SANE-specific base types: the SANE byte and word.

typedef some-scalar-type SANE_Byte;
typedef some-scalar-type SANE_Word;

4.2.2 Boolean Type

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.¹ The C declarations for this type are given below.

#define SANE_FALSE      0
#define SANE_TRUE       1
typedef SANE_Word SANE_Bool;

4.2.3 Integer Type

SANE_Int is used for variables that can take integer values in the range -2³² to 2³¹-1. Its C declaration is given below.

typedef SANE_Word SANE_Int;

4.2.4 Fixed-point Type

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.

#define SANE_FIXED_SCALE_SHIFT  16
typedef SANE_Word SANE_Fixed;

SANE_FIX(d):

Returns the largest SANE fixed-point value that is smaller than the double value d. No range checking is performed. If the value of d is out of range, the result is undefined.

SANE_UNFIX(w):

Returns the nearest double machine number that corresponds to fixed-point value w.

4.2.5 Text

4.2.5.1 Character Type

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;

4.2.5.2 String Type

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.

typedef SANE_Char *SANE_String;
typedef const SANE_Char *SANE_String_Const;

4.2.6 Scanner Handle Type

Access to a scanner is provided through an opaque type called SANE_Handle. The C declaration of this type is given below.

typedef void *SANE_Handle;

4.2.7 Status Type

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.

4.2.8 Device Descriptor Type

Each SANE device is represented by a structure of type SANE_Device. The C declaration of this type is given below.

typedef struct
  {
    SANE_String_Const name;
    SANE_String_Const vendor;
    SANE_String_Const model;
    SANE_String_Const type;
  }
SANE_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.

4.2.9 Option Descriptor Type

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;

4.2.9.1 Option Name

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).

4.2.9.2 Option Title

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.

4.2.9.3 Option Description

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.

4.2.9.4 Option Value Type

Member type specifies the type of the option value. The possible values for type SANE_Value_Type are described in Table 3.

4.2.9.5 Option Value Unit

Member unit specifies what the physical unit of the option value is. The possible values for type SANE_Unit 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).

4.2.9.6 Option Value Size

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

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.

4.2.9.7 Option Capabilities

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:

SANE_OPTION_IS_ACTIVE(cap):

This macro returns SANE_TRUE if and only if the option with the capability set cap is currently active.

SANE_OPTION_IS_SETTABLE(cap):

This macro returns SANE_TRUE if and only if the option with the capability set cap is software settable.

4.2.9.8 Option Value Constraints

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.