summaryrefslogtreecommitdiff
path: root/doc/sane.tex
blob: 1132576a7aa1bff32776904975769bb7ce0bbeb5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
\documentclass[11pt,DVIps]{report}

\usepackage{times,epsfig,html}
% Not Currently using changebar package so comment out to reduce
% external dependencies.
%\usepackage{changebar}

\setlength{\parindent}{0pt}
\setlength{\parskip}{1.5ex plus 0.5ex minus 0.5ex}
\setlength{\textwidth}{6.5in}
\setlength{\textheight}{8.5in}
\setlength{\marginparwidth}{0pt}
\setlength{\oddsidemargin}{0pt}
\setlength{\evensidemargin}{0pt}
\setlength{\marginparsep}{0pt}
\addtolength{\topmargin}{-0.75in}

\title{\huge SANE Standard Version 1.05}
\author{}
\date{2006-04-02} 

\makeindex

\begin{document}

\newcommand{\filename}[1]{{\tt #1}}
\newcommand{\code}[1]{{\tt #1}}
\newcommand{\var}[1]{{\it #1}}
\newcommand{\defn}[1]{#1\index{#1}}

% Uncomment if adding changebars to text
%\begin{latexonly}
%  \setcounter{changebargrey}{0}   % black change bars
%\end{latexonly}

\maketitle
\tableofcontents
\listoffigures
\listoftables


\chapter{Preface}

The SANE standard is being developed by a group of free-software
developers.  The process is open to the public and comments as well as
suggestions for improvements are welcome.  Information on how to join
the SANE development process can be found in Chapter
\ref{chap:contact}.

The SANE standard is intended to streamline software development by
providing a standard application programming interface to access
raster scanner hardware.  This should reduce the number of different
driver implementations, thereby reducing the need for reimplementing
similar code.


\section{About This Document}

This document is intended for developers who are creating either an
application that requires access to raster scanner hardware and for
developers who are implementing a SANE driver.  It does not cover
specific implementations of SANE components.  Its sole purpose is to
describe and define the SANE application interface that will enable
any application on any platform to interoperate with any SANE backend
for that platform.

The remainder of this document is organized as follows.
Chapter~\ref{chap:intro} provides introductional material.
Chapter~\ref{chap:environ} presents the environment SANE is designed
for.  Chapter~\ref{chap:api} details the SANE Application Programmer
Interface.  Chapter~\ref{chap:net} specifies the network protocol that
can be used to implement the SANE API in a network transparent
fashion.  Finally, Chapter~\ref{chap:contact} gives information on how
to join the SANE development process.

\subsection{Typographic Conventions}

Changes since the last revision of this document are highlighted
like this:

% \begin{changebar}
%   Paragraphs that changed since the last revision of the documention
%   are marked like this paragraph.
% \end{changebar}

\chapter{Introduction}\label{chap:intro}

SANE is an application programming interface (API) that provides
standardized access to any raster image scanner hardware.  The
standardized interface allows to write just one driver for each
scanner device instead of one driver for each scanner and application.
The reduction in the number of required drivers provides significant
savings in development time.  More importantly, SANE raises the level
at which applications can work.  As such, it will enable applications
that were previously unheard of in the UNIX world.  While SANE is
primarily targeted at a UNIX environment, the standard has been
carefully designed to make it possible to implement the API on
virtually any hardware or operating system.

SANE is an acronym for ``Scanner Access Now Easy.''  Also, the hope is
that SANE is sane in the sense that it will allow easy implementation
of the API while accommodating all features required by today's
scanner hardware and applications.  Specifically, SANE should be broad
enough to accommodate devices such as scanners, digital still and
video cameras, as well as virtual devices like image file filters.

\section{Terminology}

An application that uses the SANE interface is called a SANE {\em
  frontend}.  A driver that implements the SANE interface is called a
SANE {\em backend}.  A {\em meta backend\/} provides some means to
manage one or more other backends.


\chapter{The SANE Environment}\label{chap:environ}

SANE is defined as a C-callable library interface.  Accessing a raster
scanner device typically consists of two phases: first, various
controls of the scanner need to be setup or queried.  In the second
phase, one or more images are acquired.

Since the device controls are widely different from device to device,
SANE provides a generic interface that makes it easy for a frontend to
give a user access to all controls without having to understand each
and every device control.  The design principle used here is to
abstract each device control into a SANE {\em option\/}.  An option is
a self-describing name/value pair.  For example, the brightness
control of a camera might be represented by an option called
\code{brightness} whose value is an integer in the range from 0 to
255.

With self-describing options, a backend need not be concerned with
{\em presentation\/} issues: the backend simply provides a list of
options that describe all the controls available in the device.
Similarly, there are benefits to the frontend: it need not be
concerned with the {\em meaning\/} of each option.  It simply provides
means to present and alter the options defined by the backend.


\section{Attaching to a SANE backend}

The process through which a SANE frontend connects to a backend is
platform dependent.  Several possibilities exist:
\begin{itemize}

\item {\bf Static linking:} A SANE backend may be linked directly into
  a frontend.  While the simplest method of attaching to a backend, it
  is somewhat limited in functionality since the available devices is
  limited to the ones for which support has been linked in when the
  frontend was built.  But even so static linking can be quite useful,
  particularly when combined with a backend that can access scanners
  via a network.  Also, it is possible to support multiple backends
  simultaneously by implementing a meta backend that manages several
  backends that have been compiled in such a manner that they export
  unique function names.  For example, a backend called \code{be}
  would normally export a function called \code{sane\_read()}.  If
  each backend would provide such a function, static linking would
  fail due to multiple conflicting definitions of the same symbol.
  This can be resolved by having backend \code{be} include a
  header file that has lines of the form:
  \begin{quote}
\begin{verbatim}
#define sane_read be_sane_read
\end{verbatim}
  \end{quote}
  With definitions of this kind, backend \code{be} will export
  function name \code{be\_sane\_read()}.  Thus, all backends will
  export unique names.  As long as a meta backend knows about these
  names, it is possible to combine several backends at link time and
  select and use them dynamically at runtime.

\item {\bf Dynamic linking:} A simpler yet more powerful way to
  support multiple backends is to exploit dynamic linking on platforms
  that support it.  In this case, a frontend is linked against a
  shared library that implements any SANE backend.  Since each
  dynamically linked backend exports the same set of global symbols
  (all starting with the prefix \code{sane\_}), the dynamic library
  that gets loaded at runtime does not necessarily have to be the same
  one as one the frontend got linked against.  In other words, it is
  possible to switch the backend by installing the appropriate backend
  dynamic library.

  More importantly, dynamic linking makes it easy to implement a meta
  backend that loads other backends {\em on demand}.  This is a
  powerful mechanism since it allows adding new backends merely by
  installing a shared library and updating a configuration file.

\item {\bf Network connection:} Arguably the ultimate way to attach to
  a scanner is by using the network to connect to a backend on a
  remote machine.  This makes it possible to scan images from any host
  in the universe, as long as there is a network connection to that
  host and provided the user is permitted to access that scanner.

\end{itemize}

\begin{figure}[htbp]
  \begin{center}
    \leavevmode
    \psfig{file=figs/hierarchy.eps,angle=270,width=\textwidth}
    \caption{Example SANE Hiearchy}
    \label{fig:hierarchy}
  \end{center}
\end{figure}

The above discussion lists just a few ways for frontends to attach to
a backend.  It is of course possible to combine these solutions to
provide an entire hierarchy of SANE backends.  Such a hierarchy is
depicted in Figure~\ref{fig:hierarchy}.  The figure shows that machine
A uses a dynamic-linking based meta backend called \code{dll} to
access the backends called \code{pnm}, \code{mustek}, and \code{net}.
The first two are real backends, whereas the last one is a meta
backend that provides network transparent access to remote scanners.
In the figure, machine B provides non-local access to its scanners
through the SANE frontend called \code{saned}.  The \code{saned} in
turn has access to the \code{hp} and \code{autolum} backends through
another instance of the \code{dll} backend.  The \code{autolum} meta
backend is used to automatically adjust the luminance (brightness) of
the image data acquired by the camera backend called \code{qcam}.

Note that a meta backend really is both a frontend and a backend at
the same time.  It is a frontend from the viewpoint of the backends
that it manages and a backend from the viewpoint of the frontends that
access it.  The name ``meta backend'' was chosen primarily because the
SANE standard describes the interface from the viewpoint of a (real)
frontend.


\section{Image Data Format}\label{sec:imageformat}\index{image data format}

Arguably the most important aspect of an image acquisition system is
how images are represented.  The SANE approach is to define a simple
yet powerful representation that is sufficient for vast majority of
applications and devices.  While the representation is simple, the
interface has been defined carefully to allow extending it in the
future without breaking backwards compatibility.  Thus, it will be
possible to accommodate future applications or devices that were not
anticipated at the time this standard was created.

A SANE image is a rectangular area.  The rectangular area is
subdivided into a number of rows and columns.  At the intersection of
each row and column is a quadratic pixel.  A pixel consists of one or
more sample values.  Each sample value represents one channel (e.g.,
the red channel).  Each sample value has a certain bit depth.  The bit
depth is fixed for the entire image and can be as small as one bit.
Valid bit depths are 1, 8, or 16 bits per sample.  If a device's
natural bit depth is something else, it is up to the driver to scale
the sample values appropriately (e.g., a 4 bit sample could be scaled
by a factor of four to represent a sample value of depth 8).

\subsection{Image Transmission}

The SANE API transmits an image as a sequence of frames.  Each frame
covers the same rectangular area as the entire image, but may contain
only a subset of the channels in the final image.  For example, a
red/green/blue image could either be transmitted as a single frame
that contains the sample values for all three channels or it could be
transmitted as a sequence of three frames: the first frame containing
the red channel, the second the green channel, and the third the blue
channel.

Conceptually, each frame is transmitted a byte at a time.  Each byte
may contain 8 sample values (for an image bit depth of 1), one full
sample value (for an image bit depth of 8), or a partial sample value
(for an image bit depth of 16 or bigger).  In the latter case, the
bytes of each sample value are transmitted in the machine's native
byte order. For depth 1, the leftmost pixel is stored in the most
significant bit, and the rightmost pixel in the least significant bit.
\begin{quote}
  \begin{center}
    {\bf Backend Implementation Note}
  \end{center}
  A network-based meta backend will have to ensure that the byte order
  in image data is adjusted appropriately if necessary.  For example,
  when the meta backend attaches to the server proxy, the proxy may
  inform the backend of the server's byte order.  The backend can then
  apply the adjustment if necessary.  In essence, this implements a
  ``receiver-makes-right'' approach.
\end{quote}

\begin{figure}[htbp]
  \begin{center}
    \leavevmode
    \psfig{file=figs/xfer.eps,width=0.5\textwidth}
    \caption{Transfer order of image data bytes}
    \label{fig:xfer}
  \end{center}
\end{figure}

The order in which the sample values in a frame are transmitted is
illustrated in Figure~\ref{fig:xfer}.  As can be seen, the values are
transmitted row by row and each row is transmitted from left-most to
right-most column.  The left-to-right, top-to-bottom transmission
order applies when the image is viewed in its normal orientation (as
it would be displayed on a screen, for example).

If a frame contains multiple channels, then the channels are
transmitted in an interleaved fashion.  Figure~\ref{fig:pixels}
illustrates this for the case where a frame contains a complete
red/green/blue image with a bit-depth of 8.  For a bit depth of 1,
each byte contains 8 sample values of a {\em single\/} channel.  In
other words, a bit depth 1 frame is transmitted in a byte interleaved
fashion.

\begin{figure}[htbp]
  \begin{center}
    \leavevmode
    \psfig{file=figs/image-data.eps,width=0.8\textwidth}
    \caption{Bit and byte order or image data}
    \label{fig:pixels}
  \end{center}
\end{figure}

When transmitting an image frame by frame, the frontend needs to know
what part of the image a frame represents (and how many frames it
should expect).  For that purpose, the SANE API tags every frame with
a type.  This version of the SANE standard supports the following
frame types:
\begin{quote}
\begin{description}

\item[\code{\defn{SANE\_FRAME\_GRAY}}:] The frame contains a single
  channel of data that represents sample values from a spectral band
  that covers the human visual range.  The image consists of this
  frame only.

\item[\code{\defn{SANE\_FRAME\_RGB}}:] The frame contains three
  channels of data that represent sample values from the red, green,
  and blue spectral bands.  The sample values are interleaved in the
  order red, green, and blue.  The image consists of this frame only.

\item[\code{\defn{SANE\_FRAME\_RED}}:] The frame contains one channel
  of data that represents sample values from the red spectral band.
  The complete image consists of three frames:
  \code{SANE\_\-FRA\-ME\_RED}, \code{SANE\_FRAME\_GREEN}, and
  \code{SANE\_FRAME\_BLUE}.  The order in which the frames are
  transmitted chosen by the backend.

\item[\code{\defn{SANE\_FRAME\_GREEN}}:] The frame contains one
  channel of data that represents sample values from the green
  spectral band.  The complete image consists of three frames:
  \code{SANE\_\-FRA\-ME\_RED}, \code{SANE\_FRAME\_GREEN}, and
  \code{SANE\_FRAME\_BLUE}.  The order in which the frames are
  transmitted chosen by the backend.

\item[\code{\defn{SANE\_FRAME\_BLUE}}:] The frame contains one channel
  of data that represents sample values from the blue spectral band.
  The complete image consists of three frames:
  \code{SANE\_\-FRA\-ME\_RED}, \code{SANE\_FRAME\_GREEN}, and
  \code{SANE\_FRAME\_BLUE}.  The order in which the frames are
  transmitted chosen by the backend.

\end{description}
\end{quote}

In frames of type \code{SANE\_FRAME\_GRAY}, when the bit depth is 1 there are
only two sample values possible, 1 represents minimum intensity
(black) and 0 represents maximum intensity (white).  For all other bit
depth and frame type combinations, a sample value of 0 represents
minimum intensity and larger values represent increasing intensity.

The combination of bit depth 1 and \code{SANE\_FRAME\_RGB} (or
\code{SANE\_FRAME\_RED}, \code{SANE\_FRAME\_GREEN}, \code{SANE\_FRAME\_BLUE})
is rarely used and may not be supported by every frontend.

\chapter{The SANE Application Programmer Interface (API)}\label{chap:api}

This Section defines version 1 of the SANE application
programmer interface (API).  Any SANE frontend must depend on the
interface defined in this section only.  Converseley, 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 \filename{sane/sane.h}.  This file should
normally be included via a C pre-processor directive of the form:
\begin{verbatim}
  #include <sane/sane.h>
\end{verbatim}


\section{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 compatiblity 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 implementor
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.
\begin{quote}
  \begin{description}
  \item[\code{\defn{SANE\_CURRENT\_MAJOR}}:] The value of this macro is the
    number of the SANE standard that the interface implements.

  \item[\code{\defn{SANE\_VERSION\_CODE}(\var{maj},\var{min},\var{bld})}:]
    \label{sec:saneversioncode}
    This macro can be used to build a monotonically increasing version
    code.  A SANE version code consists of the SANE standard major
    version number (\var{maj}), the minor version number \var{min},
    and the build revision of a backend (\var{bld}).  The major and
    minor version numbers must be in the range 0\ldots255 and the
    build revision must be in the range 0\ldots65535.

    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.
  
  \item[\code{\defn{SANE\_VERSION\_MAJOR}(\var{vc})}:] This macro returns the
    major version number component of the version code passed in
    argument \var{vc}.
  \item[\code{SANE\_VERSION\_MINOR(\var{vc})}:] This macro returns the
    minor version number component of the version code passed in
    argument \var{vc}.
  \item[\code{SANE\_VERSION\_BUILD(\var{vc})}:] This macro returns the
    build revision component of the version code passed in argument
    \var{vc}.
  \end{description}
\end{quote}


\section{Data Types}

\subsection{Base Types}

The SANE standard is based on just two SANE-specific base types: the
SANE byte and word.
\begin{quote}
  \code{typedef \var{some-scalar-type\/} \defn{SANE\_Byte};} \\
  \code{typedef \var{some-scalar-type\/} \defn{SANE\_Word};}
\end{quote}
\verb|SANE_Byte| must correspond to some scalar C type that is capable
of holding values in the range 0 to 255.  \verb|SANE_Word| must be
capable of holding any of the following:
\begin{itemize}
  \item the truth values \verb|SANE_FALSE| and \verb|SANE_TRUE|
  \item signed integers in the range $-2^{31}\ldots2^{31}-1$
  \item fixed point values in the range $-32768\ldots32767.9999$ with
    a resolution of $1/65536$
  \item 32 bits (for bit sets)
\end{itemize}
Note that the SANE standard does not define what C type
\verb|SANE_Byte| and \verb|SANE_Word| map to.  For example, on some
platforms, the latter may map to \verb|long int| whereas on others it
may map to \verb|int|.  A portable SANE frontend or backend must
therefore not depend on a particular mapping.

\subsection{Boolean Type}

\code{\defn{SANE\_Bool}} is used for variables that can take one of
the two truth values \code{\defn{SANE\_FALSE}} and
\code{\defn{SANE\_TRUE}}.  The former value is defined to be 0,
whereas the latter is 1.\footnote{This is different from ANSI C where
  any non-zero integer value represents logical TRUE.} The C
declarations for this type are given below.
\begin{quote}
\begin{verbatim}
#define SANE_FALSE      0
#define SANE_TRUE       1
typedef SANE_Word SANE_Bool;
\end{verbatim}
\end{quote}
Note that \verb|SANE_Bool| is simply an alias of \verb|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
\verb|SANE_Bool| whenever a given variable or formal argument has a
fixed interpretation as a boolean object.

\subsection{Integer Type}

\code{\defn{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.
\begin{quote}
\begin{verbatim}
typedef SANE_Word SANE_Int;
\end{verbatim}
\end{quote}
Note that \verb|SANE_Int| is simply an alias of \verb|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
\verb|SANE_Int| whenever a given variable or formal argument has a
fixed interpretation as an integer object.


\subsection{Fixed-point Type}

\code{\defn{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.
\begin{quote}
\begin{verbatim}
#define SANE_FIXED_SCALE_SHIFT  16
typedef SANE_Word SANE_Fixed;
\end{verbatim}
\end{quote}
The macro \code{\defn{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 \verb|SANE_Fixed| is simply an alias of \verb|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
\verb|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.
\begin{quote}
  \begin{description}

  \item[\code{\defn{SANE\_FIX}(\var{d})}:] Returns the largest SANE
    fixed-point value that is smaller than the double value \var{d}.
    No range checking is performed.  If the value of \var{d} is out of
    range, the result is undefined.

  \item[\code{\defn{SANE\_UNFIX}(\var{w})}:] Returns the nearest
    double machine number that corresponds to fixed-point value
    \var{w}.

  \end{description}
\end{quote}
SANE does {\em not\/} require that the following two expressions hold
true (even if the values of \var{w} and \var{d} are in range):
\begin{quote}
\begin{verbatim}
SANE_UNFIX(SANE_FIX(d)) == d
SANE_FIX(SANE_UNFIX(w)) == w
\end{verbatim}
\end{quote}
In other words, conversion between fixed and double values may be
lossy.  It is therefore recommended to avoid repeated conversions
between the two representations.


\subsection{Text}

\subsubsection{Character Type}

Type \code{\defn{SANE\_Char}} represents a single text character or
symbol.  At present, this type maps directly to the underlying C
\verb|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(SANE_Char)==sizeof(char)|.
\begin{quote}
\begin{verbatim}
typedef char SANE_Char;
\end{verbatim}
\end{quote}

\subsubsection{String Type}

Type \code{\defn{SANE\_String}} represents a text string as a sequence
of C \verb|char| values.  The end of the sequence is indicated by a
\verb|'\0'| (\defn{NUL}) character.  
\begin{quote}
\begin{verbatim}
typedef SANE_Char *SANE_String;
typedef const SANE_Char *SANE_String_Const;
\end{verbatim}
\end{quote}
The type \code{\defn{SANE\_String\_Const}} is provided by SANE to
enable declaring strings whose contents is unchangable.  Note that in
ANSI C, the declaration
\begin{quote}
\begin{verbatim}
const SANE_String str;
\end{verbatim}
\end{quote}
declares a string pointer that is constant (not a string pointer that
points to a constant value).


\subsection{Scanner Handle Type}

Access to a scanner is provided through an opaque type called
\code{\defn{SANE\_Handle}}.  The C declaration of this type is given
below.
\begin{quote}
\begin{verbatim}
typedef void *SANE_Handle;
\end{verbatim}
\end{quote}
While this type is declared to be a void pointer, an application must
not attempt to interpret the value of a \verb|SANE_Handle|.  In
particular, SANE does not require that a value of this type is a legal
pointer value.


\subsection{Status Type}

Most SANE operations return a value of type \code{\defn{SANE\_Status}}
to indicate whether the completion status of the operation.  If an
operation completes successfully, \verb|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 \ref{tab:status}.  It is recommended to use function
\code{sane\_strstatus()} to convert status codes into a legible
string.

\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{|l|r|l|}
      \hline
      \multicolumn{1}{|c|}{\bf Symbol} & \multicolumn{1}{c|}{\bf Code} &
      \multicolumn{1}{c|}{\bf Description} \\
      \hline\hline
\code{\defn{SANE\_STATUS\_GOOD}}
        &  0 & Operation completed succesfully. \\
\code{\defn{SANE\_STATUS\_UNSUPPORTED}}
        &  1 & Operation is not supported. \\
\code{\defn{SANE\_STATUS\_CANCELLED}}
        &  2 & Operation was cancelled. \\
\code{\defn{SANE\_STATUS\_DEVICE\_BUSY}}
        &  3 & Device is busy---retry later. \\
\code{\defn{SANE\_STATUS\_INVAL}}
        &  4 & Data or argument is invalid. \\
\code{\defn{SANE\_STATUS\_EOF}}
        &  5 & No more data available (end-of-file). \\
\code{\defn{SANE\_STATUS\_JAMMED}}
        &  6 & Document feeder jammed. \\
\code{\defn{SANE\_STATUS\_NO\_DOCS}}
        &  7 & Document feeder out of documents. \\
\code{\defn{SANE\_STATUS\_COVER\_OPEN}}
        &  8 & Scanner cover is open. \\
\code{\defn{SANE\_STATUS\_IO\_ERROR}}
        &  9 & Error during device I/O. \\
\code{\defn{SANE\_STATUS\_NO\_MEM}}
        & 10 & Out of memory. \\
\code{\defn{SANE\_STATUS\_ACCESS\_DENIED}}
        & 11 & Access to resource has been denied. \\
      \hline
    \end{tabular}
    \caption{Status Codes}\label{tab:status}
  \end{center}
\end{table}


\subsection{Device Descriptor Type}

Each SANE device is represented by a structure of type
\code{\defn{SANE\_Device}}.  The C declaration of this type is given
below.
\begin{quote}
\begin{verbatim}
typedef struct
  {
    SANE_String_Const name;
    SANE_String_Const vendor;
    SANE_String_Const model;
    SANE_String_Const type;
  }
SANE_Device;
\end{verbatim}
\end{quote}
\index{device-name}
The structure provides the unique name of the scanner in member
\code{name}.  It is this unique name that should be passed in a call
to \code{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 {\em recommended\/} that backends keep
unique names below 32 characters in length.  However, applications
{\em must\/} be able to cope with arbitrary length unique names.

The remaining members in the device structure provide additional
information on the device corresponding to the unique name.
Specifically, members \code{vendor}, \code{model}, and \code{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):

\begin{table}[htbp]
  \begin{center}
    \leavevmode
    \hspace{\fill}
    \begin{tabular}[t]{|ll|}
      \hline
      \multicolumn{2}{|c|}{\bf \defn{Vendor Strings}} \\
      \hline\hline
      \code{AGFA}            & \code{Microtek} \\ 
      \code{Abaton}          & \code{Minolta} \\             
      \code{Acer}            & \code{Mitsubishi} \\  
      \code{Apple}           & \code{Mustek} \\      
      \code{Artec}           & \code{NEC} \\         
      \code{Avision}         & \code{Nikon} \\       
      \code{CANON}           & \code{Plustek} \\     
      \code{Connectix}       & \code{Polaroid} \\    
      \code{Epson}           & \code{Relisys} \\     
      \code{Fujitsu}         & \code{Ricoh} \\       
      \code{Hewlett-Packard} & \code{Sharp} \\       
      \code{IBM}             & \code{Siemens} \\     
      \code{Kodak}           & \code{Tamarack} \\    
      \code{Lexmark}	     & \code{UMAX} \\        
      \code{Logitech}        & \code{Noname} \\
      \hline
    \end{tabular}
    \hspace{\fill}
    \begin{tabular}[t]{|l|}
      \hline
      \multicolumn{1}{|c|}{\bf \defn{Type Strings}} \\
      \hline\hline
      \code{film scanner} \\
      \code{flatbed scanner} \\
      \code{frame grabber} \\
      \code{handheld scanner} \\
      \code{multi-function peripheral} \\
      \code{sheetfed scanner} \\
      \code{still camera} \\
      \code{video camera} \\
      \code{virtual device} \\
      \hline
    \end{tabular}
    \hspace{\fill}
    \caption{Predefined Device Information Strings}
    \label{tab:devinfo}
  \end{center}
\end{table}
Note that vendor string \code{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.


\subsection{Option Descriptor Type}\label{sec:odesc}

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
\code{\defn{SANE\_Option\_Descriptor}} type is given below.
\begin{quote}
\begin{verbatim}
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;
\end{verbatim}
\end{quote}

\subsubsection{Option Name}

Member \code{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 (\code{a}--\code{z}),
digits (\code{0}--\code{9}), or the dash character (\code{-}) only.
The first character must be a lower-case ASCII character (i.e., not a
digit or a dash).

\subsubsection{Option Title}

Member \code{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.

\subsubsection{Option Description}

Member \code{desc} is a (potentially very) long string that can be
used as a help text to describe the option.  It is the responsibility
of the frontend to break the string into managable-length lines.
Newline characters in this string should be interpreted as paragraph
breaks.

\subsubsection{Option Value Type}

Member \code{type} specifies the type of the option value.  The
possible values for type \code{\defn{SANE\_Value\_Type}} are described
in Table \ref{tab:valuetype}.

\begin{table}[htbp]
  \begin{center}
    \leavevmode
    \begin{tabular}{|l|l|p{0.6\textwidth}|}
\hline
\multicolumn{1}{|c|}{\bf Symbol} &
\multicolumn{1}{c|}{\bf Code} &
\multicolumn{1}{c|}{\bf Description} \\
\hline\hline

\code{\defn{SANE\_TYPE\_BOOL}} & 0 & Option value is of type
  \verb|SANE_Bool|. \\ 

\code{\defn{SANE\_TYPE\_INT}} & 1 & Option value is of type
  \verb|SANE_Int|. \\ 

\code{\defn{SANE\_TYPE\_FIXED}}&2 & Option value is of type
  \verb|SANE_Fixed|. \\ 

\code{\defn{SANE\_TYPE\_STRING}}&3 & Option value is of type
  \verb|SANE_String|. \\ 

\code{\defn{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. \\ 

\code{\defn{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 \code{title} and
\code{type} are valid in the option descriptor. \\ 

  \hline
    \end{tabular}
    \caption{Option Value Types (\code{SANE\_Value\_Type})}
    \label{tab:valuetype}
  \end{center}
\end{table}

\subsubsection{Option Value Unit}

Member \code{unit} specifies what the physical unit of the option
value is.  The possible values for type \code{\defn{SANE\_U\-nit}} are
described in Table \ref{tab:units}.  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).

\begin{table}[htbp]
  \begin{center}
    \leavevmode
    \begin{tabular}{|l|l|l|}
\hline
\multicolumn{1}{|c|}{\bf Symbol} &
\multicolumn{1}{|c|}{\bf Code} &
\multicolumn{1}{|c|}{\bf Description} \\

\hline\hline

\code{\defn{SANE\_UNIT\_NONE}}   & 0 & Value is unit-less (e.g., page count).\\
\code{\defn{SANE\_UNIT\_PIXEL}}  & 1 & Value is in number of pixels. \\
\code{\defn{SANE\_UNIT\_BIT}}    & 2 & Value is in number of bits. \\
\code{\defn{SANE\_UNIT\_MM}}     & 3 & Value is in millimeters. \\
\code{\defn{SANE\_UNIT\_DPI}}    & 4 & Value is a resolution in dots/inch. \\
\code{\defn{SANE\_UNIT\_PERCENT}}& 5 & Value is a percentage. \\
\code{\defn{SANE\_UNIT\_MICROSECOND}}& 6 & Value is time in $\mu$-seconds. \\

\hline
    \end{tabular}
    \caption{Physical Units (\code{SANE\_Unit})}
    \label{tab:units}
  \end{center}
\end{table}

\subsubsection{Option Value Size}\label{sec:valuesize}

Member \code{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:
\begin{quote}
  \begin{description}
  \item[\code{SANE\_TYPE\_STRING}:] The size is the maximum size of
    the string.  For the purpose of string size calcuations, the
    terminating \code{NUL} character is considered to be part of the
    string.  Note that the terminating \code{NUL} character must
    always be present in string option values.
  \item[\code{SANE\_TYPE\_INT}, \code{SANE\_TYPE\_FIXED}:] The size
    must be a positive integer multiple of the size of a
    \verb|SANE_Word|.  The option value is a vector of length
    \[ \code{size}/\code{sizeof(SANE\_Word)}. \]
  \item[\code{SANE\_TYPE\_BOOL}:] The size must be set to
    \code{sizeof(SANE\_Word)}.
  \item[\code{SANE\_TYPE\_BUTTON}, \code{SANE\_TYPE\_GROUP}:] The
    option size is ignored.
  \end{description}
\end{quote}

\subsubsection{Option Capabilities}

Member \code{cap} describes what capabilities the option posseses.
This is a bitset that is formed as the inclusive logical OR of the
capabilities described in Table \ref{tab:capabilities}.  The SANE API
provides the following to macros to test certain features of a given
capability bitset:
\begin{quote}
  \begin{description}

  \item[\code{\defn{SANE\_OPTION\_IS\_ACTIVE}(\var{cap})}:] This macro
    returns \code{SANE\_TRUE} if and only if the option with the
    capability set \var{cap} is currently active.

  \item[\code{\defn{SANE\_OPTION\_IS\_SETTABLE}(\var{cap})}:] This
    macro returns \code{SANE\_TRUE} if and only if the option with the
    capability set \var{cap} is software settable.
  \end{description}
\end{quote}

\begin{table}[htbp]
  \begin{center}
    \leavevmode
    \begin{tabular}{|l|r|p{0.59\textwidth}|}
\hline
\multicolumn{1}{|c|}{\bf Symbol} &
\multicolumn{1}{c|}{\bf Code} &
\multicolumn{1}{c|}{\bf Description} \\
\hline\hline

\code{\defn{SANE\_CAP\_SOFT\_SELECT}} & 1 & The option
  value can be set by a call to \code{sane\_con\-trol\_opt\-ion()}.\\ 

\code{\defn{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).  \\ 

\code{\defn{SANE\_CAP\_SOFT\_DETECT}} & 4 & The option
  value can be detected by software.  If
  \code{SANE\_\-CAP\_\-SO\-FT\_SEL\-ECT} is set, this capability {\em must\/}
  be set.  If \code{SANE\_CAP\_HARD\_SELECT} is set, this capability
  may or may not be set.  If this capability is set but neither
  \code{SANE\_CAP\_SO\-FT\_SEL\-ECT} nor \code{SANE\_CAP\_HA\-RD\_SEL\-ECT}
  are, then there is no way to control the option.  That is, the
  option provides read-out of the current value only.  \\ 

\code{\defn{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. \\ 

\code{\defn{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 \code{sane\_control\_option()}
  with an action value of \code{SANE\_ACTION\_SET\_AUTO}.  \\ 

\code{\defn{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). \\ 

\code{\defn{SANE\_CAP\_ADVANCED}} & 64 &
  If set, this capability indicates that the option should be
  considered an ``advanced user option.''  A frontend typically
  displays such options in a less conspicuous way than regular options
  (e.g., a command line interface may list such options last or a
  graphical interface may make them available in a seperate ``advanced
  settings'' dialog). 
  \\

\hline
    \end{tabular}
    \caption{Option Capabilities}
    \label{tab:capabilities}
  \end{center}
\end{table}

\subsubsection{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 \code{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 \code{constraint}.  The possible values of type
\code{\defn{SANE\_Constraint\_Type}} and the interpretation of the
\code{constraint} union is described in Table~\ref{tab:constraints}.

\begin{table}[htbp]
  \begin{center}
    \leavevmode
    \begin{tabular}{|l|r|p{0.5\textwidth}|}
\hline
\multicolumn{1}{|c|}{\bf Symbol} &
\multicolumn{1}{|c|}{\bf Code} &
\multicolumn{1}{|c|}{\bf Description} \\

\hline\hline

\code{\defn{SANE\_CONSTRAINT\_NONE}} & 0 & The value is unconstrained.
  The option can take any of the values possible for the option's
  type. \\

  \code{\defn{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 \code{constraint.range} points to
  a range of the type \code{\defn{SANE\_Range}}.  This type is illustrated
  below:
  \begin{quote}
\begin{verbatim}
typedef struct
  {
    SANE_Word min;
    SANE_Word max;
    SANE_Word quant;
  }
SANE_Range;
\end{verbatim}
  \end{quote}
  All three members in this structure are interpreted according to the
  option value type (\verb|SANE_TYPE_INT| or \verb|SANE_TYPE_FIXED|).
  Members \code{min} and \code{max} specify the minimum and maximum
  values, respectively.  If member \code{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$.  \\ 

\code{\defn{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
  \code{constraint.word\_list} points to a list of words that
  enumerates the legal values.  The first element in that list is an
  integer (\verb|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
  (\verb|SANE_TYPE_INT| or \verb|SANE_TYPE_FIXED|). \\ 

\code{\defn{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
  \code{con\-strai\-nt.str\-ing\_list} points to a \code{NULL} terminated
  list of strings that enumerate the legal values for the option
  value.
\\\hline
    \end{tabular}
    \caption{Option Value Constraints}
    \label{tab:constraints}
  \end{center}
\end{table}


\section{Operations}

\subsection{\code{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 \code{sane\_init} is different from
\code{\defn{SANE\_STATUS\_GOOD}}.  The version code of the backend is returned
in the value pointed to by \code{version\_code}.  If that pointer is
\code{NULL}, no version code is returned.  Argument \code{authorize} is either
a pointer to a function that is invoked when the backend requires
authentication for a specific resource or \code{NULL} if the frontend does not
support authentication.
\begin{quote}\index{sane\_init}
\begin{verbatim}
SANE_Status sane_init (SANE_Int * version_code,
                       SANE_Authorization_Callback authorize);
\end{verbatim}
\end{quote}

The authorization function may be called by a backend in response to
any of the following calls:
\begin{quote}
  \code{sane\_open}, \code{sane\_control\_option}, \code{sane\_start}
\end{quote}
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 apporpriate password based on
resource- and user-name.

The authentication function type has the following declaration:
\begin{quote}\index{SANE\_Authorization\_Callback}
  \index{domain}\index{username}\index{password}
\begin{verbatim}
#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]);
\end{verbatim}
\end{quote}
Three arguments are passed to the authorization function:
\code{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 \code{username}
and \code{password} arguments are (pointers to) an array of
\code{SANE\_MAX\_USERNAME\_LEN} and \code{SANE\_MAX\_PASSWORD\_LEN}
characters, respectively.  The authorization call should place the
entered username and password in these arrays.  The returned strings
{\em must\/} be ASCII-NUL terminated.

\subsection{\code{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 \code{sane\_clo\-se()}, but backends are required to release all
resources upon a call to this function).  After this function returns,
no function other than \code{sane\_init()} may be called (regardless
of the status value returned by \code{sane\_exit()}.  Neglecting to
call this function may result in some resources not being released
properly.
\begin{quote}\index{sane\_exit}
\begin{verbatim}
void sane_exit (void);
\end{verbatim}
\end{quote}


\subsection{\code{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 \code{NULL} terminated array of pointers to \verb|SANE_Device|
structures in \code{*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 \code{sane\_exit()} is performed.  This
function can be called repeatedly to detect when new devices become
available.  If argument \code{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.
\begin{quote}\index{sane\_get\_devices}
\begin{verbatim}
SANE_Status sane_get_devices (const SANE_Device *** device_list,
                              SANE_Bool local_only);
\end{verbatim}
\end{quote}

This function may fail with \code{SANE\_STATUS\_NO\_MEM} if an
insufficient amount of memory is available.

\begin{quote}
  \begin{center}
    {\bf Backend Implementation Note}
  \end{center}
  SANE does not require that this function is called before a
  \code{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.
\end{quote}


\subsection{\code{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
\code{name}.  If the call completes successfully, a handle for the
device is returned in \code{*h}.  As a special case, specifying a
zero-length string as the device requests opening the first available
device (if there is such a device).
\begin{quote}\index{sane\_open}
\begin{verbatim}
SANE_Status sane_open (SANE_String_Const name, SANE_Handle * h);
\end{verbatim}
\end{quote}

This function may fail with one of the following status codes.
\begin{quote}
\begin{description}
\item[\code{SANE\_STATUS\_DEVICE\_BUSY}:] The device is currently
  busy (in use by somebody else).
\item[\code{SANE\_STATUS\_INVAL}:] The device name is not valid.
\item[\code{SANE\_STATUS\_IO\_ERROR}:] An error occured while
  communicating with the device.
\item[\code{SANE\_STATUS\_NO\_MEM}:] An insufficent amount of memory
  is available.
\item[\code{SANE\_STATUS\_ACCESS\_DENIED}:] Access to the device has
  been denied due to insufficient or invalid authentication.
\end{description}
\end{quote}


\subsection{\code{sane\_close}}

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

\begin{quote}\index{sane\_close}
\begin{verbatim}
void sane_close (SANE_Handle h);
\end{verbatim}
\end{quote}

\subsection{\code{sane\_get\_option\_descriptor}}

This function is used to access option descriptors.  The function
returns the option descriptor for option number \code{n} of the device
represented by handle \code{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 \code{h} (the count
includes option 0).  If $n$ is not a valid option index, the function
returns \code{NULL}.  The returned option descriptor is guaranteed to
remain valid (and at the returned address) until the device is closed.

\begin{quote}\index{sane\_get\_option\_descriptor}
\begin{verbatim}
const SANE_Option_Descriptor *
    sane_get_option_descriptor (SANE_Handle h, SANE_Int n);
\end{verbatim}
\end{quote}

\subsection{\code{sane\_control\_option}}\label{sec:control}

This function is used to set or inquire the current value of option
number \code{n} of the device represented by handle \code{h}.  The
manner in which the option is controlled is specified by parameter
\code{a}.  The possible values of this parameter are described in more
detail below.  The value of the option is passed through argument
\code{v}.  It is a pointer to the memory that holds the option value.
The memory area pointed to by \code{v} must be big enough to hold the
entire option value (determined by member \code{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 \code{v} may be shorter since the backend will stop
reading the option value upon encountering the first \code{NUL}
terminator in the string.  If argument \code{i} is not \code{NULL},
the value of \code{*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.
\begin{quote}\index{sane\_control\_option}
\begin{verbatim}
SANE_Status sane_control_option (SANE_Handle h, SANE_Int n,
                                 SANE_Action a, void *v,
                                 SANE_Int * i);
\end{verbatim}
\end{quote}

The way the option is affected by a call to this function is
controlled by parameter \code{a} which is a value of type
\code{\defn{SANE\_Action}}.  The possible values and their meaning is
described in Table~\ref{tab:actions}.

\begin{table}[h]
  \begin{center}
    \leavevmode
    \begin{tabular}{|l|r|p{0.5\textwidth}|}
\hline
\multicolumn{1}{|c|}{\bf Symbol} &
\multicolumn{1}{|c|}{\bf Code} &
\multicolumn{1}{|c|}{\bf Description} \\

\hline\hline

\code{\defn{SANE\_ACTION\_GET\_VALUE}} & 0 & Get current option value. \\

\code{\defn{SANE\_ACTION\_SET\_VALUE}} & 1 & Set option value.  The
  option value passed through argument \code{v} may be modified by the
  backend if the value cannot be set exactly.  \\ 

\code{\defn{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 \code{v} is completely ignored in this case and
  may be \code{NULL}.  \\

\hline
    \end{tabular}
    \caption{Action Values (\code{SANE\_Action})}
    \label{tab:actions}
  \end{center}
\end{table}

After setting a value via an action value of
\verb|SANE_ACTION_SET_VALUE|, additional information on how well the
request has been met is returned in \code{*i} (if \code{i} is
non-\code{NULL}).  The returned value is a bitset that may contain any
combination of the values described in Table~\ref{tab:info}.
\begin{table}[htbp]
  \begin{center}
    \leavevmode
    \begin{tabular}{|l|r|p{0.5\textwidth}|}
\hline
\multicolumn{1}{|c|}{\bf Symbol} &
\multicolumn{1}{|c|}{\bf Code} &
\multicolumn{1}{|c|}{\bf Description} \\

\hline\hline

\code{\defn{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 \code{*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. \\

  \code{\defn{SANE\_INFO\_RELOAD\_OPTIONS}} & 2 & The setting of an
  option may affect the value or availability of one or more {\em
    other\/} options.  When this happens, the SANE backend sets this
  member in \code{*i} to indicate that the application should reload
  all options.  This member may be set if and only if at least one
  option changed. \\

\code{\defn{SANE\_INFO\_RELOAD\_PARAMS}} & 4 & The setting of an option may
  affect the parameter values (see \code{sane\_get\_parameters()}).
  If setting an option affects the parameter values, this member will
  be set in \code{*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. \\

\hline
    \end{tabular}
    \caption{Additional Information Returned When Setting an Option}
    \label{tab:info}
  \end{center}
\end{table}

This function may fail with one of the following status codes.
\begin{quote}
\begin{description}
\item[\code{SANE\_STATUS\_UNSUPPORTED}:] The operation is not
  supported for the specified handle and option number.
\item[\code{SANE\_STATUS\_INVAL}:] The option value is not valid.
\item[\code{SANE\_STATUS\_IO\_ERROR}:] An error occured while
  communicating with the device.
\item[\code{SANE\_STATUS\_NO\_MEM}:] An insufficent amount of memory
  is available.
\item[\code{SANE\_STATUS\_ACCESS\_DENIED}:] Access to the option has
  been denied due to insufficient or invalid authentication.
\end{description}
\end{quote}



\subsection{\code{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 (\code{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
\code{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 \code{h} of the device for which the
parameters should be obtained and a pointer \code{p} to a parameter
structure.  The parameter structure is described in more detail below.

\begin{quote}\index{sane\_get\_parameters}
\begin{verbatim}
SANE_Status sane_get_parameters (SANE_Handle h,
                                 SANE_Parameters * p);
\end{verbatim}
\end{quote}

The scan parameters are returned in a structure of type
\code{\defn{SANE\_Parameters}}.  The C declaration of this structure
is given below.
\begin{quote}
\begin{verbatim}
typedef struct
  {
    SANE_Frame format;
    SANE_Bool last_frame;
    SANE_Int bytes_per_line;
    SANE_Int pixels_per_line;
    SANE_Int lines;
    SANE_Int depth;
  }
SANE_Parameters;
\end{verbatim}
\end{quote}

Member \code{format} specifies the format of the next frame to be
returned.  The possible values for type \code{\defn{SANE\_Frame}} are
described in Table~\ref{tab:frameformat}.  The meaning of these
values is described in more detail in Section~\ref{sec:imageformat}.
\begin{table}[htbp]
  \begin{center}
    \leavevmode
    \begin{tabular}{|l|r|l|}
\hline
\multicolumn{1}{|c|}{\bf Symbol} &
\multicolumn{1}{|c|}{\bf Code} &
\multicolumn{1}{|c|}{\bf Description} \\

\hline\hline

\code{\defn{SANE\_FRAME\_GRAY}} & 0 & Band covering human visual range. \\
\code{\defn{SANE\_FRAME\_RGB}} & 1 & Pixel-interleaved red/green/blue bands. \\
\code{\defn{SANE\_FRAME\_RED}} & 2 & Red band of a red/green/blue image. \\
\code{\defn{SANE\_FRAME\_GREEN}} & 3 & Green band of a red/green/blue image. \\
\code{\defn{SANE\_FRAME\_BLUE}} & 4 & Blue band of a red/green/blue image. \\

\hline
    \end{tabular}
    \caption{Frame Format (\code{SANE\_Frame})}
    \label{tab:frameformat}
  \end{center}
\end{table}

Member \code{last\_frame} is set to \code{SANE\_TRUE} 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 last frame of a
multi frame image (e.g., the current frame is the blue component of a
red, green, blue image).

Member \code{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 \code{sane\_read()} until it
returns a status of \code{SANE\_STATUS\_EOF}.

Member \code{bytes\_per\_line} specifies the number of bytes that
comprise one scan line.

Member \code{depth} specifies the number of bits per sample.

Member \code{pixels\_per\_line} specifies the number of pixels that
comprise one scan line.

Assume $B$ is the number of channels in the frame, then the bit depth
$d$ (as given by member \code{depth}) and the number of pixels per
line $n$ (as given by this member \code{pixels\_per\_line}) are
related to $c$, the number of bytes per line (as given by member
\code{bytes\_per\_line}) as follows:
\[
  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.
\]
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.


\subsection{\code{sane\_start}}

This function initiates aquisition of an image from the device
represented by handle \code{h}.
\begin{quote}\index{sane\_start}
\begin{verbatim}
SANE_Status sane_start (SANE_Handle h);
\end{verbatim}
\end{quote}
This function may fail with one of the following status codes.
\begin{quote}
\begin{description}
\item[\code{SANE\_STATUS\_CANCELLED}:] The operation was cancelled through
  a call to \code{sane\_cancel}.
\item[\code{SANE\_STATUS\_DEVICE\_BUSY}:] The device is busy. The
  operation should be retried later.
\item[\code{SANE\_STATUS\_JAMMED}:] The document feeder is jammed.
\item[\code{SANE\_STATUS\_NO\_DOCS}:] The document feeder is out of
  documents.
\item[\code{SANE\_STATUS\_COVER\_OPEN}:] The scanner cover is open.
\item[\code{SANE\_STATUS\_IO\_ERROR}:] An error occurred while communicating
  with the device.
\item[\code{SANE\_STATUS\_NO\_MEM}:] An insufficent amount of memory
  is available.
\item[\code{SANE\_STATUS\_INVAL}:] The scan cannot be started with the current
  set of options. The frontend should reload the option descriptors, as if
  \code{\defn{SANE\_INFO\_RELOAD\_OPTIONS}} had been returned from a call to
  \code{sane\_control\_option()}, since the device's capabilities may have
  changed.
\end{description}
\end{quote}


\subsection{\code{sane\_read}}

This function is used to read image data from the device represented
by handle \code{h}.  Argument \code{buf} is a pointer to a memory area
that is at least \code{maxlen} bytes long.  The number of bytes
returned is stored in \code{*len}.  A backend must set this to zero
when a status other than \code{SANE\_STA\-TUS\_GOOD} is returned.
When the call succeeds, the number of bytes returned can be anywhere in
the range from 0 to \code{maxlen} bytes.
\begin{quote}\index{sane\_read}
\begin{verbatim}
SANE_Status sane_read (SANE_Handle h, SANE_Byte * buf,
                       SANE_Int maxlen, SANE_Int * len);
\end{verbatim}
\end{quote}
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 \code{h}.
\begin{enumerate}
\item 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).

\item If the device is in non-blocking I/O mode, the call returns
  immediately with status \code{SANE\_STA\-TUS\_GOOD} and with
  \code{*len} set to zero.
\end{enumerate}
The I/O mode of handle \code{h} can be set via a call to
\code{sane\_set\_io\_mode()}.

This function may fail with one of the following status codes.
\begin{quote}
\begin{description}
\item[\code{SANE\_STATUS\_CANCELLED}:] The operation was cancelled through
  a call to \code{sane\_cancel}.
\item[\code{SANE\_STATUS\_EOF}:] No more data is available for the
  current frame.
\item[\code{SANE\_STATUS\_JAMMED}:] The document feeder is jammed.
\item[\code{SANE\_STATUS\_NO\_DOCS}:] The document feeder is out of
  documents.
\item[\code{SANE\_STATUS\_COVER\_OPEN}:] The scanner cover is open.
\item[\code{SANE\_STATUS\_IO\_ERROR}:] An error occurred while communicating
  with the device.
\item[\code{SANE\_STATUS\_NO\_MEM}:] An insufficent amount of memory
  is available.
\item[\code{SANE\_STATUS\_ACCESS\_DENIED}:] Access to the device has
  been denied due to insufficient or invalid authentication.
\end{description}
\end{quote}


\subsection{\code{sane\_cancel}}

This function is used to immediately or as quickly as possible cancel
the currently pending operation of the device represented by handle
\code{h}.
\begin{quote}\index{sane\_cancel}
\begin{verbatim}
void sane_cancel (SANE_Handle h);
\end{verbatim}
\end{quote}
This function can be called at any time (as long as handle \code{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 operaton does {\em not\/} imply that
the currently pending operation has been cancelled.  It only
guarantees that cancellation has been {\em initiated}.  Cancellation
completes only when the cancelled call returns (typically with a
status value of \code{SANE\_STATUS\_CANCELLED}).  Since the SANE API
does not require any other operations to be re-entrant, this implies
that a frontend must {\em not\/} call any other operation until the
cancelled operation has returned.


\subsection{\code{sane\_set\_io\_mode}}

This function is used to set the I/O mode of handle \code{h}.  The I/O mode
can be either blocking or non-blocking.  If argument \code{m} is
\code{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
\code{sane\_start()} has been performed.
\begin{quote}\index{sane\_set\_io\_mode}
\begin{verbatim}
SANE_Status sane_set_io_mode (SANE_Handle h, SANE_Bool m);
\end{verbatim}
\end{quote}
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 \code{SANE\_STATUS\_UNSUPPORTED} is returned.  Blocking
I/O must be supported by all backends, so calling this function with
argument \code{m} set to \code{SANE\_FALSE} is guaranteed to complete
successfully.

This function may fail with one of the following status codes:
\begin{quote}
\begin{description}
\item[\code{SANE\_STATUS\_INVAL}:] No image acquisition is pending.
\item[\code{SANE\_STATUS\_UNSUPPORTED}:] The backend does not support
  the requested I/O mode.
\end{description}
\end{quote}


\subsection{\code{sane\_get\_select\_fd}}

This function is used to obtain a (platform-specific) file-descriptor
for handle \code{h} that is readable if and only if image data is
available (i.e., when a call to \code{sane\_read()} will return at
least one byte of data).  If the call completes successfully, the
select file-descriptor is returned in \code{*fd}.
\begin{quote}\index{sane\_get\_select\_fd}
\begin{verbatim}
SANE_Status sane_get_select_fd (SANE_Handle h, SANE_Int *fd);
\end{verbatim}
\end{quote}
This function can be called only after a call to \code{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 \code{sane\_cancel()} or \code{sane\_start()} get called again
or until \code{sane\_read()} returns with status
\code{SANE\_STA\-TUS\_EOF}).  Indeed, a backend must guarantee to
close the returned select file descriptor at the point when the next
\code{sane\_read()} call would return \code{SANE\_STA\-TUS\_EOF}.
This is necessary to ensure the application can detect when this
condition occurs without actually having to call \code{sane\_read()}.

A backend may elect not to support this operation.  In such a case,
the function returns with status code
\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 \code{select()}
or \code{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 \code{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:
\begin{quote}
\begin{description}
\item[\code{SANE\_STATUS\_INVAL}:] No image acquisition is pending.
\item[\code{SANE\_STATUS\_UNSUPPORTED}:] The backend does not support
  this operation.
\end{description}
\end{quote}


\subsection{\code{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 \code{NULL}.
The returned pointer is valid at least until the next call to this
function is performed.
\begin{quote}\index{sane\_strstatus}
\begin{verbatim}
const SANE_String_Const sane_strstatus (SANE_Status status);
\end{verbatim}
\end{quote}

\section{Code Flow}\index{code flow}

The code flow for the SANE API is illustrated in
Figure~\ref{fig:flow}.  Functions \code{sane\_init()} and
\code{sane\_exit()} initialize and exit the backend, respectively.
All other calls must be performed after initialization and before
exiting the backend.

\begin{figure}[htb]
  \begin{center}
    \leavevmode
    \psfig{file=figs/flow.eps,height=0.5\textheight}
    \caption{Code flow}
    \label{fig:flow}
  \end{center}
\end{figure}

Function \code{sane\_get\_devices()} can be called any time after
\code{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
\code{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 \code{sane\_get\_opt\-ion\_desc\-riptor()} and
\code{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.  However, as options are set, other options
may become active or inactive.  Thus, after setting an option, it
maybe necessary to re-read some or all option descriptors.  While
setting up the device, it is also admissible to call
\code{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 \code{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 \code{sane\_start()}.  The backend calculates the exact
image parameters at this point.  So future calls to
\code{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 \code{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
\code{sane\_set\_io\_mode()} and/or \code{sane\_get\_select\_fd()} at
this point.  Either of these functions may fail if the backend does
not support the requested operation.

Image data is collected by repeatedly calling \code{sane\_read()}.
Eventually, this function will return an end-of-file status
(\code{SANE\_STATUS\_EOF}).  This indicates the end of the current
frame.  If the frontend expects additional frames (e.g., the
individual channels in of a red/green/blue image or multiple images),
it can call \code{sane\_start()} again.  Once all desired frames have
been acquired, function \code{sane\_cancel()} must be called.  This
operation can also be called at any other time to cancel a pending
operation.  Note that \code{sane\_cancel()} must be called even if the
last read operation returned \code{SANE\_STATUS\_EOF}.

When done using the device, the handle should be closed by a call to
\code{sane\_close()}.  Finally, before exiting the application,
function \code{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.


\section{Well-Known Options}\index{well-known options}

While most backend options are completely self-describing, there are a
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 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.

\subsection{Option Number Count}\index{option count}

Option number 0 has an empty string as its name.  The value of this
option is of type \code{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
\code{sane\_get\_option\_descriptor()} returns \code{NULL}, or a
frontend can directly read out the value of option number 0.

\subsection{Scan Resolution Option}\index{scan resolution}\index{resolution option}

Option \code{resolution} is used to select the resolution at which an
image should be acquired.  The type of this option is either
\code{SANE\_TYPE\_INT} or \code{SANE\_TYPE\_FIXED}.  The unit is
\code{SANE\_UNIT\_DPI} (dots/inch).

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

\subsection{Preview Mode Option}\index{preview mode}

The boolean option \code{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 \code{SANE\_TRUE},
preview mode is in effect, when set to \code{SANE\_FALSE} image
acquisition should proceed in normal quality mode.  The setting of
this option \emph{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 \code{resolution}).  A backend is free to override the
\code{resolution} value with its own choice for preview mode, but it
is advised to leave this choice to the frontend wherever 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.

\subsection{Scan Area Options}\index{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~\ref{fig:area}.  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 {\em smallest} and the bottom-right corner is the
corner for which the abscissa and ordinate values are simulatenously
the {\em largest}.  If this coordinate system is not natural for a
given device, it is the job of the backend to perform the necessary
conversions.
\begin{figure}[tbp]
  \begin{center}
    \leavevmode
    \psfig{file=figs/area.eps,height=0.3\textheight}
    \caption{Scan area options}
    \label{fig:area}
  \end{center}
\end{figure}

The names of the four options that define the scan area are given in
the table below:
\begin{center}
\begin{tabular}{ll}
{\bf Name} & {\bf Description} \\
\code{\defn{tl-x}} & Top-left $x$ coordinate value \\
\code{\defn{tl-y}} & Top-left $y$ coordinate value \\
\code{\defn{br-x}} & Bottom-right $x$ coordinate value \\
\code{\defn{br-y}} & Bottom-right $y$ coordinate value \\
\end{tabular}
\end{center}
There are several rules that should be followed by front and backends
regarding these options:
\begin{itemize}

\item Backends must attach a unit of either pixels
  (\code{SANE\_UNIT\_PIXEL}) or millimeters (\code{SANE\_UNIT\_MM}) to
  these options.  The unit of all four options must be identical.

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

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

\item A frontend must work properly with any or all of these options
  missing.
  
\end{itemize}

\input{net.tex}

\chapter{Contact Information}\label{chap:contact}

The SANE standard is discussed and evolved via a mailing list.
Anybody with email access to the Internet can automatically join and
leave the discussion group by sending mail to the following address.
\begin{quote}\index{mailing list}
\begin{verbatim}
sane-devel-request@lists.alioth.debian.org
\end{verbatim}
\end{quote}
To subscribe, send a mail with the body ``\verb|subscribe sane-devel|'' to the
above address.

A complete list of commands supported can be obtained by sending a
mail with a subject of ``\code{help}'' to the above address.  The
mailing list is archived and available through the SANE home page at
URL:
\begin{quote}
\url{http://www.sane-project.org/}
\end{quote}

\newpage
\input{sane.ind}

\end{document}