Warning: This document is for the development version of SANE Standard. The latest version is 1.06.

4 The SANE Application Programmer Interface (API)

Attention

This Section defines version 2 of the SANE application programmer interface (API). Any SANE frontend must depend on the interface defined in this section only. Conversely, any SANE backend must implement its functionality in accordance with this specification. The interface as documented here is declared as a C callable interface in a file called sane/sane-2.h. This file should normally be included via a C preprocessor directive of the form:

#include <sane/sane-2.h>

4.1 Version Control

The SANE standard is expected to evolve over time. Whenever a change to the SANE standard is made that may render an existing frontend or backend incompatible with the new standard, the major version number must be increased. Thus, any frontend/backend pair is compatible provided the major version number of the SANE standard they implement is the same. A frontend may implement backwards compatibility by allowing major numbers that are smaller than the expected major number (provided the frontend really can cope with the older version). In contrast, a backend always provides support for one and only one version of the standard. If a specific application does require that two different versions of the same backend are accessible at the same time, it is possible to do so by installing the two versions under different names.

SANE version control also includes a minor version number and a build revision. While control of these numbers remains with the implementer of a backend, the recommended use is as follows. The minor version is incremented with each official release of a backend. The build revision is increased with each build of a backend.

The SANE API provides the following five macros to manage version numbers.

SANE_CURRENT_MAJOR

The value of this macro is the number of the SANE standard that the interface implements.

SANE_VERSION_CODE(maj, min, bld)

This macro can be used to build a monotonically increasing version code. A SANE version code consists of the SANE standard major version number (maj), the minor version number min, and the build revision of a backend (bld). The major and minor version numbers must be in the range 0…255 and the build revision must be in the range 0…65535.

Version codes are monotonic in the sense that it is possible to apply relational operators (e.g., equality or less-than test) directly on the version code rather than individually on the three components of the version code.

Note that the major version number alone determines whether a frontend/backend pair is compatible. The minor version and the build revision are used for informational and bug-fixing purposes only.

SANE_VERSION_MAJOR(vc)

This macro returns the major version number component of the version code passed in argument vc.

SANE_VERSION_MINOR(vc)

This macro returns the minor version number component of the version code passed in argument vc.

SANE_VERSION_BUILD(vc)

This macro returns the build revision component of the version code passed in argument vc.

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 \(-2^{31}\ldots2^{31}-1\)

  • fixed point values in the range \(-32768\ldots32767.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. 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 \(-2^{32}\) to \(2^{31}-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 \(\verb|sizeof|(\verb|SANE_Char|) == \verb|sizeof|(\verb|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 unchangeable. 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 4.1. It is recommended to use function sane_strstatus() to convert status codes into a legible string.

Table 4.1 Status Codes

Symbol

Code

Description

SANE_STATUS_GOOD

0

Operation completed successfully.

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.

4.2.8 Device Descriptor Type

Attention

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

Table 4.2 Predefined Device Information Strings

Vendor Strings

AGFA

Microtek

Abaton

Minolta

Acer

Mitsubishi

Apple

Mustek

Artec

NEC

Avision

Nikon

CANON

Plustek

Connectix

Polaroid

Epson

Relisys

Fujitsu

Ricoh

Hewlett-Packard

Sharp

IBM

Siemens

Kodak

Tamarack

Lexmark

UMAX

Logitech

Noname

Type Strings

film scanner

flatbed scanner

frame grabber

handheld scanner

multi-function peripheral

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

Attention

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 should 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 configurable by the administrator. This could e.g. look like this:

building 93, 2nd plane, room 2124

The string comment can be used to display any comment about the device to the user. The text should be configurable by the administrator.

The string reserved_string is unused currently but planned for future use.

All unused strings must be set to "" by the backend.

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 (az), digits (09), 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 manageable-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 4.3.

Table 4.3 Option Value Types (SANE_Value_Type)

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.

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

Table 4.4 Physical Units (SANE_Unit)

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 \(\mu\)-seconds.

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 calculations, 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 \(\verb|size| / \verb|sizeof|(\verb|SANE_Word|)\).

SANE_TYPE_BOOL: The size must be set to \(\verb|sizeof|(\verb|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 possesses. This is a bitset that is formed as the inclusive logical OR of the capabilities described in Table 4.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.

Table 4.5 Option Capabilities

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

Attention

If this capability is set for an option of type SANE_TYPE_GROUP, all options belonging to the group are also advanced, even if they don’t set the capability themselves.

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 separate “advanced settings” dialog).

SANE_CAP_HIDDEN

128

Attention

If set, this capability indicates that the option shouldn’t be displayed to and used by the user directly. Instead a hidden option is supposed to be automatically used by the frontend, like e.g. the preview option. If this capability is set for an option of type SANE_TYPE_GROUP, all options belonging to the group are also hidden, even if they don’t set the capability themselves. A frontend typically doesn’t display such options by default but there should be a way to override this default behavior.

SANE_CAP_ALWAYS_SETTABLE

256

Attention

If set, this capability indicates that the option may be at any time between sane_open() and sane_close(). I.e. it’s allowed to set it even while an image is acquired.

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

Table 4.6 Option Value Constraints

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\cdot 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.

4.2.10 Internationalization

Attention

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

Attention

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 (\(\verb|SANE_I18N|(\verb|START_SCAN_TEXT|)\)) and variables (\(\verb|SANE_I18N|(\verb|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 structures because the prototype SANE_I18N has no effect to the compiler.

4.2.10.2 Which texts shall be marked for translation?

Attention

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

Attention

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.

4.3 Operations

4.3.1 sane_init()

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 or if the status code returned by sane_init() is different from SANE_STATUS_GOOD. The version code of the backend is returned in the value pointed to by version_code. If that pointer is NULL, no version code is returned. Argument authorize is either a pointer to a function that is invoked when the backend requires authentication for a specific resource or NULL if the frontend does not support authentication.

SANE_Status sane_init (SANE_Int * version_code,
                       SANE_Authorization_Callback authorize);

The authorization function may be called by a backend in response to any of the following calls:

  • sane_open(),

  • sane_control_option(),

  • sane_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 appropriate password based on resource- and user-name.

The authentication function type has the following declaration:

#define SANE_MAX_USERNAME_LEN   128
#define SANE_MAX_PASSWORD_LEN   128

typedef void (*SANE_Authorization_Callback)
    (SANE_String_Const resource,
     SANE_Char username[SANE_MAX_USERNAME_LEN],
     SANE_Char password[SANE_MAX_PASSWORD_LEN]);

Three arguments are passed to the authorization function: resource is a string specifying the name of the resource that requires authorization. A frontend should use this string to build a user-prompt requesting a username and a password. The username and password arguments are (pointers to) an array of SANE_MAX_USERNAME_LEN and SANE_MAX_PASSWORD_LEN characters, respectively. The authorization call should place the entered username and password in these arrays. The returned strings must be ASCII-NUL terminated.

4.3.2 sane_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 sane_close(), but backends are required to release all resources upon a call to this function). After this function returns, no function other than sane_init() may be called (regardless of the status value returned by sane_exit(). Neglecting to call this function may result in some resources not being released properly.

void sane_exit (void);

4.3.3 sane_get_devices()

This function can be used to query the list of devices that are available. If the function executes successfully, it stores a pointer to a NULL terminated array of pointers to SANE_Device structures in *device_list. The returned list is guaranteed to remain unchanged and valid until (a) another call to this function is performed or (b) a call to sane_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.

SANE_Status sane_get_devices (const SANE_Device *** device_list,
                              SANE_Bool local_only);

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

Backend Implementation Note

SANE does not require that this function is called before a sane_open() call is performed. A device name may be specified explicitly by a user which would make it unnecessary and undesirable to call this function first.

Attention

The same information about a device has to be returned when sane_open() is called.

4.3.4 sane_open()

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 handle for the device is returned in *h.

Attention

The description of the device is returned in **device_description. This is the same description that is returned in the list by sane_get_devices(). The returned data *h and *device_description is guaranteed to remain unchanged and valid until a call to sane_close() is performed.

As a special case, specifying a zero-length string as the device requests opening the first available device (if there is such a device).

SANE_Status sane_open (SANE_String_Const name, SANE_Handle * h,
                       const SANE_Device ** device_description);

This function may fail with one of the following status codes.

SANE_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 occurred while communicating with the device.

SANE_STATUS_NO_MEM: An insufficient amount of memory is available.

SANE_STATUS_ACCESS_DENIED: Access to the device has been denied due to insufficient or invalid authentication.

4.3.5 sane_close()

This function terminates the association between the device handle passed in argument h and the device it represents. If the device is presently active, a call to sane_cancel() is performed first. After this function returns, handle h must not be used anymore.

void sane_close (SANE_Handle h);

4.3.6 sane_get_option_descriptor()

This function is used to access option descriptors. The function returns the option descriptor for option number n of the device represented by handle h. Option number 0 is guaranteed to be a valid option. Its value is an integer that specifies the number of options that are available for device handle h (the count includes option 0). If \(n\) is not a valid option index, the function returns NULL. The returned option descriptor is guaranteed to remain valid (and at the returned address) until the device is closed.

const SANE_Option_Descriptor *
    sane_get_option_descriptor (SANE_Handle h, SANE_Int n);

4.3.7 sane_control_option()

This function is used to set or inquire the current value of option number n of the device represented by handle h. The manner in which the option is controlled is specified by parameter a. The possible values of this parameter are described in more detail below. The value of the option is passed through argument v. It is a pointer to the memory that holds the option value. The memory area pointed to by v must be big enough to hold the entire option value (determined by member size in the corresponding option descriptor). The only exception to this rule is that when setting the value of a string option, the string pointed to by argument v may be shorter since the backend will stop reading the option value upon encountering the first NUL terminator in the string. If argument i is not NULL, the value of *i will be set to provide details on how well the request has been met. The meaning of this argument is described in more detail below.

SANE_Status sane_control_option (SANE_Handle h, SANE_Int n,
                                 SANE_Action a, void *v,
                                 SANE_Int * i);

The way the option is affected by a call to this function is controlled by parameter a which is a value of type SANE_Action. The possible values and their meaning is described in Table 4.7.

Table 4.7 Action Values (SANE_Action)

Symbol

Code

Description

SANE_ACTION_GET_VALUE

0

Get current option value.

SANE_ACTION_SET_VALUE

1

Set option value. The option value passed through argument v may be modified by the backend if the value cannot be set exactly.

SANE_ACTION_SET_AUTO

2

Turn on automatic mode. Backend or device will automatically select an appropriate value. This mode remains effective until overridden by an explicit set value request. The value of parameter v is completely ignored in this case and may be NULL.

After setting a value via an action value of SANE_ACTION_SET_VALUE, additional information on how well the request has been met is returned in *i (if i is non-NULL). The returned value is a bitset that may contain any combination of the values described in Table 4.8.

Table 4.8 Additional Information Returned When Setting an Option

Symbol

Code

Description

SANE_INFO_INEXACT

1

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.

SANE_INFO_RELOAD_OPTIONS

2

Attention

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

SANE_INFO_RELOAD_PARAMS

4

The setting of an option may affect the parameter values (see sane_get_parameters()). If setting an option affects the parameter values, this member will be set in *i. 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.

SANE_INFO_INVALIDATE_PREVIEW

8

Attention

The setting of an option may affect the validity of the preview that was acquired by the frontend earlier. When the preview image would change significantly if it was scanned again, the SANE backend sets this member in *i to indicate that the application should inform the user of the invalidity of the preview. Examples for such option settings may include setting a different scan source or significantly changing the exposure.

This function may fail with one of the following status codes.

SANE_STATUS_UNSUPPORTED: The operation is not supported for the specified handle and option number.

SANE_STATUS_INVAL: The option value is not valid.

SANE_STATUS_IO_ERROR: An error occurred while communicating with the device.

SANE_STATUS_NO_MEM: An insufficient amount of memory is available.

SANE_STATUS_ACCESS_DENIED: Access to the option has been denied due to insufficient or invalid authentication.

4.3.8 sane_get_parameters()

This function is used to obtain the current scan parameters. The returned parameters are guaranteed to be accurate between the time a scan has been started (sane_start() has been called) and the completion of that request. Outside of that window, the returned values are best-effort estimates of what the parameters will be when sane_start() gets invoked. Calling this function before a scan has actually started allows, for example, to get an estimate of how big the scanned image will be. The parameters passed to this function are the handle h of the device for which the parameters should be obtained and a pointer p to a parameter structure. The parameter structure is described in more detail below.

SANE_Status sane_get_parameters (SANE_Handle h,
                                 SANE_Parameters * p);

The scan parameters are returned in a structure of type SANE_Parameters. The C declaration of this structure is given below.

Attention

typedef struct
  {
    SANE_Frame format;
    SANE_int flags;
    SANE_Int lines;
    SANE_Int depth;
    SANE_Int pixels_per_line;
    SANE_Int bytes_per_line;
    SANE_Int channels_per_image;
    SANE_String format_desc;
    SANE_String proposed_filename;
    SANE_string proposed_comment;
    SANE_Int dpi_x;
    SANE_Int dpi_y;
    char reserved[32]; /* 32 bytes for future use */
  }
SANE_Parameters;

Member format specifies the format of the next frame to be returned. The possible values for type SANE_Frame are described in Table 4.9. The meaning of these values is described in more detail in section 3.2. The frame types used by version 1 of this standard (SANE_FRAME_GRAY, SANE_FRAME_RGB, SANE_FRAME_RED, SANE_FRAME_GREEN, and SANE_FRAME_BLUE) are obsolete and superseded by the frame type SANE_FRAME_RAW.

Table 4.9 Frame Format (SANE_Frame)

Symbol

Code

Description

SANE_FRAME_RAW

5

Arbitrary pixel property transmission.

SANE_FRAME_MIME

6

Data described by a mime descriptor.

The flags member is a 32-bit bit field, for which up to now 4 informational bits are defined, all unused bits have to be set to 0:

  • SANE_PFLAG_LAST_FRAME

    (bit 0, bitvalue 1) is set to 1 if and only if the frame that is currently being acquired (or the frame that will be acquired next if there is no current frame) is the only frame or the last frame of a multi frame image (e.g., the current frame is the blue component of a red, green, blue image).

  • SANE_PFLAG_MORE_IMAGES

    (bit 1, bitvalue 2) is set to 1 to indicate further pending images. The frontend is expected to call sane_start() again after the end of the current scan to get more images, e.g. from an automatic document feeder. It is permissible to set that value to 1 “in good faith”, as it has to be determined at a very early time, where it might not be detectable, if there actually are more images to transfer. E.g. you will usually not know if the document feeder contains further pages when starting to scan the current one. Thus you are allowed to set that bit but later fail at sane_start().

  • SANE_PFLAG_NEW_PAGE

    (bit 2, bitvalue 4) is set to 1 to indicate that the current frame comes from a new physical page. This bit is of informational character only to help frontends to group multi-image scans.

  • SANE_PFLAG_BACKSIDE

    (bit 3, bitvalue 8) tells if the current image was acquired from the front (0) or backside (1) of the currently processed sheet. It is of informational character and allows to group and order multi-image transfers regardless of scanner acquisition order (front first/back first).

Note, that flags is compatible to member last_frame of SANE_Parameters of SANE standard version 1 (same size and only bit 0 (bitvalue 1) was used with same function).

Member lines specifies how many scan lines the frame is comprised of. If this value is -1, the number of lines is not known a priori and the frontend should call sane_read() until it returns a status of SANE_STATUS_EOF.

Attention

Note, that even when transferring formats that have this information in-band, it is recommended to set that member, if available. If unavailable or not applicable, set to -1 as mentioned above.

Member bytes_per_line specifies the number of bytes that comprise one scan line.

Attention

If this value is not applicable for image data of type SANE_FRAME_MIME, it must be set to -1. In this case the frontend should just call sane_read() until SANE_STATUS_EOF is returned.

Member depth specifies the number of bits per sample.

Attention

Note, that only -1 (for not applicable), 1, and multiples of 8 are allowed values. Data with other depths has to be scaled up accordingly. Depth 1 is only allowed if the image consists of a single channel (Lineart or Halftone modes).

Member pixels_per_line specifies the number of pixels that comprise one scan line.

Attention

If unavailable or not applicable, set to -1.

Assume \(B\) is the number of channels in the frame, then the bit depth \(d\) (as given by member depth) and the number of pixels per line \(n\) (as given by this member pixels_per_line) are related to \(c\), the number of bytes per line (as given by member bytes_per_line) as follows:

Attention

\[\begin{split}c >= \left\{ \begin{array}{ll} B\cdot \lfloor (n + 7) / 8\rfloor & \mbox{if $d=1$}\\ B\cdot n \cdot d / 8 & \mbox{if $d>1$} \end{array} \right.\end{split}\]

Note that the number of bytes per line can be larger than the minimum value imposed by the right side of this equation. A frontend must be able to properly cope with such “padded” image formats.

Attention

Member channels_per_image specifies the number of channels the image consists of. When the image is transmitted in more than one frame channels_per_image has to be the same for all frames for this image.

Member format_desc is used to describe the details of the frame formats. Its meaning differs between the two types:

  • SANE_FRAME_RAW

    The format_desc contains a description of the channel data and an optional depth information separated by a colon(:).

    A plane is described by one channel, e.g. “gray” or “gray:12”.

    Channel interleaved data is described by a comma separated list of channel descriptions, for example “red,green,blue” or “red:8,green:8,blue:8”, the channel data is sent in the given order.

    The depth information does not define the size of the transmitted channel data, it is only an information for the frontend. The channel data has to be sent in the size defined by member depth.

    Well known channels are red, green, blue and gray. It also is allowed to use other channel descriptions, e.g. if you use an infrared camera or scanner it could be infrared or a wavelength description like 1100nm, but be aware that a frontend may not be able to display such channels with useful colors.

    Note that an image can be sent in single planes, in one interleaved frame that contains all channels or in several frames that contain one or more (interleaved) channels. When an RGB image is sent it is preferred to send the image data in one interleaved frame that consist of red, green and blue data in this order. The number of channels is defined in member channels_per_image.

  • SANE_FRAME_MIME

    format_desc contains the MIME Content-Type: header field as described in RFC 1521 (section 4) without the prefixing “Content-Type:”. MIME Types and subtypes should be either chosen from the RFC or from the list of IANA-approved values. The data stream must be compliant with the corresponding specification.

    When data is transmitted with the frame type SANE_FRAME_MIME all data has to be transmitted within one frame, multiple frames are not allowed (so the flag last_frame has to be set when using this frame type).

    A SANE backend must be able to at least optionally transmit SANE_FRAME_RAW (possibly with the help of a meta backend), if the hardware supports delivering image data at all. For data that doesn’t comprise images, it’s admissible to only provide MIME frames. As a general principle, if there are several choices in MIME types, the format that is most widely implemented should be used.

The member proposed_filename can be used to suggest a reasonable default filename or -extension in case the backend can make such a suggestion, like e.g. an image database. If no such suggestion is intended, set the field to "".

In the case of raw frames, proposed_filename is expected to hold the basename for the image, with the extension determined by the save function of the frontend, as the frontend can fully understand the data and is thus able to encode it in any format it wishes.

For MIME frames proposed_filename can contain either:

  • A name with a leading dot, which is considered to be a proposed filename extension. This could also be gotten from the mime database, but for systems lacking it, this might be convenient. Or:

  • A complete filename, including extension.

Note, that for frontends that are able to parse a given MIME type internally, it is perfectly permissible to ignore the extension part of the proposed filename and only make use of the basename, when using internal save algorithms for different formats.

The string proposed_comment can be used to transmit additional image information, that can be stored in the comment areas several file formats offer. It can contain any textual information the backend wishes to convey to the user, like date/time of exposure, engaged filters, etc. Set to "" if unused.

The members dpi_x and dpi_y encode the horizontal and vertical resolution. Note, that multiple-image scans may have different resolutions of each image. It is not permissible to change resolution between frames of the same image. If not applicable, set to -1.

The member reserved is an array of 32 bytes (char) to keep the size of the struct unchanged when future extensions are done. The backend has to set the reserved bytes to 0.

4.3.9 sane_start()

This function initiates acquisition of an image from the device represented by handle h.

SANE_Status sane_start (SANE_Handle h);

This function may fail with one of the following status codes.

SANE_STATUS_CANCELLED: The operation was cancelled through a call to sane_cancel().

SANE_STATUS_DEVICE_BUSY: The device is busy. The operation should be retried later.

SANE_STATUS_JAMMED: The document feeder is jammed.

SANE_STATUS_NO_DOCS: The document feeder is out of documents.

SANE_STATUS_COVER_OPEN: The scanner cover is open.

SANE_STATUS_IO_ERROR: An error occurred while communicating with the device.

SANE_STATUS_NO_MEM: An insufficient amount of memory is available.

SANE_STATUS_INVAL: The scan cannot be started with the current set of options. The frontend should reload the option descriptors, as if SANE_INFO_RELOAD_OPTIONS had been returned from a call to sane_control_option(), since the device’s capabilities may have changed.

4.3.10 sane_read()

This function is used to read image data from the device represented by handle h. Argument buf is a pointer to a memory area that is at least maxlen bytes long. The number of bytes returned is stored in *len. A backend must set this to zero when a status other than SANE_STATUS_GOOD is returned). When the call succeeds, the number of bytes returned can be anywhere in the range from 0 to maxlen bytes.

SANE_Status sane_read (SANE_Handle h, SANE_Byte * buf,
                       SANE_Int maxlen, SANE_Int * len);

Attention

For efficiency reasons, medium to large block sizes (in the range of a few kilobytes) should be used. Returning short reads is allowed to allow for small buffers in the backend.

If this function is called when no data is available, one of two things may happen, depending on the I/O mode that is in effect for handle h.

  1. If the device is in blocking I/O mode (the default mode), the call blocks until at least one data byte is available (or until some error occurs).

  2. If the device is in non-blocking I/O mode, the call returns immediately with status SANE_STATUS_GOOD and with *len set to zero.

The I/O mode of handle h can be set via a call to sane_set_io_mode().

This function may fail with one of the following status codes.

SANE_STATUS_CANCELLED: The operation was cancelled through a call to sane_cancel().

SANE_STATUS_EOF: No more data is available for the current frame.

Attention

If sane_read() sends back any image data it is not allowed to return with SANE_STATUS_EOF.

SANE_STATUS_JAMMED: The document feeder is jammed.

SANE_STATUS_NO_DOCS: The document feeder is out of documents.

SANE_STATUS_COVER_OPEN: The scanner cover is open.

SANE_STATUS_IO_ERROR: An error occurred while communicating with the device.

SANE_STATUS_NO_MEM: An insufficient amount of memory is available.

SANE_STATUS_ACCESS_DENIED: Access to the device has been denied due to insufficient or invalid authentication.

4.3.11 sane_cancel()

This function is used to immediately or as quickly as possible cancel the currently pending operation of the device represented by handle h.

void sane_cancel (SANE_Handle h);

This function can be called at any time (as long as handle h is a valid handle) but usually affects long-running operations only (such as image is acquisition). It is safe to call this function asynchronously (e.g., from within a signal handler). It is important to note that completion of this operation does not imply that the currently pending operation has been cancelled. It only guarantees that cancellation has been initiated. Cancellation completes only when the cancelled call returns (typically with a status value of SANE_STATUS_CANCELLED). Since the SANE API does not require any other operations to be re-entrant, this implies that a frontend must not call any other operation until the cancelled operation has returned.

4.3.12 sane_set_io_mode()

This function is used to set the I/O mode of handle h. The I/O mode can be either blocking or non-blocking. If argument m is SANE_TRUE, the mode is set to non-blocking mode, otherwise it’s set to blocking mode. This function can be called only after a call to sane_start() has been performed.

SANE_Status sane_set_io_mode (SANE_Handle h, SANE_Bool m);

By default, newly opened handles operate in blocking mode. A backend may elect not to support non-blocking I/O mode. In such a case the status value SANE_STATUS_UNSUPPORTED is returned. Blocking I/O must be supported by all backends, so calling this function with argument m set to SANE_FALSE is guaranteed to complete successfully.

This function may fail with one of the following status codes:

SANE_STATUS_INVAL: No image acquisition is pending.

SANE_STATUS_UNSUPPORTED: The backend does not support the requested I/O mode.

4.3.13 sane_get_select_fd()

This function is used to obtain a (platform-specific) file-descriptor for handle h that is readable if and only if image data is available (i.e., when a call to sane_read() will return at least one byte of data). If the call completes successfully, the select file-descriptor is returned in *fd.

SANE_Status sane_get_select_fd (SANE_Handle h, SANE_Int *fd);

This function can be called only after a call to sane_start() has been performed and the returned file-descriptor is guaranteed to remain valid for the duration of the current image acquisition (i.e., until sane_cancel() or sane_start() get called again or until sane_read() returns with status SANE_STATUS_EOF). Indeed, a backend must guarantee to close the returned select file descriptor at the point when the next sane_read() call would return SANE_STATUS_EOF. This is necessary to ensure the application can detect when this condition occurs without actually having to call sane_read().

A backend may elect not to support this operation. In such a case, the function returns with status code SANE_STATUS_UNSUPPORTED.

Note that the only operation supported by the returned file-descriptor is a host operating-system dependent test whether the file-descriptor is readable (e.g., this test can be implemented using select() or poll() under UNIX). If any other operation is performed on the file descriptor, the behavior of the backend becomes unpredictable. Once the file-descriptor signals “readable” status, it will remain in that state until a call to sane_read() is performed. Since many input devices are very slow, support for this operation is strongly encouraged as it permits an application to do other work while image acquisition is in progress.

This function may fail with one of the following status codes:

SANE_STATUS_INVAL: No image acquisition is pending.

SANE_STATUS_UNSUPPORTED: The backend does not support this operation.

4.3.14 sane_strstatus()

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). The function is guaranteed to never return NULL. The returned pointer is valid at least until the next call to this function is performed.

SANE_String_Const sane_strstatus (SANE_Status status);

4.4 Code Flow

The code flow for the SANE API is illustrated in Figure 4.1. Functions sane_init() and sane_exit() initialize and exit the backend, respectively. All other calls must be performed after initialization and before exiting the backend.

_images/flow.svg

Figure 4.1 Code flow

Function sane_get_devices() can be called any time after sane_init() has been called. It returns the list of the devices that are known at the time of the call. This list may change over time since some devices may be turned on or off or a remote host may boot or shutdown between different calls. It should be noted that this operation may be relatively slow since it requires contacting all configured devices (some of which may be on remote hosts). A frontend may therefore want to provide the ability for a user to directly select a desired device without requiring a call to this function.

Once a device has been chosen, it is opened using a call to sane_open(). Multiple devices can be open at any given time. A SANE backend must not impose artificial constraints on how many devices can be open at any given time.

An opened device can be setup through the corresponding device handle using functions sane_get_option_descriptor() and sane_control_option(). While setting up a device, obtaining option descriptors and setting and reading of option values can be mixed freely. It is typical for a frontend to read out all available options at the beginning and then build a dialog (either graphical or a command-line oriented option list) that allows to control the available options. It should be noted that the number of options is fixed for a given handle.

Attention

However, as options are set, other options may become active or inactive or their constraint may change. Thus, after setting an option, it may be necessary to re-read the descriptors.

While setting up the device, it is also admissible to call sane_get_parameters() to get an estimate of what the image parameters will look like once image acquisition begins.

The device handle can be put in blocking or non-blocking mode by a call to sane_set_io_mode(). Devices are required to support blocking mode (which is the default mode), but support for non-blocking I/O is strongly encouraged for operating systems such as UNIX.

After the device is setup properly, image acquisition can be started by a call to sane_start(). The backend calculates the exact image parameters at this point. So future calls to sane_get_parameters() will return the exact values, rather than estimates. Whether the physical image acquisition starts at this point or during the first call to sane_read() is unspecified by the SANE API. If non-blocking I/O and/or a select-style interface is desired, the frontend may attempt to call sane_set_io_mode() and/or sane_get_select_fd() at this point. Either of these functions may fail if the backend does not support the requested operation.

Attention

Image data is collected by repeatedly calling sane_read() until this function will return an end-of-file status (SANE_STATUS_EOF). This indicates the end of the current frame. If the frontend expects additional frames (e.g., the individual channels of a red/green/blue image or multiple images), it can call sane_start() again. If the SANE_PFLAG_LAST_FRAME bit is set in flags, the current image is complete. In this case, it should be tested, if flags has the SANE_PFLAG_MORE_IMAGES bit set. If yes, further calls to sane_start() can be made to acquire more images. Please note, that as this bit has to be set at the beginning of a the transmission of the last frame before the new image, it is possible, that no reliable decision can be made at this time. It is thus permissible for a backend to set this bit, and then later at the actual call to sane_start() return an error like SANE_STATUS_NO_DOCS. Such a sequence is permitted to transmit multiple images from a single page as well as multiple pages. This behavior should be controlled by backend options as required, to allow single-page scanning as well as ADF batch scanning. The frontend should always continue reading all images until a frame with SANE_PFLAG_LAST_FRAME on and SANE_PFLAG_MORE_IMAGES off is encountered, or an error other than SANE_STATUS_EOF occurs in a SANE function. Note that SANE_STATUS_NO_DOCS also is an allowed way for the backend to indicate the end of a multiple image scan.

A frontend may choose to skip frames (e.g. because it cannot parse them), which is accomplished by simply calling sane_start() again, which will get you to the next frame, without having to read and discard the current one.

In order to prematurely stop scanning and to reset the backend state, sane_cancel() can be called at any time. This call is required as well after normal termination of a multiple image scan as described above.

When done using the device, the handle should be closed by a call to sane_close(). Finally, before exiting the application, function sane_exit() must be called. It is important not to forget to call this function since otherwise some resources (e.g., temporary files or locks) may remain unclaimed.

Attention

The following C sample code implements a reference loop for acquiring multiple images:

SANE_Parameters parms;
SANE_Status     status;

do
  {
    do
      {
        /* Now start acquiring the next frame. */
        status = sane_start (handle);

        /* if that failed, we have a problem, and no more frames can be
         * read at this time. Due to SANE_PFLAG_MORE_IMAGES still
         * being clear, this will break out of _BOTH_ loops.
         */
        if (status != SANE_STATUS_GOOD)
          break;

        /* Now let us see what the next frame brings. */
        status = sane_get_parameters (handle, &parms);

        /* This actually should not fail, but maybe the doc feeder
         * jammed or something, so we break as well, if something
         * is wrong.
         */
        if (status != SANE_STATUS_GOOD)
          break;

        /* Now we check the announced parameters, if we can make use
         * of the frame data. If not, we skip over to the next frame.
         */
        if (do_i_like_that (&parms) == NO)
          continue;

        /* Set up for reading the data here. Mangle filenames,
         * allocate memory, rewind multiframe files, ask user
         * for confirmation, ...
         */
        setup_for_transfer (...);

        /* Now we read in the frame data and process it. This should
         * return SANE_STATUS_GOOD, until the frame is complete,
         * what causes SANE_STATUS_EOF to be returned.
         */
        while (SANE_STATUS_GOOD == (status = sane_read (...)))
          read_in_and_process_data_as_required ();

        /* If transfer was broken due to anything but EOF, break out. */
        if (status != SANE_STATUS_EOF)
          break;

        /* Now loop until we have all frames of an image. */
      }
    while(!(parms.flag & SANE_PFLAG_LAST_FRAME));

    /* O.K. - we now have a complete image. Fit it together, save it,
     * flush buffers, transmit it, increment filenames, etc.
     */

    /* Now check for more pending images. If we have more, redo from start.
     * Some backends might cheat here and send us for an extra round which
     * will fail at sane_start, as they were not able to determine if they
     * would have more data at the start of the last frame we read.
     */
  }
while(parms.flags & SANE_PFLAG_MORE_IMAGES);

/* No more data. Fine. Reset the backend and go back to option-control
 * loop.
 */

sane_cancel (handle);

4.5 Well-Known Options

While most backend options are completely self-describing, there are cases where a user interface might want to special-case the handling of certain options. For example, the scan area is typically defined by four options that specify the top-left and bottom-right corners of the area. With a graphical user interface, it would be tedious to force the user to type in these four numbers. Instead, most such interfaces will want to present to the user a preview (low-resolution scan of the full scanner surface or a high(er) resolution scan of a subpart of the scanner surface) and let the user pick the scan area by dragging a rectangle into the desired position. For this reason, the SANE API specifies a small number of option names that have well-defined meanings.

4.5.1 Option Number Count

Option number 0 has an empty string as its name. The value of this option is of type SANE_TYPE_INT and it specifies the total number of options available for a given device (the count includes option number 0). This means that there are two ways of counting the number of options available: a frontend can either cycle through all option numbers starting at one until sane_get_option_descriptor() returns NULL, or a frontend can directly read out the value of option number 0.

4.5.2 Scan Resolution Options

Option resolution is used to select the resolution at which an image should be acquired.

Attention

When the backend wants to allow different values for x- and y-resolution it has to define the options x-resolution and y-resolution. Note that only the option resolution or the options x-resolution and y-resolution may be active at the same time.

The type of this option is either SANE_TYPE_INT or SANE_TYPE_FIXED. The unit is SANE_UNIT_DPI (dots/inch).

These options are not mandatory, but if a backend does support them, it must implement them in a manner consistent with the above definition.

4.5.3 Preview Mode Option

The Boolean option preview is used by a frontend to inform the backend when image acquisition should be optimized for speed, rather than quality (“preview mode”). When set to SANE_TRUE, preview mode is in effect, when set to SANE_FALSE image acquisition should proceed in normal quality mode. The setting of this option must not affect any other option. That is, as far as the other options are concerned, the preview mode is completely side effect free. A backend can assume that the frontend will take care of appropriately setting the scan resolution for preview mode (through option resolution). A backend is free to override the resolution value with its own choice for preview mode, but it is advised to leave this choice to the frontend wherever possible.

Attention

When the preview option is set the backend should transfer the image in frame type SANE_FRAME_RAW if possible.

This option is not mandatory, but if a backend does support it, it must implement it in a manner consistent with the above definition.

4.5.4 Scan Area Options

The four most important well-known options are the ones that define the scan area. The scan area is defined by two points (x/y coordinate pairs) that specify the top-left and the bottom-right corners. This is illustrated in Figure 4.2. Note that the origin of the coordinate system is at the top-left corner of the scan surface as seen by the sensor (which typically is a mirror image of the scan surface seen by the user). For this reason, the top-left corner is the corner for which the abscissa and ordinate values are simultaneously the smallest and the bottom-right corner is the corner for which the abscissa and ordinate values are simultaneously the largest. If this coordinate system is not natural for a given device, it is the job of the backend to perform the necessary conversions.

_images/area.svg

Figure 4.2 Scan area options

The names of the four options that define the scan area are given in the table below:

Name

Description

tl-x

Top-left \(x\) coordinate value

tl-y

Top-left \(y\) coordinate value

br-x

Bottom-right \(x\) coordinate value

br-y

Bottom-right \(y\) coordinate value

There are several rules that should be followed by front and backends regarding these options:

  • Backends must attach a unit of either pixels (SANE_UNIT_PIXEL) or millimeters (SANE_UNIT_MM) to these options. The unit of all four options must be identical.

  • Whenever meaningful, a backend should attach a range or a word-list constraint to these options.

  • A frontend can determine the size of the scan surface by first checking that the options have range constraints associated. If a range or word-list constraints exist, the frontend can take the minimum and maximum values of one of the x and y option range-constraints to determine the scan surface size.

  • A frontend must work properly with any or all of these options missing.

Attention

  • A frontend may temporarily set the values in a way that tl-x is larger than br-x and tl-y is larger than br-y.

These options are not mandatory, but if a backend does support them, it must implement them in a manner consistent with the above definition.

4.5.5 Depth Option

Attention

Option depth is used to select the image depth in bits/sample in multi bit mode - (e.g. for 24 bit RGB mode this value must be 8). The type of this option is SANE_TYPE_INT. The unit is SANE_UNIT_BIT. For 1 bit modes (Lineart or Halftone) this option has to be inactive. For selection of 1 bit modes (Lineart or Halftone) the backend should use the well-known option mode.

This option is not mandatory, but if a backend does support it, it must implement it in a manner consistent with the above definition.

4.5.6 Scan Mode Options

Attention

The option mode defines a SANE_CONSTRAINT_STRING_LIST of type SANE_TYPE_STRING. It is used to select the scan mode (e.g. Color or Gray). Well known modes are: Color, Gray, Halftone and Lineart. Color and Gray are multi bit modes (8 or 16 bits/sample), Halftone and Lineart are single bit modes. When well-known scan modes are used, a frontend is able to automatically decide which mode is appropriate for a specific task, e.g the mode Gray for scanning a fax.

This option is not mandatory, but if a backend does support it, it must implement it in a manner consistent with the above definition.

4.5.7 Scan Source Options

Attention

The option source is used to select the scan source (e.g. Automatic Document Feeder). It defines a SANE_CONSTRAINT_STRING_LIST of type SANE_TYPE_STRING. Well known sources are: Flatbed, Transparancy Adapter and Automatic Document Feeder.

This option is not mandatory, but if a backend does support it, it must implement it in a manner consistent with the above definition.

4.5.8 Threshold Option

Attention

The option threshold is used to define the threshold for Lineart and maybe Halftone mode. In multi bit modes this option should be set inactive. The type of this option is SANE_TYPE_FIXED. The unit is SANE_UNIT_PERCENT. The value range should be \(0.0\ldots100.0\) if possible. It defines the minimum intensity to get a white point / full intensity.

The backend has to scale the values in the following way:

A value of 0.0 means all pixels get white / full intensity. A value of 50.0 means intensities brighter than medium gray get white / full intensity. A value of 100.0 means all pixels get black. If the scanner is not able to cover the full range the backend has to define a reduced value range (e.g. \(30\ldots70\) percent).

This option is not mandatory, but if a backend does support it, it must implement it in a manner consistent with the above definition.

4.5.9 Gamma Table Options

Attention

The gamma-table option defines a SANE_CONSTRAINT_RANGE of the type SANE_TYPE_INT which represents the gamma correction table for gray. In color mode the gamma-table may be used to set a common gamma correction for red, green and blue. The options red-gamma-table, green-gamma-table and blue-gamma-table are used in color mode to set a gamma correction for each color separately. In color mode the backend is free to use only the gamma-table option, only the red-, green- and blue-gamma-table or all four options. When all four options are used then the color tables should do a gamma correction with the same input and output bit depth and the gray gamma table should reduce (if necessary) the bit depth from the scanner internal bit depth to the output bit depth. This should e.g. look like this:

red_value   = gamma-table(red-gamma-table(value))
green_value = gamma-table(green-gamma-table(value))
blue_value  = gamma-table(blue-gamma-table(value))

The backend should not use the gamma tables to emulate other functions or options like highlight, shadow, contrast, brightness, threshold, analog_gamma. These functions are common for all backends and should be added to the frontend or a meta-backend.

It is also discouraged to emulate gamma tables in the backend. The backend should disable (or not define) this option when the scanner does not support gamma tables in hardware.

This option is not mandatory, but if a backend does support it, it must implement it in a manner consistent with the above definition.

4.5.10 Analog Gamma

Attention

The option analog-gamma is used to define the gamma value for an analog gamma function of the scanner in multi bit modes. In 1 bit modes this option should be set inactive. The type of this option is SANE_TYPE_FIXED. The unit is SANE_UNIT_NONE. The value range can be defined by the backend as supported. The values have to be positive. A gamma value of 1.0 means that the gamma correction has no effect. A value larger than 1.0 increases the brightness of the image. In color mode there also can be options analog-gamma-red, analog-gamma-green and analog-gamma-blue. It is not allowed to emulate an analog gamma function by a digital gamma table. The backend has to disable (or not define) this option when the scanner does not support an analog (hardware) gamma function.

When analog gamma, highlight and shadow functions are available at the same time then the backend author has to care about the order in which the functions are implemented in the scanner hardware. The SANE standard expects that changing the analog gamma value has no effect on the shadow and highlight function. When the analog gamma function is executed in the scanner hardware before the shadow and highlight functions then the backend should do a compensation. For this the shadow and highlight values have to be gamma corrected with the relevant analog gamma value.

This option is not mandatory, but if a backend does support it, it must implement it in a manner consistent with the above definition.

4.5.11 Shadow Option

Attention

The option shadow is used to define the shadow level / black point level. The type of this option is SANE_TYPE_FIXED. The unit is SANE_UNIT_PERCENT. The value range should be \(0.0\ldots100.0\) if possible. It is used to define the maximum intensity level that creates an image data value of 0 (black). The backend has to scale the values in the following way:

A value of 0.0 means that the sensitivity range is not reduced, only the minimum intensity produces an image data value of 0 (black). A value of 50.0 means that that a medium intensity and everything that is darker produces an image data value of 0 (black). A value of 100.0 means the sensitivity range is reduced to 0, all image data values are 0 (black). If the scanner is not able to cover the full range the backend has to define a reduced value range (e.g. \(30\ldots70\) percent). In color mode there can be options shadow-red, shadow-green and shadow-blue, in this case the shadow function has to be disabled. It is not allowed to emulate a shadow function by a digital gamma table. The backend has to disable (or not define) this option when the scanner does not support an analog (hardware) shadow function.

This option is not mandatory, but if a backend does support it, it must implement it in a manner consistent with the above definition.

4.5.12 Highlight Option

Attention

The option highlight is used to define the highlight level / white point level. The type of this option is SANE_TYPE_FIXED. The unit is SANE_UNIT_PERCENT. The value range should be \(0.0\ldots100.0\) if possible. It is used to define the minimum intensity level that creates the maximum possible image data value (white/full intensity). The backend has to scale the values in the following way:

A value of 0.0 means the sensitivity range is reduced to 0, all image data have maximum value (white / full intensity). A value of 50.0 means that a medium intensity and everything that is brighter produces the maximum possible image data value (white / full intensity). A value of 100.0 means that the sensitivity range is not reduced, only the maximum intensity produces an image data with maximum possible value (white / full intensity). If the scanner is not able to cover the full range the backend has to define a reduced value range (e.g. \(30\ldots70\) percent). In color mode there can be options highlight-red, highlight-green and highlight-blue, in this case highlight has to be disabled. It is not allowed to emulate a highlight function by a digital gamma table. The backend has to disable (or not define) this option when the scanner does not support an analog (hardware) highlight function.

This option is not mandatory, but if a backend does support it, it must implement it in a manner consistent with the above definition.

4.5.13 Lamp Options

Attention

The options lamp-on and lamp-off are button options (SANE_TYPE_BUTTON) and don’t have a unit (SANE_UNIT_NONE).

Option lamp-on is used to turn on the lamp of the scanner while lamp-off turns it off.

These options are not mandatory, but if a backend does support them, it must implement them in a manner consistent with the above definition.

4.5.14 Scanner Button Options

Attention

Some scanners have buttons which state can be read by the scanner driver. It is necessary to implement a locking function for the buttons because it is possible that several frontends try to connect to the same backend/scanner at the same time. Imagine what could happen when no locking would be implemented:

Five people have started a scanning application which is connected via network to the scanner you want to use. You start a frontend, put a paper to the scanner and press the scan-button on the scanner. The scanner does scan three times (because three frontends asked the button status when you pressed the button). For three people the image is saved to the hard disk, but it is not sure that your frontend did scan the image.

A backend that does make available the scanner-buttons has to implement the following options:

When setting these options the backend does not set SANE_INFO_RELOAD_OPTIONS or SANE_INFO_RELOAD_PARAMS if not explicitly defined.

A frontend has to disable the usage of the scanner-buttons by default. This is important because other frontends will not be able to use the buttons when the button-functions are locked. Another important thing is that some scanners do not turn off their lamp when the driver does frequently talk to the scanner (what is done when reading the button status from the scanner).

  • A frontend that wants to read the button status has to lock the button functions at first. For this it does set the option scanner-buttons-lock to SANE_TRUE. While setting the value of option scanner-buttons-lock to SANE_TRUE the backend does check if a lockfile (e.g. “backend”-buttons.lock) does exist. The lockfile has to be placed in a directory where every user has read and write access to.

    • If the lockfile does not exist then the backend creates the lockfile and writes the process ID (PID) of the backend to the file. Button access is allowed: the value of option scanner-buttons-lock is set to SANE_TRUE

    • If the file does exist and the backend PID is not the file PID then the backend has to check if the process with the PID stored in the lockfile still is running. If yes then the button access is not allowed: the value of option scanner-buttons-lock is set to SANE_FALSE. If not then the lockfile is recreated and the PID of the backend is stored in the lockfile, button access is allowed: the value of option scanner-buttons-lock is set to SANE_TRUE

  • The frontend does read the value of option scanner-buttons-lock. If it is SANE_TRUE then the frontend has access to the scanner buttons. If it is SANE_FALSE then access has been denied.

  • If the button access is allowed the frontend has to do the following about once per second (while not scanning):

    • The frontend does set option scanner-buttons-status-update. The backend checks if access to the buttons is allowed by comparing the backend PID with the lockfile PID. If access is allowed it does read the button status from the scanner and stores it in the option scanner-buttons-status, each bit represents a button, a value of 0 means the button is not pressed, a value of 1 means that the button is pressed. When the scanner is busy the backend must not wait, it has to return immediately and the button state keeps unchanged. The backend has to implement a timeout function. When no button has been pressed within a predefined time (e.g. 15 minutes) then the access permission is lost. In this case the backend does set option scanner-buttons-lock to SANE_FALSE and does set SANE_INFO_RELOAD_OPTIONS to inform the frontend that it has lost permission to access the scanner-button functions. If access is not allowed it does set the scanner-buttons-status to 0.

    • The frontend does read the value of option scanner-buttons-status

  • When the frontend does exit or it does not want to use the buttons it does set option scanner-buttons-lock to SANE_FALSE. The backend does check if the backend PID and the lockfile PID are the same. If this is true then it removes the lockfile and sets the value of scanner-buttons-lock to SANE_FALSE.

    sane_close() should do the same as setting option scanner-buttons-lock to SANE_FALSE.

4.5.15 Batch Scan Options

Attention

The batch scan options can be used by a frontend to indicate that more than one image will be scanned in a batch. The backend can optimize for such scans by e.g. avoiding calibration and not moving home the sensor array in this case. The backend provides the options batch-scan, batch-scan-next-tl-x, batch-scan-next-tl-y, batch-scan-next-br-x, and batch-scan-next-br-y. The option batch-scan provides a string list with the values of No if batch scanning isn’t used, Start for the first, End for the last and Loop for any other (intermediate) image. The batch-scan-next options specify the coordinates of the next scan and follow the same rules as the scan area options (see section 4.5.4).

These options are not mandatory, but if a backend does support them, it must implement them in a manner consistent with the above definition. In this case, all options must be implemented.

1

This is different from ANSI C where any non-zero integer value represents logical TRUE.