## 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;`

`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:

- the truth values `SANE_FALSE` and `SANE_TRUE`
- signed integers in the range -231...231-1
- fixed point values in the range -32768...32767.9999 with a resolution of 1/65536
- 32 bits (for bit sets)

Note that the SANE standard does not define what C type `SANE_Byte` and `SANE_Word` map to. For example, on some platforms, the latter may map to `long int` whereas on others it may map to `int`. A portable SANE frontend or backend must therefore not depend on a particular mapping.

### 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.<fontsize=-2>1 The C declarations for this type are given below.

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

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.

### 4.2.3 Integer Type

`SANE_Int` is used for variables that can take integer values in the range -232 to 231-1. Its C declaration is given below.

>     typedef SANE_Word SANE_Int;

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.

### 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;

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.

Note that `SANE_Fixed` 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_Fixed` whenever a given variable or formal argument has a fixed interpretation as a fixed-point object.

For convenience, SANE also defines two macros that convert fixed-point values to and from C double floating point values.

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

SANE does not require that the following two expressions hold true (even if the values of w and d are in range):

>     SANE_UNFIX(SANE_FIX(d)) == d
>     SANE_FIX(SANE_UNFIX(w)) == w

In other words, conversion between fixed and double values may be lossy. It is therefore recommended to avoid repeated conversions between the two representations.

### 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;

The type `SANE_String_Const` is provided by SANE to enable declaring strings whose contents is unchangable. Note that in ANSI C, the declaration

>     const SANE_String str;

declares a string pointer that is constant (not a string pointer that points to a constant value).

### 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;

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.

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

Symbol | Code | Description
`SANE_STATUS_GOOD` | 0 | Operation completed succesfully.
`SANE_STATUS_UNSUPPORTED` | 1 | Operation is not supported.
`SANE_STATUS_CANCELLED` | 2 | Operation was cancelled.
`SANE_STATUS_DEVICE_BUSY` | 3 | Device is busy---retry later.
`SANE_STATUS_INVAL` | 4 | Data or argument is invalid.
`SANE_STATUS_EOF` | 5 | No more data available (end-of-file).
`SANE_STATUS_JAMMED` | 6 | Document feeder jammed.
`SANE_STATUS_NO_DOCS` | 7 | Document feeder out of documents.
`SANE_STATUS_COVER_OPEN` | 8 | Scanner cover is open.
`SANE_STATUS_IO_ERROR` | 9 | Error during device I/O.
`SANE_STATUS_NO_MEM` | 10 | Out of memory.
`SANE_STATUS_ACCESS_DENIED` | 11 | Access to resource has been denied.

Table 1: Status Codes

### 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_String_Const email_backend_author;
>         SANE_String_Const backend_website;
>         SANE_String_Const device_location;
>         SANE_String_Const comment;
>         SANE_String_Const reserved_string;
>         SANE_Int backend_version_code;
>         SANE_Int backend_capablity_flags;
>         SANE_Int reserved_int;
>       }
>     SANE_Device;

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.

The next three members in the device structure provide additional information on the device corresponding to the unique name. Specifically, members `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
`AGFA` | `Microtek`
`Abaton` | `Minolta`
`Acer` | `Mustek`
`Apple` | `NEC`
`Artec` | `Nikon`
`Avision` | `Plustek`
`CANON` | `Polaroid`
`Connectix` | `Ricoh`
`Epson` | `Sharp`
`Fujitsu` | `Siemens`
`Hewlett-Packard` | `Tamarack`
`IBM` | `UMAX`
`Kodak` | `Noname`
`Logitech` |

Type Strings
`film scanner`
`flatbed scanner`
`frame grabber`
`handheld scanner`
`multi-function peripheral`
`sheetfed scanner`
`still camera`
`video camera`
`virtual device`

Table 2: Predefined Device Information Strings

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.

The backend has to set up the string `email_backend_author` with the name and the email address of the backend author or a contact person in the format:

    Firstname Lastname <name@domain.org>

The string `backend_website` has to be set up by the backend with the website or ftp address of the backend in the format:

    http://www.domain.org/sane-hello/index.html

The backend should fill the string `device_location` with a text that describes where a user can find this device, the text should be read from the backend config file. This could e.g. look like this:

    building 93, 2nd plane, room 2124

The string `comment` can be used to display any comment to the user, the text should be read from the backend config file.

The string `reserved_string` is planed for future use, the backend has to set this string to "".

With member `backend_version_code` a frontend can find out the version of a backend it is connected to via one or more meta backends.

The member `backend_capability_flags` contains 32 bits that are planned to give the backend the chance to inform the frontend about its capabilities. The meaning of the flags will be defined when there is the need for it. The backend has to set all not defined bits (in the moment all 32 bits) to 0.

The member `reserved_int` is planned for future use, the backend has to set the value of the integer to 0.

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

Symbol | Code | Description
`SANE_TYPE_BOOL` | 0 | Option value is of type `SANE_Bool`.
`SANE_TYPE_INT` | 1 | Option value is of type `SANE_Int`.
`SANE_TYPE_FIXED` | 2 | Option value is of type `SANE_Fixed`.
`SANE_TYPE_STRING` | 3 | Option value is of type `SANE_String`.
`SANE_TYPE_BUTTON` | 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.
`SANE_TYPE_GROUP` | 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.

Table 3: Option Value Types (`SANE_Value_Type`)

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

Symbol | Code | Description
`SANE_UNIT_NONE` | 0 | Value is unit-less (e.g., page count).
`SANE_UNIT_PIXEL` | 1 | Value is in number of pixels.
`SANE_UNIT_BIT` | 2 | Value is in number of bits.
`SANE_UNIT_MM` | 3 | Value is in millimeters.
`SANE_UNIT_DPI` | 4 | Value is a resolution in dots/inch.
`SANE_UNIT_PERCENT` | 5 | Value is a percentage.
`SANE_UNIT_MICROSECOND` | 6 | Value is time in µ-seconds.

Table 4: Physical Units (`SANE_Unit`)

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

Symbol | Code | Description
`SANE_CAP_SOFT_SELECT` | 1 | The option value can be set by a call to `sane_control_option()`.
`SANE_CAP_HARD_SELECT` | 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).

`SANE_CAP_SOFT_DETECT`

4

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.

`SANE_CAP_EMULATED` | 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.
`SANE_CAP_AUTOMATIC` | 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`.
`SANE_CAP_INACTIVE` | 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).
`SANE_CAP_ADVANCED` | 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).

Table 5: Option Capabilities

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

Symbol | Code | Description
`SANE_CONSTRAINT_NONE` | 0 | The value is unconstrained. The option can take any of the values possible for the option's type.

`SANE_CONSTRAINT_RANGE`

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:

>     typedef struct
>       {
>         SANE_Word min;
>         SANE_Word max;
>         SANE_Word quant;
>       }
>     SANE_Range;

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.

`SANE_CONSTRAINT_WORD_LIST`

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

`SANE_CONSTRAINT_STRING_LIST` | 3 | This constraint is applicable to string-valued options only. It constrains the option value to a list of strings. The option descriptor member `constraint.string_list` points to a `NULL` terminated list of strings that enumerate the legal values for the option value.

Table 6: Option Value Constraints

### 4.2.10 Internationalization

All backend texts should be written in english. Localization (translation of backend texts) has to be done in the frontend. To automatically prepare translation tables (e.g. english to german) it is necessary to mark the texts that shall be translated.

#### 4.2.10.1 How is a text marked for translation

The keyword `SANE_I18N` is used to mark a text for translation. `SANE_I18N` has to be defined as a dummy prototype:

>     #ifndef SANE_I18N
>     #  define SANE_I18N(text) text
>     #endif

You should not mark prototypes or variables with `SANE_I18N` because it is not possible (or very hard) to find out the texts that are covered by prototypes (`SANE_I18N(START_SCAN_TEXT)`) and variables (`SANE_I18N(option[7].name)`).

A correct marked text can look like this:
`snprintf(buf, sizeof(buf), SANE_I18N("Start scan")`
or
`#define START_SCAN_TEXT SANE_I18N("Start scan")`.
It also is allowed to mark texts in structs because the prototype `SANE_I18N` has no effect to the compiler.

#### 4.2.10.2 Which texts shall be marked for translation?

All option texts that are visible for the user should be marked for translation. This is:

- member `title`
- member `desc`
- member `string_list`

of `SANE_Option_Descriptor`.

It is not allowed to mark/translate member `name`. Please also do not mark any error or debug messages that are displayed by the backend.

#### 4.2.10.3 File formats and translation functions

The recommended file formats for translation tables are the `po` files and `mo` or `gmo` files. The po file contains the original text marked with the keyword `msgid` and the translated text marked with the keyword `msgstr`. A `po` file that contains all needed `msgid`s can be created e.g. by the gnu gettext tool `xgettext` with the option `-k SANE_I18N`. The translator adds the translated texts to the `po` files. The gettext tool `msgfmt` converts the `po` files to the `mo` or `gmo` files.

Translation is done in the frontend. A backend has nothing to do with the translation of texts. The frontend should use the function `gettext` to translate the texts. This e.g. can look like this:
`snprintf(buf, sizeof(buf), gettext("english text"));`

If a frontend author decides to use translation functions that need different translation tables, then the frontend is responsible to create/convert the translation tables. In this case it should use the `po` files to create its own translation tables from it.

Note that it is strongly recommended to use the gettext tools.