scan/sane/sane.h

   1 /* sane - Scanner Access Now Easy.
   2    Copyright (C) 1997-1999 David Mosberger-Tang and Andreas Beck
   3    This file is part of the SANE package.
   4
   5    This file is in the public domain.  You may use and modify it as
   6    you see fit, as long as this copyright message is included and
   7    that there is an indication as to what modifications have been
   8    made (if any).
   9
  10    SANE is distributed in the hope that it will be useful, but WITHOUT
  11    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12    FITNESS FOR A PARTICULAR PURPOSE.
  13
  14    This file declares SANE application interface.  See the SANE
  15    standard for a detailed explanation of the interface.  */
  16 #ifndef sane_h
  17 #define sane_h
  18
  19 #define SANE_CURRENT_MAJOR      1
  20
  21 #define SANE_VERSION_CODE(major, minor, build)  \
  22   (  (((SANE_Word) (major) &   0xff) << 24)     \
  23    | (((SANE_Word) (minor) &   0xff) << 16)     \
  24    | (((SANE_Word) (build) & 0xffff) <<  0))
  25
  26 #define SANE_VERSION_MAJOR(code)        ((((SANE_Word)(code)) >> 24) &   0xff)
  27 #define SANE_VERSION_MINOR(code)        ((((SANE_Word)(code)) >> 16) &   0xff)
  28 #define SANE_VERSION_BUILD(code)        ((((SANE_Word)(code)) >>  0) & 0xffff)
  29
  30 #define SANE_FALSE      0
  31 #define SANE_TRUE       1
  32
  33 typedef unsigned char SANE_Byte;
  34 typedef int SANE_Word;
  35 typedef SANE_Word SANE_Bool;
  36 typedef SANE_Word SANE_Int;
  37 typedef char SANE_Char;
  38 typedef SANE_Char *SANE_String;
  39 typedef const SANE_Char *SANE_String_Const;
  40 typedef void *SANE_Handle;
  41 typedef SANE_Word SANE_Fixed;
  42
  43 #define SANE_FIXED_SCALE_SHIFT  16
  44 #define SANE_FIX(v)     ((SANE_Word) ((v) * (1 << SANE_FIXED_SCALE_SHIFT)))
  45 #define SANE_UNFIX(v)   ((double)(v) / (1 << SANE_FIXED_SCALE_SHIFT))
  46
  47 typedef enum
  48   {
  49     SANE_STATUS_GOOD = 0,       /* everything A-OK */
  50     SANE_STATUS_UNSUPPORTED,    /* operation is not supported */
  51     SANE_STATUS_CANCELLED,      /* operation was cancelled */
  52     SANE_STATUS_DEVICE_BUSY,    /* device is busy; try again later */
  53     SANE_STATUS_INVAL,          /* data is invalid (includes no dev at open) */
  54     SANE_STATUS_EOF,            /* no more data available (end-of-file) */
  55     SANE_STATUS_JAMMED,         /* document feeder jammed */
  56     SANE_STATUS_NO_DOCS,        /* document feeder out of documents */
  57     SANE_STATUS_COVER_OPEN,     /* scanner cover is open */
  58     SANE_STATUS_IO_ERROR,       /* error during device I/O */
  59     SANE_STATUS_NO_MEM,         /* out of memory */
  60     SANE_STATUS_ACCESS_DENIED   /* access to resource has been denied */
  61   }
  62 SANE_Status;
  63
  64 typedef enum
  65   {
  66     SANE_TYPE_BOOL = 0,
  67     SANE_TYPE_INT,
  68     SANE_TYPE_FIXED,
  69     SANE_TYPE_STRING,
  70     SANE_TYPE_BUTTON,
  71     SANE_TYPE_GROUP
  72   }
  73 SANE_Value_Type;
  74
  75 typedef enum
  76   {
  77     SANE_UNIT_NONE = 0,         /* the value is unit-less (e.g., # of scans) */
  78     SANE_UNIT_PIXEL,            /* value is number of pixels */
  79     SANE_UNIT_BIT,              /* value is number of bits */
  80     SANE_UNIT_MM,               /* value is millimeters */
  81     SANE_UNIT_DPI,              /* value is resolution in dots/inch */
  82     SANE_UNIT_PERCENT,          /* value is a percentage */
  83     SANE_UNIT_MICROSECOND       /* value is micro seconds */
  84   }
  85 SANE_Unit;
  86
  87 typedef struct
  88   {
  89     SANE_String_Const name;     /* unique device name */
  90     SANE_String_Const vendor;   /* device vendor string */
  91     SANE_String_Const model;    /* device model name */
  92     SANE_String_Const type;     /* device type (e.g., "flatbed scanner") */
  93   }
  94 SANE_Device;
  95
  96 #define SANE_CAP_SOFT_SELECT            (1 << 0)
  97 #define SANE_CAP_HARD_SELECT            (1 << 1)
  98 #define SANE_CAP_SOFT_DETECT            (1 << 2)
  99 #define SANE_CAP_EMULATED               (1 << 3)
 100 #define SANE_CAP_AUTOMATIC              (1 << 4)
 101 #define SANE_CAP_INACTIVE               (1 << 5)
 102 #define SANE_CAP_ADVANCED               (1 << 6)
 103 #define SANE_CAP_ALWAYS_SETTABLE        (1 << 7)
 104
 105 #define SANE_OPTION_IS_ACTIVE(cap)      (((cap) & SANE_CAP_INACTIVE) == 0)
 106 #define SANE_OPTION_IS_SETTABLE(cap)    (((cap) & SANE_CAP_SOFT_SELECT) != 0)
 107
 108 #define SANE_INFO_INEXACT               (1 << 0)
 109 #define SANE_INFO_RELOAD_OPTIONS        (1 << 1)
 110 #define SANE_INFO_RELOAD_PARAMS         (1 << 2)
 111
 112 typedef enum
 113   {
 114     SANE_CONSTRAINT_NONE = 0,
 115     SANE_CONSTRAINT_RANGE,
 116     SANE_CONSTRAINT_WORD_LIST,
 117     SANE_CONSTRAINT_STRING_LIST
 118   }
 119 SANE_Constraint_Type;
 120
 121 typedef struct
 122   {
 123     SANE_Word min;              /* minimum (element) value */
 124     SANE_Word max;              /* maximum (element) value */
 125     SANE_Word quant;            /* quantization value (0 if none) */
 126   }
 127 SANE_Range;
 128
 129 typedef struct
 130   {
 131     SANE_String_Const name;     /* name of this option (command-line name) */
 132     SANE_String_Const title;    /* title of this option (single-line) */
 133     SANE_String_Const desc;     /* description of this option (multi-line) */
 134     SANE_Value_Type type;       /* how are values interpreted? */
 135     SANE_Unit unit;             /* what is the (physical) unit? */
 136     SANE_Int size;
 137     SANE_Int cap;               /* capabilities */
 138
 139     SANE_Constraint_Type constraint_type;
 140     union
 141       {
 142         const SANE_String_Const *string_list;   /* NULL-terminated list */
 143         const SANE_Word *word_list;     /* first element is list-length */
 144         const SANE_Range *range;
 145       }
 146     constraint;
 147   }
 148 SANE_Option_Descriptor;
 149
 150 typedef enum
 151   {
 152     SANE_ACTION_GET_VALUE = 0,
 153     SANE_ACTION_SET_VALUE,
 154     SANE_ACTION_SET_AUTO
 155   }
 156 SANE_Action;
 157
 158 typedef enum
 159   {
 160     SANE_FRAME_GRAY,            /* band covering human visual range */
 161     SANE_FRAME_RGB,             /* pixel-interleaved red/green/blue bands */
 162     SANE_FRAME_RED,             /* red band only */
 163     SANE_FRAME_GREEN,           /* green band only */
 164     SANE_FRAME_BLUE             /* blue band only */
 165   }
 166 SANE_Frame;
 167
 168 typedef struct
 169   {
 170     SANE_Frame format;
 171     SANE_Bool last_frame;
 172     SANE_Int bytes_per_line;
 173     SANE_Int pixels_per_line;
 174     SANE_Int lines;
 175     SANE_Int depth;
 176   }
 177 SANE_Parameters;
 178
 179 struct SANE_Auth_Data;
 180
 181 #define SANE_MAX_USERNAME_LEN   128
 182 #define SANE_MAX_PASSWORD_LEN   128
 183
 184 typedef void (*SANE_Auth_Callback) (SANE_String_Const resource,
 185                                     SANE_Char username[SANE_MAX_USERNAME_LEN],
 186                                     SANE_Char password[SANE_MAX_PASSWORD_LEN]);
 187
 188 extern SANE_Status sane_init (SANE_Int * version_code,
 189                               SANE_Auth_Callback authorize);
 190 extern void sane_exit (void);
 191 extern SANE_Status sane_get_devices (const SANE_Device *** device_list,
 192                                      SANE_Bool local_only);
 193 extern SANE_Status sane_open (SANE_String_Const devicename,
 194                               SANE_Handle * handle);
 195 extern void sane_close (SANE_Handle handle);
 196 extern const SANE_Option_Descriptor *
 197   sane_get_option_descriptor (SANE_Handle handle, SANE_Int option);
 198 extern SANE_Status sane_control_option (SANE_Handle handle, SANE_Int option,
 199                                         SANE_Action action, void *value,
 200                                         SANE_Int * info);
 201 extern SANE_Status sane_get_parameters (SANE_Handle handle,
 202                                         SANE_Parameters * params);
 203 extern SANE_Status sane_start (SANE_Handle handle);
 204 extern SANE_Status sane_read (SANE_Handle handle, SANE_Byte * data,
 205                               SANE_Int max_length, SANE_Int * length);
 206 extern void sane_cancel (SANE_Handle handle);
 207 extern SANE_Status sane_set_io_mode (SANE_Handle handle,
 208                                      SANE_Bool non_blocking);
 209 extern SANE_Status sane_get_select_fd (SANE_Handle handle,
 210                                        SANE_Int * fd);
 211 extern SANE_String_Const sane_strstatus (SANE_Status status);
 212
 213 #endif /* sane_h */