Next Up Previous Contents

4.2 Data Types

Data Types

/* Truth values.  */
#define SANE_FALSE      0
#define SANE_TRUE       1

/* A byte must be big enough to hold 8 bits.  */
typedef unsigned char SANE_Byte;

/* A word must be big enough to hold: truth values (SANE_FALSE and
   SANE_TRUE), signed integers in the range -2^31..2^31-1, unsigned
   integers in the range 0..2^32-1, and fixed point values in the
   range -32768..32767.9999 with a resolution of 1/65536, and at least
   32 bits.  */
typedef int SANE_Word;

typedef SANE_Word SANE_Bool;    /* boolean */
typedef SANE_Word SANE_Int;     /* integer */
typedef SANE_Word SANE_Fixed;   /* fixed point number */

/* Fixed point variables are scaled by 2^16.  This allows to express
   values in the range -32768..32767.9999 with a resolution of 1.5e-5.  */
#define SANE_FIXED_SCALE_SHIFT  16
#define SANE_FIX(v)     ((SANE_Word) ((v) * (1 << SANE_FIXED_SCALE_SHIFT)))
#define SANE_UNFIX(v)   ((double)(v) / (1 << SANE_FIXED_SCALE_SHIFT))

/* A '\0'-terminated character string.  Characters are in the host
   native format.  For now, characters should be restricted to
   iso-latin-1, though eventually this might be expanded to cover UTC.  */
typedef char *SANE_String;
typedef const char *SANE_String_Const;  /* const SANE_String is NOT the same */

/* An opaque data type that represents a device.  A handle may be
   anything that fits into a pointer value (e.g., an integer value).
   An application must not use a handle in any other way than by
   passing it as an argument to other interface functions.  */
typedef void *SANE_Handle;

typedef enum
  {
    SANE_STATUS_GOOD = 0,       /* everything A-OK */
    SANE_STATUS_UNSUPPORTED,    /* operation is not supported */
    SANE_STATUS_CANCELLED,      /* operation was cancelled */
    SANE_STATUS_DEVICE_BUSY,    /* device is busy; try again later */
    SANE_STATUS_AGAIN,          /* currently, no data available; try again */
    SANE_STATUS_INVAL,          /* data is invalid (includes no dev at open) */
    SANE_STATUS_EOF,            /* no more data available (end-of-file) */
    SANE_STATUS_JAMMED,         /* document feeder jammed */
    SANE_STATUS_NO_DOCS,        /* document feeder out of documents */
    SANE_STATUS_COVER_OPEN,     /* scanner cover is open */
    SANE_STATUS_IO_ERROR,       /* error during device I/O */
    SANE_STATUS_NO_MEM          /* out of memory */
  }
SANE_Status;

/* The type of option values is one of the following:
   SANE_TYPE_BOOL:      A SANE_Word with value SANE_FALSE or SANE_TRUE.
   SANE_TYPE_INT:       A SANE_Word interpreted as a signed integer.
   SANE_TYPE_FIXED:     A SANE_Word interpreted as a fixed point value.
   SANE_TYPE_STRING:    A SANE_String
   SANE_TYPE_GROUP:     A pseudo-option that is used to label and group
   a sequence of options.  The group is in effect
   for the options that follow up to the point where
   another group option is encountered.  These pseudo-
   options have no value but their name can be used
   as a group title.
   SANE_TYPE_BUTTON:    A pseudo-option that is used to make push-buttons
   like "Set Defaults" or "ADF next sheet"
   These pseudo-options have no value but their name 
   should be used as a button-name.
 */
typedef enum
  {
    SANE_TYPE_BOOL = 0,
    SANE_TYPE_INT,
    SANE_TYPE_FIXED,
    SANE_TYPE_STRING,
    SANE_TYPE_GROUP,
    SANE_TYPE_BUTTON
  }
SANE_Value_Type;

/* Every option value has a unit associated.  Note that these are the
   units that are used by the SANE interface---what is presented to
   the user is entirely up to the application.  For example, SANE
   lengths are always expressed in millimeters, but an application
   should give the user the ability to select some other unit (e.g.,
   inches or centimeters).  */
typedef enum
  {
    SANE_UNIT_NONE = 0,         /* the value is unit-less (e.g., # of scans) */
    SANE_UNIT_PIXEL,            /* value is number of pixels */
    SANE_UNIT_BIT,              /* value is number of bits */
    SANE_UNIT_MM,               /* value is millimeters */
    SANE_UNIT_DPI,              /* value is resolution in dots/inch */
    SANE_UNIT_PERCENT           /* value is a percentage */
  }
SANE_Unit;

/* Each device is represented by a structure of the following form.
   The structure gives the unique name of the device that can be used
   in a call to sane_open().  The rest of the structure provides
   additional info on what device the structure represents).  The
   unique name may be physical (e.g., /dev/scanner or
   hostname:/dev/scanner) or logical (e.g., "Flatbed Scanner on host
   foobar") but the interpretation is entirely up to the backend.
   Unique names should not be overly long (a SANE application must be
   able to _cope_ with arbitrarily long names, but it can expect that
   most names are relatively short, e.g., less than 32 characters).
   VENDOR, MODEL, and TYPE are single-line strings that give
   information on the vendor (manufacturer), model, and the type of
   the device.  For consistency's sake, the following strings should
   be used when appropriate (the lists will be expanded as need
   arises):

   Vendor Strings:
   Artec
   Connectix
   Epson
   Hewlett-Packard
   Kodak
   Logitech
   Microtek
   Minolta
   Mustek
   UMAX
   None  (e.g. for virtual devices)

   Model strings:
   (vendor specific)

   Type Strings:
   flatbed scanner
   frame grabber
   hand-held scanner
   still camera
   video camera
   virtual device
 */
typedef struct
  {
    SANE_String_Const name;     /* unique device name */
    SANE_String_Const vendor;   /* device vendor string */
    SANE_String_Const model;    /* device model name */
    SANE_String_Const type;     /* device type (e.g., "flatbed scanner") */
  }
SANE_Device;

/* Options can be supported to a varying degree.  The amount of support
   is expressed by the capability bitset (member CAP).  The meaning of
   each possible member is explained below:

   SANE_CAP_SOFT_SELECT: The value(s) of the option is
   software-controlled.

   SANE_CAP_HARD_SELECT: The value(s) of the option is
   hardware-controlled.  To set the value(s) of such an option,
   the application using SANE must prompt the user to set the
   option to the selected value before scanning can
   start/progress.  This bit is mutually exclusive with
   SANE_CAP_SOFT_SELECT (either one of them can be set, but not both
   simultaneously.

   SANE_CAP_SOFT_DETECT: The value of the option can be detected by
   software.  If SANE_CAP_SOFT_SELECT is set, this bit must be set
   too.  If SANE_CAP_HARD_SELECT is set, this capability may or may
   not be set.  If this capability is set but neither
   SANE_CAP_SOFT_SELECT nor SANE_CAP_HARD_SELECT are then there is no way
   to control the option (it's possible to read out the current
   values only).

   SANE_CAP_EMULATED: This member is set if an option is not directly
   supported by the device and is instead emulated in the backend.
   Advanced scanner applications may use their own (presumably
   better) emulation in lieu of such an option.

   SANE_CAP_AUTOMATIC: If this bit is set then the backend is able to pick
   a reasonable option value automatically.

   SANE_CAP_INACTIVE: If this bit is set then the option is not
   currently active (e.g., because it's meaningful only if another
   option is set to some other value).

 */
#define SANE_CAP_SOFT_SELECT    (1 << 0)
#define SANE_CAP_HARD_SELECT    (1 << 1)
#define SANE_CAP_SOFT_DETECT    (1 << 2)
#define SANE_CAP_EMULATED       (1 << 3)
#define SANE_CAP_AUTOMATIC      (1 << 4)
#define SANE_CAP_INACTIVE       (1 << 5)

/* This macro can be used to determine whether an option is currently
   active or not.  It expects a capability-bitset as its only argument
   and returns TRUE if the option is active.  */
#define SANE_OPTION_IS_ACTIVE(cap)      (((cap) & SANE_CAP_INACTIVE) == 0)

/* This macro can be used to determine whether an option is (software)
   settable or not.  It expects a capability-bitset as its only
   argument and returns TRUE if the option is settable.  */
#define SANE_OPTION_IS_SETTABLE(cap)    (((cap) & SANE_CAP_SOFT_SELECT) != 0)

/* When operating on options, a bit mask with additional status
   information is returned.  The following members are possible:

   SANE_INFO_INEXACT: This value is returned when setting an option value
   resulted in a value being selected that does not exactly match
   the requested value.  For example, some scanners can set the
   resolution in increments of 30dpi only.  Setting the resolution
   to 307dpi may therefore result in an actual setting of 300dpi.
   In such a case, the SANE backend should set this member in the
   info return value.

   SANE_INFO_RELOAD_OPTIONS: Setting one option may affect the value or
   availability of _other_ options.  When this happens, the SANE
   backend sets this member in the return value to indicate that
   the application should reload all options. If you are unsure
   about what to return, set this bit to be safe.

   SANE_INFO_RELOAD_PARAMS: Setting one option may affect parameter
   values.  If setting an option affects the parameter values,
   bit SANE_INFO_RELOAD_PARAMS will be set.  Note that this bit
   may be set even if the parameters did not actually change.
   However, it is guaranteed that the parameters never change
   without this bit being set.
 */
#define SANE_INFO_INEXACT               (1 << 0)
#define SANE_INFO_RELOAD_OPTIONS        (1 << 1)
#define SANE_INFO_RELOAD_PARAMS         (1 << 2)

/* The values of each option may be constrained in one of several
   ways.  The simplest constraint gives simply a minimum and a maximum
   value.  Optionally, the range may be quantized by a value Q (which
   has the same interpretation as the value; e.g., fixed-point if the
   value type is fixed-point).  In that case, any value that is an
   non-negative integer multiple of Q plus the minimum value is a
   legal value---provided the resulting value is not greater than the
   maximum value).

   XXX Need to say that Range is for fixed-point and integer types
   only and that a quantization value of 0 implies no quantization
   constraint.

   Alternatively, the values can be constrained by explicitly
   enumerating the legal values.  Depending on the value type,
   this list is either a string list or a word list.

   Note that a application using SANE does not _have_ to take
   constraints into account.  However, constraints typically guide the
   user and make sure no unreasonable values are entered.  It also
   allows the application to use more sophisticated graphical elements
   to represent options.  For example, if the scanner source may be
   the flatbed, an automatic document feeder, or a transparency
   adapter, then a properly constrained option for the scanner source
   could be represented as a set of three radio-buttons.  */
typedef enum
  {
    SANE_CONSTRAINT_NONE = 0,
    SANE_CONSTRAINT_RANGE,
    SANE_CONSTRAINT_WORD_LIST,
    SANE_CONSTRAINT_STRING_LIST
  }
SANE_Constraint_Type;

typedef struct
  {
    SANE_Word min;              /* minimum (element) value */
    SANE_Word max;              /* maximum (element) value */
    SANE_Word quant;            /* quantization value (0 if none) */
  }
SANE_Range;

typedef struct
  {
    SANE_String_Const name;     /* name of this option (command-line name) */
    SANE_String_Const title;    /* title of this option (single-line) */
    SANE_String_Const desc;     /* description of this option (multi-line) */
    SANE_Value_Type type;       /* how are values interpreted? */
    SANE_Unit unit;             /* what is the (physical) unit? */
      /* XXX Number of bytes in option value.  For an option of type
         SANE_TYPE_STRING, it gives the maximum number of bytes in the
         option string (0 means the unbounded).  For boolean options,
         the size is ignored (but backends should set it to sizeof
         (SANE_Word)).  For all other types, it implies the option is
         a vector of maximum length SIZE/sizeof(SANE_Word).  Note that
         the size implies the _maximum_ length of a vector.  It is
         backend-dependent whether setting a vector that is shorter
         than the maximum length is admissible or not.  */
    SANE_Int size;
    SANE_Int cap;               /* capabilities */

    SANE_Constraint_Type constraint_type;
    union
      {
        const SANE_String_Const *string_list;   /* NULL-terminated list */
        const SANE_Word *word_list;     /* first element is list-length */
        const SANE_Range *range;
      }
    constraint;
  }
SANE_Option_Descriptor;

typedef enum
  {
    SANE_ACTION_GET_VALUE = 0,  /* get current value */
    SANE_ACTION_SET_VALUE,      /* get current value */
    SANE_ACTION_SET_AUTO        /* let backend select value automatically */
  }
SANE_Action;

typedef enum
  {
    SANE_FRAME_GRAY,            /* band covering human visual range */
    SANE_FRAME_RGB,             /* pixel-interleaved red/green/blue bands */
    SANE_FRAME_RED,             /* red band only */
    SANE_FRAME_GREEN,           /* green band only */
    SANE_FRAME_BLUE             /* blue band only */
  }
SANE_Frame;

typedef struct
  {
    /* Format of the current/next frame. */
    SANE_Frame format;
    /* This is SANE_TRUE if the frame is the first frame of a picture.  */
    SANE_Bool first_frame;
    /* Number of bytes returned per scan line: */
    SANE_Int bytes_per_line;
    /* Number of pixels per scan line.  This value multiplied by the
       number of bands and the number of bits per sample must by <=
       byte_per_line.  */
    SANE_Int pixels_per_line;
    /* Number of lines for the current scan.  If -1, sane_read() should
       be called until it returns SANE_STATUS_EOF.  */
    SANE_Int lines;
    /* Number of bits per sample.  Each pixel consists of a DEPTH bits
       times the number of bands (3 for SANE_BAND_RGB, 1 otherwise).  */
    SANE_Int depth;
  }
SANE_Parameters;


Next Up Previous Contents