xref: /aoo42x/main/sane/inc/sane.h (revision 7a164331)
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 #ifdef __cplusplus
20 extern "C" {
21 #endif
22 
23 /*
24  * SANE types and defines
25  */
26 
27 #define SANE_CURRENT_MAJOR	1
28 #define SANE_CURRENT_MINOR	0
29 
30 #define SANE_VERSION_CODE(major, minor, build)	\
31   (  (((SANE_Word) (major) &   0xff) << 24)	\
32    | (((SANE_Word) (minor) &   0xff) << 16)	\
33    | (((SANE_Word) (build) & 0xffff) <<  0))
34 
35 #define SANE_VERSION_MAJOR(code)	((((SANE_Word)(code)) >> 24) &   0xff)
36 #define SANE_VERSION_MINOR(code)	((((SANE_Word)(code)) >> 16) &   0xff)
37 #define SANE_VERSION_BUILD(code)	((((SANE_Word)(code)) >>  0) & 0xffff)
38 
39 #define SANE_FALSE	0
40 #define SANE_TRUE	1
41 
42 typedef unsigned char  SANE_Byte;
43 typedef int  SANE_Word;
44 typedef SANE_Word  SANE_Bool;
45 typedef SANE_Word  SANE_Int;
46 typedef char SANE_Char;
47 typedef SANE_Char *SANE_String;
48 typedef const SANE_Char *SANE_String_Const;
49 typedef void *SANE_Handle;
50 typedef SANE_Word SANE_Fixed;
51 
52 #define SANE_FIXED_SCALE_SHIFT	16
53 #define SANE_FIX(v)	((SANE_Word) ((v) * (1 << SANE_FIXED_SCALE_SHIFT)))
54 #define SANE_UNFIX(v)	((double)(v) / (1 << SANE_FIXED_SCALE_SHIFT))
55 
56 typedef enum
57   {
58     SANE_STATUS_GOOD = 0,	/* everything A-OK */
59     SANE_STATUS_UNSUPPORTED,	/* operation is not supported */
60     SANE_STATUS_CANCELLED,	/* operation was cancelled */
61     SANE_STATUS_DEVICE_BUSY,	/* device is busy; try again later */
62     SANE_STATUS_INVAL,		/* data is invalid (includes no dev at open) */
63     SANE_STATUS_EOF,		/* no more data available (end-of-file) */
64     SANE_STATUS_JAMMED,		/* document feeder jammed */
65     SANE_STATUS_NO_DOCS,	/* document feeder out of documents */
66     SANE_STATUS_COVER_OPEN,	/* scanner cover is open */
67     SANE_STATUS_IO_ERROR,	/* error during device I/O */
68     SANE_STATUS_NO_MEM,		/* out of memory */
69     SANE_STATUS_ACCESS_DENIED	/* access to resource has been denied */
70   }
71 SANE_Status;
72 
73 /* following are for later sane version, older frontends won't support */
74 #if 0
75 #define SANE_STATUS_WARMING_UP 12 /* lamp not ready, please retry */
76 #define SANE_STATUS_HW_LOCKED  13 /* scanner mechanism locked for transport */
77 #endif
78 
79 typedef enum
80   {
81     SANE_TYPE_BOOL = 0,
82     SANE_TYPE_INT,
83     SANE_TYPE_FIXED,
84     SANE_TYPE_STRING,
85     SANE_TYPE_BUTTON,
86     SANE_TYPE_GROUP
87   }
88 SANE_Value_Type;
89 
90 typedef enum
91   {
92     SANE_UNIT_NONE = 0,		/* the value is unit-less (e.g., # of scans) */
93     SANE_UNIT_PIXEL,		/* value is number of pixels */
94     SANE_UNIT_BIT,		/* value is number of bits */
95     SANE_UNIT_MM,		/* value is millimeters */
96     SANE_UNIT_DPI,		/* value is resolution in dots/inch */
97     SANE_UNIT_PERCENT,		/* value is a percentage */
98     SANE_UNIT_MICROSECOND	/* value is micro seconds */
99   }
100 SANE_Unit;
101 
102 typedef struct
103   {
104     SANE_String_Const name;	/* unique device name */
105     SANE_String_Const vendor;	/* device vendor string */
106     SANE_String_Const model;	/* device model name */
107     SANE_String_Const type;	/* device type (e.g., "flatbed scanner") */
108   }
109 SANE_Device;
110 
111 #define SANE_CAP_SOFT_SELECT		(1 << 0)
112 #define SANE_CAP_HARD_SELECT		(1 << 1)
113 #define SANE_CAP_SOFT_DETECT		(1 << 2)
114 #define SANE_CAP_EMULATED		(1 << 3)
115 #define SANE_CAP_AUTOMATIC		(1 << 4)
116 #define SANE_CAP_INACTIVE		(1 << 5)
117 #define SANE_CAP_ADVANCED		(1 << 6)
118 
119 #define SANE_OPTION_IS_ACTIVE(cap)	(((cap) & SANE_CAP_INACTIVE) == 0)
120 #define SANE_OPTION_IS_SETTABLE(cap)	(((cap) & SANE_CAP_SOFT_SELECT) != 0)
121 
122 #define SANE_INFO_INEXACT		(1 << 0)
123 #define SANE_INFO_RELOAD_OPTIONS	(1 << 1)
124 #define SANE_INFO_RELOAD_PARAMS		(1 << 2)
125 
126 typedef enum
127   {
128     SANE_CONSTRAINT_NONE = 0,
129     SANE_CONSTRAINT_RANGE,
130     SANE_CONSTRAINT_WORD_LIST,
131     SANE_CONSTRAINT_STRING_LIST
132   }
133 SANE_Constraint_Type;
134 
135 typedef struct
136   {
137     SANE_Word min;		/* minimum (element) value */
138     SANE_Word max;		/* maximum (element) value */
139     SANE_Word quant;		/* quantization value (0 if none) */
140   }
141 SANE_Range;
142 
143 typedef struct
144   {
145     SANE_String_Const name;	/* name of this option (command-line name) */
146     SANE_String_Const title;	/* title of this option (single-line) */
147     SANE_String_Const desc;	/* description of this option (multi-line) */
148     SANE_Value_Type type;	/* how are values interpreted? */
149     SANE_Unit unit;		/* what is the (physical) unit? */
150     SANE_Int size;
151     SANE_Int cap;		/* capabilities */
152 
153     SANE_Constraint_Type constraint_type;
154     union
155       {
156 	const SANE_String_Const *string_list;	/* NULL-terminated list */
157 	const SANE_Word *word_list;	/* first element is list-length */
158 	const SANE_Range *range;
159       }
160     constraint;
161   }
162 SANE_Option_Descriptor;
163 
164 typedef enum
165   {
166     SANE_ACTION_GET_VALUE = 0,
167     SANE_ACTION_SET_VALUE,
168     SANE_ACTION_SET_AUTO
169   }
170 SANE_Action;
171 
172 typedef enum
173   {
174     SANE_FRAME_GRAY,	/* band covering human visual range */
175     SANE_FRAME_RGB,	/* pixel-interleaved red/green/blue bands */
176     SANE_FRAME_RED,	/* red band only */
177     SANE_FRAME_GREEN,	/* green band only */
178     SANE_FRAME_BLUE 	/* blue band only */
179   }
180 SANE_Frame;
181 
182 /* push remaining types down to match existing backends */
183 /* these are to be exposed in a later version of SANE */
184 /* most front-ends will require updates to understand them */
185 #if 0
186 #define SANE_FRAME_TEXT  0x0A  /* backend specific textual data */
187 #define SANE_FRAME_JPEG  0x0B  /* complete baseline JPEG file */
188 #define SANE_FRAME_G31D  0x0C  /* CCITT Group 3 1-D Compressed (MH) */
189 #define SANE_FRAME_G32D  0x0D  /* CCITT Group 3 2-D Compressed (MR) */
190 #define SANE_FRAME_G42D  0x0E  /* CCITT Group 4 2-D Compressed (MMR) */
191 
192 #define SANE_FRAME_IR    0x0F  /* bare infrared channel */
193 #define SANE_FRAME_RGBI  0x10  /* red+green+blue+infrared */
194 #define SANE_FRAME_GRAYI 0x11  /* gray+infrared */
195 #define SANE_FRAME_XML   0x12  /* undefined schema */
196 #endif
197 
198 typedef struct
199   {
200     SANE_Frame format;
201     SANE_Bool last_frame;
202     SANE_Int bytes_per_line;
203     SANE_Int pixels_per_line;
204     SANE_Int lines;
205     SANE_Int depth;
206   }
207 SANE_Parameters;
208 
209 struct SANE_Auth_Data;
210 
211 #define SANE_MAX_USERNAME_LEN	128
212 #define SANE_MAX_PASSWORD_LEN	128
213 
214 typedef void (*SANE_Auth_Callback) (SANE_String_Const resource,
215 				    SANE_Char *username,
216 				    SANE_Char *password);
217 
218 extern SANE_Status sane_init (SANE_Int * version_code,
219 			      SANE_Auth_Callback authorize);
220 extern void sane_exit (void);
221 extern SANE_Status sane_get_devices (const SANE_Device *** device_list,
222 				     SANE_Bool local_only);
223 extern SANE_Status sane_open (SANE_String_Const devicename,
224 			      SANE_Handle * handle);
225 extern void sane_close (SANE_Handle handle);
226 extern const SANE_Option_Descriptor *
227   sane_get_option_descriptor (SANE_Handle handle, SANE_Int option);
228 extern SANE_Status sane_control_option (SANE_Handle handle, SANE_Int option,
229 					SANE_Action action, void *value,
230 					SANE_Int * info);
231 extern SANE_Status sane_get_parameters (SANE_Handle handle,
232 					SANE_Parameters * params);
233 extern SANE_Status sane_start (SANE_Handle handle);
234 extern SANE_Status sane_read (SANE_Handle handle, SANE_Byte * data,
235 			      SANE_Int max_length, SANE_Int * length);
236 extern void sane_cancel (SANE_Handle handle);
237 extern SANE_Status sane_set_io_mode (SANE_Handle handle,
238 				     SANE_Bool non_blocking);
239 extern SANE_Status sane_get_select_fd (SANE_Handle handle,
240 				       SANE_Int * fd);
241 extern SANE_String_Const sane_strstatus (SANE_Status status);
242 
243 #ifdef __cplusplus
244 }
245 #endif
246 
247 
248 #endif /* sane_h */
249