kopia lustrzana https://gitlab.com/sane-project/website
Added SANE standard.
Henning Geinitz
rodzic
5025eb1545
commit
1fa4d8cfd4
|
|
@ -0,0 +1,116 @@
|
|||
<html><body>
|
||||
<a href="doc001.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<img src=../icons/up_gr.gif border=2 alt="Previous"></a>
|
||||
<img src=../icons/previous_gr.gif border=2 alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
<title>Contents</title>
|
||||
<h1>Contents</h1><p>
|
||||
|
||||
<table>
|
||||
<tr></tr><tr><td colspan=20>1<tt> </tt><a href="doc002.html#s1"><b>Preface</b></a></td></tr>
|
||||
<tr><td></td><td colspan=20>1.1<tt> </tt><a href="doc003.html#s1.1">About This Document</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>1.1.1<tt> </tt><a href="doc003.html#s1.1.1">Typographic Conventions</a></td></tr>
|
||||
<tr></tr><tr><td colspan=20>2<tt> </tt><a href="doc004.html#s2"><b>Introduction</b></a></td></tr>
|
||||
<tr><td></td><td colspan=20>2.1<tt> </tt><a href="doc005.html#s2.1">Terminology</a></td></tr>
|
||||
<tr></tr><tr><td colspan=20>3<tt> </tt><a href="doc006.html#s3"><b>The SANE Environment</b></a></td></tr>
|
||||
<tr><td></td><td colspan=20>3.1<tt> </tt><a href="doc007.html#s3.1">Attaching to a SANE backend</a></td></tr>
|
||||
<tr><td></td><td colspan=20>3.2<tt> </tt><a href="doc008.html#s3.2">Image Data Format</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>3.2.1<tt> </tt><a href="doc008.html#s3.2.1">Image Transmission</a></td></tr>
|
||||
<tr></tr><tr><td colspan=20>4<tt> </tt><a href="doc009.html#s4"><b>The SANE Application Programmer Interface (API)</b></a></td></tr>
|
||||
<tr><td></td><td colspan=20>4.1<tt> </tt><a href="doc010.html#s4.1">Version Control</a></td></tr>
|
||||
<tr><td></td><td colspan=20>4.2<tt> </tt><a href="doc011.html#s4.2">Data Types</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.1<tt> </tt><a href="doc011.html#s4.2.1">Base Types</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.2<tt> </tt><a href="doc011.html#s4.2.2">Boolean Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.3<tt> </tt><a href="doc011.html#s4.2.3">Integer Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.4<tt> </tt><a href="doc011.html#s4.2.4">Fixed-point Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.5<tt> </tt><a href="doc011.html#s4.2.5">Text</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.5.1<tt> </tt><a href="doc011.html#s4.2.5.1">Character Type</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.5.2<tt> </tt><a href="doc011.html#s4.2.5.2">String Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.6<tt> </tt><a href="doc011.html#s4.2.6">Scanner Handle Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.7<tt> </tt><a href="doc011.html#s4.2.7">Status Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.8<tt> </tt><a href="doc011.html#s4.2.8">Device Descriptor Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.9<tt> </tt><a href="doc011.html#s4.2.9">Option Descriptor Type</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.1<tt> </tt><a href="doc011.html#s4.2.9.1">Option Name</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.2<tt> </tt><a href="doc011.html#s4.2.9.2">Option Title</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.3<tt> </tt><a href="doc011.html#s4.2.9.3">Option Description</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.4<tt> </tt><a href="doc011.html#s4.2.9.4">Option Value Type</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.5<tt> </tt><a href="doc011.html#s4.2.9.5">Option Value Unit</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.6<tt> </tt><a href="doc011.html#s4.2.9.6">Option Value Size</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.7<tt> </tt><a href="doc011.html#s4.2.9.7">Option Capabilities</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.8<tt> </tt><a href="doc011.html#s4.2.9.8">Option Value Constraints</a></td></tr>
|
||||
<tr><td></td><td colspan=20>4.3<tt> </tt><a href="doc012.html#s4.3">Operations</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.1<tt> </tt><a href="doc012.html#s4.3.1"><tt>sane_init</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.2<tt> </tt><a href="doc012.html#s4.3.2"><tt>sane_exit</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.3<tt> </tt><a href="doc012.html#s4.3.3"><tt>sane_get_devices</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.4<tt> </tt><a href="doc012.html#s4.3.4"><tt>sane_open</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.5<tt> </tt><a href="doc012.html#s4.3.5"><tt>sane_close</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.6<tt> </tt><a href="doc012.html#s4.3.6"><tt>sane_get_option_descriptor</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.7<tt> </tt><a href="doc012.html#s4.3.7"><tt>sane_control_option</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.8<tt> </tt><a href="doc012.html#s4.3.8"><tt>sane_get_parameters</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.9<tt> </tt><a href="doc012.html#s4.3.9"><tt>sane_start</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.10<tt> </tt><a href="doc012.html#s4.3.10"><tt>sane_read</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.11<tt> </tt><a href="doc012.html#s4.3.11"><tt>sane_cancel</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.12<tt> </tt><a href="doc012.html#s4.3.12"><tt>sane_set_io_mode</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.13<tt> </tt><a href="doc012.html#s4.3.13"><tt>sane_get_select_fd</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.14<tt> </tt><a href="doc012.html#s4.3.14"><tt>sane_strstatus</tt></a></td></tr>
|
||||
<tr><td></td><td colspan=20>4.4<tt> </tt><a href="doc013.html#s4.4">Code Flow</a></td></tr>
|
||||
<tr><td></td><td colspan=20>4.5<tt> </tt><a href="doc014.html#s4.5">Well-Known Options</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.1<tt> </tt><a href="doc014.html#s4.5.1">Option Number Count</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.2<tt> </tt><a href="doc014.html#s4.5.2">Scan Resolution Option</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.3<tt> </tt><a href="doc014.html#s4.5.3">Preview Mode Option</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.4<tt> </tt><a href="doc014.html#s4.5.4">Scan Area Options</a></td></tr>
|
||||
<tr></tr><tr><td colspan=20>5<tt> </tt><a href="doc015.html#s5"><b>Network Protocol</b></a></td></tr>
|
||||
<tr><td></td><td colspan=20>5.1<tt> </tt><a href="doc016.html#s5.1">Data Type Encoding</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.1.1<tt> </tt><a href="doc016.html#s5.1.1">Primitive Data Types</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.1.2<tt> </tt><a href="doc016.html#s5.1.2">Type Constructors</a></td></tr>
|
||||
<tr><td></td><td colspan=20>5.2<tt> </tt><a href="doc017.html#s5.2">Remote Procedure Call Requests</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.1<tt> </tt><a href="doc017.html#s5.2.1"><tt>SANE_NET_INIT<a name="i128"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.2<tt> </tt><a href="doc017.html#s5.2.2"><tt>SANE_NET_GET_DEVICES<a name="i130"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.3<tt> </tt><a href="doc017.html#s5.2.3"><tt>SANE_NET_OPEN<a name="i132"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.4<tt> </tt><a href="doc017.html#s5.2.4"><tt>SANE_NET_CLOSE<a name="i134"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.5<tt> </tt><a href="doc017.html#s5.2.5"><tt>SANE_NET_GET_OPTION_DESCRIPTORS<a name="i136"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.6<tt> </tt><a href="doc017.html#s5.2.6"><tt>SANE_NET_CONTROL_OPTION<a name="i139"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.7<tt> </tt><a href="doc017.html#s5.2.7"><tt>SANE_NET_GET_PARAMETERS<a name="i141"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.8<tt> </tt><a href="doc017.html#s5.2.8"><tt>SANE_NET_START<a name="i143"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.9<tt> </tt><a href="doc017.html#s5.2.9"><tt>SANE_NET_CANCEL<a name="i145"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.10<tt> </tt><a href="doc017.html#s5.2.10"><tt>SANE_NET_AUTHORIZE<a name="i147"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.11<tt> </tt><a href="doc017.html#s5.2.11"><tt>SANE_NET_EXIT<a name="i150"></tt></a></td></tr>
|
||||
<tr></tr><tr><td colspan=20>6<tt> </tt><a href="doc018.html#s6"><b>Contact Information</b></a></td></tr>
|
||||
</table>
|
||||
|
||||
<h1>List of Figures</h1>
|
||||
|
||||
<table>
|
||||
<tr><td>1</td><td><a href="doc007.html#f1">Example SANE Hiearchy</a></td></tr>
|
||||
<tr><td>2</td><td><a href="doc008.html#f2">Transfer order of image data bytes</a></td></tr>
|
||||
<tr><td>3</td><td><a href="doc008.html#f3">Bit and byte order or image data</a></td></tr>
|
||||
<tr><td>4</td><td><a href="doc013.html#f4">Code flow</a></td></tr>
|
||||
<tr><td>5</td><td><a href="doc014.html#f5">Scan area options</a></td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
<h1>List of Tables</h1>
|
||||
|
||||
<table>
|
||||
<tr><td>1</td><td><a href="doc011.html#f1">Status Codes</a></td></tr>
|
||||
<tr><td>2</td><td><a href="doc011.html#f2">Predefined Device Information Strings</a></td></tr>
|
||||
<tr><td>3</td><td><a href="doc011.html#f3">Option Value Types (<tt>SANE_Value_Type</tt>)</a></td></tr>
|
||||
<tr><td>4</td><td><a href="doc011.html#f4">Physical Units (<tt>SANE_Unit</tt>)</a></td></tr>
|
||||
<tr><td>5</td><td><a href="doc011.html#f5">Option Capabilities</a></td></tr>
|
||||
<tr><td>6</td><td><a href="doc011.html#f6">Option Value Constraints</a></td></tr>
|
||||
<tr><td>7</td><td><a href="doc012.html#f7">Action Values (<tt>SANE_Action</tt>)</a></td></tr>
|
||||
<tr><td>8</td><td><a href="doc012.html#f8">Additional Information Returned When Setting an Option</a></td></tr>
|
||||
<tr><td>9</td><td><a href="doc012.html#f9">Frame Format (<tt>SANE_Frame</tt>)</a></td></tr>
|
||||
</table>
|
||||
|
||||
<p><hr>
|
||||
<a href="doc001.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<img src=../icons/up_gr.gif border=2 alt="Previous"></a>
|
||||
<img src=../icons/previous_gr.gif border=2 alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,56 @@
|
|||
<html><body>
|
||||
<a href="doc002.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc000.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
<title>./sane</title>
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
<p>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
<p><center><h1><font size=+4>SANE Standard Version 1.03</font></h1></center>
|
||||
<center></center>
|
||||
<center>2003-02-22</center>
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
<p><h1><a href="doc002.html">1 Preface</a></h1><h1><a href="doc004.html">2 Introduction</a></h1><h1><a href="doc006.html">3 The SANE Environment</a></h1><h1><a href="doc009.html">4 The SANE Application Programmer Interface (API)</a></h1><h1><a href="doc015.html">5 Network Protocol</a></h1><h1><a href="doc018.html">6 Contact Information</a></h1><p><hr>
|
||||
<a href="doc002.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc000.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
<html><body>
|
||||
<a href="doc003.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc001.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Preface</title>
|
||||
<h1><a name="s1">1 Preface</a></h1>
|
||||
|
||||
<p>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
|
||||
<a href="doc018.html#s6">6</a>.
|
||||
|
||||
<p>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.
|
||||
|
||||
<p><h2><a href="doc003.html">1.1 About This Document</a></h2><p><hr>
|
||||
<a href="doc003.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc001.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,42 @@
|
|||
<html><body>
|
||||
<a href="doc004.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc002.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>About This Document</title>
|
||||
<h2><a name="s1.1">1.1 About This Document</a></h2>
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>The remainder of this document is organized as follows.
|
||||
Chapter <a href="doc004.html#s2">2</a> provides introductional material.
|
||||
Chapter <a href="doc006.html#s3">3</a> presents the environment SANE is designed
|
||||
for. Chapter <a href="doc009.html#s4">4</a> details the SANE Application Programmer
|
||||
Interface. Chapter <a href="doc015.html#s5">5</a> specifies the network protocol that
|
||||
can be used to implement the SANE API in a network transparent
|
||||
fashion. Finally, Chapter <a href="doc018.html#s6">6</a> gives information on how
|
||||
to join the SANE development process.
|
||||
|
||||
<p><h3><a name="s1.1.1">1.1.1 Typographic Conventions</a></h3>
|
||||
|
||||
<p>Changes since the last revision of this document are highlighted
|
||||
like this:
|
||||
|
||||
<p>
|
||||
<p><hr>
|
||||
<a href="doc004.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc002.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
<html><body>
|
||||
<a href="doc005.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc003.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Introduction</title>
|
||||
<h1><a name="s2">2 Introduction</a></h1>
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>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.
|
||||
|
||||
<p><h2><a href="doc005.html">2.1 Terminology</a></h2><p><hr>
|
||||
<a href="doc005.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc003.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
<html><body>
|
||||
<a href="doc006.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc004.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Terminology</title>
|
||||
<h2><a name="s2.1">2.1 Terminology</a></h2>
|
||||
|
||||
<p>An application that uses the SANE interface is called a SANE <em>
|
||||
frontend</em>. A driver that implements the SANE interface is called a
|
||||
SANE <em>backend</em>. A <em>meta backend</em> provides some means to
|
||||
manage one or more other backends.
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc006.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc004.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
<html><body>
|
||||
<a href="doc007.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc005.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>The SANE Environment</title>
|
||||
<h1><a name="s3">3 The SANE Environment</a></h1>
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>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</em>. An option is
|
||||
a self-describing name/value pair. For example, the brightness
|
||||
control of a camera might be represented by an option called
|
||||
<tt>brightness</tt> whose value is an integer in the range from 0 to
|
||||
255.
|
||||
|
||||
<p>With self-describing options, a backend need not be concerned with
|
||||
<em>presentation</em> 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</em> of each option. It simply provides
|
||||
means to present and alter the options defined by the backend.
|
||||
|
||||
<p><h2><a href="doc007.html">3.1 Attaching to a SANE backend</a></h2><h2><a href="doc008.html">3.2 Image Data Format</a></h2><p><hr>
|
||||
<a href="doc007.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc005.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,104 @@
|
|||
<html><body>
|
||||
<a href="doc008.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc006.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Attaching to a SANE backend</title>
|
||||
<h2><a name="s3.1">3.1 Attaching to a SANE backend</a></h2>
|
||||
|
||||
<p>The process through which a SANE frontend connects to a backend is
|
||||
platform dependent. Several possibilities exist:
|
||||
<ul>
|
||||
|
||||
<p><li><b>Static linking:</b> 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 <tt>be</tt>
|
||||
would normally export a function called <tt>sane_read()</tt>. 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 <tt>be</tt> include a
|
||||
header file that has lines of the form:
|
||||
<blockquote>
|
||||
<pre>
|
||||
#define sane_read be_sane_read
|
||||
</pre>
|
||||
</blockquote>
|
||||
With definitions of this kind, backend <tt>be</tt> will export
|
||||
function name <tt>be_sane_read()</tt>. 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.
|
||||
|
||||
<p><li><b>Dynamic linking:</b> 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 <tt>sane_</tt>), 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.
|
||||
|
||||
<p> More importantly, dynamic linking makes it easy to implement a meta
|
||||
backend that loads other backends <em>on demand</em>. This is a
|
||||
powerful mechanism since it allows adding new backends merely by
|
||||
installing a shared library and updating a configuration file.
|
||||
|
||||
<p><li><b>Network connection:</b> 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.
|
||||
|
||||
<p></ul>
|
||||
|
||||
<p><p><a name="f1"></a>
|
||||
<center>
|
||||
|
||||
<img width=780 height=384 src="img000.gif">
|
||||
<p><center>Figure 1: Example SANE Hiearchy</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>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 <a href="doc007.html#f1">1</a>. The figure shows that machine
|
||||
A uses a dynamic-linking based meta backend called <tt>dll</tt> to
|
||||
access the backends called <tt>pnm</tt>, <tt>mustek</tt>, and <tt>net</tt>.
|
||||
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 <tt>saned</tt>. The <tt>saned</tt> in
|
||||
turn has access to the <tt>hp</tt> and <tt>autolum</tt> backends through
|
||||
another instance of the <tt>dll</tt> backend. The <tt>autolum</tt> meta
|
||||
backend is used to automatically adjust the luminance (brightness) of
|
||||
the image data acquired by the camera backend called <tt>qcam</tt>.
|
||||
|
||||
<p>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.
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc008.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc006.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,154 @@
|
|||
<html><body>
|
||||
<a href="doc009.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc007.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Image Data Format</title>
|
||||
<h2><a name="s3.2">3.2 Image Data Format</a></h2><a name="i0">
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>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).
|
||||
|
||||
<p><h3><a name="s3.2.1">3.2.1 Image Transmission</a></h3>
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>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.
|
||||
<blockquote>
|
||||
<center>
|
||||
<b>Backend Implementation Note</b>
|
||||
</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.
|
||||
</blockquote>
|
||||
|
||||
<p><p><a name="f2"></a>
|
||||
<center>
|
||||
|
||||
<img width=390 height=196 src="img001.gif">
|
||||
<p><center>Figure 2: Transfer order of image data bytes</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>The order in which the sample values in a frame are transmitted is
|
||||
illustrated in Figure <a href="doc008.html#f2">2</a>. 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).
|
||||
|
||||
<p>If a frame contains multiple channels, then the channels are
|
||||
transmitted in an interleaved fashion. Figure <a href="doc008.html#f3">3</a>
|
||||
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</em> channel. In
|
||||
other words, a bit depth 1 frame is transmitted in a byte interleaved
|
||||
fashion.
|
||||
|
||||
<p><p><a name="f3"></a>
|
||||
<center>
|
||||
|
||||
<img width=624 height=111 src="img002.gif">
|
||||
<p><center>Figure 3: Bit and byte order or image data</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>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:
|
||||
<blockquote>
|
||||
<dl>
|
||||
|
||||
<p><dt><tt>SANE_FRAME_GRAY<a name="i1"></tt>:<dd> 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.
|
||||
|
||||
<p><dt><tt>SANE_FRAME_RGB<a name="i2"></tt>:<dd> 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.
|
||||
|
||||
<p><dt><tt>SANE_FRAME_RED<a name="i3"></tt>:<dd> The frame contains one channel
|
||||
of data that represents sample values from the red spectral band.
|
||||
The complete image consists of three frames:
|
||||
<tt>SANE_FRAME_RED</tt>, <tt>SANE_FRAME_GREEN</tt>, and
|
||||
<tt>SANE_FRAME_BLUE</tt>. The order in which the frames are
|
||||
transmitted chosen by the backend.
|
||||
|
||||
<p><dt><tt>SANE_FRAME_GREEN<a name="i4"></tt>:<dd> The frame contains one
|
||||
channel of data that represents sample values from the green
|
||||
spectral band. The complete image consists of three frames:
|
||||
<tt>SANE_FRAME_RED</tt>, <tt>SANE_FRAME_GREEN</tt>, and
|
||||
<tt>SANE_FRAME_BLUE</tt>. The order in which the frames are
|
||||
transmitted chosen by the backend.
|
||||
|
||||
<p><dt><tt>SANE_FRAME_BLUE<a name="i5"></tt>:<dd> The frame contains one channel
|
||||
of data that represents sample values from the blue spectral band.
|
||||
The complete image consists of three frames:
|
||||
<tt>SANE_FRAME_RED</tt>, <tt>SANE_FRAME_GREEN</tt>, and
|
||||
<tt>SANE_FRAME_BLUE</tt>. The order in which the frames are
|
||||
transmitted chosen by the backend.
|
||||
|
||||
<p></dl>
|
||||
</blockquote>
|
||||
|
||||
<p>In frames of type <tt>SANE_FRAME_GRAY</tt>, 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.
|
||||
|
||||
<p>The combination of bit depth 1 and <tt>SANE_FRAME_RGB</tt> (or
|
||||
<tt>SANE_FRAME_RED</tt>, <tt>SANE_FRAME_GREEN</tt>, <tt>SANE_FRAME_BLUE</tt>)
|
||||
is rarely used and may not be supported by every frontend.
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc009.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc007.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
<html><body>
|
||||
<a href="doc010.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc008.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>The SANE Application Programmer Interface (API)</title>
|
||||
<h1><a name="s4">4 The SANE Application Programmer Interface (API)</a></h1>
|
||||
|
||||
<p>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 <tt>sane/sane.h</tt>. This file should
|
||||
normally be included via a C pre-processor directive of the form:
|
||||
<pre>
|
||||
#include <sane/sane.h>
|
||||
</pre>
|
||||
|
||||
<p><h2><a href="doc010.html">4.1 Version Control</a></h2><h2><a href="doc011.html">4.2 Data Types</a></h2><h2><a href="doc012.html">4.3 Operations</a></h2><h2><a href="doc013.html">4.4 Code Flow</a></h2><h2><a href="doc014.html">4.5 Well-Known Options</a></h2><p><hr>
|
||||
<a href="doc010.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc008.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,77 @@
|
|||
<html><body>
|
||||
<a href="doc011.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc009.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Version Control</title>
|
||||
<h2><a name="s4.1">4.1 Version Control</a></h2>
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>The SANE API provides the following five macros to manage version
|
||||
numbers.
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_CURRENT_MAJOR<a name="i6"></tt>:<dd> The value of this macro is the
|
||||
number of the SANE standard that the interface implements.
|
||||
|
||||
<p> <dt><tt>SANE_VERSION_CODE<a name="i7">(<i>maj</i>,<i>min</i>,<i>bld</i>)</tt>:<dd>
|
||||
|
||||
This macro can be used to build a monotonically increasing version
|
||||
code. A SANE version code consists of the SANE standard major
|
||||
version number (<i>maj</i>), the minor version number <i>min</i>,
|
||||
and the build revision of a backend (<i>bld</i>). The major and
|
||||
minor version numbers must be in the range 0...255 and the
|
||||
build revision must be in the range 0...65535.
|
||||
|
||||
<p> 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.
|
||||
|
||||
<p> 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.
|
||||
|
||||
<dt><tt>SANE_VERSION_MAJOR<a name="i8">(<i>vc</i>)</tt>:<dd> This macro returns the
|
||||
major version number component of the version code passed in
|
||||
argument <i>vc</i>.
|
||||
<dt><tt>SANE_VERSION_MINOR(<i>vc</i>)</tt>:<dd> This macro returns the
|
||||
minor version number component of the version code passed in
|
||||
argument <i>vc</i>.
|
||||
<dt><tt>SANE_VERSION_BUILD(<i>vc</i>)</tt>:<dd> This macro returns the
|
||||
build revision component of the version code passed in argument
|
||||
<i>vc</i>.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc011.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc009.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,878 @@
|
|||
<html><body>
|
||||
<a href="doc012.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc010.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Data Types</title>
|
||||
<h2><a name="s4.2">4.2 Data Types</a></h2>
|
||||
|
||||
<p><h3><a name="s4.2.1">4.2.1 Base Types</a></h3>
|
||||
|
||||
<p>The SANE standard is based on just two SANE-specific base types: the
|
||||
SANE byte and word.
|
||||
<blockquote>
|
||||
<tt>typedef <i>some-scalar-type</i> SANE_Byte<a name="i9">;</tt> <br>
|
||||
<tt>typedef <i>some-scalar-type</i> SANE_Word<a name="i10">;</tt>
|
||||
</blockquote>
|
||||
<tt>SANE_Byte</tt> must correspond to some scalar C type that is capable
|
||||
of holding values in the range 0 to 255. <tt>SANE_Word</tt> must be
|
||||
capable of holding any of the following:
|
||||
<ul>
|
||||
<li>the truth values <tt>SANE_FALSE</tt> and <tt>SANE_TRUE</tt>
|
||||
<li>signed integers in the range -2<sup>31</sup>...2<sup>31</sup>-1
|
||||
<li>fixed point values in the range -32768...32767.9999 with
|
||||
a resolution of 1/65536
|
||||
<li>32 bits (for bit sets)
|
||||
</ul>
|
||||
Note that the SANE standard does not define what C type
|
||||
<tt>SANE_Byte</tt> and <tt>SANE_Word</tt> map to. For example, on some
|
||||
platforms, the latter may map to <tt>long int</tt> whereas on others it
|
||||
may map to <tt>int</tt>. A portable SANE frontend or backend must
|
||||
therefore not depend on a particular mapping.
|
||||
|
||||
<p><h3><a name="s4.2.2">4.2.2 Boolean Type</a></h3>
|
||||
|
||||
<p><tt>SANE_Bool<a name="i11"></tt> is used for variables that can take one of
|
||||
the two truth values <tt>SANE_FALSE<a name="i12"></tt> and
|
||||
<tt>SANE_TRUE<a name="i13"></tt>. The former value is defined to be 0,
|
||||
whereas the latter is 1.<a name="F1"><a href="footnotes.html#000001"><sup><fontsize=-2>1</font></sup></a></a> The C
|
||||
declarations for this type are given below.
|
||||
<blockquote>
|
||||
<pre>
|
||||
#define SANE_FALSE 0
|
||||
#define SANE_TRUE 1
|
||||
typedef SANE_Word SANE_Bool;
|
||||
</pre>
|
||||
</blockquote>
|
||||
Note that <tt>SANE_Bool</tt> is simply an alias of <tt>SANE_Word</tt>. It
|
||||
is therefore always legal to use the latter type in place of the
|
||||
former. However, for clarity, it is recommended to use
|
||||
<tt>SANE_Bool</tt> whenever a given variable or formal argument has a
|
||||
fixed interpretation as a boolean object.
|
||||
|
||||
<p><h3><a name="s4.2.3">4.2.3 Integer Type</a></h3>
|
||||
|
||||
<p><tt>SANE_Int<a name="i14"></tt> is used for variables that can take integer
|
||||
values in the range -2<sup>32</sup> to 2<sup>31</sup>-1. Its C declaration is
|
||||
given below.
|
||||
<blockquote>
|
||||
<pre>
|
||||
typedef SANE_Word SANE_Int;
|
||||
</pre>
|
||||
</blockquote>
|
||||
Note that <tt>SANE_Int</tt> is simply an alias of <tt>SANE_Word</tt>. It
|
||||
is therefore always legal to use the latter type in place of the
|
||||
former. However, for clarity, it is recommended to use
|
||||
<tt>SANE_Int</tt> whenever a given variable or formal argument has a
|
||||
fixed interpretation as an integer object.
|
||||
|
||||
<p><h3><a name="s4.2.4">4.2.4 Fixed-point Type</a></h3>
|
||||
|
||||
<p><tt>SANE_Fixed<a name="i15"></tt> 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.
|
||||
<blockquote>
|
||||
<pre>
|
||||
#define SANE_FIXED_SCALE_SHIFT 16
|
||||
typedef SANE_Word SANE_Fixed;
|
||||
</pre>
|
||||
</blockquote>
|
||||
The macro <tt>SANE_FIXED_SCALE_SHIFT<a name="i16"></tt> gives the location
|
||||
of the fixed binary point. This standard defines that value to be 16,
|
||||
which yields a resolution of 1/65536.
|
||||
|
||||
<p>Note that <tt>SANE_Fixed</tt> is simply an alias of <tt>SANE_Word</tt>.
|
||||
It is therefore always legal to use the latter type in place of the
|
||||
former. However, for clarity, it is recommended to use
|
||||
<tt>SANE_Fixed</tt> whenever a given variable or formal argument has a
|
||||
fixed interpretation as a fixed-point object.
|
||||
|
||||
<p>For convenience, SANE also defines two macros that convert fixed-point
|
||||
values to and from C double floating point values.
|
||||
<blockquote>
|
||||
<dl>
|
||||
|
||||
<p> <dt><tt>SANE_FIX<a name="i17">(<i>d</i>)</tt>:<dd> Returns the largest SANE
|
||||
fixed-point value that is smaller than the double value <i>d</i>.
|
||||
No range checking is performed. If the value of <i>d</i> is out of
|
||||
range, the result is undefined.
|
||||
|
||||
<p> <dt><tt>SANE_UNFIX<a name="i18">(<i>w</i>)</tt>:<dd> Returns the nearest
|
||||
double machine number that corresponds to fixed-point value
|
||||
<i>w</i>.
|
||||
|
||||
<p> </dl>
|
||||
</blockquote>
|
||||
SANE does <em>not</em> require that the following two expressions hold
|
||||
true (even if the values of <i>w</i> and <i>d</i> are in range):
|
||||
<blockquote>
|
||||
<pre>
|
||||
SANE_UNFIX(SANE_FIX(d)) == d
|
||||
SANE_FIX(SANE_UNFIX(w)) == w
|
||||
</pre>
|
||||
</blockquote>
|
||||
In other words, conversion between fixed and double values may be
|
||||
lossy. It is therefore recommended to avoid repeated conversions
|
||||
between the two representations.
|
||||
|
||||
<p><h3><a name="s4.2.5">4.2.5 Text</a></h3>
|
||||
|
||||
<p><h4><a name="s4.2.5.1">4.2.5.1 Character Type</a></h4>
|
||||
|
||||
<p>Type <tt>SANE_Char<a name="i19"></tt> represents a single text character or
|
||||
symbol. At present, this type maps directly to the underlying C
|
||||
<tt>char</tt> 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
|
||||
<tt>sizeof(SANE_Char)==sizeof(char)</tt>.
|
||||
<blockquote>
|
||||
<pre>
|
||||
typedef char SANE_Char;
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><h4><a name="s4.2.5.2">4.2.5.2 String Type</a></h4>
|
||||
|
||||
<p>Type <tt>SANE_String<a name="i20"></tt> represents a text string as a sequence
|
||||
of C <tt>char</tt> values. The end of the sequence is indicated by a
|
||||
<tt>'\0'</tt> (NUL<a name="i21">) character.
|
||||
<blockquote>
|
||||
<pre>
|
||||
typedef SANE_Char *SANE_String;
|
||||
typedef const SANE_Char *SANE_String_Const;
|
||||
</pre>
|
||||
</blockquote>
|
||||
The type <tt>SANE_String_Const<a name="i22"></tt> is provided by SANE to
|
||||
enable declaring strings whose contents is unchangable. Note that in
|
||||
ANSI C, the declaration
|
||||
<blockquote>
|
||||
<pre>
|
||||
const SANE_String str;
|
||||
</pre>
|
||||
</blockquote>
|
||||
declares a string pointer that is constant (not a string pointer that
|
||||
points to a constant value).
|
||||
|
||||
<p><h3><a name="s4.2.6">4.2.6 Scanner Handle Type</a></h3>
|
||||
|
||||
<p>Access to a scanner is provided through an opaque type called
|
||||
<tt>SANE_Handle<a name="i23"></tt>. The C declaration of this type is given
|
||||
below.
|
||||
<blockquote>
|
||||
<pre>
|
||||
typedef void *SANE_Handle;
|
||||
</pre>
|
||||
</blockquote>
|
||||
While this type is declared to be a void pointer, an application must
|
||||
not attempt to interpret the value of a <tt>SANE_Handle</tt>. In
|
||||
particular, SANE does not require that a value of this type is a legal
|
||||
pointer value.
|
||||
|
||||
<p><h3><a name="s4.2.7">4.2.7 Status Type</a></h3>
|
||||
|
||||
<p>Most SANE operations return a value of type <tt>SANE_Status<a name="i24"></tt>
|
||||
to indicate whether the completion status of the operation. If an
|
||||
operation completes successfully, <tt>SANE_STATUS_GOOD</tt> 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 <a href="doc011.html#t1">1</a>. It is recommended to use function
|
||||
<tt>sane_strstatus()</tt> to convert status codes into a legible
|
||||
string.
|
||||
|
||||
<p><p><a name="t1"></a>
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Code</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<tt>SANE_STATUS_GOOD<a name="i25"></tt>
|
||||
</td>
|
||||
<td colspan=1 align=right nowrap> 0 </td>
|
||||
<td colspan=1 align=left nowrap> Operation completed succesfully. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_STATUS_UNSUPPORTED<a name="i26"></tt>
|
||||
</td>
|
||||
<td colspan=1 align=right nowrap> 1 </td>
|
||||
<td colspan=1 align=left nowrap> Operation is not supported. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_STATUS_CANCELLED<a name="i27"></tt>
|
||||
</td>
|
||||
<td colspan=1 align=right nowrap> 2 </td>
|
||||
<td colspan=1 align=left nowrap> Operation was cancelled. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_STATUS_DEVICE_BUSY<a name="i28"></tt>
|
||||
</td>
|
||||
<td colspan=1 align=right nowrap> 3 </td>
|
||||
<td colspan=1 align=left nowrap> Device is busy---retry later. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_STATUS_INVAL<a name="i29"></tt>
|
||||
</td>
|
||||
<td colspan=1 align=right nowrap> 4 </td>
|
||||
<td colspan=1 align=left nowrap> Data or argument is invalid. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_STATUS_EOF<a name="i30"></tt>
|
||||
</td>
|
||||
<td colspan=1 align=right nowrap> 5 </td>
|
||||
<td colspan=1 align=left nowrap> No more data available (end-of-file). </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_STATUS_JAMMED<a name="i31"></tt>
|
||||
</td>
|
||||
<td colspan=1 align=right nowrap> 6 </td>
|
||||
<td colspan=1 align=left nowrap> Document feeder jammed. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_STATUS_NO_DOCS<a name="i32"></tt>
|
||||
</td>
|
||||
<td colspan=1 align=right nowrap> 7 </td>
|
||||
<td colspan=1 align=left nowrap> Document feeder out of documents. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_STATUS_COVER_OPEN<a name="i33"></tt>
|
||||
</td>
|
||||
<td colspan=1 align=right nowrap> 8 </td>
|
||||
<td colspan=1 align=left nowrap> Scanner cover is open. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_STATUS_IO_ERROR<a name="i34"></tt>
|
||||
</td>
|
||||
<td colspan=1 align=right nowrap> 9 </td>
|
||||
<td colspan=1 align=left nowrap> Error during device I/O. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_STATUS_NO_MEM<a name="i35"></tt>
|
||||
</td>
|
||||
<td colspan=1 align=right nowrap> 10 </td>
|
||||
<td colspan=1 align=left nowrap> Out of memory. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_STATUS_ACCESS_DENIED<a name="i36"></tt>
|
||||
</td>
|
||||
<td colspan=1 align=right nowrap> 11 </td>
|
||||
<td colspan=1 align=left nowrap> Access to resource has been denied. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
</td></tr>
|
||||
</table>
|
||||
<p><center>Table 1: Status Codes</center>
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p><h3><a name="s4.2.8">4.2.8 Device Descriptor Type</a></h3>
|
||||
|
||||
<p>Each SANE device is represented by a structure of type
|
||||
<tt>SANE_Device<a name="i37"></tt>. The C declaration of this type is given
|
||||
below.
|
||||
<blockquote>
|
||||
<pre>
|
||||
typedef struct
|
||||
{
|
||||
SANE_String_Const name;
|
||||
SANE_String_Const vendor;
|
||||
SANE_String_Const model;
|
||||
SANE_String_Const type;
|
||||
}
|
||||
SANE_Device;
|
||||
</pre>
|
||||
</blockquote>
|
||||
<a name="i38">
|
||||
The structure provides the unique name of the scanner in member
|
||||
<tt>name</tt>. It is this unique name that should be passed in a call
|
||||
to <tt>sane_open()</tt>. 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</em> that backends keep
|
||||
unique names below 32 characters in length. However, applications
|
||||
<em>must</em> be able to cope with arbitrary length unique names.
|
||||
|
||||
<p>The remaining members in the device structure provide additional
|
||||
information on the device corresponding to the unique name.
|
||||
Specifically, members <tt>vendor</tt>, <tt>model</tt>, and <tt>type</tt> 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):
|
||||
|
||||
<p><p><a name="t2"></a>
|
||||
<center>
|
||||
|
||||
<spacer type=horizontal size=72>
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=2 align=center nowrap><b>Vendor Strings<a name="i39"></b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<tt>AGFA</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>Minolta</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>Abaton</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>Mitsubishi</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>Acer</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>Mustek</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>Apple</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>NEC</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>Artec</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>Nikon</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>Avision</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>Plustek</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>CANON</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>Polaroid</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>Connectix</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>Relisys</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>Epson</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>Ricoh</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>Fujitsu</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>Sharp</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>Hewlett-Packard</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>Siemens</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>IBM</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>Tamarack</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>Kodak</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>UMAX</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>Logitech</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>Noname</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>Microtek</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap> </td>
|
||||
<td colspan=1 align=left nowrap> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
</td></tr>
|
||||
</table>
|
||||
<spacer type=horizontal size=72>
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=center nowrap><b>Type Strings<a name="i40"></b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<tt>film scanner</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>flatbed scanner</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>frame grabber</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>handheld scanner</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>multi-function peripheral</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>sheetfed scanner</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>still camera</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>video camera</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>virtual device</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
</td></tr>
|
||||
</table>
|
||||
<spacer type=horizontal size=72>
|
||||
<p><center>Table 2: Predefined Device Information Strings</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
Note that vendor string <tt>Noname</tt> 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.
|
||||
|
||||
<p><h3><a name="s4.2.9">4.2.9 Option Descriptor Type</a></h3>
|
||||
|
||||
<p>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
|
||||
<tt>SANE_Option_Descriptor<a name="i41"></tt> type is given below.
|
||||
<blockquote>
|
||||
<pre>
|
||||
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;
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><h4><a name="s4.2.9.1">4.2.9.1 Option Name</a></h4>
|
||||
|
||||
<p>Member <tt>name</tt> 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 (<tt>a</tt>--<tt>z</tt>),
|
||||
digits (<tt>0</tt>--<tt>9</tt>), or the dash character (<tt>-</tt>) only.
|
||||
The first character must be a lower-case ASCII character (i.e., not a
|
||||
digit or a dash).
|
||||
|
||||
<p><h4><a name="s4.2.9.2">4.2.9.2 Option Title</a></h4>
|
||||
|
||||
<p>Member <tt>title</tt> 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.
|
||||
|
||||
<p><h4><a name="s4.2.9.3">4.2.9.3 Option Description</a></h4>
|
||||
|
||||
<p>Member <tt>desc</tt> 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.
|
||||
|
||||
<p><h4><a name="s4.2.9.4">4.2.9.4 Option Value Type</a></h4>
|
||||
|
||||
<p>Member <tt>type</tt> specifies the type of the option value. The
|
||||
possible values for type <tt>SANE_Value_Type<a name="i42"></tt> are described
|
||||
in Table <a href="doc011.html#t3">3</a>.
|
||||
|
||||
<p><p><a name="t3"></a>
|
||||
<center>
|
||||
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Code</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
|
||||
<p><tt>SANE_TYPE_BOOL<a name="i43"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> 0 </td>
|
||||
<td colspan=1 align=left> Option value is of type
|
||||
<tt>SANE_Bool</tt>. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_TYPE_INT<a name="i44"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> 1 </td>
|
||||
<td colspan=1 align=left> Option value is of type
|
||||
<tt>SANE_Int</tt>. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_TYPE_FIXED<a name="i45"></tt></td>
|
||||
<td colspan=1 align=left nowrap>2 </td>
|
||||
<td colspan=1 align=left> Option value is of type
|
||||
<tt>SANE_Fixed</tt>. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_TYPE_STRING<a name="i46"></tt></td>
|
||||
<td colspan=1 align=left nowrap>3 </td>
|
||||
<td colspan=1 align=left> Option value is of type
|
||||
<tt>SANE_String</tt>. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_TYPE_BUTTON<a name="i47"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> 4 </td>
|
||||
<td colspan=1 align=left> 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. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_TYPE_GROUP<a name="i48"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> 5 </td>
|
||||
<td colspan=1 align=left> 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 <tt>title</tt> and
|
||||
<tt>type</tt> are valid in the option descriptor. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
</td></tr>
|
||||
</table>
|
||||
<p><center>Table 3: Option Value Types (<tt>SANE_Value_Type</tt>)</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p><h4><a name="s4.2.9.5">4.2.9.5 Option Value Unit</a></h4>
|
||||
|
||||
<p>Member <tt>unit</tt> specifies what the physical unit of the option
|
||||
value is. The possible values for type <tt>SANE_Unit<a name="i49"></tt> are
|
||||
described in Table <a href="doc011.html#t4">4</a>. 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).
|
||||
|
||||
<p><p><a name="t4"></a>
|
||||
<center>
|
||||
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Code</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
|
||||
<p><tt>SANE_UNIT_NONE<a name="i50"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> 0 </td>
|
||||
<td colspan=1 align=left nowrap> Value is unit-less (e.g., page count).</td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_UNIT_PIXEL<a name="i51"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> 1 </td>
|
||||
<td colspan=1 align=left nowrap> Value is in number of pixels. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_UNIT_BIT<a name="i52"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> 2 </td>
|
||||
<td colspan=1 align=left nowrap> Value is in number of bits. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_UNIT_MM<a name="i53"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> 3 </td>
|
||||
<td colspan=1 align=left nowrap> Value is in millimeters. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_UNIT_DPI<a name="i54"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> 4 </td>
|
||||
<td colspan=1 align=left nowrap> Value is a resolution in dots/inch. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_UNIT_PERCENT<a name="i55"></tt></td>
|
||||
<td colspan=1 align=left nowrap> 5 </td>
|
||||
<td colspan=1 align=left nowrap> Value is a percentage. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_UNIT_MICROSECOND<a name="i56"></tt></td>
|
||||
<td colspan=1 align=left nowrap> 6 </td>
|
||||
<td colspan=1 align=left nowrap> Value is time in µ-seconds. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
</td></tr>
|
||||
</table>
|
||||
<p><center>Table 4: Physical Units (<tt>SANE_Unit</tt>)</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p><h4><a name="s4.2.9.6">4.2.9.6 Option Value Size</a></h4>
|
||||
|
||||
<p>Member <tt>size</tt> specifies the size of the option value (in bytes).
|
||||
This member has a slightly different interpretation depending on the
|
||||
type of the option value:
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_TYPE_STRING</tt>:<dd> The size is the maximum size of
|
||||
the string. For the purpose of string size calcuations, the
|
||||
terminating <tt>NUL</tt> character is considered to be part of the
|
||||
string. Note that the terminating <tt>NUL</tt> character must
|
||||
always be present in string option values.
|
||||
<dt><tt>SANE_TYPE_INT</tt>, <tt>SANE_TYPE_FIXED</tt>:<dd> The size
|
||||
must be a positive integer multiple of the size of a
|
||||
<tt>SANE_Word</tt>. The option value is a vector of length
|
||||
|
||||
<p>
|
||||
<center>
|
||||
<tt>size</tt>/<tt>sizeof(SANE_Word)</tt>. </center>
|
||||
<p>
|
||||
<dt><tt>SANE_TYPE_BOOL</tt>:<dd> The size must be set to
|
||||
<tt>sizeof(SANE_Word)</tt>.
|
||||
<dt><tt>SANE_TYPE_BUTTON</tt>, <tt>SANE_TYPE_GROUP</tt>:<dd> The
|
||||
option size is ignored.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h4><a name="s4.2.9.7">4.2.9.7 Option Capabilities</a></h4>
|
||||
|
||||
<p>Member <tt>cap</tt> describes what capabilities the option posseses.
|
||||
This is a bitset that is formed as the inclusive logical OR of the
|
||||
capabilities described in Table <a href="doc011.html#t5">5</a>. The SANE API
|
||||
provides the following to macros to test certain features of a given
|
||||
capability bitset:
|
||||
<blockquote>
|
||||
<dl>
|
||||
|
||||
<p> <dt><tt>SANE_OPTION_IS_ACTIVE<a name="i57">(<i>cap</i>)</tt>:<dd> This macro
|
||||
returns <tt>SANE_TRUE</tt> if and only if the option with the
|
||||
capability set <i>cap</i> is currently active.
|
||||
|
||||
<p> <dt><tt>SANE_OPTION_IS_SETTABLE<a name="i58">(<i>cap</i>)</tt>:<dd> This
|
||||
macro returns <tt>SANE_TRUE</tt> if and only if the option with the
|
||||
capability set <i>cap</i> is software settable.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><p><a name="t5"></a>
|
||||
<center>
|
||||
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Code</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
|
||||
<p><tt>SANE_CAP_SOFT_SELECT<a name="i59"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 1 </td>
|
||||
<td colspan=1 align=left> The option
|
||||
value can be set by a call to <tt>sane_control_option()</tt>.</td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_CAP_HARD_SELECT<a name="i60"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 2 </td>
|
||||
<td colspan=1 align=left> 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). </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_CAP_SOFT_DETECT<a name="i61"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 4 </td>
|
||||
<td colspan=1 align=left> The option
|
||||
value can be detected by software. If
|
||||
<tt>SANE_CAP_SOFT_SELECT</tt> is set, this capability <em>must</em>
|
||||
be set. If <tt>SANE_CAP_HARD_SELECT</tt> is set, this capability
|
||||
may or may not be set. If this capability is set but neither
|
||||
<tt>SANE_CAP_SOFT_SELECT</tt> nor <tt>SANE_CAP_HARD_SELECT</tt>
|
||||
are, then there is no way to control the option. That is, the
|
||||
option provides read-out of the current value only. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_CAP_EMULATED<a name="i62"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 8 </td>
|
||||
<td colspan=1 align=left> 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. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_CAP_AUTOMATIC<a name="i63"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 16 </td>
|
||||
<td colspan=1 align=left> 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 <tt>sane_control_option()</tt>
|
||||
with an action value of <tt>SANE_ACTION_SET_AUTO</tt>. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_CAP_INACTIVE<a name="i64"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 32 </td>
|
||||
<td colspan=1 align=left> 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). </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_CAP_ADVANCED<a name="i65"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 64 </td>
|
||||
<td colspan=1 align=left>
|
||||
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).
|
||||
</td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
</td></tr>
|
||||
</table>
|
||||
<p><center>Table 5: Option Capabilities</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p><h4><a name="s4.2.9.8">4.2.9.8 Option Value Constraints</a></h4>
|
||||
|
||||
<p>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 <tt>constraint_type</tt> 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 <tt>constraint</tt>. The possible values of type
|
||||
<tt>SANE_Constraint_Type<a name="i66"></tt> and the interpretation of the
|
||||
<tt>constraint</tt> union is described in Table <a href="doc011.html#t6">6</a>.
|
||||
|
||||
<p><p><a name="t6"></a>
|
||||
<center>
|
||||
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Code</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
|
||||
<p><tt>SANE_CONSTRAINT_NONE<a name="i67"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 0 </td>
|
||||
<td colspan=1 align=left> The value is unconstrained.
|
||||
The option can take any of the values possible for the option's
|
||||
type. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p> <tt>SANE_CONSTRAINT_RANGE<a name="i68"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 1 </td>
|
||||
<td colspan=1 align=left> 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 <tt>constraint.range</tt> points to
|
||||
a range of the type <tt>SANE_Range<a name="i69"></tt>. This type is illustrated
|
||||
below:
|
||||
<blockquote>
|
||||
<pre>
|
||||
typedef struct
|
||||
{
|
||||
SANE_Word min;
|
||||
SANE_Word max;
|
||||
SANE_Word quant;
|
||||
}
|
||||
SANE_Range;
|
||||
</pre>
|
||||
</blockquote>
|
||||
All three members in this structure are interpreted according to the
|
||||
option value type (<tt>SANE_TYPE_INT</tt> or <tt>SANE_TYPE_FIXED</tt>).
|
||||
Members <tt>min</tt> and <tt>max</tt> specify the minimum and maximum
|
||||
values, respectively. If member <tt>quant</tt> 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*q+l for all non-negative
|
||||
integer values of k such that v<=u. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_CONSTRAINT_WORD_LIST<a name="i70"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 2 </td>
|
||||
<td colspan=1 align=left> 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
|
||||
<tt>constraint.word_list</tt> points to a list of words that
|
||||
enumerates the legal values. The first element in that list is an
|
||||
integer (<tt>SANE_Int</tt>) 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
|
||||
(<tt>SANE_TYPE_INT</tt> or <tt>SANE_TYPE_FIXED</tt>). </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_CONSTRAINT_STRING_LIST<a name="i71"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 3 </td>
|
||||
<td colspan=1 align=left> This constraint is
|
||||
applicable to string-valued options only. It constrains the option
|
||||
value to a list of strings. The option descriptor member
|
||||
<tt>constraint.string_list</tt> points to a <tt>NULL</tt> terminated
|
||||
list of strings that enumerate the legal values for the option
|
||||
value.
|
||||
</td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
<p><center>Table 6: Option Value Constraints</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc012.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc010.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,666 @@
|
|||
<html><body>
|
||||
<a href="doc013.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc011.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Operations</title>
|
||||
<h2><a name="s4.3">4.3 Operations</a></h2>
|
||||
|
||||
<p><h3><a name="s4.3.1">4.3.1 <tt>sane_init</tt></a></h3>
|
||||
|
||||
<p>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 <tt>sane_init</tt> is different from
|
||||
<tt>SANE_STATUS_GOOD<a name="i72"></tt>. The version code of the backend is returned
|
||||
in the value pointed to by <tt>version_code</tt>. If that pointer is
|
||||
<tt>NULL</tt>, no version code is returned. Argument <tt>authorize</tt> is either
|
||||
a pointer to a function that is invoked when the backend requires
|
||||
authentication for a specific resource or <tt>NULL</tt> if the frontend does not
|
||||
support authentication.
|
||||
<blockquote><a name="i73">
|
||||
<pre>
|
||||
SANE_Status sane_init (SANE_Int * version_code,
|
||||
SANE_Authorization_Callback authorize);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>The authorization function may be called by a backend in response to
|
||||
any of the following calls:
|
||||
<blockquote>
|
||||
<tt>sane_open</tt>, <tt>sane_control_option</tt>, <tt>sane_start</tt>
|
||||
</blockquote>
|
||||
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.
|
||||
|
||||
<p>The authentication function type has the following declaration:
|
||||
<blockquote><a name="i74">
|
||||
<a name="i75"><a name="i76"><a name="i77">
|
||||
<pre>
|
||||
#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]);
|
||||
</pre>
|
||||
</blockquote>
|
||||
Three arguments are passed to the authorization function:
|
||||
<tt>resource</tt> 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 <tt>username</tt>
|
||||
and <tt>password</tt> arguments are (pointers to) an array of
|
||||
<tt>SANE_MAX_USERNAME_LEN</tt> and <tt>SANE_MAX_PASSWORD_LEN</tt>
|
||||
characters, respectively. The authorization call should place the
|
||||
entered username and password in these arrays. The returned strings
|
||||
<em>must</em> be ASCII-NUL terminated.
|
||||
|
||||
<p><h3><a name="s4.3.2">4.3.2 <tt>sane_exit</tt></a></h3>
|
||||
|
||||
<p>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 <tt>sane_close()</tt>, but backends are required to release all
|
||||
resources upon a call to this function). After this function returns,
|
||||
no function other than <tt>sane_init()</tt> may be called (regardless
|
||||
of the status value returned by <tt>sane_exit()</tt>. Neglecting to
|
||||
call this function may result in some resources not being released
|
||||
properly.
|
||||
<blockquote><a name="i78">
|
||||
<pre>
|
||||
void sane_exit (void);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.3">4.3.3 <tt>sane_get_devices</tt></a></h3>
|
||||
|
||||
<p>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 <tt>NULL</tt> terminated array of pointers to <tt>SANE_Device</tt>
|
||||
structures in <tt>*device_list</tt>. The returned list is guaranteed
|
||||
to remain unchanged and valid until (a) another call to this function
|
||||
is performed or (b) a call to <tt>sane_exit()</tt> is performed. This
|
||||
function can be called repeatedly to detect when new devices become
|
||||
available. If argument <tt>local_only</tt> 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.
|
||||
<blockquote><a name="i79">
|
||||
<pre>
|
||||
SANE_Status sane_get_devices (const SANE_Device *** device_list,
|
||||
SANE_Bool local_only);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>This function may fail with <tt>SANE_STATUS_NO_MEM</tt> if an
|
||||
insufficient amount of memory is available.
|
||||
|
||||
<p><blockquote>
|
||||
<center>
|
||||
<b>Backend Implementation Note</b>
|
||||
</center>
|
||||
SANE does not require that this function is called before a
|
||||
<tt>sane_open()</tt> 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.
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.4">4.3.4 <tt>sane_open</tt></a></h3>
|
||||
|
||||
<p>This function is used to establish a connection to a particular
|
||||
device. The name of the device to be opened is passed in argument
|
||||
<tt>name</tt>. If the call completes successfully, a handle for the
|
||||
device is returned in <tt>*h</tt>. As a special case, specifying a
|
||||
zero-length string as the device requests opening the first available
|
||||
device (if there is such a device).
|
||||
<blockquote><a name="i80">
|
||||
<pre>
|
||||
SANE_Status sane_open (SANE_String_Const name, SANE_Handle * h);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>This function may fail with one of the following status codes.
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_DEVICE_BUSY</tt>:<dd> The device is currently
|
||||
busy (in use by somebody else).
|
||||
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> The device name is not valid.
|
||||
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occured while
|
||||
communicating with the device.
|
||||
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
||||
is available.
|
||||
<dt><tt>SANE_STATUS_ACCESS_DENIED</tt>:<dd> Access to the device has
|
||||
been denied due to insufficient or invalid authentication.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.5">4.3.5 <tt>sane_close</tt></a></h3>
|
||||
|
||||
<p>This function terminates the association between the device handle
|
||||
passed in argument <tt>h</tt> and the device it represents. If the
|
||||
device is presently active, a call to <tt>sane_cancel()</tt> is
|
||||
performed first. After this function returns, handle <tt>h</tt> must
|
||||
not be used anymore.
|
||||
|
||||
<p><blockquote><a name="i81">
|
||||
<pre>
|
||||
void sane_close (SANE_Handle h);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.6">4.3.6 <tt>sane_get_option_descriptor</tt></a></h3>
|
||||
|
||||
<p>This function is used to access option descriptors. The function
|
||||
returns the option descriptor for option number <tt>n</tt> of the device
|
||||
represented by handle <tt>h</tt>. 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 <tt>h</tt> (the count
|
||||
includes option 0). If n is not a valid option index, the function
|
||||
returns <tt>NULL</tt>. The returned option descriptor is guaranteed to
|
||||
remain valid (and at the returned address) until the device is closed.
|
||||
|
||||
<p><blockquote><a name="i82">
|
||||
<pre>
|
||||
const SANE_Option_Descriptor *
|
||||
sane_get_option_descriptor (SANE_Handle h, SANE_Int n);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.7">4.3.7 <tt>sane_control_option</tt></a></h3>
|
||||
|
||||
<p>This function is used to set or inquire the current value of option
|
||||
number <tt>n</tt> of the device represented by handle <tt>h</tt>. The
|
||||
manner in which the option is controlled is specified by parameter
|
||||
<tt>a</tt>. The possible values of this parameter are described in more
|
||||
detail below. The value of the option is passed through argument
|
||||
<tt>v</tt>. It is a pointer to the memory that holds the option value.
|
||||
The memory area pointed to by <tt>v</tt> must be big enough to hold the
|
||||
entire option value (determined by member <tt>size</tt> 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 <tt>v</tt> may be shorter since the backend will stop
|
||||
reading the option value upon encountering the first <tt>NUL</tt>
|
||||
terminator in the string. If argument <tt>i</tt> is not <tt>NULL</tt>,
|
||||
the value of <tt>*i</tt> 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.
|
||||
<blockquote><a name="i83">
|
||||
<pre>
|
||||
SANE_Status sane_control_option (SANE_Handle h, SANE_Int n,
|
||||
SANE_Action a, void *v,
|
||||
SANE_Int * i);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>The way the option is affected by a call to this function is
|
||||
controlled by parameter <tt>a</tt> which is a value of type
|
||||
<tt>SANE_Action<a name="i84"></tt>. The possible values and their meaning is
|
||||
described in Table <a href="doc012.html#t7">7</a>.
|
||||
|
||||
<p><p><a name="t7"></a>
|
||||
<center>
|
||||
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Code</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
|
||||
<p><tt>SANE_ACTION_GET_VALUE<a name="i85"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 0 </td>
|
||||
<td colspan=1 align=left> Get current option value. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_ACTION_SET_VALUE<a name="i86"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 1 </td>
|
||||
<td colspan=1 align=left> Set option value. The
|
||||
option value passed through argument <tt>v</tt> may be modified by the
|
||||
backend if the value cannot be set exactly. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_ACTION_SET_AUTO<a name="i87"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 2 </td>
|
||||
<td colspan=1 align=left> 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 <tt>v</tt> is completely ignored in this case and
|
||||
may be <tt>NULL</tt>. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
</td></tr>
|
||||
</table>
|
||||
<p><center>Table 7: Action Values (<tt>SANE_Action</tt>)</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>After setting a value via an action value of
|
||||
<tt>SANE_ACTION_SET_VALUE</tt>, additional information on how well the
|
||||
request has been met is returned in <tt>*i</tt> (if <tt>i</tt> is
|
||||
non-<tt>NULL</tt>). The returned value is a bitset that may contain any
|
||||
combination of the values described in Table <a href="doc012.html#t8">8</a>.
|
||||
<p><a name="t8"></a>
|
||||
<center>
|
||||
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Code</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
|
||||
<p><tt>SANE_INFO_INEXACT<a name="i88"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 1 </td>
|
||||
<td colspan=1 align=left> 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 <tt>*i</tt> 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. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p> <tt>SANE_INFO_RELOAD_OPTIONS<a name="i89"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 2 </td>
|
||||
<td colspan=1 align=left> The setting of an
|
||||
option may affect the value or availability of one or more <em>
|
||||
other</em> options. When this happens, the SANE backend sets this
|
||||
member in <tt>*i</tt> to indicate that the application should reload
|
||||
all options. This member may be set if and only if at least one
|
||||
option changed. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_INFO_RELOAD_PARAMS<a name="i90"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 4 </td>
|
||||
<td colspan=1 align=left> The setting of an option may
|
||||
affect the parameter values (see <tt>sane_get_parameters()</tt>).
|
||||
If setting an option affects the parameter values, this member will
|
||||
be set in <tt>*i</tt>. 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. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
</td></tr>
|
||||
</table>
|
||||
<p><center>Table 8: Additional Information Returned When Setting an Option</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>This function may fail with one of the following status codes.
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_UNSUPPORTED</tt>:<dd> The operation is not
|
||||
supported for the specified handle and option number.
|
||||
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> The option value is not valid.
|
||||
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occured while
|
||||
communicating with the device.
|
||||
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
||||
is available.
|
||||
<dt><tt>SANE_STATUS_ACCESS_DENIED</tt>:<dd> Access to the option has
|
||||
been denied due to insufficient or invalid authentication.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.8">4.3.8 <tt>sane_get_parameters</tt></a></h3>
|
||||
|
||||
<p>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 (<tt>sane_start()</tt> 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
|
||||
<tt>sane_start()</tt> 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 <tt>h</tt> of the device for which the
|
||||
parameters should be obtained and a pointer <tt>p</tt> to a parameter
|
||||
structure. The parameter structure is described in more detail below.
|
||||
|
||||
<p><blockquote><a name="i91">
|
||||
<pre>
|
||||
SANE_Status sane_get_parameters (SANE_Handle h,
|
||||
SANE_Parameters * p);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>The scan parameters are returned in a structure of type
|
||||
<tt>SANE_Parameters<a name="i92"></tt>. The C declaration of this structure
|
||||
is given below.
|
||||
<blockquote>
|
||||
<pre>
|
||||
typedef struct
|
||||
{
|
||||
SANE_Frame format;
|
||||
SANE_Bool last_frame;
|
||||
SANE_Int lines;
|
||||
SANE_Int depth;
|
||||
SANE_Int pixels_per_line;
|
||||
SANE_Int bytes_per_line;
|
||||
}
|
||||
SANE_Parameters;
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>Member <tt>format</tt> specifies the format of the next frame to be
|
||||
returned. The possible values for type <tt>SANE_Frame<a name="i93"></tt> are
|
||||
described in Table <a href="doc012.html#t9">9</a>. The meaning of these
|
||||
values is described in more detail in Section <a href="doc008.html#s3.2">3.2</a>.
|
||||
<p><a name="t9"></a>
|
||||
<center>
|
||||
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Code</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
|
||||
<p><tt>SANE_FRAME_GRAY<a name="i94"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 0 </td>
|
||||
<td colspan=1 align=left nowrap> Band covering human visual range. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_FRAME_RGB<a name="i95"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 1 </td>
|
||||
<td colspan=1 align=left nowrap> Pixel-interleaved red/green/blue bands. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_FRAME_RED<a name="i96"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 2 </td>
|
||||
<td colspan=1 align=left nowrap> Red band of a red/green/blue image. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_FRAME_GREEN<a name="i97"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 3 </td>
|
||||
<td colspan=1 align=left nowrap> Green band of a red/green/blue image. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_FRAME_BLUE<a name="i98"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 4 </td>
|
||||
<td colspan=1 align=left nowrap> Blue band of a red/green/blue image. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
</td></tr>
|
||||
</table>
|
||||
<p><center>Table 9: Frame Format (<tt>SANE_Frame</tt>)</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>Member <tt>last_frame</tt> is set to <tt>SANE_TRUE</tt> 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).
|
||||
|
||||
<p>Member <tt>lines</tt> 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 <tt>sane_read()</tt> until it
|
||||
returns a status of <tt>SANE_STATUS_EOF</tt>.
|
||||
|
||||
<p>Member <tt>bytes_per_line</tt> specifies the number of bytes that
|
||||
comprise one scan line.
|
||||
|
||||
<p>Member <tt>depth</tt> specifies the number of bits per sample.
|
||||
|
||||
<p>Member <tt>pixels_per_line</tt> specifies the number of pixels that
|
||||
comprise one scan line.
|
||||
|
||||
<p>Assume B is the number of channels in the frame, then the bit depth
|
||||
d (as given by member <tt>depth</tt>) and the number of pixels per
|
||||
line n (as given by this member <tt>pixels_per_line</tt>) are
|
||||
related to c, the number of bytes per line (as given by member
|
||||
<tt>bytes_per_line</tt>) as follows:
|
||||
|
||||
<p>
|
||||
<center>
|
||||
|
||||
c >= \left{
|
||||
ll
|
||||
\lceil B*n / 8\rceil if d=1
|
||||
</td><td align=right>(1)</td></tr><tr><td align=center>
|
||||
|
||||
B*n *\lceil (d + 7)/8 \rceil if d>1
|
||||
|
||||
\right.
|
||||
</center>
|
||||
<p>
|
||||
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.
|
||||
|
||||
<p><h3><a name="s4.3.9">4.3.9 <tt>sane_start</tt></a></h3>
|
||||
|
||||
<p>This function initiates aquisition of an image from the device
|
||||
represented by handle <tt>h</tt>.
|
||||
<blockquote><a name="i99">
|
||||
<pre>
|
||||
SANE_Status sane_start (SANE_Handle h);
|
||||
</pre>
|
||||
</blockquote>
|
||||
This function may fail with one of the following status codes.
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_CANCELLED</tt>:<dd> The operation was cancelled through
|
||||
a call to <tt>sane_cancel</tt>.
|
||||
<dt><tt>SANE_STATUS_DEVICE_BUSY</tt>:<dd> The device is busy. The
|
||||
operation should be retried later.
|
||||
<dt><tt>SANE_STATUS_JAMMED</tt>:<dd> The document feeder is jammed.
|
||||
<dt><tt>SANE_STATUS_NO_DOCS</tt>:<dd> The document feeder is out of
|
||||
documents.
|
||||
<dt><tt>SANE_STATUS_COVER_OPEN</tt>:<dd> The scanner cover is open.
|
||||
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occurred while communicating
|
||||
with the device.
|
||||
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
||||
is available.
|
||||
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> The scan cannot be started with the current
|
||||
set of options. The frontend should reload the option descriptors, as if
|
||||
<tt>SANE_INFO_RELOAD_OPTIONS<a name="i100"></tt> had been returned from a call to
|
||||
<tt>sane_control_option()</tt>, since the device's capabilities may have
|
||||
changed.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.10">4.3.10 <tt>sane_read</tt></a></h3>
|
||||
|
||||
<p>This function is used to read image data from the device represented
|
||||
by handle <tt>h</tt>. Argument <tt>buf</tt> is a pointer to a memory area
|
||||
that is at least <tt>maxlen</tt> bytes long. The number of bytes
|
||||
returned is stored in <tt>*len</tt>. A backend must set this to zero
|
||||
when a status other than <tt>SANE_STATUS_GOOD</tt> is returned.
|
||||
When the call succeeds, the number of bytes returned can be anywhere in
|
||||
the range from 0 to <tt>maxlen</tt> bytes.
|
||||
<blockquote><a name="i101">
|
||||
<pre>
|
||||
SANE_Status sane_read (SANE_Handle h, SANE_Byte * buf,
|
||||
SANE_Int maxlen, SANE_Int * len);
|
||||
</pre>
|
||||
</blockquote>
|
||||
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 <tt>h</tt>.
|
||||
<ol>
|
||||
<li>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).
|
||||
|
||||
<p><li>If the device is in non-blocking I/O mode, the call returns
|
||||
immediately with status <tt>SANE_STATUS_GOOD</tt> and with
|
||||
<tt>*len</tt> set to zero.
|
||||
</ol>
|
||||
The I/O mode of handle <tt>h</tt> can be set via a call to
|
||||
<tt>sane_set_io_mode()</tt>.
|
||||
|
||||
<p>This function may fail with one of the following status codes.
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_CANCELLED</tt>:<dd> The operation was cancelled through
|
||||
a call to <tt>sane_cancel</tt>.
|
||||
<dt><tt>SANE_STATUS_EOF</tt>:<dd> No more data is available for the
|
||||
current frame.
|
||||
<dt><tt>SANE_STATUS_JAMMED</tt>:<dd> The document feeder is jammed.
|
||||
<dt><tt>SANE_STATUS_NO_DOCS</tt>:<dd> The document feeder is out of
|
||||
documents.
|
||||
<dt><tt>SANE_STATUS_COVER_OPEN</tt>:<dd> The scanner cover is open.
|
||||
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occurred while communicating
|
||||
with the device.
|
||||
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
||||
is available.
|
||||
<dt><tt>SANE_STATUS_ACCESS_DENIED</tt>:<dd> Access to the device has
|
||||
been denied due to insufficient or invalid authentication.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.11">4.3.11 <tt>sane_cancel</tt></a></h3>
|
||||
|
||||
<p>This function is used to immediately or as quickly as possible cancel
|
||||
the currently pending operation of the device represented by handle
|
||||
<tt>h</tt>.
|
||||
<blockquote><a name="i102">
|
||||
<pre>
|
||||
void sane_cancel (SANE_Handle h);
|
||||
</pre>
|
||||
</blockquote>
|
||||
This function can be called at any time (as long as handle <tt>h</tt> 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</em> imply that
|
||||
the currently pending operation has been cancelled. It only
|
||||
guarantees that cancellation has been <em>initiated</em>. Cancellation
|
||||
completes only when the cancelled call returns (typically with a
|
||||
status value of <tt>SANE_STATUS_CANCELLED</tt>). Since the SANE API
|
||||
does not require any other operations to be re-entrant, this implies
|
||||
that a frontend must <em>not</em> call any other operation until the
|
||||
cancelled operation has returned.
|
||||
|
||||
<p><h3><a name="s4.3.12">4.3.12 <tt>sane_set_io_mode</tt></a></h3>
|
||||
|
||||
<p>This function is used to set the I/O mode of handle <tt>h</tt>. The I/O mode
|
||||
can be either blocking or non-blocking. If argument <tt>m</tt> is
|
||||
<tt>SANE_TRUE</tt>, 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
|
||||
<tt>sane_start()</tt> has been performed.
|
||||
<blockquote><a name="i103">
|
||||
<pre>
|
||||
SANE_Status sane_set_io_mode (SANE_Handle h, SANE_Bool m);
|
||||
</pre>
|
||||
</blockquote>
|
||||
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 <tt>SANE_STATUS_UNSUPPORTED</tt> is returned. Blocking
|
||||
I/O must be supported by all backends, so calling this function with
|
||||
argument <tt>m</tt> set to <tt>SANE_FALSE</tt> is guaranteed to complete
|
||||
successfully.
|
||||
|
||||
<p>This function may fail with one of the following status codes:
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> No image acquisition is pending.
|
||||
<dt><tt>SANE_STATUS_UNSUPPORTED</tt>:<dd> The backend does not support
|
||||
the requested I/O mode.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.13">4.3.13 <tt>sane_get_select_fd</tt></a></h3>
|
||||
|
||||
<p>This function is used to obtain a (platform-specific) file-descriptor
|
||||
for handle <tt>h</tt> that is readable if and only if image data is
|
||||
available (i.e., when a call to <tt>sane_read()</tt> will return at
|
||||
least one byte of data). If the call completes successfully, the
|
||||
select file-descriptor is returned in <tt>*fd</tt>.
|
||||
<blockquote><a name="i104">
|
||||
<pre>
|
||||
SANE_Status sane_get_select_fd (SANE_Handle h, SANE_Int *fd);
|
||||
</pre>
|
||||
</blockquote>
|
||||
This function can be called only after a call to <tt>sane_start()</tt>
|
||||
has been performed and the returned file-descriptor is guaranteed to
|
||||
remain valid for the duration of the current image acquisition (i.e.,
|
||||
until <tt>sane_cancel()</tt> or <tt>sane_start()</tt> get called again
|
||||
or until <tt>sane_read()</tt> returns with status
|
||||
<tt>SANE_STATUS_EOF</tt>). Indeed, a backend must guarantee to
|
||||
close the returned select file descriptor at the point when the next
|
||||
<tt>sane_read()</tt> call would return <tt>SANE_STATUS_EOF</tt>.
|
||||
This is necessary to ensure the application can detect when this
|
||||
condition occurs without actually having to call <tt>sane_read()</tt>.
|
||||
|
||||
<p>A backend may elect not to support this operation. In such a case,
|
||||
the function returns with status code
|
||||
<tt>SANE_STATUS_UNSUPPORTED</tt>.
|
||||
|
||||
<p>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 <tt>select()</tt>
|
||||
or <tt>poll()</tt> 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 <tt>sane_read()</tt> 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.
|
||||
|
||||
<p>This function may fail with one of the following status codes:
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> No image acquisition is pending.
|
||||
<dt><tt>SANE_STATUS_UNSUPPORTED</tt>:<dd> The backend does not support
|
||||
this operation.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.14">4.3.14 <tt>sane_strstatus</tt></a></h3>
|
||||
|
||||
<p>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 <tt>NULL</tt>.
|
||||
The returned pointer is valid at least until the next call to this
|
||||
function is performed.
|
||||
<blockquote><a name="i105">
|
||||
<pre>
|
||||
const SANE_String_Const sane_strstatus (SANE_Status status);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc013.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc011.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,99 @@
|
|||
<html><body>
|
||||
<a href="doc014.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc012.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Code Flow</title>
|
||||
<h2><a name="s4.4">4.4 Code Flow</a></h2><a name="i106">
|
||||
|
||||
<p>The code flow for the SANE API is illustrated in
|
||||
Figure <a href="doc013.html#f4">4</a>. Functions <tt>sane_init()</tt> and
|
||||
<tt>sane_exit()</tt> initialize and exit the backend, respectively.
|
||||
All other calls must be performed after initialization and before
|
||||
exiting the backend.
|
||||
|
||||
<p><p><a name="f4"></a>
|
||||
<center>
|
||||
|
||||
<img width=566 height=510 src="img003.gif">
|
||||
<p><center>Figure 4: Code flow</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>Function <tt>sane_get_devices()</tt> can be called any time after
|
||||
<tt>sane_init()</tt> 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.
|
||||
|
||||
<p>Once a device has been chosen, it is opened using a call to
|
||||
<tt>sane_open()</tt>. 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.
|
||||
|
||||
<p>An opened device can be setup through the corresponding device handle
|
||||
using functions <tt>sane_get_option_descriptor()</tt> and
|
||||
<tt>sane_control_option()</tt>. 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
|
||||
<tt>sane_get_parameters()</tt> to get an estimate of what the image
|
||||
parameters will look like once image acquisition begins.
|
||||
|
||||
<p>The device handle can be put in blocking or non-blocking mode by a
|
||||
call to <tt>sane_set_io_mode()</tt>. 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.
|
||||
|
||||
<p>After the device is setup properly, image acquisition can be started
|
||||
by a call to <tt>sane_start()</tt>. The backend calculates the exact
|
||||
image parameters at this point. So future calls to
|
||||
<tt>sane_get_parameters()</tt> will return the exact values, rather
|
||||
than estimates. Whether the physical image acquisition starts at this
|
||||
point or during the first call to <tt>sane_read()</tt> 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
|
||||
<tt>sane_set_io_mode()</tt> and/or <tt>sane_get_select_fd()</tt> at
|
||||
this point. Either of these functions may fail if the backend does
|
||||
not support the requested operation.
|
||||
|
||||
<p>Image data is collected by repeatedly calling <tt>sane_read()</tt>.
|
||||
Eventually, this function will return an end-of-file status
|
||||
(<tt>SANE_STATUS_EOF</tt>). 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 <tt>sane_start()</tt> again. Once all desired frames have
|
||||
been acquired, function <tt>sane_cancel()</tt> must be called. This
|
||||
operation can also be called at any other time to cancel a pending
|
||||
operation. Note that <tt>sane_cancel()</tt> must be called even if the
|
||||
last read operation returned <tt>SANE_STATUS_EOF</tt>.
|
||||
|
||||
<p>When done using the device, the handle should be closed by a call to
|
||||
<tt>sane_close()</tt>. Finally, before exiting the application,
|
||||
function <tt>sane_exit()</tt> 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.
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc014.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc012.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,145 @@
|
|||
<html><body>
|
||||
<a href="doc015.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc013.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Well-Known Options</title>
|
||||
<h2><a name="s4.5">4.5 Well-Known Options</a></h2><a name="i107">
|
||||
|
||||
<p>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.
|
||||
|
||||
<p><h3><a name="s4.5.1">4.5.1 Option Number Count</a></h3><a name="i108">
|
||||
|
||||
<p>Option number 0 has an empty string as its name. The value of this
|
||||
option is of type <tt>SANE_TYPE_INT</tt> 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
|
||||
<tt>sane_get_option_descriptor()</tt> returns <tt>NULL</tt>, or a
|
||||
frontend can directly read out the value of option number 0.
|
||||
|
||||
<p><h3><a name="s4.5.2">4.5.2 Scan Resolution Option</a></h3><a name="i109"><a name="i110">
|
||||
|
||||
<p>Option <tt>resolution</tt> is used to select the resolution at which an
|
||||
image should be acquired. The type of this option is either
|
||||
<tt>SANE_TYPE_INT</tt> or <tt>SANE_TYPE_FIXED</tt>. The unit is
|
||||
<tt>SANE_UNIT_DPI</tt> (dots/inch).
|
||||
|
||||
<p>This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.
|
||||
|
||||
<p><h3><a name="s4.5.3">4.5.3 Preview Mode Option</a></h3><a name="i111">
|
||||
|
||||
<p>The boolean option <tt>preview</tt> 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 <tt>SANE_TRUE</tt>,
|
||||
preview mode is in effect, when set to <tt>SANE_FALSE</tt> image
|
||||
acquisition should proceed in normal quality mode. The setting of
|
||||
this option <em>must not</em> 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 <tt>resolution</tt>). A backend is free to override the
|
||||
<tt>resolution</tt> value with its own choice for preview mode, but it
|
||||
is advised to leave this choice to the frontend wherever possible.
|
||||
|
||||
<p>This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.
|
||||
|
||||
<p><h3><a name="s4.5.4">4.5.4 Scan Area Options</a></h3><a name="i112">
|
||||
|
||||
<p>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 <a href="doc014.html#f5">5</a>. 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</em> and the bottom-right corner is the
|
||||
corner for which the abscissa and ordinate values are simulatenously
|
||||
the <em>largest</em>. If this coordinate system is not natural for a
|
||||
given device, it is the job of the backend to perform the necessary
|
||||
conversions.
|
||||
<p><a name="f5"></a>
|
||||
<center>
|
||||
|
||||
<img width=330 height=306 src="img004.gif">
|
||||
<p><center>Figure 5: Scan area options</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>The names of the four options that define the scan area are given in
|
||||
the table below:
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>Name</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>Description</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>tl-x<a name="i113"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> Top-left x coordinate value </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>tl-y<a name="i114"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> Top-left y coordinate value </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>br-x<a name="i115"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> Bottom-right x coordinate value </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>br-y<a name="i116"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> Bottom-right y coordinate value </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
There are several rules that should be followed by front and backends
|
||||
regarding these options:
|
||||
<ul>
|
||||
|
||||
<p><li>Backends must attach a unit of either pixels
|
||||
(<tt>SANE_UNIT_PIXEL</tt>) or millimeters (<tt>SANE_UNIT_MM</tt>) to
|
||||
these options. The unit of all four options must be identical.
|
||||
|
||||
<p><li>Whenever meaningful, a backend should attach a range or a
|
||||
word-list constraint to these options.
|
||||
|
||||
<p><li>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.
|
||||
|
||||
<p><li>A frontend must work properly with any or all of these options
|
||||
missing.
|
||||
|
||||
</ul>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc015.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc013.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,82 @@
|
|||
<html><body>
|
||||
<a href="doc016.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc014.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Network Protocol</title>
|
||||
<h1><a name="s5">5 Network Protocol</a></h1>
|
||||
|
||||
<p>The SANE interface has been designed to facilitate network access to
|
||||
image acquisition devices. In particular, most SANE implementations
|
||||
are expected to support a network backend (net client) and a
|
||||
corresponding network daemon (net server) that allows accessing image
|
||||
acquisition devices through a network connection. Network access is
|
||||
useful in several situations:
|
||||
<ul>
|
||||
|
||||
<p><li>To provide controlled access to resources that are inaccessible
|
||||
to a regular user. For example, a user may want to access a device
|
||||
on a host where she has no account on. With the network protocol,
|
||||
it is possible to allow certain users to access scanners without
|
||||
giving them full access to the system.
|
||||
|
||||
<p> Controlling access through the network daemon can be useful even in
|
||||
the local case: for example, certain backends may require root
|
||||
privileges to access a device. Rather than installing each frontend
|
||||
as setuid-root, a system administrator could instead install the
|
||||
SANE network daemon as setuid-root. This enables regular users to
|
||||
access the privileged device through the SANE daemon (which,
|
||||
presumably, supports a more fine-grained access control mechanism
|
||||
than the simple setuid approach). This has the added benefit that
|
||||
the system administrator only needs to trust the SANE daemon, not
|
||||
each and every frontend that may need access to the privileged
|
||||
device.
|
||||
|
||||
<p><li>Network access provides a sense of ubiquity of the available
|
||||
image acquisition devices. For example, in a local area network
|
||||
environment, this allows a user to log onto any machine and have
|
||||
convenient access to any resource available to any machine on the
|
||||
network (subject to permission constraints).
|
||||
|
||||
<p><li>For devices that do not require physical access when used (e.g.,
|
||||
video cameras), network access allows a user to control and use
|
||||
these devices without being in physical proximity. Indeed, if such
|
||||
devices are connected to the Internet, access from any place in the
|
||||
world is possible.
|
||||
|
||||
<p></ul>
|
||||
|
||||
<p>The network protocol described in this chapter has been design with
|
||||
the following goals in mind:
|
||||
<ol>
|
||||
|
||||
<p><li>Image transmission should be efficient (have low encoding
|
||||
overhead).
|
||||
|
||||
<p><li>Accessing option descriptors on the client side must be
|
||||
efficient (since this is a very common operation).
|
||||
|
||||
<p><li>Other operations, such as setting or inquiring the value of an
|
||||
option are less performance critical since they typically require
|
||||
explicit user action.
|
||||
|
||||
<p><li>The network protocol should be simple and easy to implement on
|
||||
any host architecture and any programming language.
|
||||
|
||||
<p></ol>
|
||||
The SANE protocol can be run across any transport protocol that
|
||||
provides reliable data delivery. While SANE does not specify a
|
||||
specific transport protocol, it is expected that TCP/IP will be among
|
||||
the most commonly used protocols.
|
||||
|
||||
<p><h2><a href="doc016.html">5.1 Data Type Encoding</a></h2><h2><a href="doc017.html">5.2 Remote Procedure Call Requests</a></h2><p><hr>
|
||||
<a href="doc016.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc014.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,89 @@
|
|||
<html><body>
|
||||
<a href="doc017.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc015.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Data Type Encoding</title>
|
||||
<h2><a name="s5.1">5.1 Data Type Encoding</a></h2>
|
||||
|
||||
<p><h3><a name="s5.1.1">5.1.1 Primitive Data Types</a></h3>
|
||||
|
||||
<p>The four primitive types of the SANE standard are encoded as follows:
|
||||
<dl>
|
||||
|
||||
<p><dt><tt>SANE_Byte<a name="i117"></tt>:<dd> A byte is encoded as an 8 bit value.
|
||||
Since the transport protocol is assumed to be byte-orientd, the bit
|
||||
order is irrelevant.
|
||||
|
||||
<p><dt><tt>SANE_Word<a name="i118"></tt>:<dd> A word is encoded as 4 bytes (32
|
||||
bits). The bytes are ordered from most-significant to
|
||||
least-significant byte (big-endian byte-order).
|
||||
|
||||
<p><dt><tt>SANE_Char<a name="i119"></tt>:<dd> A character is currently encoded as an 8-bit
|
||||
ISO LATIN-1 value. An extension to support wider character sets (16 or 32
|
||||
bits) is planned for the future, but not supported at this point.
|
||||
|
||||
<p><dt><tt>SANE_String<a name="i120"></tt>:<dd> A string pointer is encoded as a
|
||||
<tt>SANE_Char</tt> array. The trailing NUL byte is considered part
|
||||
of the array and a <tt>NULL</tt> pointer is encoded as a zero-length
|
||||
array.
|
||||
|
||||
<dt><tt>SANE_Handle<a name="i121"></tt>:<dd> A handle is encoded like a word.
|
||||
The network backend needs to take care of converting these integer
|
||||
values to the opaque pointer values that are presented to the user
|
||||
of the network backend. Similarly, the SANE daemon needs to take
|
||||
care of converting the opaque pointer values it receives from its
|
||||
backends into 32-bit integers suitable for use for network encoding.
|
||||
|
||||
<p><dt><em>enumeration types<a name="i122"></em>:<dd> Enumeration types are encoded
|
||||
like words.
|
||||
|
||||
<p></dl>
|
||||
|
||||
<p><h3><a name="s5.1.2">5.1.2 Type Constructors</a></h3>
|
||||
|
||||
<p>Closely following the type constructors of the C language, the SANE network
|
||||
protocol supports the following four constructors:
|
||||
<dl>
|
||||
|
||||
<p><dt><em>pointer<a name="i123"></em>:<dd> A pointer is encoded by a word that indicates
|
||||
whether the pointer is a NULL-pointer which is then followed by the
|
||||
value that the pointer points to (in the case of a non-NULL pointer;
|
||||
in the case of a NULL pointer, no bytes are encoded for the pointer
|
||||
value).
|
||||
|
||||
<p><dt><em>array<a name="i124"></em>:<dd> An array is encoded by a word that indicates
|
||||
the length of the array followed by the values of the elements in
|
||||
the array. The length may be zero in which case no bytes are
|
||||
encoded for the element values.
|
||||
|
||||
<p><dt><em>structure<a name="i125"></em>:<dd> A structure is encoded by simply encoding the
|
||||
structure members in the order in which they appear in the
|
||||
corresponding C type declaration.
|
||||
|
||||
<p><dt><em>union<a name="i126"></em>:<dd> A union must always be accompanied by a tag
|
||||
value that indicates which of the union members is the currently the
|
||||
active one. For this reason, the union itself is encoded simply by
|
||||
encoding the value of the currently active member.
|
||||
|
||||
<p></dl>
|
||||
|
||||
<p>Note that for type constructors, the pointer, element, or member
|
||||
values themselves may have a constructed type. Thus, the above rules
|
||||
should be applied recursively until a sequence of primitive types has
|
||||
been found.
|
||||
|
||||
<p>Also SANE had no need for encoding of circular structures. This
|
||||
greatly simplifies the network protocol.
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc017.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc015.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,460 @@
|
|||
<html><body>
|
||||
<a href="doc018.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc016.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Remote Procedure Call Requests</title>
|
||||
<h2><a name="s5.2">5.2 Remote Procedure Call Requests</a></h2>
|
||||
|
||||
<p>The SANE network protocol is a client/server-style remote procedure
|
||||
call (RPC) protocol. This means that all activity is initiated by the
|
||||
client side (the network backend)---a server is restricted to
|
||||
answering request by the client.
|
||||
|
||||
<p><h3><a name="s5.2.1">5.2.1 <tt>SANE_NET_INIT<a name="i127"></tt></a></h3>
|
||||
|
||||
<p>This RPC establishes a connection to a particular SANE network daemon.
|
||||
It must be the first call in a SANE network session. The parameter
|
||||
and reply arguments for this call are shown in the table below:
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word version_code</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_String user_name</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word version_code</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>version_code</tt> argument in the request is the SANE
|
||||
version-code of the network backend that is contacting the network
|
||||
daemon (see Section <a href="doc010.html#s4.1">4.1</a>). The
|
||||
``build-revision'' in the version code is used to hold the network
|
||||
protocol version. The SANE network daemon receiving such a request
|
||||
must make sure that the network protocol version corresponds to a
|
||||
supported version since otherwise the encoding of the network stream
|
||||
may be incompatible (even though the SANE interface itself may be
|
||||
compatible). The <tt>user_name</tt> argument is the name of the user
|
||||
on whose behalf this call is being performed. If the network backend
|
||||
cannot determine a user-name, it passes a <tt>NULL</tt> pointer for this
|
||||
argument. No trust should be placed in the authenticity of this
|
||||
user-name. The intent of this string is to provide more convenience
|
||||
to the user. E.g., it could be used as the default-user name in
|
||||
subsequent authentication calls.
|
||||
|
||||
<p>In the reply, <tt>status</tt> indicates the completion status. If the
|
||||
value is anything other than <tt>SANE_STATUS_SUCCESS</tt>, the
|
||||
remainder of the reply has undefined values.<a name="F2"><a href="footnotes.html#000002"><sup><fontsize=-2>2</font></sup></a></a> The <tt>version_code</tt> argument returns the
|
||||
SANE version-code that the network daemon supports. See the comments
|
||||
in the previous paragraph on the meaning of the build-revision in this
|
||||
version code.
|
||||
|
||||
<p><h3><a name="s5.2.2">5.2.2 <tt>SANE_NET_GET_DEVICES<a name="i129"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to obtain the list of devices accessible by the SANE
|
||||
daemon.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>void</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Device ***device_list</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
There are no arguments in the request for this call.
|
||||
|
||||
<p>In the reply, <tt>status</tt> indicates the completion status. If the
|
||||
value is anything other than <tt>SANE_STATUS_SUCCESS</tt>, the
|
||||
remainder of the reply has undefined values. The <tt>device_list</tt>
|
||||
argument is a pointer to a <tt>NULL</tt>-terminated array of
|
||||
<tt>SANE_Device</tt> pointers.
|
||||
|
||||
<p><h3><a name="s5.2.3">5.2.3 <tt>SANE_NET_OPEN<a name="i131"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to open a connection to a remote SANE device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_String device_name</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word handle</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_String resource</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>device_name</tt> argument specifies the name of the device to
|
||||
open.
|
||||
|
||||
<p>In the reply, <tt>status</tt> indicates the completion status. If the
|
||||
value is anything other than <tt>SANE_STATUS_SUCCESS</tt>, the
|
||||
remainder of the reply has undefined values. The <tt>handle</tt>
|
||||
argument specifies the device handle that uniquely identifies the
|
||||
connection. The <tt>resource</tt> argument is used to request
|
||||
authentication. If it has a non-<tt>NULL</tt> value, the network
|
||||
backend should authenticate the specified resource and then retry this
|
||||
operation (see Section <a href="doc017.html#s5.2.10">5.2.10</a> for details on how to
|
||||
authorize a resource).
|
||||
|
||||
<p><h3><a name="s5.2.4">5.2.4 <tt>SANE_NET_CLOSE<a name="i133"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to close a connection to a remote SANE device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word dummy</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the connection that should be
|
||||
closed.
|
||||
|
||||
<p>In the reply, the <tt>dummy</tt> argument is unused. Its purpose is to
|
||||
ensure proper synchronization (without it, a net client would not be
|
||||
able to determine when the RPC has completed).
|
||||
|
||||
<p><h3><a name="s5.2.5">5.2.5 <tt>SANE_NET_GET_OPTION_DESCRIPTORS<a name="i135"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to obtain <em>all</em> the option descriptors for a
|
||||
remote SANE device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>Option_Descriptor_Array odesc</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the remote device whose option
|
||||
descriptors should be obtained.
|
||||
|
||||
<p>In the reply, the <tt>odesc</tt> argument is used to return the array of
|
||||
option descriptors. The option descriptor array has the following
|
||||
structure:
|
||||
<blockquote><a name="i137">
|
||||
<pre>
|
||||
struct Option_Descriptor_Array
|
||||
{
|
||||
SANE_Word num_options;
|
||||
SANE_Option_Descriptor **desc;
|
||||
};
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s5.2.6">5.2.6 <tt>SANE_NET_CONTROL_OPTION<a name="i138"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to control (inquire, set, or set to automatic) a
|
||||
specific option of a remote SANE device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Status status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word option</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word info</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word action</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word value_type</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word value_type</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word value_size</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word value_size</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>void *value</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>void *value</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_String *resource</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the remote device whose option
|
||||
should be controlled. Argument <tt>option</tt> is the number (index) of
|
||||
the option that should be controlled. Argument <tt>action</tt>
|
||||
specifies what action should be taken (get, set, or set automatic).
|
||||
Argument <tt>value_type</tt> specifies the type of the option value
|
||||
(must be one of <tt>SANE_TYPE_BOOL</tt>, <tt>SANE_TYPE_INT</tt>,
|
||||
<tt>SANE_TYPE_FIXED</tt>, <tt>SANE_TYPE_STRING</tt>,
|
||||
<tt>SANE_TYPE_BUTTON</tt>). Argument <tt>value_size</tt> specifies
|
||||
the size of the option value in number of bytes (see
|
||||
Section <a href="doc011.html#s4.2.9.6">4.2.9.6</a> for the precise meaning of this value).
|
||||
Finally, argument <tt>value</tt> is a pointer to the option value. It
|
||||
must be a writeable area that is at least <tt>value_size</tt> bytes
|
||||
large. (Note that this area must be writable even if the action is to
|
||||
set the option value. This is because the backend may not be able to
|
||||
set the exact option value, in which case the option value is used to
|
||||
return the next best value that the backend has chosen.)
|
||||
|
||||
<p>In the reply, argument <tt>resource</tt> is set to the name of the
|
||||
resource that must be authorized before this call can be retried. If
|
||||
this value is non-<tt>NULL</tt>, all other arguments have undefined
|
||||
values (see Section <a href="doc017.html#s5.2.10">5.2.10</a> for details on how to
|
||||
authorize a resource). Argument <tt>status</tt> indicates the
|
||||
completion status. If the value is anything other than
|
||||
<tt>SANE_STATUS_SUCCESS</tt>, the remainder of the reply has undefined
|
||||
values. The <tt>info</tt> argument returns the information on how well
|
||||
the backend was able to satisfy the request. For details, see the
|
||||
description of the corresponding argument in
|
||||
Section <a href="doc012.html#s4.3.7">4.3.7</a>. Arguments <tt>value_type</tt> and
|
||||
<tt>value_size</tt> have the same values as the arguments by the same
|
||||
name in corresponding request. The values are repeated here to ensure
|
||||
that both the request and the reply are self-contained (i.e., they can
|
||||
be encoded and decoded independently). Argument <tt>value</tt> is holds
|
||||
the value of the option that has become effective as a result of this
|
||||
RPC.
|
||||
|
||||
<p><h3><a name="s5.2.7">5.2.7 <tt>SANE_NET_GET_PARAMETERS<a name="i140"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to obtain the scan parameters of a remote SANE
|
||||
device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Status status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Parameters params</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the connection to the remote
|
||||
device whose scan parameters should be returned.
|
||||
|
||||
<p>In the reply, <tt>status</tt> indicates the completion status. If the
|
||||
value is anything other than <tt>SANE_STATUS_SUCCESS</tt>, the
|
||||
remainder of the reply has undefined values. The argument
|
||||
<tt>params</tt> is used to return the scan parameters.
|
||||
|
||||
<p><h3><a name="s5.2.8">5.2.8 <tt>SANE_NET_START<a name="i142"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to start image acquisition (scanning).
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Status status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word port</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word byte_order</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_String resource</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the connection to the remote
|
||||
device from which the image should be acquired.
|
||||
|
||||
<p>In the reply, argument <tt>resource</tt> is set to the name of the
|
||||
resource that must be authorized before this call can be retried. If
|
||||
this value is non-<tt>NULL</tt>, all other arguments have undefined
|
||||
values (see Section <a href="doc017.html#s5.2.10">5.2.10</a> for details on how to
|
||||
authorize a resource). Argument, <tt>status</tt> indicates the
|
||||
completion status. If the value is anything other than
|
||||
<tt>SANE_STATUS_SUCCESS</tt>, the remainder of the reply has
|
||||
undefined values. The argument <tt>port</tt> returns the port number
|
||||
from which the image data will be available. To read the image data,
|
||||
a network client must connect to the remote host at the indicated port
|
||||
number. Through this port, the image data is transmitted as a
|
||||
sequence of data records. Each record starts with the data length in
|
||||
bytes. The data length is transmitted as a sequence of four bytes.
|
||||
These bytes should be interpreted as an unsigned integer in big-endian
|
||||
format. The four length bytes are followed by the number of data
|
||||
bytes indicated by the length. Except for byte-order, the data is in
|
||||
the same format as defined for <tt>sane_read()</tt>. Since some
|
||||
records may contain no data at all, a length value of zero is
|
||||
perfectly valid. The special length value of <tt>0xffffffff</tt> is
|
||||
used to indicate the end of the data stream. That is, after receiving
|
||||
a record length of <tt>0xffffffff</tt>, the network client should close
|
||||
the data connection and stop reading data.
|
||||
|
||||
<p>Argument <tt>byte_order</tt> specifies the byte-order of the image
|
||||
data. A value of 0x1234 indicates little-endian format, a value of
|
||||
0x4321 indicates big-endian format. All other values are presently
|
||||
undefined and reserved for future enhancements of this protocol. The
|
||||
intent is that a network server sends data in its own byte-order and
|
||||
the client is responsible for adjusting the byte-order, if necessary.
|
||||
This approach causes no unnecessary overheads in the case where the
|
||||
server and client byte-order match and puts the extra burden on the
|
||||
client side when there is a byte-order mismatch. Putting the burden
|
||||
on the client-side improves the scalability properties of this
|
||||
protocol.
|
||||
|
||||
<p><h3><a name="s5.2.9">5.2.9 <tt>SANE_NET_CANCEL<a name="i144"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to cancel the current operation of a remote SANE
|
||||
device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word dummy</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the connection whose operation
|
||||
should be cancelled.
|
||||
|
||||
<p>In the reply, the <tt>dummy</tt> argument is unused. Its purpose is to
|
||||
ensure proper synchronization (without it, a net client would not be
|
||||
able to determine when the RPC has completed).
|
||||
|
||||
<p><h3><a name="s5.2.10">5.2.10 <tt>SANE_NET_AUTHORIZE<a name="i146"></tt></a></h3>
|
||||
<a name="i148">
|
||||
|
||||
<p>This RPC is used to pass authorization data from the net client to the
|
||||
net server.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_String resource</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word dummy</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_String username</tt> </td>
|
||||
<td colspan=1 align=left nowrap> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_String password</tt> </td>
|
||||
<td colspan=1 align=left nowrap> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>resource</tt> argument specifies the name of the resource to be
|
||||
authorized. This argument should be set to the string returned in the
|
||||
<tt>resource</tt> argument of the RPC reply that required this
|
||||
authorization call. The <tt>username</tt> and <tt>password</tt> are the
|
||||
name of the user that is accessing the resource and the password for
|
||||
the specified resource/user pair.
|
||||
|
||||
<p>Since the password is not encrypted during network transmission, it is
|
||||
recommended to use the following extension:
|
||||
|
||||
<p>If the server adds the string `<tt>$MD5$</tt>' to the resource-name followed
|
||||
by a random string not longer then 128 bytes, the client may answer with the
|
||||
MD5 digest of the concatenation of the password and the random string. To
|
||||
differentiate between the MD5 digest and a strange password the client prepends
|
||||
the MD5 digest with the string `<tt>$MD5$</tt>'.
|
||||
|
||||
<p>In the reply, <tt>dummy</tt> is completely unused. Note that there is
|
||||
no direct failure indication. This is unnecessary since a net client
|
||||
will retry the RPC that resulted in the authorization request until
|
||||
that call succeeds (or until the request is cancelled). The RPC that resulted
|
||||
in the authorization request continues after the reply from the client and may
|
||||
fail with <tt>SANE_STATUS_ACCESS_DENIED</tt>.
|
||||
|
||||
<p><h3><a name="s5.2.11">5.2.11 <tt>SANE_NET_EXIT<a name="i149"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to disconnect a net client from a net server. There
|
||||
are no request or reply arguments in this call. As a result of this
|
||||
call, the connection between the client and the server that was
|
||||
established by the <tt>SANE_NET_INIT</tt> call will be closed.
|
||||
|
||||
<p>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc018.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc016.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
<html><body>
|
||||
<a href="doc019.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc017.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Contact Information</title>
|
||||
<h1><a name="s6">6 Contact Information</a></h1>
|
||||
|
||||
<p>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.
|
||||
<blockquote><a name="i151">
|
||||
<pre>
|
||||
sane-devel-request@mostang.com
|
||||
</pre>
|
||||
</blockquote>
|
||||
To subscribe, send a mail with the body ``<tt>subscribe sane-devel</tt>'' to the
|
||||
above address.
|
||||
|
||||
<p>A complete list of commands supported can be obtained by sending a
|
||||
mail with a subject of ``<tt>help</tt>'' to the above address. The
|
||||
mailing list is archived and available through the SANE home page at
|
||||
URL:
|
||||
<blockquote>
|
||||
http://www.mostang.com/sane/
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
<p><hr>
|
||||
<a href="doc019.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc017.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,186 @@
|
|||
<html><body>
|
||||
<img src=../icons/next_gr.gif border=2 alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc018.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
<h1>Index</h1>
|
||||
|
||||
|
||||
<p><multicol cols=2>
|
||||
<p><a href="doc016.html#i124">array</a><br>
|
||||
|
||||
<p><a href="doc014.html#i115">br-x</a><br>
|
||||
<a href="doc014.html#i116">br-y</a><br>
|
||||
|
||||
<p><a href="doc013.html#i106">code flow</a><br>
|
||||
|
||||
<p><a href="doc011.html#i38">device-name</a><br>
|
||||
<a href="doc012.html#i75">domain</a><br>
|
||||
|
||||
<p><a href="doc016.html#i122">enumeration types</a><br>
|
||||
|
||||
<p><a href="doc008.html#i0">image data format</a><br>
|
||||
|
||||
<p><a href="doc018.html#i151">mailing list</a><br>
|
||||
|
||||
<p><a href="doc017.html#i148">network authorization</a><br>
|
||||
<a href="doc011.html#i21">NUL</a><br>
|
||||
|
||||
<p><a href="doc014.html#i108">option count</a><br>
|
||||
<a href="doc017.html#i137">Option_Descriptor_Array</a><br>
|
||||
|
||||
<p><a href="doc012.html#i77">password</a><br>
|
||||
<a href="doc016.html#i123">pointer</a><br>
|
||||
<a href="doc014.html#i111">preview mode</a><br>
|
||||
|
||||
<p><a href="doc014.html#i110">resolution option</a><br>
|
||||
|
||||
<p><a href="doc012.html#i84">SANE_Action</a><br>
|
||||
<a href="doc012.html#i85">SANE_ACTION_GET_VALUE</a><br>
|
||||
<a href="doc012.html#i87">SANE_ACTION_SET_AUTO</a><br>
|
||||
<a href="doc012.html#i86">SANE_ACTION_SET_VALUE</a><br>
|
||||
<a href="doc012.html#i74">SANE_Authorization_Callback</a><br>
|
||||
<a href="doc011.html#i11">SANE_Bool</a><br>
|
||||
<a href="doc011.html#i9">SANE_Byte</a><br>
|
||||
<a href="doc016.html#i117">SANE_Byte</a><br>
|
||||
<a href="doc012.html#i102">sane_cancel</a><br>
|
||||
<a href="doc011.html#i65">SANE_CAP_ADVANCED</a><br>
|
||||
<a href="doc011.html#i63">SANE_CAP_AUTOMATIC</a><br>
|
||||
<a href="doc011.html#i62">SANE_CAP_EMULATED</a><br>
|
||||
<a href="doc011.html#i60">SANE_CAP_HARD_SELECT</a><br>
|
||||
<a href="doc011.html#i64">SANE_CAP_INACTIVE</a><br>
|
||||
<a href="doc011.html#i61">SANE_CAP_SOFT_DETECT</a><br>
|
||||
<a href="doc011.html#i59">SANE_CAP_SOFT_SELECT</a><br>
|
||||
<a href="doc011.html#i19">SANE_Char</a><br>
|
||||
<a href="doc016.html#i119">SANE_Char</a><br>
|
||||
<a href="doc012.html#i81">sane_close</a><br>
|
||||
<a href="doc011.html#i67">SANE_CONSTRAINT_NONE</a><br>
|
||||
<a href="doc011.html#i68">SANE_CONSTRAINT_RANGE</a><br>
|
||||
<a href="doc011.html#i71">SANE_CONSTRAINT_STRING_LIST</a><br>
|
||||
<a href="doc011.html#i66">SANE_Constraint_Type</a><br>
|
||||
<a href="doc011.html#i70">SANE_CONSTRAINT_WORD_LIST</a><br>
|
||||
<a href="doc012.html#i83">sane_control_option</a><br>
|
||||
<a href="doc010.html#i6">SANE_CURRENT_MAJOR</a><br>
|
||||
<a href="doc011.html#i37">SANE_Device</a><br>
|
||||
<a href="doc012.html#i78">sane_exit</a><br>
|
||||
<a href="doc011.html#i12">SANE_FALSE</a><br>
|
||||
<a href="doc011.html#i17">SANE_FIX</a><br>
|
||||
<a href="doc011.html#i15">SANE_Fixed</a><br>
|
||||
<a href="doc011.html#i16">SANE_FIXED_SCALE_SHIFT</a><br>
|
||||
<a href="doc012.html#i93">SANE_Frame</a><br>
|
||||
<a href="doc008.html#i5">SANE_FRAME_BLUE</a><br>
|
||||
<a href="doc012.html#i98">SANE_FRAME_BLUE</a><br>
|
||||
<a href="doc008.html#i1">SANE_FRAME_GRAY</a><br>
|
||||
<a href="doc012.html#i94">SANE_FRAME_GRAY</a><br>
|
||||
<a href="doc008.html#i4">SANE_FRAME_GREEN</a><br>
|
||||
<a href="doc012.html#i97">SANE_FRAME_GREEN</a><br>
|
||||
<a href="doc008.html#i3">SANE_FRAME_RED</a><br>
|
||||
<a href="doc012.html#i96">SANE_FRAME_RED</a><br>
|
||||
<a href="doc008.html#i2">SANE_FRAME_RGB</a><br>
|
||||
<a href="doc012.html#i95">SANE_FRAME_RGB</a><br>
|
||||
<a href="doc012.html#i79">sane_get_devices</a><br>
|
||||
<a href="doc012.html#i82">sane_get_option_descriptor</a><br>
|
||||
<a href="doc012.html#i91">sane_get_parameters</a><br>
|
||||
<a href="doc012.html#i104">sane_get_select_fd</a><br>
|
||||
<a href="doc011.html#i23">SANE_Handle</a><br>
|
||||
<a href="doc016.html#i121">SANE_Handle</a><br>
|
||||
<a href="doc012.html#i88">SANE_INFO_INEXACT</a><br>
|
||||
<a href="doc012.html#i89">SANE_INFO_RELOAD_OPTIONS</a><br>
|
||||
<a href="doc012.html#i100">SANE_INFO_RELOAD_OPTIONS</a><br>
|
||||
<a href="doc012.html#i90">SANE_INFO_RELOAD_PARAMS</a><br>
|
||||
<a href="doc012.html#i73">sane_init</a><br>
|
||||
<a href="doc011.html#i14">SANE_Int</a><br>
|
||||
<a href="doc017.html#i146">SANE_NET_AUTHORIZE</a><br>
|
||||
<a href="doc017.html#i147">SANE_NET_AUTHORIZE</a><br>
|
||||
<a href="doc017.html#i144">SANE_NET_CANCEL</a><br>
|
||||
<a href="doc017.html#i145">SANE_NET_CANCEL</a><br>
|
||||
<a href="doc017.html#i133">SANE_NET_CLOSE</a><br>
|
||||
<a href="doc017.html#i134">SANE_NET_CLOSE</a><br>
|
||||
<a href="doc017.html#i138">SANE_NET_CONTROL_OPTION</a><br>
|
||||
<a href="doc017.html#i139">SANE_NET_CONTROL_OPTION</a><br>
|
||||
<a href="doc017.html#i149">SANE_NET_EXIT</a><br>
|
||||
<a href="doc017.html#i150">SANE_NET_EXIT</a><br>
|
||||
<a href="doc017.html#i129">SANE_NET_GET_DEVICES</a><br>
|
||||
<a href="doc017.html#i130">SANE_NET_GET_DEVICES</a><br>
|
||||
<a href="doc017.html#i135">SANE_NET_GET_OPTION_DESCRIPTORS</a><br>
|
||||
<a href="doc017.html#i136">SANE_NET_GET_OPTION_DESCRIPTORS</a><br>
|
||||
<a href="doc017.html#i140">SANE_NET_GET_PARAMETERS</a><br>
|
||||
<a href="doc017.html#i141">SANE_NET_GET_PARAMETERS</a><br>
|
||||
<a href="doc017.html#i127">SANE_NET_INIT</a><br>
|
||||
<a href="doc017.html#i128">SANE_NET_INIT</a><br>
|
||||
<a href="doc017.html#i131">SANE_NET_OPEN</a><br>
|
||||
<a href="doc017.html#i132">SANE_NET_OPEN</a><br>
|
||||
<a href="doc017.html#i142">SANE_NET_START</a><br>
|
||||
<a href="doc017.html#i143">SANE_NET_START</a><br>
|
||||
<a href="doc012.html#i80">sane_open</a><br>
|
||||
<a href="doc011.html#i41">SANE_Option_Descriptor</a><br>
|
||||
<a href="doc011.html#i57">SANE_OPTION_IS_ACTIVE</a><br>
|
||||
<a href="doc011.html#i58">SANE_OPTION_IS_SETTABLE</a><br>
|
||||
<a href="doc012.html#i92">SANE_Parameters</a><br>
|
||||
<a href="doc011.html#i69">SANE_Range</a><br>
|
||||
<a href="doc012.html#i101">sane_read</a><br>
|
||||
<a href="doc012.html#i103">sane_set_io_mode</a><br>
|
||||
<a href="doc012.html#i99">sane_start</a><br>
|
||||
<a href="doc011.html#i24">SANE_Status</a><br>
|
||||
<a href="doc011.html#i36">SANE_STATUS_ACCESS_DENIED</a><br>
|
||||
<a href="doc011.html#i27">SANE_STATUS_CANCELLED</a><br>
|
||||
<a href="doc011.html#i33">SANE_STATUS_COVER_OPEN</a><br>
|
||||
<a href="doc011.html#i28">SANE_STATUS_DEVICE_BUSY</a><br>
|
||||
<a href="doc011.html#i30">SANE_STATUS_EOF</a><br>
|
||||
<a href="doc011.html#i25">SANE_STATUS_GOOD</a><br>
|
||||
<a href="doc012.html#i72">SANE_STATUS_GOOD</a><br>
|
||||
<a href="doc011.html#i29">SANE_STATUS_INVAL</a><br>
|
||||
<a href="doc011.html#i34">SANE_STATUS_IO_ERROR</a><br>
|
||||
<a href="doc011.html#i31">SANE_STATUS_JAMMED</a><br>
|
||||
<a href="doc011.html#i32">SANE_STATUS_NO_DOCS</a><br>
|
||||
<a href="doc011.html#i35">SANE_STATUS_NO_MEM</a><br>
|
||||
<a href="doc011.html#i26">SANE_STATUS_UNSUPPORTED</a><br>
|
||||
<a href="doc011.html#i20">SANE_String</a><br>
|
||||
<a href="doc016.html#i120">SANE_String</a><br>
|
||||
<a href="doc011.html#i22">SANE_String_Const</a><br>
|
||||
<a href="doc012.html#i105">sane_strstatus</a><br>
|
||||
<a href="doc011.html#i13">SANE_TRUE</a><br>
|
||||
<a href="doc011.html#i43">SANE_TYPE_BOOL</a><br>
|
||||
<a href="doc011.html#i47">SANE_TYPE_BUTTON</a><br>
|
||||
<a href="doc011.html#i45">SANE_TYPE_FIXED</a><br>
|
||||
<a href="doc011.html#i48">SANE_TYPE_GROUP</a><br>
|
||||
<a href="doc011.html#i44">SANE_TYPE_INT</a><br>
|
||||
<a href="doc011.html#i46">SANE_TYPE_STRING</a><br>
|
||||
<a href="doc011.html#i49">SANE_Unit</a><br>
|
||||
<a href="doc011.html#i18">SANE_UNFIX</a><br>
|
||||
<a href="doc011.html#i52">SANE_UNIT_BIT</a><br>
|
||||
<a href="doc011.html#i54">SANE_UNIT_DPI</a><br>
|
||||
<a href="doc011.html#i56">SANE_UNIT_MICROSECOND</a><br>
|
||||
<a href="doc011.html#i53">SANE_UNIT_MM</a><br>
|
||||
<a href="doc011.html#i50">SANE_UNIT_NONE</a><br>
|
||||
<a href="doc011.html#i55">SANE_UNIT_PERCENT</a><br>
|
||||
<a href="doc011.html#i51">SANE_UNIT_PIXEL</a><br>
|
||||
<a href="doc011.html#i42">SANE_Value_Type</a><br>
|
||||
<a href="doc010.html#i7">SANE_VERSION_CODE</a><br>
|
||||
<a href="doc010.html#i8">SANE_VERSION_MAJOR</a><br>
|
||||
<a href="doc011.html#i10">SANE_Word</a><br>
|
||||
<a href="doc016.html#i118">SANE_Word</a><br>
|
||||
<a href="doc014.html#i112">scan area options</a><br>
|
||||
<a href="doc014.html#i109">scan resolution</a><br>
|
||||
<a href="doc016.html#i125">structure</a><br>
|
||||
|
||||
<p><a href="doc014.html#i113">tl-x</a><br>
|
||||
<a href="doc014.html#i114">tl-y</a><br>
|
||||
<a href="doc011.html#i40">Type Strings</a><br>
|
||||
|
||||
<p><a href="doc016.html#i126">union</a><br>
|
||||
<a href="doc012.html#i76">username</a><br>
|
||||
|
||||
<p><a href="doc011.html#i39">Vendor Strings</a><br>
|
||||
|
||||
<p><a href="doc014.html#i107">well-known options</a><br>
|
||||
</multicol><p><hr>
|
||||
<img src=../icons/next_gr.gif border=2 alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc018.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
<title>Footnotes</title><h1>Footnotes</h1><p>
|
||||
|
||||
<hr><p><b><a href="doc011.html#F1">1</a></b> This is different from ANSI C where
|
||||
any non-zero integer value represents logical TRUE.
|
||||
<hr><p><b><a href="doc017.html#F2">2</a></b> The sane network
|
||||
daemon should be careful not to leak information in the undefined
|
||||
portion of the reply.
|
||||
|
|
@ -0,0 +1,56 @@
|
|||
<html><body>
|
||||
<a href="doc002.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc000.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
<title>./sane</title>
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
<p>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
<p><center><h1><font size=+4>SANE Standard Version 1.03</font></h1></center>
|
||||
<center></center>
|
||||
<center>2003-02-22</center>
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
<p><h1><a href="doc002.html">1 Preface</a></h1><h1><a href="doc004.html">2 Introduction</a></h1><h1><a href="doc006.html">3 The SANE Environment</a></h1><h1><a href="doc009.html">4 The SANE Application Programmer Interface (API)</a></h1><h1><a href="doc015.html">5 Network Protocol</a></h1><h1><a href="doc018.html">6 Contact Information</a></h1><p><hr>
|
||||
<a href="doc002.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc000.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
Plik diff jest za duży
Load Diff
Plik binarny nie jest wyświetlany.
Plik diff jest za duży
Load Diff
Plik diff jest za duży
Load Diff
Plik binarny nie jest wyświetlany.
Plik diff jest za duży
Load Diff
Plik diff jest za duży
Load Diff
|
|
@ -0,0 +1,131 @@
|
|||
<html><body>
|
||||
<a href="doc001.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<img src=../icons/up_gr.gif border=2 alt="Previous"></a>
|
||||
<img src=../icons/previous_gr.gif border=2 alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
<title>Contents</title>
|
||||
<h1>Contents</h1><p>
|
||||
|
||||
<table>
|
||||
<tr></tr><tr><td colspan=20>1<tt> </tt><a href="doc002.html#s1"><b>Preface</b></a></td></tr>
|
||||
<tr><td></td><td colspan=20>1.1<tt> </tt><a href="doc003.html#s1.1">About This Document</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>1.1.1<tt> </tt><a href="doc003.html#s1.1.1">Typographic Conventions</a></td></tr>
|
||||
<tr></tr><tr><td colspan=20>2<tt> </tt><a href="doc004.html#s2"><b>Introduction</b></a></td></tr>
|
||||
<tr><td></td><td colspan=20>2.1<tt> </tt><a href="doc005.html#s2.1">Terminology</a></td></tr>
|
||||
<tr></tr><tr><td colspan=20>3<tt> </tt><a href="doc006.html#s3"><b>The SANE Environment</b></a></td></tr>
|
||||
<tr><td></td><td colspan=20>3.1<tt> </tt><a href="doc007.html#s3.1">Attaching to a SANE backend</a></td></tr>
|
||||
<tr><td></td><td colspan=20>3.2<tt> </tt><a href="doc008.html#s3.2">Image Data Format</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>3.2.1<tt> </tt><a href="doc008.html#s3.2.1">Pixel oriented frames</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>3.2.2<tt> </tt><a href="doc008.html#s3.2.2">Arbitrary data frames</a></td></tr>
|
||||
<tr></tr><tr><td colspan=20>4<tt> </tt><a href="doc009.html#s4"><b>The SANE Application Programmer Interface (API)</b></a></td></tr>
|
||||
<tr><td></td><td colspan=20>4.1<tt> </tt><a href="doc010.html#s4.1">Version Control</a></td></tr>
|
||||
<tr><td></td><td colspan=20>4.2<tt> </tt><a href="doc011.html#s4.2">Data Types</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.1<tt> </tt><a href="doc011.html#s4.2.1">Base Types</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.2<tt> </tt><a href="doc011.html#s4.2.2">Boolean Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.3<tt> </tt><a href="doc011.html#s4.2.3">Integer Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.4<tt> </tt><a href="doc011.html#s4.2.4">Fixed-point Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.5<tt> </tt><a href="doc011.html#s4.2.5">Text</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.5.1<tt> </tt><a href="doc011.html#s4.2.5.1">Character Type</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.5.2<tt> </tt><a href="doc011.html#s4.2.5.2">String Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.6<tt> </tt><a href="doc011.html#s4.2.6">Scanner Handle Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.7<tt> </tt><a href="doc011.html#s4.2.7">Status Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.8<tt> </tt><a href="doc011.html#s4.2.8">Device Descriptor Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.9<tt> </tt><a href="doc011.html#s4.2.9">Option Descriptor Type</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.1<tt> </tt><a href="doc011.html#s4.2.9.1">Option Name</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.2<tt> </tt><a href="doc011.html#s4.2.9.2">Option Title</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.3<tt> </tt><a href="doc011.html#s4.2.9.3">Option Description</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.4<tt> </tt><a href="doc011.html#s4.2.9.4">Option Value Type</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.5<tt> </tt><a href="doc011.html#s4.2.9.5">Option Value Unit</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.6<tt> </tt><a href="doc011.html#s4.2.9.6">Option Value Size</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.7<tt> </tt><a href="doc011.html#s4.2.9.7">Option Capabilities</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.8<tt> </tt><a href="doc011.html#s4.2.9.8">Option Value Constraints</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.10<tt> </tt><a href="doc011.html#s4.2.10">Internationalization</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.10.1<tt> </tt><a href="doc011.html#s4.2.10.1">How is a text marked for translation</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.10.2<tt> </tt><a href="doc011.html#s4.2.10.2">Which texts shall be marked for translation?</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.10.3<tt> </tt><a href="doc011.html#s4.2.10.3">File formats and translation functions</a></td></tr>
|
||||
<tr><td></td><td colspan=20>4.3<tt> </tt><a href="doc012.html#s4.3">Operations</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.1<tt> </tt><a href="doc012.html#s4.3.1"><tt>sane_init</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.2<tt> </tt><a href="doc012.html#s4.3.2"><tt>sane_exit</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.3<tt> </tt><a href="doc012.html#s4.3.3"><tt>sane_get_devices</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.4<tt> </tt><a href="doc012.html#s4.3.4"><tt>sane_open</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.5<tt> </tt><a href="doc012.html#s4.3.5"><tt>sane_close</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.6<tt> </tt><a href="doc012.html#s4.3.6"><tt>sane_get_option_descriptor</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.7<tt> </tt><a href="doc012.html#s4.3.7"><tt>sane_control_option</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.8<tt> </tt><a href="doc012.html#s4.3.8"><tt>sane_get_parameters</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.9<tt> </tt><a href="doc012.html#s4.3.9"><tt>sane_start</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.10<tt> </tt><a href="doc012.html#s4.3.10"><tt>sane_read</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.11<tt> </tt><a href="doc012.html#s4.3.11"><tt>sane_cancel</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.12<tt> </tt><a href="doc012.html#s4.3.12"><tt>sane_set_io_mode</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.13<tt> </tt><a href="doc012.html#s4.3.13"><tt>sane_get_select_fd</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.14<tt> </tt><a href="doc012.html#s4.3.14"><tt>sane_strstatus</tt></a></td></tr>
|
||||
<tr><td></td><td colspan=20>4.4<tt> </tt><a href="doc013.html#s4.4">Code Flow</a></td></tr>
|
||||
<tr><td></td><td colspan=20>4.5<tt> </tt><a href="doc014.html#s4.5">Well-Known Options</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.1<tt> </tt><a href="doc014.html#s4.5.1">Option Number Count</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.2<tt> </tt><a href="doc014.html#s4.5.2">Scan Resolution Options</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.3<tt> </tt><a href="doc014.html#s4.5.3">Preview Mode Option</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.4<tt> </tt><a href="doc014.html#s4.5.4">Scan Area Options</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.5<tt> </tt><a href="doc014.html#s4.5.5">Depth option</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.6<tt> </tt><a href="doc014.html#s4.5.6">Gamma table options</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.7<tt> </tt><a href="doc014.html#s4.5.7">Scan Mode options</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.8<tt> </tt><a href="doc014.html#s4.5.8">Scan Source options</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.9<tt> </tt><a href="doc014.html#s4.5.9">Threshold</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.10<tt> </tt><a href="doc014.html#s4.5.10">Analog gamma</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.11<tt> </tt><a href="doc014.html#s4.5.11">Shadow</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.12<tt> </tt><a href="doc014.html#s4.5.12">Highlight</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.13<tt> </tt><a href="doc014.html#s4.5.13">Turn lamp on and off</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.14<tt> </tt><a href="doc014.html#s4.5.14">Scanner buttons</a></td></tr>
|
||||
<tr></tr><tr><td colspan=20>5<tt> </tt><a href="doc015.html#s5"><b>Network Protocol</b></a></td></tr>
|
||||
<tr><td></td><td colspan=20>5.1<tt> </tt><a href="doc016.html#s5.1">Data Type Encoding</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.1.1<tt> </tt><a href="doc016.html#s5.1.1">Primitive Data Types</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.1.2<tt> </tt><a href="doc016.html#s5.1.2">Type Constructors</a></td></tr>
|
||||
<tr><td></td><td colspan=20>5.2<tt> </tt><a href="doc017.html#s5.2">Remote Procedure Call Requests</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.1<tt> </tt><a href="doc017.html#s5.2.1"><tt>SANE_NET_INIT<a name="i146"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.2<tt> </tt><a href="doc017.html#s5.2.2"><tt>SANE_NET_GET_DEVICES<a name="i148"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.3<tt> </tt><a href="doc017.html#s5.2.3"><tt>SANE_NET_OPEN<a name="i150"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.4<tt> </tt><a href="doc017.html#s5.2.4"><tt>SANE_NET_CLOSE<a name="i152"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.5<tt> </tt><a href="doc017.html#s5.2.5"><tt>SANE_NET_GET_OPTION_DESCRIPTORS<a name="i154"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.6<tt> </tt><a href="doc017.html#s5.2.6"><tt>SANE_NET_CONTROL_OPTION<a name="i157"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.7<tt> </tt><a href="doc017.html#s5.2.7"><tt>SANE_NET_GET_PARAMETERS<a name="i159"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.8<tt> </tt><a href="doc017.html#s5.2.8"><tt>SANE_NET_START<a name="i161"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.9<tt> </tt><a href="doc017.html#s5.2.9"><tt>SANE_NET_CANCEL<a name="i163"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.10<tt> </tt><a href="doc017.html#s5.2.10"><tt>SANE_NET_AUTHORIZE<a name="i165"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.11<tt> </tt><a href="doc017.html#s5.2.11"><tt>SANE_NET_EXIT<a name="i168"></tt></a></td></tr>
|
||||
<tr></tr><tr><td colspan=20>6<tt> </tt><a href="doc018.html#s6"><b>Contact Information</b></a></td></tr>
|
||||
</table>
|
||||
|
||||
<h1>List of Figures</h1>
|
||||
|
||||
<table>
|
||||
<tr><td>1</td><td><a href="doc007.html#f1">Example SANE Hiearchy</a></td></tr>
|
||||
<tr><td>2</td><td><a href="doc008.html#f2">Transfer order of image data bytes</a></td></tr>
|
||||
<tr><td>3</td><td><a href="doc008.html#f3">Bit and byte order of image data</a></td></tr>
|
||||
<tr><td>4</td><td><a href="doc013.html#f4">Code flow</a></td></tr>
|
||||
<tr><td>5</td><td><a href="doc014.html#f5">Scan area options</a></td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
<h1>List of Tables</h1>
|
||||
|
||||
<table>
|
||||
<tr><td>1</td><td><a href="doc011.html#f1">Status Codes</a></td></tr>
|
||||
<tr><td>2</td><td><a href="doc011.html#f2">Predefined Device Information Strings</a></td></tr>
|
||||
<tr><td>3</td><td><a href="doc011.html#f3">Option Value Types (<tt>SANE_Value_Type</tt>)</a></td></tr>
|
||||
<tr><td>4</td><td><a href="doc011.html#f4">Physical Units (<tt>SANE_Unit</tt>)</a></td></tr>
|
||||
<tr><td>5</td><td><a href="doc011.html#f5">Option Capabilities</a></td></tr>
|
||||
<tr><td>6</td><td><a href="doc011.html#f6">Option Value Constraints</a></td></tr>
|
||||
<tr><td>7</td><td><a href="doc012.html#f7">Action Values (<tt>SANE_Action</tt>)</a></td></tr>
|
||||
<tr><td>8</td><td><a href="doc012.html#f8">Additional Information Returned When Setting an Option</a></td></tr>
|
||||
<tr><td>9</td><td><a href="doc012.html#f9">Frame Format (<tt>SANE_Frame</tt>)</a></td></tr>
|
||||
</table>
|
||||
|
||||
<p><hr>
|
||||
<a href="doc001.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<img src=../icons/up_gr.gif border=2 alt="Previous"></a>
|
||||
<img src=../icons/previous_gr.gif border=2 alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
<html><body>
|
||||
<a href="doc002.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc000.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
<title>./sane</title>
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
<p>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
<p><center><h1><font size=+4>SANE Standard Version 2.0 proposal 0.07 - rauch/beck</font></h1></center>
|
||||
<center></center>
|
||||
<center>Dec 5, 2002</center>
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
<p><h1><a href="doc002.html">1 Preface</a></h1><h1><a href="doc004.html">2 Introduction</a></h1><h1><a href="doc006.html">3 The SANE Environment</a></h1><h1><a href="doc009.html">4 The SANE Application Programmer Interface (API)</a></h1><h1><a href="doc015.html">5 Network Protocol</a></h1><h1><a href="doc018.html">6 Contact Information</a></h1><p><hr>
|
||||
<a href="doc002.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc000.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
<html><body>
|
||||
<a href="doc003.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc001.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Preface</title>
|
||||
<h1><a name="s1">1 Preface</a></h1>
|
||||
|
||||
<p>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
|
||||
<a href="doc018.html#s6">6</a>.
|
||||
|
||||
<p>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.
|
||||
|
||||
<p><h2><a href="doc003.html">1.1 About This Document</a></h2><p><hr>
|
||||
<a href="doc003.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc001.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
<html><body>
|
||||
<a href="doc004.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc002.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>About This Document</title>
|
||||
<h2><a name="s1.1">1.1 About This Document</a></h2>
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>The remainder of this document is organized as follows.
|
||||
Chapter <a href="doc004.html#s2">2</a> provides introductional material.
|
||||
Chapter <a href="doc006.html#s3">3</a> presents the environment SANE is designed
|
||||
for. Chapter <a href="doc009.html#s4">4</a> details the SANE Application Programmer
|
||||
Interface. Chapter <a href="doc015.html#s5">5</a> specifies the network protocol that
|
||||
can be used to implement the SANE API in a network transparent
|
||||
fashion. Finally, Chapter <a href="doc018.html#s6">6</a> gives information on how
|
||||
to join the SANE development process.
|
||||
|
||||
<p><h3><a name="s1.1.1">1.1.1 Typographic Conventions</a></h3>
|
||||
|
||||
<p>Changes since the last revision of this document are highlighted
|
||||
like this:
|
||||
|
||||
<p><font color="darkgreen">
|
||||
Paragraphs that changed since the last revision of the documention
|
||||
are marked like this paragraph.
|
||||
</font>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc004.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc002.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
<html><body>
|
||||
<a href="doc005.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc003.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Introduction</title>
|
||||
<h1><a name="s2">2 Introduction</a></h1>
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>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.
|
||||
|
||||
<p><h2><a href="doc005.html">2.1 Terminology</a></h2><p><hr>
|
||||
<a href="doc005.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc003.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
<html><body>
|
||||
<a href="doc006.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc004.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Terminology</title>
|
||||
<h2><a name="s2.1">2.1 Terminology</a></h2>
|
||||
|
||||
<p>An application that uses the SANE interface is called a SANE <em>
|
||||
frontend</em>. A driver that implements the SANE interface is called a
|
||||
SANE <em>backend</em>. A <em>meta backend</em> provides some means to
|
||||
manage one or more other backends.
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc006.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc004.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
<html><body>
|
||||
<a href="doc007.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc005.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>The SANE Environment</title>
|
||||
<h1><a name="s3">3 The SANE Environment</a></h1>
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>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</em>. An option is
|
||||
a self-describing name/value pair. For example, the brightness
|
||||
control of a camera might be represented by an option called
|
||||
<tt>brightness</tt> whose value is an integer in the range from 0 to
|
||||
255.
|
||||
|
||||
<p>With self-describing options, a backend need not be concerned with
|
||||
<em>presentation</em> 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</em> of each option. It simply provides
|
||||
means to present and alter the options defined by the backend.
|
||||
|
||||
<p><h2><a href="doc007.html">3.1 Attaching to a SANE backend</a></h2><h2><a href="doc008.html">3.2 Image Data Format</a></h2><p><hr>
|
||||
<a href="doc007.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc005.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,104 @@
|
|||
<html><body>
|
||||
<a href="doc008.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc006.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Attaching to a SANE backend</title>
|
||||
<h2><a name="s3.1">3.1 Attaching to a SANE backend</a></h2>
|
||||
|
||||
<p>The process through which a SANE frontend connects to a backend is
|
||||
platform dependent. Several possibilities exist:
|
||||
<ul>
|
||||
|
||||
<p><li><b>Static linking:</b> 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 <tt>be</tt>
|
||||
would normally export a function called <tt>sane_read()</tt>. 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 <tt>be</tt> include a
|
||||
header file that has lines of the form:
|
||||
<blockquote>
|
||||
<pre>
|
||||
#define sane_read be_sane_read
|
||||
</pre>
|
||||
</blockquote>
|
||||
With definitions of this kind, backend <tt>be</tt> will export
|
||||
function name <tt>be_sane_read()</tt>. 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.
|
||||
|
||||
<p><li><b>Dynamic linking:</b> 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 <tt>sane_</tt>), 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.
|
||||
|
||||
<p> More importantly, dynamic linking makes it easy to implement a meta
|
||||
backend that loads other backends <em>on demand</em>. This is a
|
||||
powerful mechanism since it allows adding new backends merely by
|
||||
installing a shared library and updating a configuration file.
|
||||
|
||||
<p><li><b>Network connection:</b> 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.
|
||||
|
||||
<p></ul>
|
||||
|
||||
<p><p><a name="f1"></a>
|
||||
<center>
|
||||
|
||||
<img width=780 height=384 src="img000.gif">
|
||||
<p><center>Figure 1: Example SANE Hiearchy</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>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 <a href="doc007.html#f1">1</a>. The figure shows that machine
|
||||
A uses a dynamic-linking based meta backend called <tt>dll</tt> to
|
||||
access the backends called <tt>pnm</tt>, <tt>mustek</tt>, and <tt>net</tt>.
|
||||
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 <tt>saned</tt>. The <tt>saned</tt> in
|
||||
turn has access to the <tt>hp</tt> and <tt>autolum</tt> backends through
|
||||
another instance of the <tt>dll</tt> backend. The <tt>autolum</tt> meta
|
||||
backend is used to automatically adjust the luminance (brightness) of
|
||||
the image data acquired by the camera backend called <tt>qcam</tt>.
|
||||
|
||||
<p>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.
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc008.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc006.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,155 @@
|
|||
<html><body>
|
||||
<a href="doc009.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc007.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Image Data Format</title>
|
||||
<h2><a name="s3.2">3.2 Image Data Format</a></h2><a name="i0">
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>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
|
||||
(preferable quadratic) pixel. A pixel consists of one or more sample values.
|
||||
Each sample value represents one channel (e.g., the red channel).
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>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 and a format
|
||||
descriptor.
|
||||
|
||||
<p><font color="darkgreen">
|
||||
There are two different types of frames: pixel oriented frames
|
||||
<tt>SANE_FRAME_RAW<a name="i1"></tt> and arbitrary data frames
|
||||
<tt>SANE_FRAME_MIME<a name="i2"></tt>. These types are discussed in detail in the
|
||||
following sections. The frame types used by version 1 of this standard
|
||||
(<tt>SANE_FRAME_GRAY<a name="i3"></tt>, <tt>SANE_FRAME_RGB<a name="i4"></tt>,
|
||||
<tt>SANE_FRAME_RED<a name="i5"></tt>, <tt>SANE_FRAME_GREEN<a name="i6"></tt>, and
|
||||
<tt>SANE_FRAME_BLUE<a name="i7"></tt>) are obsolete and superseded by
|
||||
<tt>SANE_FRAME_RAW<a name="i8"></tt>.
|
||||
|
||||
<p> <h3><a name="s3.2.1">3.2.1 Pixel oriented frames</a></h3>
|
||||
|
||||
<p> The type of pixel oriented frames is <tt>SANE_FRAME_RAW<a name="i9"></tt>. The
|
||||
frame contains one or more channels of data in a channel-interleaved format,
|
||||
that represents sample values from a property of the individual pixels that
|
||||
is subject to further description in the <tt>format_desc</tt> member of the
|
||||
<tt>SANE_Parameters</tt> structured type. See section <a href="doc012.html#s4.3.8">4.3.8</a>
|
||||
on page <a href="doc012.html#s4.3.8">4.3.8</a> for details about the format
|
||||
descriptions.
|
||||
</font>
|
||||
|
||||
<p> 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).
|
||||
|
||||
<p><font color="darkgreen">
|
||||
The complete image may consist of several different channels. The number of channels
|
||||
is defined by member <tt>channels_per_image</tt> of <tt>SANE_Parameters</tt>.
|
||||
The image may be transmitted in an arbitary number of frames which can be
|
||||
determined by watching the <tt>SANE_PFLAG_LAST_FRAME</tt> flag in said type (or by
|
||||
counting the channels). Note: This frame type replaces all frame types of
|
||||
the SANE standard version 1.
|
||||
</font>
|
||||
|
||||
<p>Conceptually, each pixel oriented 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.
|
||||
<blockquote>
|
||||
<center>
|
||||
<b>Backend Implementation Note</b>
|
||||
</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.
|
||||
</blockquote>
|
||||
|
||||
<p><p><a name="f2"></a>
|
||||
<center>
|
||||
|
||||
<img width=390 height=196 src="img001.gif">
|
||||
<p><center>Figure 2: Transfer order of image data bytes</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>The order in which the sample values in a frame are transmitted is illustrated
|
||||
in Figure <a href="doc008.html#f2">2</a>. 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).
|
||||
|
||||
<p>If a frame contains multiple channels, then the channels are transmitted in an
|
||||
interleaved fashion. Figure <a href="doc008.html#f3">3</a> illustrates this for the case
|
||||
where a frame contains a complete red/green/blue image with a bit-depth of 8.
|
||||
|
||||
<p><p><a name="f3"></a>
|
||||
<center>
|
||||
|
||||
<img width=624 height=111 src="img002.gif">
|
||||
<p><center>Figure 3: Bit and byte order of image data</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>For a bit depth of 1, each byte contains 8 sample values of a <em>single</em>
|
||||
channel. In other words, a bit depth 1 frame is transmitted in a byte
|
||||
interleaved fashion. The first sample of each byte is represented by the most
|
||||
significant bit.
|
||||
|
||||
<p><font color="darkgreen">
|
||||
For gray channels at a bit depth of 1 only two sample values are possible: 1
|
||||
represents minimum intensity (black) and 0 represents maximum intensity
|
||||
(white). For all other channel types and bit depths a sample value of 0
|
||||
represents minimum intensity and larger values represent increasing intensity.
|
||||
|
||||
<p><h3><a name="s3.2.2">3.2.2 Arbitrary data frames</a></h3>
|
||||
|
||||
<p>It also is possible to transmit arbitrary (not necessaryly pixel oriented)
|
||||
data. This allows transmission of compressed images like jpeg, tiff, etc.
|
||||
|
||||
<p>The type of arbitrary data frames is <tt>SANE_FRAME_MIME<a name="i10"></tt>.
|
||||
The frame contains arbitrary data of the MIME (see RFC 1521/1522) type that is
|
||||
given in the <tt>format_desc</tt> member of the <tt>SANE_Parameters</tt>
|
||||
structured type (see See section <a href="doc012.html#s4.3.8">4.3.8</a> on
|
||||
page <a href="doc012.html#s4.3.8">4.3.8</a>). As such, it is assumed to be
|
||||
incomprehensible to the frontend, except for selected types the frontend is
|
||||
specifically capable of handling internally. The frontend is free to ignore
|
||||
those frames, or employ any appropriate means to otherwise handle this data
|
||||
(like saving them to disk or spawning an external viewer).
|
||||
</font>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc009.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc007.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
<html><body>
|
||||
<a href="doc010.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc008.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>The SANE Application Programmer Interface (API)</title>
|
||||
<h1><a name="s4">4 The SANE Application Programmer Interface (API)</a></h1>
|
||||
|
||||
<p><font color="darkgreen">
|
||||
This Section defines version 2 of the SANE application
|
||||
programmer interface (API). Any SANE frontend must depend on the
|
||||
interface defined in this section only. 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 <tt>sane/sane-2.h</tt>. This file should
|
||||
normally be included via a C pre-processor directive of the form:
|
||||
<pre>
|
||||
#include <sane/sane-2.h>
|
||||
</pre>
|
||||
</font>
|
||||
|
||||
<p><h2><a href="doc010.html">4.1 Version Control</a></h2><h2><a href="doc011.html">4.2 Data Types</a></h2><h2><a href="doc012.html">4.3 Operations</a></h2><h2><a href="doc013.html">4.4 Code Flow</a></h2><h2><a href="doc014.html">4.5 Well-Known Options</a></h2><p><hr>
|
||||
<a href="doc010.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc008.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,77 @@
|
|||
<html><body>
|
||||
<a href="doc011.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc009.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Version Control</title>
|
||||
<h2><a name="s4.1">4.1 Version Control</a></h2>
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>The SANE API provides the following five macros to manage version
|
||||
numbers.
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_CURRENT_MAJOR<a name="i11"></tt>:<dd> The value of this macro is the
|
||||
number of the SANE standard that the interface implements.
|
||||
|
||||
<p> <dt><tt>SANE_VERSION_CODE<a name="i12">(<i>maj</i>,<i>min</i>,<i>bld</i>)</tt>:<dd>
|
||||
|
||||
This macro can be used to build a monotonically increasing version
|
||||
code. A SANE version code consists of the SANE standard major
|
||||
version number (<i>maj</i>), the minor version number <i>min</i>,
|
||||
and the build revision of a backend (<i>bld</i>). The major and
|
||||
minor version numbers must be in the range 0...255 and the
|
||||
build revision must be in the range 0...65535.
|
||||
|
||||
<p> 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.
|
||||
|
||||
<p> 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.
|
||||
|
||||
<dt><tt>SANE_VERSION_MAJOR<a name="i13">(<i>vc</i>)</tt>:<dd> This macro returns the
|
||||
major version number component of the version code passed in
|
||||
argument <i>vc</i>.
|
||||
<dt><tt>SANE_VERSION_MINOR(<i>vc</i>)</tt>:<dd> This macro returns the
|
||||
minor version number component of the version code passed in
|
||||
argument <i>vc</i>.
|
||||
<dt><tt>SANE_VERSION_BUILD(<i>vc</i>)</tt>:<dd> This macro returns the
|
||||
build revision component of the version code passed in argument
|
||||
<i>vc</i>.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc011.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc009.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
Plik diff jest za duży
Load Diff
|
|
@ -0,0 +1,874 @@
|
|||
<html><body>
|
||||
<a href="doc013.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc011.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Operations</title>
|
||||
<h2><a name="s4.3">4.3 Operations</a></h2>
|
||||
|
||||
<p><h3><a name="s4.3.1">4.3.1 <tt>sane_init</tt></a></h3>
|
||||
|
||||
<p>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 <tt>sane_init</tt> is different from
|
||||
<tt>SANE_STATUS_GOOD<a name="i77"></tt>. The version code of the backend is returned
|
||||
in the value pointed to by <tt>version_code</tt>. If that pointer is
|
||||
<tt>NULL</tt>, no version code is returned. Argument <tt>authorize</tt> is either
|
||||
a pointer to a function that is invoked when the backend requires
|
||||
authentication for a specific resource or <tt>NULL</tt> if the frontend does not
|
||||
support authentication.
|
||||
<blockquote><a name="i78">
|
||||
<pre>
|
||||
SANE_Status sane_init (SANE_Int * version_code,
|
||||
SANE_Authorization_Callback authorize);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>The authorization function may be called by a backend in response to
|
||||
any of the following calls:
|
||||
<blockquote>
|
||||
<tt>sane_open</tt>, <tt>sane_control_option</tt>, <tt>sane_start</tt>
|
||||
</blockquote>
|
||||
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.
|
||||
|
||||
<p>The authentication function type has the following declaration:
|
||||
<blockquote><a name="i79">
|
||||
<a name="i80"><a name="i81"><a name="i82">
|
||||
<pre>
|
||||
#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]);
|
||||
</pre>
|
||||
</blockquote>
|
||||
Three arguments are passed to the authorization function:
|
||||
<tt>resource</tt> 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 <tt>username</tt>
|
||||
and <tt>password</tt> arguments are (pointers to) an array of
|
||||
<tt>SANE_MAX_USERNAME_LEN</tt> and <tt>SANE_MAX_PASSWORD_LEN</tt>
|
||||
characters, respectively. The authorization call should place the
|
||||
entered username and password in these arrays. The returned strings
|
||||
<em>must</em> be ASCII-NUL terminated.
|
||||
|
||||
<p><h3><a name="s4.3.2">4.3.2 <tt>sane_exit</tt></a></h3>
|
||||
|
||||
<p>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 <tt>sane_close()</tt>, but backends are required to release all
|
||||
resources upon a call to this function). After this function returns,
|
||||
no function other than <tt>sane_init()</tt> may be called (regardless
|
||||
of the status value returned by <tt>sane_exit()</tt>. Neglecting to
|
||||
call this function may result in some resources not being released
|
||||
properly.
|
||||
<blockquote><a name="i83">
|
||||
<pre>
|
||||
void sane_exit (void);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.3">4.3.3 <tt>sane_get_devices</tt></a></h3>
|
||||
|
||||
<p>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 <tt>NULL</tt> terminated array of pointers to <tt>SANE_Device</tt>
|
||||
structures in <tt>*device_list</tt>. The returned list is guaranteed
|
||||
to remain unchanged and valid until (a) another call to this function
|
||||
is performed or (b) a call to <tt>sane_exit()</tt> is performed. This
|
||||
function can be called repeatedly to detect when new devices become
|
||||
available. If argument <tt>local_only</tt> 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.
|
||||
<blockquote><a name="i84">
|
||||
<pre>
|
||||
SANE_Status sane_get_devices (const SANE_Device *** device_list,
|
||||
SANE_Bool local_only);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>This function may fail with <tt>SANE_STATUS_NO_MEM</tt> if an
|
||||
insufficient amount of memory is available.
|
||||
|
||||
<p><blockquote>
|
||||
<center>
|
||||
<b>Backend Implementation Note</b>
|
||||
</center>
|
||||
SANE does not require that this function is called before a
|
||||
<tt>sane_open()</tt> 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.
|
||||
<font color="darkgreen">
|
||||
The same information about
|
||||
a device has to be returned when <tt>sane_open</tt> is called.
|
||||
</font>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.4">4.3.4 <tt>sane_open</tt></a></h3>
|
||||
|
||||
<p>This function is used to establish a connection to a particular
|
||||
device. The name of the device to be opened is passed in argument
|
||||
<tt>name</tt>. If the call completes successfully, a handle for the
|
||||
device is returned in <tt>*h</tt>.
|
||||
<font color="darkgreen">
|
||||
The description of the device
|
||||
is returned in <tt>**device_description</tt>. This is the
|
||||
same description that is returned in the list by <tt>sane_get_devices</tt>.
|
||||
The returned data <tt>*h</tt> and <tt>*device_description</tt> is guaranteed
|
||||
to remain unchanged and valid until a call to <tt>sane_close()</tt>
|
||||
is performed.
|
||||
</font>
|
||||
As a special case, specifying a zero-length string as the device requests
|
||||
opening the first available device (if there is such a device).
|
||||
<blockquote><a name="i85">
|
||||
<pre>
|
||||
SANE_Status sane_open (SANE_String_Const name, SANE_Handle * h,
|
||||
const SANE_Device ** device_description);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>This function may fail with one of the following status codes.
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_DEVICE_BUSY</tt>:<dd> The device is currently
|
||||
busy (in use by somebody else).
|
||||
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> The device name is not valid.
|
||||
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occured while
|
||||
communicating with the device.
|
||||
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
||||
is available.
|
||||
<dt><tt>SANE_STATUS_ACCESS_DENIED</tt>:<dd> Access to the device has
|
||||
been denied due to insufficient or invalid authentication.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.5">4.3.5 <tt>sane_close</tt></a></h3>
|
||||
|
||||
<p>This function terminates the association between the device handle
|
||||
passed in argument <tt>h</tt> and the device it represents. If the
|
||||
device is presently active, a call to <tt>sane_cancel()</tt> is
|
||||
performed first. After this function returns, handle <tt>h</tt> must
|
||||
not be used anymore.
|
||||
|
||||
<p><blockquote><a name="i86">
|
||||
<pre>
|
||||
void sane_close (SANE_Handle h);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.6">4.3.6 <tt>sane_get_option_descriptor</tt></a></h3>
|
||||
|
||||
<p>This function is used to access option descriptors. The function
|
||||
returns the option descriptor for option number <tt>n</tt> of the device
|
||||
represented by handle <tt>h</tt>. 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 <tt>h</tt> (the count
|
||||
includes option 0). If n is not a valid option index, the function
|
||||
returns <tt>NULL</tt>. The returned option descriptor is guaranteed to
|
||||
remain valid (and at the returned address) until the device is closed.
|
||||
|
||||
<p><blockquote><a name="i87">
|
||||
<pre>
|
||||
const SANE_Option_Descriptor *
|
||||
sane_get_option_descriptor (SANE_Handle h, SANE_Int n);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.7">4.3.7 <tt>sane_control_option</tt></a></h3>
|
||||
|
||||
<p>This function is used to set or inquire the current value of option
|
||||
number <tt>n</tt> of the device represented by handle <tt>h</tt>. The
|
||||
manner in which the option is controlled is specified by parameter
|
||||
<tt>a</tt>. The possible values of this parameter are described in more
|
||||
detail below. The value of the option is passed through argument
|
||||
<tt>v</tt>. It is a pointer to the memory that holds the option value.
|
||||
The memory area pointed to by <tt>v</tt> must be big enough to hold the
|
||||
entire option value (determined by member <tt>size</tt> 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 <tt>v</tt> may be shorter since the backend will stop
|
||||
reading the option value upon encountering the first <tt>NUL</tt>
|
||||
terminator in the string. If argument <tt>i</tt> is not <tt>NULL</tt>,
|
||||
the value of <tt>*i</tt> 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.
|
||||
<blockquote><a name="i88">
|
||||
<pre>
|
||||
SANE_Status sane_control_option (SANE_Handle h, SANE_Int n,
|
||||
SANE_Action a, void *v,
|
||||
SANE_Int * i);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>The way the option is affected by a call to this function is
|
||||
controlled by parameter <tt>a</tt> which is a value of type
|
||||
<tt>SANE_Action<a name="i89"></tt>. The possible values and their meaning is
|
||||
described in Table <a href="doc012.html#t7">7</a>.
|
||||
|
||||
<p><p><a name="t7"></a>
|
||||
<center>
|
||||
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Code</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
|
||||
<p><tt>SANE_ACTION_GET_VALUE<a name="i90"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 0 </td>
|
||||
<td colspan=1 align=left> Get current option value. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_ACTION_SET_VALUE<a name="i91"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 1 </td>
|
||||
<td colspan=1 align=left> Set option value. The
|
||||
option value passed through argument <tt>v</tt> may be modified by the
|
||||
backend if the value cannot be set exactly. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_ACTION_SET_AUTO<a name="i92"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 2 </td>
|
||||
<td colspan=1 align=left> 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 <tt>v</tt> is completely ignored in this case and
|
||||
may be <tt>NULL</tt>. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
</td></tr>
|
||||
</table>
|
||||
<p><center>Table 7: Action Values (<tt>SANE_Action</tt>)</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>After setting a value via an action value of
|
||||
<tt>SANE_ACTION_SET_VALUE</tt>, additional information on how well the
|
||||
request has been met is returned in <tt>*i</tt> (if <tt>i</tt> is
|
||||
non-<tt>NULL</tt>). The returned value is a bitset that may contain any
|
||||
combination of the values described in Table <a href="doc012.html#t8">8</a>.
|
||||
<p><a name="t8"></a>
|
||||
<center>
|
||||
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Code</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
|
||||
<p><tt>SANE_INFO_INEXACT<a name="i93"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 1 </td>
|
||||
<td colspan=1 align=left> 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 <tt>*i</tt> 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. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_INFO_RELOAD_OPTIONS<a name="i94"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 2 </td>
|
||||
<td colspan=1 align=left> The setting of an
|
||||
option may affect the value or availability of one or more <em>
|
||||
other</em> options. When this happens, the SANE backend sets this
|
||||
member in <tt>*i</tt> to indicate that the application should reload
|
||||
all options. This member may be set if and only if at least one
|
||||
option changed. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_INFO_RELOAD_PARAMS<a name="i95"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 4 </td>
|
||||
<td colspan=1 align=left> The setting of an option may
|
||||
affect the parameter values (see <tt>sane_get_parameters()</tt>).
|
||||
If setting an option affects the parameter values, this member will
|
||||
be set in <tt>*i</tt>. 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. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
</td></tr>
|
||||
</table>
|
||||
<p><center>Table 8: Additional Information Returned When Setting an Option</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>This function may fail with one of the following status codes.
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_UNSUPPORTED</tt>:<dd> The operation is not
|
||||
supported for the specified handle and option number.
|
||||
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> The option value is not valid.
|
||||
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occured while
|
||||
communicating with the device.
|
||||
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
||||
is available.
|
||||
<dt><tt>SANE_STATUS_ACCESS_DENIED</tt>:<dd> Access to the option has
|
||||
been denied due to insufficient or invalid authentication.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.8">4.3.8 <tt>sane_get_parameters</tt></a></h3>
|
||||
|
||||
<p>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 (<tt>sane_start()</tt> 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
|
||||
<tt>sane_start()</tt> 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 <tt>h</tt> of the device for which the
|
||||
parameters should be obtained and a pointer <tt>p</tt> to a parameter
|
||||
structure. The parameter structure is described in more detail below.
|
||||
|
||||
<p><blockquote><a name="i96">
|
||||
<pre>
|
||||
SANE_Status sane_get_parameters (SANE_Handle h,
|
||||
SANE_Parameters * p);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>The scan parameters are returned in a structure of type
|
||||
<tt>SANE_Parameters<a name="i97"></tt>. The C declaration of this structure
|
||||
is given below.
|
||||
<font color="darkgreen">
|
||||
<blockquote>
|
||||
<pre>
|
||||
typedef struct
|
||||
{
|
||||
SANE_Frame format;
|
||||
SANE_Int flags;
|
||||
SANE_Int lines;
|
||||
SANE_Int depth;
|
||||
SANE_Int pixels_per_line;
|
||||
SANE_Int bytes_per_line;
|
||||
SANE_Int channels_per_image;
|
||||
SANE_String format_desc;
|
||||
SANE_String proposed_filename;
|
||||
SANE_Int dpi_x;
|
||||
SANE_Int dpi_y;
|
||||
char reserved[32]; /* 32 bytes for future use */
|
||||
}
|
||||
SANE_Parameters;
|
||||
</pre>
|
||||
</blockquote>
|
||||
</font>
|
||||
|
||||
<p><font color="darkgreen">
|
||||
Member <tt>format</tt> specifies the format of the next frame to be
|
||||
returned. The possible values for type <tt>SANE_Frame<a name="i98"></tt> are
|
||||
described in Table <a href="doc012.html#t9">9</a>. The meaning of these
|
||||
values is described in more detail in Section <a href="doc008.html#s3.2">3.2</a>.
|
||||
<p><a name="t9"></a>
|
||||
<center>
|
||||
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Code</b></td>
|
||||
<td colspan=1 align=center nowrap><b>SANE standard</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
|
||||
<p><tt>SANE_FRAME_GRAY<a name="i99"></tt> </td>
|
||||
<td colspan=1 align=center nowrap> 0 </td>
|
||||
<td colspan=1 align=center nowrap> version 1 </td>
|
||||
<td colspan=1 align=left nowrap> Band covering human visual range. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_FRAME_RGB<a name="i100"></tt> </td>
|
||||
<td colspan=1 align=center nowrap> 1 </td>
|
||||
<td colspan=1 align=center nowrap> version 1 </td>
|
||||
<td colspan=1 align=left nowrap> Pixel-interleaved red/green/blue bands. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_FRAME_RED<a name="i101"></tt> </td>
|
||||
<td colspan=1 align=center nowrap> 2 </td>
|
||||
<td colspan=1 align=center nowrap> version 1 </td>
|
||||
<td colspan=1 align=left nowrap> Red band of a red/green/blue image. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_FRAME_GREEN<a name="i102"></tt> </td>
|
||||
<td colspan=1 align=center nowrap> 3 </td>
|
||||
<td colspan=1 align=center nowrap> version 1 </td>
|
||||
<td colspan=1 align=left nowrap> Green band of a red/green/blue image. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_FRAME_BLUE<a name="i103"></tt> </td>
|
||||
<td colspan=1 align=center nowrap> 4 </td>
|
||||
<td colspan=1 align=center nowrap> version 1 </td>
|
||||
<td colspan=1 align=left nowrap> Blue band of a red/green/blue image. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_FRAME_RAW<a name="i104"></tt> </td>
|
||||
<td colspan=1 align=center nowrap> 5 </td>
|
||||
<td colspan=1 align=center nowrap> version 2 </td>
|
||||
<td colspan=1 align=left nowrap> Arbitrary pixel property transmission. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_FRAME_MIME<a name="i105"></tt> </td>
|
||||
<td colspan=1 align=center nowrap> 6 </td>
|
||||
<td colspan=1 align=center nowrap> version 2 </td>
|
||||
<td colspan=1 align=left nowrap> Data described by a mime descriptor. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
</td></tr>
|
||||
</table>
|
||||
<p><center>Table 9: Frame Format (<tt>SANE_Frame</tt>)</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>The <tt>flags</tt> member is a 32 bit bitfield, for which up to now 4
|
||||
informational bits are defined, all unused bits have to be set to 0:
|
||||
|
||||
<p><ul>
|
||||
|
||||
<p><li>
|
||||
<tt>SANE_PFLAG_LAST_FRAME</tt> (bit 0, bitvalue 1) is set to 1 if and
|
||||
only if the frame that is currently being acquired (or the frame that
|
||||
will be acquired next if there is no current frame) is the last frame
|
||||
of a multi frame image (e.g., the current frame is the blue component
|
||||
of a red, green, blue image). Note, that it is possible to transmit
|
||||
multiple images in succession.
|
||||
|
||||
<p><li>
|
||||
<tt>SANE_PFLAG_MORE_IMAGES</tt> (bit 1, bitvalue 2) is set to 1 to indicate
|
||||
further pending images. It is permissible to set that value to 1 "in good
|
||||
faith", as it has to be determined at a very early time, where it might
|
||||
not be detectable, if there actually are more images to transfer. E.g.
|
||||
you will usually not know if the document feeder contains further pages
|
||||
when starting to scan the current one. Thus you are allowed to set that
|
||||
bit but later fail at <tt>sane_start()</tt>.
|
||||
|
||||
<p><li>
|
||||
<tt>SANE_PFLAG_NEW_PAGE</tt> (bit 2, bitvalue 4) is set to 1 to indicate
|
||||
that the current frame comes from a new physical page. This bit is of
|
||||
informational character only to help frontends to group multi-image
|
||||
scans.
|
||||
|
||||
<p><li>
|
||||
<tt>SANE_PFLAG_BACKSIDE</tt> (bit 3, bitvalue 8) tells if the current image
|
||||
was acquired from the front (0) or backside (1) of the currently processed
|
||||
sheet. It is of informational character and allows to group and order
|
||||
multi-image transfers regardless of scanner acquisition order (front
|
||||
first/back first).
|
||||
|
||||
<p></ul>
|
||||
|
||||
<p>Note, that <tt>flags</tt> is compatible to member <tt>last_frame</tt> of
|
||||
<tt>SANE_Parameters</tt> of SANE standard version 1 (same size
|
||||
and only bit 0 (bitvalue 1) was used with same function).
|
||||
|
||||
<p>Member <tt>lines</tt> 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 <tt>sane_read()</tt> until it
|
||||
returns a status of <tt>SANE_STATUS_EOF</tt>.
|
||||
Note, that even when transferring formats that have this information
|
||||
inband, it is recommended to set that member, if available. If
|
||||
unavailable or not applicable, set to -1 as mentioned above.
|
||||
|
||||
<p>Member <tt>bytes_per_line</tt> specifies the number of bytes that
|
||||
comprise one scan line.
|
||||
If <tt>bytes_per_line</tt> is set to 0, which can currently only be the case for
|
||||
<tt>SANE_FRAME_MIME</tt>, the frontend shall not assume a constant line
|
||||
length. Instead it should simply try to read until <tt>SANE_STATUS_EOF</tt>
|
||||
with an arbitrary block length.
|
||||
|
||||
<p>Member <tt>depth</tt> specifies the number of bits per sample.
|
||||
Note, that only 0 (for not applicable), 1, and n*8 are allowed
|
||||
values. Data with other depths has to be scaled up accordingly.
|
||||
|
||||
<p>Member <tt>pixels_per_line</tt> specifies the number of pixels that
|
||||
comprise one scan line.
|
||||
|
||||
<p>Assume B is the number of channels in the frame, then the bit depth
|
||||
d (as given by member <tt>depth</tt>) and the number of pixels per
|
||||
line n (as given by this member <tt>pixels_per_line</tt>) are
|
||||
related to c, the number of bytes per line (as given by member
|
||||
<tt>bytes_per_line</tt>) as follows:
|
||||
|
||||
<p>
|
||||
<center>
|
||||
|
||||
c >= \left{
|
||||
ll
|
||||
\lceil B*n / 8\rceil if d=1
|
||||
</td><td align=right>(1)</td></tr><tr><td align=center>
|
||||
|
||||
B*n *\lceil (d + 7)/8 \rceil if d>1
|
||||
|
||||
\right.
|
||||
</center>
|
||||
<p>
|
||||
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.
|
||||
|
||||
<p>Member <tt>channels_per_image</tt> specifies the number of channels the
|
||||
image consists of. When the image is transmitted in more than one frame
|
||||
<tt>channels_per_image</tt> has to be the same for all frames for this image.
|
||||
|
||||
<p>Member <tt>format_desc</tt> is used for the new frametypes
|
||||
<tt>SANE_FRAME_RAW</tt> and <tt>SANE_FRAME_MIME</tt>. Its meaning differs
|
||||
between the two types:
|
||||
|
||||
<p><ul>
|
||||
<li>
|
||||
<tt>SANE_FRAME_RAW</tt>:
|
||||
The <tt>format_desc</tt> contains a description of the channel data and
|
||||
an optional depth information separated by a colon(:).
|
||||
|
||||
<p>A plane is descibed by one channel, e.g. "<tt>gray</tt>" or "<tt>gray:12</tt>".
|
||||
|
||||
<p>Channel interleaved data is described by a comma separated list of channel descriptions,
|
||||
for example "<tt>red,green,blue</tt>" or "<tt>red:8,green:8,blue:8</tt>",
|
||||
the channel data is sent in the given order.
|
||||
|
||||
<p>The depth information does <b>not</b> define the size of the transmitted
|
||||
channel data, it is only an information for the frontend. The channel data has
|
||||
to be sent in the size defined by member <tt>depth</tt>.
|
||||
|
||||
<p>Well known channels are <tt>red</tt>, <tt>green</tt>, <tt>blue</tt> and <tt>gray</tt>.
|
||||
It also is allowed to use other channel descriptions, e.g. if you
|
||||
use an infrared camera or scanner it could be <tt>infrared</tt> or
|
||||
a wavelength description like <tt>1100nm</tt>, but be aware that a
|
||||
frontend may not be able to display such channels with useful colors.
|
||||
|
||||
<p>Note that an image can be sent in single planes, in one interleaved
|
||||
frame that contains all channels or in several frames that contain
|
||||
one or more (interleaved) channels. When an RGB image is sent it
|
||||
is prefered to send the image data in one interleaved frame
|
||||
that consist of red, green and blue data in this order.
|
||||
The number of channels is defined in member <tt>channels_per_image</tt>.
|
||||
|
||||
<p><li>
|
||||
<tt>SANE_FRAME_MIME</tt>:
|
||||
The <tt>format_desc</tt> contains the MIME type/subtype *(;parameter)
|
||||
fields as described in RFC 1521, 4. The Content-Type header field,
|
||||
without the prefixing "Content-Type:".
|
||||
Note, that it is discouraged to transfer proprietary file formats over
|
||||
SANE. If at all possible, please stick to the IANA assigned MIME types,
|
||||
and make sure the data stream is compliant with the corresponding
|
||||
specification.
|
||||
When data is transmitted with the frame type <tt>SANE_FRAME_MIME</tt>
|
||||
all data has to be transmitted within one frame, multiple frames
|
||||
are not allowed (so the flag <tt>last_frame</tt> has to be set
|
||||
when using this frame type).
|
||||
A fully compliant SANE backend is required to transmit in either
|
||||
SANE native frametypes, or in a MIME type, for which a converting
|
||||
meta backend exists and is freely available for all platforms.
|
||||
|
||||
<p>Other formats may be transmitted, but the only thing the average
|
||||
frontend can do with them, is save them. This is not considered a
|
||||
good option, as it does not facilitate transmitting the data to a
|
||||
client application that may be running the frontend.
|
||||
However, if the data transferred by the backend is not an image in
|
||||
nature, it wouldn't make sense to try converting it anyway, so it is
|
||||
acceptable to use a simple <tt>SANE_FRAME_MIME</tt> transfer for that
|
||||
case. But even then, try to stick to well known stuff with freely
|
||||
existing standards and viewers as well.
|
||||
</ul>
|
||||
|
||||
<p>The member <tt>proposed_filename</tt> can be used to suggest a reasonable
|
||||
default filename or -extension in case the backend can make such a
|
||||
suggestion, like e.g. an image database.
|
||||
If no such suggestion is intended, set the field to "".
|
||||
|
||||
<p>In the case of raw frames, <tt>proposed_filename</tt> is expected to hold
|
||||
the basename for the image, with the extension determined by the save function
|
||||
of the frontend, as the frontend can fully understand the data and is thus
|
||||
able to encode it in any format it wishes.
|
||||
|
||||
<p>For MIME frames <tt>proposed_filename</tt> can contain either:
|
||||
|
||||
<p><ul>
|
||||
<li>
|
||||
A name with a leading dot, which is considered to be a proposed
|
||||
filename extension. This could also be gotten from the mime database,
|
||||
but for systems lacking it, this might be convenient. Or:
|
||||
|
||||
<p><li>
|
||||
A complete filename, including extension.
|
||||
</ul>
|
||||
|
||||
<p>Note, that for frontends that are able to parse a given MIME type
|
||||
internally, it is perfectly permissible to ignore the extension
|
||||
part of the proposed filename and only make use of the basename,
|
||||
when using internal save algorithms for different formats.
|
||||
|
||||
<p>In any case, if the frontend makes use of this field, the frontend
|
||||
must mangle this proposal or the final filename it produces with
|
||||
its help to suit local filesystem restrictions.
|
||||
|
||||
<p>Special care should be taken not to cause security flaws this way.
|
||||
For Unix, that means killing out all path separators (/) [to avoid
|
||||
to save away stuff in obscure places or create critical files like
|
||||
/etc/hosts.allow] and avoiding to overwrite existing files.
|
||||
(Creating of leading dot files - like .rhosts - is not an issue here,
|
||||
because that's only a proposed filename extension as mentioned above.
|
||||
|
||||
<p>The string <tt>proposed_comment</tt> can be used to transmit additional
|
||||
image data, that can be stored in the comment areas several fileformats
|
||||
offer. It can contain any textual information the backend wishes to
|
||||
convey to the user, like date/time of exposure, enganged filters,
|
||||
etc.
|
||||
|
||||
<p>The members <tt>dpi_x, dpi_y</tt> encode the horizontal and vertical
|
||||
resolution. Note, that multiple-image scans may have different
|
||||
resolutions of each image. It is not permissible to change resolution
|
||||
between frames of the same image.
|
||||
|
||||
<p>The member <tt>reserved</tt> is an array of 32 bytes (char) to keep
|
||||
the size of the struct unchanged when future extensions are done.
|
||||
The backend has to set the reserved bytes to 0.
|
||||
</font>
|
||||
|
||||
<p><h3><a name="s4.3.9">4.3.9 <tt>sane_start</tt></a></h3>
|
||||
|
||||
<p>This function initiates aquisition of an image from the device
|
||||
represented by handle <tt>h</tt>.
|
||||
<blockquote><a name="i106">
|
||||
<pre>
|
||||
SANE_Status sane_start (SANE_Handle h);
|
||||
</pre>
|
||||
</blockquote>
|
||||
This function may fail with one of the following status codes.
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_CANCELLED</tt>:<dd> The operation was cancelled through
|
||||
a call to <tt>sane_cancel</tt>.
|
||||
<dt><tt>SANE_STATUS_DEVICE_BUSY</tt>:<dd> The device is busy. The
|
||||
operation should be retried later.
|
||||
<dt><tt>SANE_STATUS_JAMMED</tt>:<dd> The document feeder is jammed.
|
||||
<dt><tt>SANE_STATUS_NO_DOCS</tt>:<dd> The document feeder is out of
|
||||
documents.
|
||||
<dt><tt>SANE_STATUS_COVER_OPEN</tt>:<dd> The scanner cover is open.
|
||||
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occurred while communicating
|
||||
with the device.
|
||||
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
||||
is available.
|
||||
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> The scan cannot be started with the current
|
||||
set of options. The frontend should reload the option descriptors, as if
|
||||
<tt>SANE_INFO_RELOAD_OPTIONS<a name="i107"></tt> had been returned from a call to
|
||||
<tt>sane_control_option()</tt>, since the device's capabilities may have
|
||||
changed.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.10">4.3.10 <tt>sane_read</tt></a></h3>
|
||||
|
||||
<p>This function is used to read image data from the device represented
|
||||
by handle <tt>h</tt>. Argument <tt>buf</tt> is a pointer to a memory area
|
||||
that is at least <tt>maxlen</tt> bytes long. The number of bytes
|
||||
returned is stored in <tt>*len</tt>. A backend must set this to zero
|
||||
when a status other than <tt>SANE_STATUS_GOOD</tt> is returned).
|
||||
When the call succeeds, the number of bytes returned can be anywhere in
|
||||
the range from 0 to <tt>maxlen</tt> bytes.
|
||||
<blockquote><a name="i108">
|
||||
<pre>
|
||||
SANE_Status sane_read (SANE_Handle h, SANE_Byte * buf,
|
||||
SANE_Int maxlen, SANE_Int * len);
|
||||
</pre>
|
||||
</blockquote>
|
||||
For efficiency reasons, medium to large
|
||||
block sizes (in the range of a few kilobytes) should be used.
|
||||
Returning short reads is allowed to allow for small buffers
|
||||
in the backend.
|
||||
If this function is called when no data is available, one of two
|
||||
things may happen, depending on the I/O mode that is in effect for
|
||||
handle <tt>h</tt>.
|
||||
<ol>
|
||||
<li>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).
|
||||
|
||||
<p><li>If the device is in non-blocking I/O mode, the call returns
|
||||
immediately with status <tt>SANE_STATUS_GOOD</tt> and with
|
||||
<tt>*len</tt> set to zero.
|
||||
</ol>
|
||||
The I/O mode of handle <tt>h</tt> can be set via a call to
|
||||
<tt>sane_set_io_mode()</tt>.
|
||||
|
||||
<p>This function may fail with one of the following status codes.
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_CANCELLED</tt>:<dd> The operation was cancelled through
|
||||
a call to <tt>sane_cancel</tt>.
|
||||
<dt><tt>SANE_STATUS_EOF</tt>:<dd> No more data is available for the
|
||||
current frame. If <tt>sane_read</tt> sends back any image data it
|
||||
is not allowed to return with <tt>SANE_STATUS_EOF</tt>.
|
||||
<dt><tt>SANE_STATUS_JAMMED</tt>:<dd> The document feeder is jammed.
|
||||
<dt><tt>SANE_STATUS_NO_DOCS</tt>:<dd> The document feeder is out of
|
||||
documents.
|
||||
<dt><tt>SANE_STATUS_COVER_OPEN</tt>:<dd> The scanner cover is open.
|
||||
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occurred while communicating
|
||||
with the device.
|
||||
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
||||
is available.
|
||||
<dt><tt>SANE_STATUS_ACCESS_DENIED</tt>:<dd> Access to the device has
|
||||
been denied due to insufficient or invalid authentication.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.11">4.3.11 <tt>sane_cancel</tt></a></h3>
|
||||
|
||||
<p>This function is used to immediately or as quickly as possible cancel
|
||||
the currently pending operation of the device represented by handle
|
||||
<tt>h</tt>.
|
||||
<blockquote><a name="i109">
|
||||
<pre>
|
||||
void sane_cancel (SANE_Handle h);
|
||||
</pre>
|
||||
</blockquote>
|
||||
This function can be called at any time (as long as handle <tt>h</tt> 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</em> imply that
|
||||
the currently pending operation has been cancelled. It only
|
||||
guarantees that cancellation has been <em>initiated</em>. Cancellation
|
||||
completes only when the cancelled call returns (typically with a
|
||||
status value of <tt>SANE_STATUS_CANCELLED</tt>). Since the SANE API
|
||||
does not require any other operations to be re-entrant, this implies
|
||||
that a frontend must <em>not</em> call any other operation until the
|
||||
cancelled operation has returned.
|
||||
|
||||
<p><h3><a name="s4.3.12">4.3.12 <tt>sane_set_io_mode</tt></a></h3>
|
||||
|
||||
<p>This function is used to set the I/O mode of handle <tt>h</tt>. The I/O mode
|
||||
can be either blocking or non-blocking. If argument <tt>m</tt> is
|
||||
<tt>SANE_TRUE</tt>, 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
|
||||
<tt>sane_start()</tt> has been performed.
|
||||
<blockquote><a name="i110">
|
||||
<pre>
|
||||
SANE_Status sane_set_io_mode (SANE_Handle h, SANE_Bool m);
|
||||
</pre>
|
||||
</blockquote>
|
||||
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 <tt>SANE_STATUS_UNSUPPORTED</tt> is returned. Blocking
|
||||
I/O must be supported by all backends, so calling this function with
|
||||
argument <tt>m</tt> set to <tt>SANE_FALSE</tt> is guaranteed to complete
|
||||
successfully.
|
||||
|
||||
<p>This function may fail with one of the following status codes:
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> No image acquisition is pending.
|
||||
<dt><tt>SANE_STATUS_UNSUPPORTED</tt>:<dd> The backend does not support
|
||||
the requested I/O mode.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.13">4.3.13 <tt>sane_get_select_fd</tt></a></h3>
|
||||
|
||||
<p>This function is used to obtain a (platform-specific) file-descriptor
|
||||
for handle <tt>h</tt> that is readable if and only if image data is
|
||||
available (i.e., when a call to <tt>sane_read()</tt> will return at
|
||||
least one byte of data). If the call completes successfully, the
|
||||
select file-descriptor is returned in <tt>*fd</tt>.
|
||||
<blockquote><a name="i111">
|
||||
<pre>
|
||||
SANE_Status sane_get_select_fd (SANE_Handle h, SANE_Int *fd);
|
||||
</pre>
|
||||
</blockquote>
|
||||
This function can be called only after a call to <tt>sane_start()</tt>
|
||||
has been performed and the returned file-descriptor is guaranteed to
|
||||
remain valid for the duration of the current image acquisition (i.e.,
|
||||
until <tt>sane_cancel()</tt> or <tt>sane_start()</tt> get called again
|
||||
or until <tt>sane_read()</tt> returns with status
|
||||
<tt>SANE_STATUS_EOF</tt>). Indeed, a backend must guarantee to
|
||||
close the returned select file descriptor at the point when the next
|
||||
<tt>sane_read()</tt> call would return <tt>SANE_STATUS_EOF</tt>.
|
||||
This is necessary to ensure the application can detect when this
|
||||
condition occurs without actually having to call <tt>sane_read()</tt>.
|
||||
|
||||
<p>A backend may elect not to support this operation. In such a case,
|
||||
the function returns with status code
|
||||
<tt>SANE_STATUS_UNSUPPORTED</tt>.
|
||||
|
||||
<p>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 <tt>select()</tt>
|
||||
or <tt>poll()</tt> 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 <tt>sane_read()</tt> 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.
|
||||
|
||||
<p>This function may fail with one of the following status codes:
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> No image acquisition is pending.
|
||||
<dt><tt>SANE_STATUS_UNSUPPORTED</tt>:<dd> The backend does not support
|
||||
this operation.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.14">4.3.14 <tt>sane_strstatus</tt></a></h3>
|
||||
|
||||
<p>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 <tt>NULL</tt>.
|
||||
The returned pointer is valid at least until the next call to this
|
||||
function is performed.
|
||||
<blockquote><a name="i112">
|
||||
<pre>
|
||||
const SANE_String_Const sane_strstatus (SANE_Status status);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc013.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc011.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,197 @@
|
|||
<html><body>
|
||||
<a href="doc014.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc012.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Code Flow</title>
|
||||
<h2><a name="s4.4">4.4 Code Flow</a></h2><a name="i113">
|
||||
|
||||
<p>The code flow for the SANE API is illustrated in
|
||||
Figure <a href="doc013.html#f4">4</a>. Functions <tt>sane_init()</tt> and
|
||||
<tt>sane_exit()</tt> initialize and exit the backend, respectively.
|
||||
All other calls must be performed after initialization and before
|
||||
exiting the backend.
|
||||
|
||||
<p><p><a name="f4"></a>
|
||||
<center>
|
||||
|
||||
<img width=566 height=510 src="img003.gif">
|
||||
<p><center>Figure 4: Code flow</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>Function <tt>sane_get_devices()</tt> can be called any time after
|
||||
<tt>sane_init()</tt> 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.
|
||||
|
||||
<p>Once a device has been chosen, it is opened using a call to
|
||||
<tt>sane_open()</tt>. 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.
|
||||
|
||||
<p>An opened device can be setup through the corresponding device handle
|
||||
using functions <tt>sane_get_option_descriptor()</tt> and
|
||||
<tt>sane_control_option()</tt>. 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
|
||||
may be necessary to re-read some or all option descriptors. While
|
||||
setting up the device, it is also admissible to call
|
||||
<tt>sane_get_parameters()</tt> to get an estimate of what the image
|
||||
parameters will look like once image acquisition begins.
|
||||
|
||||
<p>The device handle can be put in blocking or non-blocking mode by a
|
||||
call to <tt>sane_set_io_mode()</tt>. 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.
|
||||
|
||||
<p>After the device is setup properly, image acquisition can be started
|
||||
by a call to <tt>sane_start()</tt>. The backend calculates the exact
|
||||
image parameters at this point. So future calls to
|
||||
<tt>sane_get_parameters()</tt> will return the exact values, rather
|
||||
than estimates. Whether the physical image acquisition starts at this
|
||||
point or during the first call to <tt>sane_read()</tt> 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
|
||||
<tt>sane_set_io_mode()</tt> and/or <tt>sane_get_select_fd()</tt> at
|
||||
this point. Either of these functions may fail if the backend does
|
||||
not support the requested operation.
|
||||
|
||||
<p><font color="darkgreen">
|
||||
Image data is collected by repeatedly calling <tt>sane_read()</tt>
|
||||
until this function will return an end-of-file status
|
||||
(<tt>SANE_STATUS_EOF</tt>). This indicates the end of the current
|
||||
frame. If the frontend expects additional frames (e.g., the
|
||||
individual channels of a red/green/blue image or multiple images),
|
||||
it can call <tt>sane_start()</tt> again.
|
||||
If the <tt>SANE_PFLAG_LAST_FRAME</tt> bit is set in <tt>flags</tt>, the
|
||||
current image is complete. In this case, it should be tested, if
|
||||
<tt>flags</tt> has the <tt>SANE_PFLAG_MORE_IMAGES</tt> bit set.
|
||||
If yes, further calls to <tt>sane_start()</tt> can be made to acquire
|
||||
more images. Please note, that as this bit has to be set at the beginning
|
||||
of a the transmission of the last frame before the new image, it is possible,
|
||||
that no reliable decision can be made at this time. It is thus permissible
|
||||
for a backend to set this bit, and then later at the actual call to
|
||||
<tt>sane_start()</tt> return an error like <tt>SANE_STATUS_NO_DOCS</tt>.
|
||||
Such a sequence is permitted to transmit multiple images from a single
|
||||
page as well as multiple pages. This behaviour should be controlled by
|
||||
backend options as required, to allow single-page scanning as well as
|
||||
ADF-batch-scanning. The frontend should always continue reading all images
|
||||
until a frame with <tt>SANE_PFLAG_LAST_FRAME</tt> on
|
||||
and <tt>SANE_PFLAG_MORE_IMAGES</tt> off is encountered, or an error other
|
||||
than <tt>SANE_STATUS_EOF</tt> occurs in a SANE function.
|
||||
Note that <tt>SANE_STATUS_NO_DOCS</tt> also is an allowed way for the backend
|
||||
to indicate the end of a multiple image scan.
|
||||
|
||||
<p>A frontend may choose to skip frames (e.g. because it cannot parse them),
|
||||
which is accomplished by simply calling <tt>sane_start</tt> again, which will get
|
||||
you to the next frame, without having to read and discard the current one.
|
||||
|
||||
<p>In order to prematurely stop scanning and to reset the backend state,
|
||||
<tt>sane_cancel()</tt> can be called at any time. This call is required
|
||||
as well after normal termination of a multiple image scan as described above.
|
||||
|
||||
<p>When done using the device, the handle should be closed by a call to
|
||||
<tt>sane_close()</tt>. Finally, before exiting the application,
|
||||
function <tt>sane_exit()</tt> 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.
|
||||
|
||||
<p>The following C sample code implements a reference loop for acquiring
|
||||
multiple images:
|
||||
|
||||
<p><pre>
|
||||
SANE_Parameters parms;
|
||||
SANE_Status status;
|
||||
|
||||
do
|
||||
{
|
||||
do
|
||||
{
|
||||
/* Now start acquiring the next frame. */
|
||||
status=sane_start(handle);
|
||||
|
||||
/* if that failed, we have a problem, and no more frames can be
|
||||
* read at this time. Due to SANE_PFLAG_MORE_IMAGES still
|
||||
* being clear, this will break out of _BOTH_ loops.
|
||||
*/
|
||||
if (status != SANE_STATUS_GOOD) break;
|
||||
|
||||
/* Now let us see what the next frame brings. */
|
||||
status=sane_get_parameters(handle,&parms);
|
||||
|
||||
/* This actually should not fail, but maybe the doc feeder
|
||||
* jammed or something, so we break as well, if something
|
||||
* is wrong.
|
||||
*/
|
||||
if (status != SANE_STATUS_GOOD) break;
|
||||
|
||||
/* Now we check the announced parameters, if we can make use
|
||||
* of the frame data. If not, we skip over to the next frame.
|
||||
*/
|
||||
if ( do_i_like_that(&parms) == NO ) continue;
|
||||
|
||||
/* Set up for reading the data here. Mangle filenames,
|
||||
* allocate memory, rewind multiframe files, ask user
|
||||
* for confirmation, ...
|
||||
*/
|
||||
setup_for_transfer(...);
|
||||
|
||||
/* Now we read in the frame data and process it. This should
|
||||
* return SANE_STATUS_GOOD, until the frame is complete,
|
||||
* what causes SANE_STATUS_EOF to be returned.
|
||||
*/
|
||||
while( SANE_STATUS_GOOD == ( status=sane_read(...) ) )
|
||||
read_in_and_process_data_as_required();
|
||||
|
||||
/* If transfer was broken due to anything but EOF, break out. */
|
||||
if (status != SANE_STATUS_EOF) {
|
||||
break;
|
||||
}
|
||||
|
||||
/* Now loop until we have all frames of an image. */
|
||||
} while(!(parms.flag & SANE_PFLAG_LAST_FRAME));
|
||||
|
||||
/* O.K. - we now have a complete image. Fit it together, save it,
|
||||
* flush buffers, transmit it, increment filenames, etc.
|
||||
*/
|
||||
|
||||
/* Now check for more pending images. If we have more, redo from start.
|
||||
* Some backends might cheat here and send us for an extra round which
|
||||
* will fail at sane_start, as they were not able to determine if they
|
||||
* would have more data at the start of the last frame we read.
|
||||
*/
|
||||
} while(parms.flags & SANE_PFLAG_MORE_IMAGES);
|
||||
|
||||
/* No more data. Fine. Reset the backend and go back to option-control
|
||||
* loop.
|
||||
*/
|
||||
|
||||
sane_cancel(handle);
|
||||
</pre>
|
||||
|
||||
<p></font>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc014.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc012.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,455 @@
|
|||
<html><body>
|
||||
<a href="doc015.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc013.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Well-Known Options</title>
|
||||
<h2><a name="s4.5">4.5 Well-Known Options</a></h2><a name="i114">
|
||||
|
||||
<p>While most backend options are completely self-describing, there are
|
||||
cases where a user interface might want to special-case the handling
|
||||
of certain options. For example, the scan area is typically defined
|
||||
by four options that specify the top-left and bottom-right corners of
|
||||
the area. With a graphical user interface, it would be tedious to
|
||||
force the user to type in these four numbers. Instead, most such
|
||||
interfaces will want to present to the user a preview (low-resolution
|
||||
scan of the full scanner surface or a high(er) resolution scan of a subpart
|
||||
of the scanner surface) and let the user pick the scan area by
|
||||
dragging a rectangle into the desired position. For this reason, the
|
||||
SANE API specifies a small number of option names that have
|
||||
well-defined meanings.
|
||||
|
||||
<p><h3><a name="s4.5.1">4.5.1 Option Number Count</a></h3><a name="i115">
|
||||
|
||||
<p>Option number 0 has an empty string as its name. The value of this
|
||||
option is of type <tt>SANE_TYPE_INT</tt> 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
|
||||
<tt>sane_get_option_descriptor()</tt> returns <tt>NULL</tt>, or a
|
||||
frontend can directly read out the value of option number 0.
|
||||
|
||||
<p><h3><a name="s4.5.2">4.5.2 Scan Resolution Options</a></h3><a name="i116"><a name="i117">
|
||||
|
||||
<p><font color="darkgreen">
|
||||
Option <tt>resolution</tt> is used to select the resolution at which an
|
||||
image should be acquired. When the backend wants to allow different
|
||||
values for x- and y-resolution it has to define the options
|
||||
<tt>x_resolution</tt> and <tt>y_resolution</tt>. Note that only
|
||||
the option <tt>resolution</tt> <b>or</b> the options
|
||||
<tt>x_resolution</tt> <b>and</b> <tt>y_resolution</tt> may be active.
|
||||
|
||||
<p>The type of this option is either <tt>SANE_TYPE_INT</tt> or
|
||||
<tt>SANE_TYPE_FIXED</tt>. The unit is <tt>SANE_UNIT_DPI</tt> (dots/inch).
|
||||
|
||||
<p>This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.
|
||||
</font>
|
||||
|
||||
<p><h3><a name="s4.5.3">4.5.3 Preview Mode Option</a></h3><a name="i118">
|
||||
|
||||
<p>The boolean option <tt>preview</tt> 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 <tt>SANE_TRUE</tt>,
|
||||
preview mode is in effect, when set to <tt>SANE_FALSE</tt> image
|
||||
acquisition should proceed in normal quality mode. The setting of
|
||||
this option <em>must not</em> 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 <tt>resolution</tt>). A backend is free to override the
|
||||
<tt>resolution</tt> value with its own choice for preview mode, but it
|
||||
is advised to leave this choice to the frontend wherever possible.
|
||||
<font color="darkgreen">
|
||||
When the <tt>preview</tt> option is set the backend should transfer
|
||||
the image in frame type <tt>SANE_FRAME_RAW</tt> if possible.
|
||||
</font>
|
||||
|
||||
<p>This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.
|
||||
|
||||
<p><h3><a name="s4.5.4">4.5.4 Scan Area Options</a></h3><a name="i119">
|
||||
|
||||
<p>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 <a href="doc014.html#f5">5</a>. 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</em> and the bottom-right corner is the
|
||||
corner for which the abscissa and ordinate values are simulatenously
|
||||
the <em>largest</em>. If this coordinate system is not natural for a
|
||||
given device, it is the job of the backend to perform the necessary
|
||||
conversions.
|
||||
<p><a name="f5"></a>
|
||||
<center>
|
||||
|
||||
<img width=330 height=306 src="img004.gif">
|
||||
<p><center>Figure 5: Scan area options</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>The names of the four options that define the scan area are given in
|
||||
the table below:
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>Name</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>Description</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>tl-x<a name="i120"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> Top-left x coordinate value </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>tl-y<a name="i121"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> Top-left y coordinate value </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>br-x<a name="i122"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> Bottom-right x coordinate value </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>br-y<a name="i123"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> Bottom-right y coordinate value </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
There are several rules that should be followed by front and backends
|
||||
regarding these options:
|
||||
<ul>
|
||||
|
||||
<p><li>Backends must attach a unit of either pixels
|
||||
(<tt>SANE_UNIT_PIXEL</tt>) or millimeters (<tt>SANE_UNIT_MM</tt>) to
|
||||
these options. The unit of all four options must be identical.
|
||||
|
||||
<p><li>Whenever meaningful, a backend should attach a range or a
|
||||
word-list constraint to these options.
|
||||
|
||||
<p><li>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.
|
||||
|
||||
<p><li>A frontend must work properly with any or all of these options
|
||||
missing.
|
||||
|
||||
<font color="darkgreen">
|
||||
<li>A frontend may temporarily set the values in a way that
|
||||
<tt>tl-x</tt> is larger than <tt>br-x</tt> and <tt>tl-y</tt> is larger than
|
||||
<tt>br-y</tt>.
|
||||
</font>
|
||||
|
||||
<p></ul>
|
||||
|
||||
<p><h3><a name="s4.5.5">4.5.5 Depth option</a></h3><a name="i124">
|
||||
<font color="darkgreen">
|
||||
Option <tt>depth</tt> is used to select the image depth in bits/sample
|
||||
in multi bit mode - (this means for 24 bit RGB mode this value must be 8).
|
||||
The type of this option is <tt>SANE_TYPE_INT</tt>.
|
||||
The unit is <tt>SANE_UNIT_BIT</tt>. For 1 bit modes
|
||||
(Lineart or Halftone) this option has to be inactive.
|
||||
For selection of 1 bit modes (Lineart or Halftone) the
|
||||
backend should use the well-known option <tt>mode</tt>.<br>
|
||||
|
||||
This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.<br>
|
||||
</font>
|
||||
|
||||
<h3><a name="s4.5.6">4.5.6 Gamma table options</a></h3><a name="i125">
|
||||
<font color="darkgreen">
|
||||
The <tt>gamma-table</tt> option defines a <tt>SANE_CONSTRAINT_RANGE</tt>
|
||||
of the type <tt>SANE_TYPE_INT</tt> which represents the gamma correction
|
||||
table for gray. In color mode the <tt>gamma-table</tt> may be used to set
|
||||
a common gamma correction for red, green and blue. The options
|
||||
<tt>red-gamma-table</tt>, <tt>green-gamma-table</tt> and <tt>blue-gamma-table</tt>
|
||||
are used in color mode to set a gamma correction for each color
|
||||
separately. In color mode the backend is free to use only the
|
||||
<tt>gamma-table</tt> option, only the <tt>red-</tt>, <tt>green-</tt> and
|
||||
<tt>blue-gamma-table</tt> or all four options. When all four options
|
||||
are used then the color tables should do a gamma correction with
|
||||
the same input and output bit depth and the gray gamma table should
|
||||
reduce (if necessary) the bit depth from the scanner internal
|
||||
bit depth to the output bit depth. This should e.g. look like this:
|
||||
<pre>
|
||||
red_value = gamma-table(red-gamma-table(value))
|
||||
green_value = gamma-table(green-gamma-table(value))
|
||||
blue_value = gamma-table(blue-gamma-table(value))
|
||||
</pre>
|
||||
|
||||
<p>The backend should not use the gamma tables to emulate other functions or options
|
||||
like highlight, shadow, contrast, brightness, threshold, analog_gamma.
|
||||
These functions are common for all backends and should be added to the frontend
|
||||
or a meta-backend.<br>
|
||||
|
||||
This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.<br>
|
||||
</font>
|
||||
|
||||
<h3><a name="s4.5.7">4.5.7 Scan Mode options</a></h3><a name="i126">
|
||||
<font color="darkgreen">
|
||||
The option <tt>mode</tt> defines a <tt>SANE_CONSTRAINT_STRING_LIST</tt>
|
||||
of type <tt>SANE_TYPE_STRING</tt>.
|
||||
It is used to select the scanmode (e.g. Color or Gray).
|
||||
Well known modes are: <tt>Color</tt>, <tt>Gray</tt>, <tt>Halftone</tt>
|
||||
and <tt>Lineart</tt>. <tt>Color</tt> and <tt>Gray</tt> are multi bit
|
||||
modes (8 or 16 bits/sample), <tt>Halftone</tt> and <tt>Lineart</tt>
|
||||
are single bit modes.<br>
|
||||
This way a frontend can select e.g the mode <tt>Gray</tt>
|
||||
for scanning a fax.<br>
|
||||
|
||||
This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.<br>
|
||||
</font>
|
||||
|
||||
<h3><a name="s4.5.8">4.5.8 Scan Source options</a></h3><a name="i127">
|
||||
<font color="darkgreen">
|
||||
The option <tt>source</tt> is used to select the scan source
|
||||
(e.g. Automatic Document Feeder).
|
||||
It defines a <tt>SANE_CONSTRAINT_STRING_LIST</tt>
|
||||
of type <tt>SANE_TYPE_STRING</tt>.
|
||||
Well known sources are: <tt>Flatbed</tt>, <tt>Transparancy Adapter</tt> and
|
||||
<tt>Automatic Document Feeder</tt>.<br>
|
||||
|
||||
This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.<br>
|
||||
</font>
|
||||
|
||||
<p><h3><a name="s4.5.9">4.5.9 Threshold</a></h3><a name="i128">
|
||||
<font color="darkgreen">
|
||||
The option <tt>threshold</tt> is used to define the threshold
|
||||
for Lineart and maybe Halftone mode. In multi bit modes
|
||||
this option should be set inactive.
|
||||
The type of this option is <tt>SANE_TYPE_FIXED</tt>.
|
||||
The unit is <tt>SANE_UNIT_PERCENT</tt>. The value range
|
||||
should be 0.0...100.0 if possible.
|
||||
It defines the minimum intensity to get a white point / full intensity
|
||||
(image data bit = 0). The backend has to
|
||||
scale the values in the following way:<br>
|
||||
A value of 0.0 means all pixels get white /full intensity (all image data
|
||||
bits are 0). A value of 50.0 means intensities brighter than medium gray
|
||||
get white / full intensity (bit 0). A value of 100.0 means all pixels get
|
||||
black (all image data bits are 1). If the scanner is not able to
|
||||
cover the full range the backend has to define a reduced
|
||||
value range (e.g. 30...70 percent).
|
||||
|
||||
<p>This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.<br>
|
||||
</font>
|
||||
|
||||
<p><h3><a name="s4.5.10">4.5.10 Analog gamma</a></h3><a name="i129">
|
||||
<font color="darkgreen">
|
||||
The option <tt>analog-gamma</tt> is used to define the gamma value
|
||||
for an analog gamma function of the scanner in multi bit modes.
|
||||
In 1 bit modes this option should be set inactive.
|
||||
The type of this option is <tt>SANE_TYPE_FIXED</tt>.
|
||||
The unit is <tt>SANE_UNIT_NONE</tt>. The value range
|
||||
can be defined by the backend as supported. The values
|
||||
have to be positive. A gamma value of 1.0 means that
|
||||
the gamma correction has no effect. A value larger than
|
||||
1.0 increases the brightness of the image.
|
||||
In color mode there also can be options <tt>analog-gamma-red</tt>,
|
||||
<tt>analog-gamma-green</tt> and <tt>analog-gamma-blue</tt>.
|
||||
It is not allowed to emulate an analog gamma function by
|
||||
a digital gamma table. The backend has to disable (or not
|
||||
define) this option when the scanner does not support an
|
||||
analog (hardware) gamma function.
|
||||
|
||||
<p>When analog gamma, highlight and shadow functions are available
|
||||
at the same time then the backend author has to care about the order
|
||||
in which the functions are implemented in the scanner hardware.
|
||||
The SANE standard expects that changing the analog gamma value
|
||||
has no effect on the shadow and highlight function. When the
|
||||
analog gamma function is executed in the scanner hardware
|
||||
before the shadow and highlight functions then the backend
|
||||
should do a compensation. For this the shadow and highlight
|
||||
values have to be gamma corrected with the relevant analog gamma value.
|
||||
|
||||
<p>This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.<br>
|
||||
</font>
|
||||
|
||||
<p><h3><a name="s4.5.11">4.5.11 Shadow</a></h3><a name="i130">
|
||||
<font color="darkgreen">
|
||||
The option <tt>shadow</tt> is used to define the shadow level / black point level.
|
||||
The type of this option is <tt>SANE_TYPE_FIXED</tt>.
|
||||
The unit is <tt>SANE_UNIT_PERCENT</tt>. The value range
|
||||
should be 0.0...100.0 if possible.
|
||||
It is used to define the maximum intensity level that creates an image data value
|
||||
of 0 (black). The backend has to scale the values in the following way:<br>
|
||||
A value of 0.0 means that the sensitivity range is not reduced, only the
|
||||
minimum intensity produces an image data value of 0 (black).
|
||||
A value of 50.0 means that that a medium intensity and everything that is darker
|
||||
produces an image data value of 0 (black).
|
||||
A value of 100.0 means the sensitivity range is reduced to 0, all image
|
||||
data values are 0 (black). If the scanner is not able to
|
||||
cover the full range the backend has to define a reduced
|
||||
value range (e.g. 30...70 percent).
|
||||
In color mode there can be options <tt>shadow-red</tt>, <tt>shadow-green</tt>
|
||||
and <tt>shadow-blue</tt>, in this case the <tt>shadow</tt> function has to be disabled.
|
||||
It is not allowed to emulate a shadow function by
|
||||
a digital gamma table. The backend has to disable (or not
|
||||
define) this option when the scanner does not support an
|
||||
analog (hardware) shadow function.
|
||||
|
||||
<p>This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.<br>
|
||||
</font>
|
||||
|
||||
<p><h3><a name="s4.5.12">4.5.12 Highlight</a></h3><a name="i131">
|
||||
<font color="darkgreen">
|
||||
The option <tt>highlight</tt> is used to define the highlight level / white point level.
|
||||
The type of this option is <tt>SANE_TYPE_FIXED</tt>.
|
||||
The unit is <tt>SANE_UNIT_PERCENT</tt>. The value range
|
||||
should be 0.0...100.0 if possible.
|
||||
It is used to define the minimum intensity level that creates the maximum possible
|
||||
image data value (white/full intensity). The backend has to scale the values in the
|
||||
following way:<br>
|
||||
A value of 0.0 means the sensitivity range is reduced to 0, all image
|
||||
data have maximum value (white / full intensity).
|
||||
A value of 50.0 means that a medium intensity and everything that is brighter
|
||||
produces the maximum possible image data value (white / full intensity).
|
||||
A value of 100.0 means that the sensitivity range is not reduced, only the
|
||||
maximum intensity produces an image data with maximum possible value (white / full intensity).
|
||||
If the scanner is not able to cover the full range the backend has to define a reduced
|
||||
value range (e.g. 30...70 percent).
|
||||
In color mode there can be options <tt>highlight-red</tt>, <tt>highlight-green</tt>
|
||||
and <tt>highlight-blue</tt>, in this case <tt>highlight</tt> has to be disabled.
|
||||
It is not allowed to emulate a highlight function by
|
||||
a digital gamma table. The backend has to disable (or not
|
||||
define) this option when the scanner does not support an
|
||||
analog (hardware) highlight function.
|
||||
|
||||
<p>This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.<br>
|
||||
</font>
|
||||
|
||||
<p><h3><a name="s4.5.13">4.5.13 Turn lamp on and off</a></h3><a name="i132"><a name="i133">
|
||||
<font color="darkgreen">
|
||||
The option <tt>lamp-on</tt> is used to turn the lamp of the scanner on.
|
||||
The type of this option is <tt>SANE_TYPE_BUTTON</tt>.
|
||||
The unit is <tt>SANE_UNIT_NONE</tt>. When the option is set
|
||||
then the lamp of the scanner is turned on.
|
||||
|
||||
<p>The option <tt>lamp-off</tt> is used to turn the lamp of the scanner off.
|
||||
The type of this option is <tt>SANE_TYPE_BUTTON</tt>.
|
||||
The unit is <tt>SANE_UNIT_NONE</tt>. When the option is set
|
||||
then the lamp of the scanner is turned off.
|
||||
|
||||
<p>These options are not mandatory, but if a backend does support them, it
|
||||
must implement them in a manner consistent with the above definition.<br>
|
||||
</font>
|
||||
|
||||
<p><h3><a name="s4.5.14">4.5.14 Scanner buttons</a></h3><a name="i134">
|
||||
<font color="darkgreen">
|
||||
Some scanners have buttons which state can be read by the scanner driver.
|
||||
It is necessary to implement a locking function for the buttons
|
||||
because it is possible that several frontends try to connect to the
|
||||
same backend/scanner at the same time. Imagine what could happen
|
||||
when no locking would be implemented:
|
||||
Five people have started a scanning application which is connected
|
||||
via network to the scanner you want to use. You start a frontend,
|
||||
put a paper to the scanner and press the scan-button on the scanner.
|
||||
The scanner does scan three times (because three frontends asked the
|
||||
button status when you pressed the button). For three people the
|
||||
image is saved to the harddisk, but it is not sure that your
|
||||
frontend did scan the image.<br>
|
||||
|
||||
<p>A backend that does make available the scanner-buttons has to
|
||||
implement the following options:<br>
|
||||
<tt>scanner-buttons-lock</tt> is of type <tt>SANE_TYPE_BOOL</tt>, default = <tt>SANE_FALSE</tt><br>
|
||||
<tt>scanner-buttons-status</tt> is of type <tt>SANE_TYPE_INT</tt>, default = 0<br>
|
||||
<tt>scanner-buttons-status-update</tt> is of type <tt>SANE_TYPE_BUTTON</tt><br>
|
||||
When setting these options the backend does not set <tt>SANE_INFO_RELOAD_OPTIONS</tt>
|
||||
or <tt>SANE_INFO_RELOAD_PARAMS</tt> if not explictly defined.
|
||||
|
||||
<p>A frontend has to disable the usage of the scanner-buttons by default. This is important
|
||||
because other frontends will not be able to use the buttons when the button-functions are locked.
|
||||
Another important thing is that some scanners do not turn off their lamp when the driver
|
||||
does frequently talk to the scanner (what is done when reading the button status from the scanner).
|
||||
|
||||
<p><ul>
|
||||
|
||||
<p><li>
|
||||
A frontend that wants to read the button status has to lock the
|
||||
button functions at first. For this it does set the option
|
||||
<tt>scanner-buttons-lock</tt> to <tt>SANE_TRUE</tt>.
|
||||
While setting the value of option <tt>scanner-buttons-lock</tt> to <tt>SANE_TRUE</tt>
|
||||
the backend does check if a lockfile (e.g. "backend"-buttons.lock) does exist.
|
||||
The lockfile has to be placed in a directory where every user has read and write access to.
|
||||
|
||||
<p> <ul>
|
||||
<li>
|
||||
If the lockfile does not exist then the backend creates the lockfile and writes the
|
||||
process ID (PID) of the backend to the file. Button access is allowed: the value
|
||||
of option <tt>scanner-buttons-lock</tt> is set to <tt>SANE_TRUE</tt>
|
||||
<li>
|
||||
If the file does exist and the backend PID is not the file PID then the
|
||||
backend has to check if the process with the PID stored in the lockfile
|
||||
still is running. If yes then the button access is not allowed: the value of
|
||||
option <tt>scanner-buttons-lock</tt> is set to <tt>SANE_FALSE</tt>. If not then the lockfile
|
||||
is recreated and the PID of the backend is stored in the lockfile, button
|
||||
access is allowed: the value of option <tt>scanner-buttons-lock</tt> is set to <tt>SANE_TRUE</tt>
|
||||
</ul>
|
||||
|
||||
<p><li>
|
||||
The frontend does read the value of option <tt>scanner-buttons-lock</tt>. If
|
||||
it is <tt>SANE_TRUE</tt> then the frontend has access to the scanner buttons.
|
||||
If it is <tt>SANE_FALSE</tt> then access has been denied.
|
||||
|
||||
<p><li>
|
||||
If the button access is allowed the frontend has to do the following about
|
||||
once per second (while not scanning):
|
||||
<ul>
|
||||
<li>
|
||||
The frontend does set option <tt>scanner-buttons-status-update</tt>.
|
||||
The backend checks if access to the buttons is allowed by comparing
|
||||
the backend PID with the lockfile PID. If access is allowed it
|
||||
does read the button status from the scanner and stores it in
|
||||
the option <tt>scanner-buttons-status</tt>, each bit represents a button, a
|
||||
value of 0 means the button is not pressed, a value of 1 means that the button
|
||||
is pressed. When the scanner is busy the backend must not wait, it has to
|
||||
return immedeatly and the button state keeps unchanged.
|
||||
The backend has to implement a timeout function. When no button has been pressed
|
||||
within a predefined time (e.g. 15 minutes) then the access permission is lost.
|
||||
In this case the backend does set option <tt>scanner-buttons-lock</tt> to <tt>SANE_FALSE</tt>
|
||||
and does set <tt>SANE_INFO_RELOAD_OPTIONS</tt> to inform the frontend that it has
|
||||
lost permission to access the scanner-button functions.
|
||||
If access is not allowed it does set the <tt>scanner-buttons-status</tt> to 0.
|
||||
|
||||
<p> <li>
|
||||
The frontend does read the value of option <tt>scanner-buttons-status</tt>
|
||||
</ul>
|
||||
|
||||
<p><li>
|
||||
When the frontend does exit or it does not want to use the buttons
|
||||
it does set option <tt>scanner-buttons-lock</tt> to <tt>SANE_FALSE</tt>.
|
||||
The backend does check if the backend PID and the lockfile PID are
|
||||
the same. If this is true then it removes the lockfile and sets the value
|
||||
of <tt>scanner-buttons-lock</tt> to <tt>SANE_FALSE</tt>.
|
||||
|
||||
<p><tt>sane_close()</tt> should do the same as setting option
|
||||
<tt>scanner-buttons-lock</tt> to <tt>SANE_FALSE</tt>.
|
||||
|
||||
<p></ul>
|
||||
</font>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc015.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc013.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,82 @@
|
|||
<html><body>
|
||||
<a href="doc016.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc014.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Network Protocol</title>
|
||||
<h1><a name="s5">5 Network Protocol</a></h1>
|
||||
|
||||
<p>The SANE interface has been designed to facilitate network access to
|
||||
image acquisition devices. In particular, most SANE implementations
|
||||
are expected to support a network backend (net client) and a
|
||||
corresponding network daemon (net server) that allows accessing image
|
||||
acquisition devices through a network connection. Network access is
|
||||
useful in several situations:
|
||||
<ul>
|
||||
|
||||
<p><li>To provide controlled access to resources that are inaccessible
|
||||
to a regular user. For example, a user may want to access a device
|
||||
on a host where she has no account on. With the network protocol,
|
||||
it is possible to allow certain users to access scanners without
|
||||
giving them full access to the system.
|
||||
|
||||
<p> Controlling access through the network daemon can be useful even in
|
||||
the local case: for example, certain backends may require root
|
||||
privileges to access a device. Rather than installing each frontend
|
||||
as setuid-root, a system administrator could instead install the
|
||||
SANE network daemon as setuid-root. This enables regular users to
|
||||
access the privileged device through the SANE daemon (which,
|
||||
presumably, supports a more fine-grained access control mechanism
|
||||
than the simple setuid approach). This has the added benefit that
|
||||
the system administrator only needs to trust the SANE daemon, not
|
||||
each and every frontend that may need access to the privileged
|
||||
device.
|
||||
|
||||
<p><li>Network access provides a sense of ubiquity of the available
|
||||
image acquisition devices. For example, in a local area network
|
||||
environment, this allows a user to log onto any machine and have
|
||||
convenient access to any resource available to any machine on the
|
||||
network (subject to permission constraints).
|
||||
|
||||
<p><li>For devices that do not require physical access when used (e.g.,
|
||||
video cameras), network access allows a user to control and use
|
||||
these devices without being in physical proximity. Indeed, if such
|
||||
devices are connected to the Internet, access from any place in the
|
||||
world is possible.
|
||||
|
||||
<p></ul>
|
||||
|
||||
<p>The network protocol described in this chapter has been design with
|
||||
the following goals in mind:
|
||||
<ol>
|
||||
|
||||
<p><li>Image transmission should be efficient (have low encoding
|
||||
overhead).
|
||||
|
||||
<p><li>Accessing option descriptors on the client side must be
|
||||
efficient (since this is a very common operation).
|
||||
|
||||
<p><li>Other operations, such as setting or inquiring the value of an
|
||||
option are less performance critical since they typically require
|
||||
explicit user action.
|
||||
|
||||
<p><li>The network protocol should be simple and easy to implement on
|
||||
any host architecture and any programming language.
|
||||
|
||||
<p></ol>
|
||||
The SANE protocol can be run across any transport protocol that
|
||||
provides reliable data delivery. While SANE does not specify a
|
||||
specific transport protocol, it is expected that TCP/IP will be among
|
||||
the most commonly used protocols.
|
||||
|
||||
<p><h2><a href="doc016.html">5.1 Data Type Encoding</a></h2><h2><a href="doc017.html">5.2 Remote Procedure Call Requests</a></h2><p><hr>
|
||||
<a href="doc016.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc014.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,89 @@
|
|||
<html><body>
|
||||
<a href="doc017.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc015.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Data Type Encoding</title>
|
||||
<h2><a name="s5.1">5.1 Data Type Encoding</a></h2>
|
||||
|
||||
<p><h3><a name="s5.1.1">5.1.1 Primitive Data Types</a></h3>
|
||||
|
||||
<p>The four primitive types of the SANE standard are encoded as follows:
|
||||
<dl>
|
||||
|
||||
<p><dt><tt>SANE_Byte<a name="i135"></tt>:<dd> A byte is encoded as an 8 bit value.
|
||||
Since the transport protocol is assumed to be byte-orientd, the bit
|
||||
order is irrelevant.
|
||||
|
||||
<p><dt><tt>SANE_Word<a name="i136"></tt>:<dd> A word is encoded as 4 bytes (32
|
||||
bits). The bytes are ordered from most-significant to
|
||||
least-significant byte (big-endian byte-order).
|
||||
|
||||
<p><dt><tt>SANE_Char<a name="i137"></tt>:<dd> A character is currently encoded as an 8-bit
|
||||
ISO LATIN-1 value. An extension to support wider character sets (16 or 32
|
||||
bits) is planned for the future, but not supported at this point.
|
||||
|
||||
<p><dt><tt>SANE_String<a name="i138"></tt>:<dd> A string pointer is encoded as a
|
||||
<tt>SANE_Char</tt> array. The trailing NUL byte is considered part
|
||||
of the array and a <tt>NULL</tt> pointer is encoded as a zero-length
|
||||
array.
|
||||
|
||||
<dt><tt>SANE_Handle<a name="i139"></tt>:<dd> A handle is encoded like a word.
|
||||
The network backend needs to take care of converting these integer
|
||||
values to the opaque pointer values that are presented to the user
|
||||
of the network backend. Similarly, the SANE daemon needs to take
|
||||
care of converting the opaque pointer values it receives from its
|
||||
backends into 32-bit integers suitable for use for network encoding.
|
||||
|
||||
<p><dt><em>enumeration types<a name="i140"></em>:<dd> Enumeration types are encoded
|
||||
like words.
|
||||
|
||||
<p></dl>
|
||||
|
||||
<p><h3><a name="s5.1.2">5.1.2 Type Constructors</a></h3>
|
||||
|
||||
<p>Closely following the type constructors of the C language, the SANE network
|
||||
protocol supports the following four constructors:
|
||||
<dl>
|
||||
|
||||
<p><dt><em>pointer<a name="i141"></em>:<dd> A pointer is encoded by a word that indicates
|
||||
whether the pointer is a NULL-pointer which is then followed by the
|
||||
value that the pointer points to (in the case of a non-NULL pointer;
|
||||
in the case of a NULL pointer, no bytes are encoded for the pointer
|
||||
value).
|
||||
|
||||
<p><dt><em>array<a name="i142"></em>:<dd> An array is encoded by a word that indicates
|
||||
the length of the array followed by the values of the elements in
|
||||
the array. The length may be zero in which case no bytes are
|
||||
encoded for the element values.
|
||||
|
||||
<p><dt><em>structure<a name="i143"></em>:<dd> A structure is encoded by simply encoding the
|
||||
structure members in the order in which they appear in the
|
||||
corresponding C type declaration.
|
||||
|
||||
<p><dt><em>union<a name="i144"></em>:<dd> A union must always be accompanied by a tag
|
||||
value that indicates which of the union members is the currently the
|
||||
active one. For this reason, the union itself is encoded simply by
|
||||
encoding the value of the currently active member.
|
||||
|
||||
<p></dl>
|
||||
|
||||
<p>Note that for type constructors, the pointer, element, or member
|
||||
values themselves may have a constructed type. Thus, the above rules
|
||||
should be applied recursively until a sequence of primitive types has
|
||||
been found.
|
||||
|
||||
<p>Also SANE had no need for encoding of circular structures. This
|
||||
greatly simplifies the network protocol.
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc017.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc015.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,460 @@
|
|||
<html><body>
|
||||
<a href="doc018.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc016.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Remote Procedure Call Requests</title>
|
||||
<h2><a name="s5.2">5.2 Remote Procedure Call Requests</a></h2>
|
||||
|
||||
<p>The SANE network protocol is a client/server-style remote procedure
|
||||
call (RPC) protocol. This means that all activity is initiated by the
|
||||
client side (the network backend)---a server is restricted to
|
||||
answering request by the client.
|
||||
|
||||
<p><h3><a name="s5.2.1">5.2.1 <tt>SANE_NET_INIT<a name="i145"></tt></a></h3>
|
||||
|
||||
<p>This RPC establishes a connection to a particular SANE network daemon.
|
||||
It must be the first call in a SANE network session. The parameter
|
||||
and reply arguments for this call are shown in the table below:
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word version_code</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_String user_name</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word version_code</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>version_code</tt> argument in the request is the SANE
|
||||
version-code of the network backend that is contacting the network
|
||||
daemon (see Section <a href="doc010.html#s4.1">4.1</a>). The
|
||||
``build-revision'' in the version code is used to hold the network
|
||||
protocol version. The SANE network daemon receiving such a request
|
||||
must make sure that the network protocol version corresponds to a
|
||||
supported version since otherwise the encoding of the network stream
|
||||
may be incompatible (even though the SANE interface itself may be
|
||||
compatible). The <tt>user_name</tt> argument is the name of the user
|
||||
on whose behalf this call is being performed. If the network backend
|
||||
cannot determine a user-name, it passes a <tt>NULL</tt> pointer for this
|
||||
argument. No trust should be placed in the authenticity of this
|
||||
user-name. The intent of this string is to provide more convenience
|
||||
to the user. E.g., it could be used as the default-user name in
|
||||
subsequent authentication calls.
|
||||
|
||||
<p>In the reply, <tt>status</tt> indicates the completion status. If the
|
||||
value is anything other than <tt>SANE_STATUS_SUCCESS</tt>, the
|
||||
remainder of the reply has undefined values.<a name="F2"><a href="footnotes.html#000002"><sup><fontsize=-2>2</font></sup></a></a> The <tt>version_code</tt> argument returns the
|
||||
SANE version-code that the network daemon supports. See the comments
|
||||
in the previous paragraph on the meaning of the build-revision in this
|
||||
version code.
|
||||
|
||||
<p><h3><a name="s5.2.2">5.2.2 <tt>SANE_NET_GET_DEVICES<a name="i147"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to obtain the list of devices accessible by the SANE
|
||||
daemon.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>void</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Device ***device_list</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
There are no arguments in the request for this call.
|
||||
|
||||
<p>In the reply, <tt>status</tt> indicates the completion status. If the
|
||||
value is anything other than <tt>SANE_STATUS_SUCCESS</tt>, the
|
||||
remainder of the reply has undefined values. The <tt>device_list</tt>
|
||||
argument is a pointer to a <tt>NULL</tt>-terminated array of
|
||||
<tt>SANE_Device</tt> pointers.
|
||||
|
||||
<p><h3><a name="s5.2.3">5.2.3 <tt>SANE_NET_OPEN<a name="i149"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to open a connection to a remote SANE device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_String device_name</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word handle</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_String resource</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>device_name</tt> argument specifies the name of the device to
|
||||
open.
|
||||
|
||||
<p>In the reply, <tt>status</tt> indicates the completion status. If the
|
||||
value is anything other than <tt>SANE_STATUS_SUCCESS</tt>, the
|
||||
remainder of the reply has undefined values. The <tt>handle</tt>
|
||||
argument specifies the device handle that uniquely identifies the
|
||||
connection. The <tt>resource</tt> argument is used to request
|
||||
authentication. If it has a non-<tt>NULL</tt> value, the network
|
||||
backend should authenticate the specified resource and then retry this
|
||||
operation (see Section <a href="doc017.html#s5.2.10">5.2.10</a> for details on how to
|
||||
authorize a resource).
|
||||
|
||||
<p><h3><a name="s5.2.4">5.2.4 <tt>SANE_NET_CLOSE<a name="i151"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to close a connection to a remote SANE device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word dummy</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the connection that should be
|
||||
closed.
|
||||
|
||||
<p>In the reply, the <tt>dummy</tt> argument is unused. Its purpose is to
|
||||
ensure proper synchronization (without it, a net client would not be
|
||||
able to determine when the RPC has completed).
|
||||
|
||||
<p><h3><a name="s5.2.5">5.2.5 <tt>SANE_NET_GET_OPTION_DESCRIPTORS<a name="i153"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to obtain <em>all</em> the option descriptors for a
|
||||
remote SANE device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>Option_Descriptor_Array odesc</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the remote device whose option
|
||||
descriptors should be obtained.
|
||||
|
||||
<p>In the reply, the <tt>odesc</tt> argument is used to return the array of
|
||||
option descriptors. The option descriptor array has the following
|
||||
structure:
|
||||
<blockquote><a name="i155">
|
||||
<pre>
|
||||
struct Option_Descriptor_Array
|
||||
{
|
||||
SANE_Word num_options;
|
||||
SANE_Option_Descriptor **desc;
|
||||
};
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s5.2.6">5.2.6 <tt>SANE_NET_CONTROL_OPTION<a name="i156"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to control (inquire, set, or set to automatic) a
|
||||
specific option of a remote SANE device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Status status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word option</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word info</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word action</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word value_type</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word value_type</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word value_size</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word value_size</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>void *value</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>void *value</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_String *resource</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the remote device whose option
|
||||
should be controlled. Argument <tt>option</tt> is the number (index) of
|
||||
the option that should be controlled. Argument <tt>action</tt>
|
||||
specifies what action should be taken (get, set, or set automatic).
|
||||
Argument <tt>value_type</tt> specifies the type of the option value
|
||||
(must be one of <tt>SANE_TYPE_BOOL</tt>, <tt>SANE_TYPE_INT</tt>,
|
||||
<tt>SANE_TYPE_FIXED</tt>, <tt>SANE_TYPE_STRING</tt>,
|
||||
<tt>SANE_TYPE_BUTTON</tt>). Argument <tt>value_size</tt> specifies
|
||||
the size of the option value in number of bytes (see
|
||||
Section <a href="doc011.html#s4.2.9.6">4.2.9.6</a> for the precise meaning of this value).
|
||||
Finally, argument <tt>value</tt> is a pointer to the option value. It
|
||||
must be a writeable area that is at least <tt>value_size</tt> bytes
|
||||
large. (Note that this area must be writable even if the action is to
|
||||
set the option value. This is because the backend may not be able to
|
||||
set the exact option value, in which case the option value is used to
|
||||
return the next best value that the backend has chosen.)
|
||||
|
||||
<p>In the reply, argument <tt>resource</tt> is set to the name of the
|
||||
resource that must be authorized before this call can be retried. If
|
||||
this value is non-<tt>NULL</tt>, all other arguments have undefined
|
||||
values (see Section <a href="doc017.html#s5.2.10">5.2.10</a> for details on how to
|
||||
authorize a resource). Argument <tt>status</tt> indicates the
|
||||
completion status. If the value is anything other than
|
||||
<tt>SANE_STATUS_SUCCESS</tt>, the remainder of the reply has undefined
|
||||
values. The <tt>info</tt> argument returns the information on how well
|
||||
the backend was able to satisfy the request. For details, see the
|
||||
description of the corresponding argument in
|
||||
Section <a href="doc012.html#s4.3.7">4.3.7</a>. Arguments <tt>value_type</tt> and
|
||||
<tt>value_size</tt> have the same values as the arguments by the same
|
||||
name in corresponding request. The values are repeated here to ensure
|
||||
that both the request and the reply are self-contained (i.e., they can
|
||||
be encoded and decoded independently). Argument <tt>value</tt> is holds
|
||||
the value of the option that has become effective as a result of this
|
||||
RPC.
|
||||
|
||||
<p><h3><a name="s5.2.7">5.2.7 <tt>SANE_NET_GET_PARAMETERS<a name="i158"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to obtain the scan parameters of a remote SANE
|
||||
device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Status status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Parameters params</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the connection to the remote
|
||||
device whose scan parameters should be returned.
|
||||
|
||||
<p>In the reply, <tt>status</tt> indicates the completion status. If the
|
||||
value is anything other than <tt>SANE_STATUS_SUCCESS</tt>, the
|
||||
remainder of the reply has undefined values. The argument
|
||||
<tt>params</tt> is used to return the scan parameters.
|
||||
|
||||
<p><h3><a name="s5.2.8">5.2.8 <tt>SANE_NET_START<a name="i160"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to start image acquisition (scanning).
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Status status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word port</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word byte_order</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_String resource</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the connection to the remote
|
||||
device from which the image should be acquired.
|
||||
|
||||
<p>In the reply, argument <tt>resource</tt> is set to the name of the
|
||||
resource that must be authorized before this call can be retried. If
|
||||
this value is non-<tt>NULL</tt>, all other arguments have undefined
|
||||
values (see Section <a href="doc017.html#s5.2.10">5.2.10</a> for details on how to
|
||||
authorize a resource). Argument, <tt>status</tt> indicates the
|
||||
completion status. If the value is anything other than
|
||||
<tt>SANE_STATUS_SUCCESS</tt>, the remainder of the reply has
|
||||
undefined values. The argument <tt>port</tt> returns the port number
|
||||
from which the image data will be available. To read the image data,
|
||||
a network client must connect to the remote host at the indicated port
|
||||
number. Through this port, the image data is transmitted as a
|
||||
sequence of data records. Each record starts with the data length in
|
||||
bytes. The data length is transmitted as a sequence of four bytes.
|
||||
These bytes should be interpreted as an unsigned integer in big-endian
|
||||
format. The four length bytes are followed by the number of data
|
||||
bytes indicated by the length. Except for byte-order, the data is in
|
||||
the same format as defined for <tt>sane_read()</tt>. Since some
|
||||
records may contain no data at all, a length value of zero is
|
||||
perfectly valid. The special length value of <tt>0xffffffff</tt> is
|
||||
used to indicate the end of the data stream. That is, after receiving
|
||||
a record length of <tt>0xffffffff</tt>, the network client should close
|
||||
the data connection and stop reading data.
|
||||
|
||||
<p>Argument <tt>byte_order</tt> specifies the byte-order of the image
|
||||
data. A value of 0x1234 indicates little-endian format, a value of
|
||||
0x4321 indicates big-endian format. All other values are presently
|
||||
undefined and reserved for future enhancements of this protocol. The
|
||||
intent is that a network server sends data in its own byte-order and
|
||||
the client is responsible for adjusting the byte-order, if necessary.
|
||||
This approach causes no unnecessary overheads in the case where the
|
||||
server and client byte-order match and puts the extra burden on the
|
||||
client side when there is a byte-order mismatch. Putting the burden
|
||||
on the client-side improves the scalability properties of this
|
||||
protocol.
|
||||
|
||||
<p><h3><a name="s5.2.9">5.2.9 <tt>SANE_NET_CANCEL<a name="i162"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to cancel the current operation of a remote SANE
|
||||
device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word dummy</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the connection whose operation
|
||||
should be cancelled.
|
||||
|
||||
<p>In the reply, the <tt>dummy</tt> argument is unused. Its purpose is to
|
||||
ensure proper synchronization (without it, a net client would not be
|
||||
able to determine when the RPC has completed).
|
||||
|
||||
<p><h3><a name="s5.2.10">5.2.10 <tt>SANE_NET_AUTHORIZE<a name="i164"></tt></a></h3>
|
||||
<a name="i166">
|
||||
|
||||
<p>This RPC is used to pass authorization data from the net client to the
|
||||
net server.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_String resource</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word dummy</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_String username</tt> </td>
|
||||
<td colspan=1 align=left nowrap> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_String password</tt> </td>
|
||||
<td colspan=1 align=left nowrap> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>resource</tt> argument specifies the name of the resource to be
|
||||
authorized. This argument should be set to the string returned in the
|
||||
<tt>resource</tt> argument of the RPC reply that required this
|
||||
authorization call. The <tt>username</tt> and <tt>password</tt> are the
|
||||
name of the user that is accessing the resource and the password for
|
||||
the specified resource/user pair.
|
||||
|
||||
<p>Since the password is not encrypted during network transmission, it is
|
||||
recommended to use the following extension:
|
||||
|
||||
<p>If the server adds the string `<tt>$MD5$</tt>' to the resource-name followed
|
||||
by a random string not longer then 128 bytes, the client may answer with the
|
||||
MD5 digest of the concatenation of the password and the random string. To
|
||||
differentiate between the MD5 digest and a strange password the client prepends
|
||||
the MD5 digest with the string `<tt>$MD5$</tt>'.
|
||||
|
||||
<p>In the reply, <tt>dummy</tt> is completely unused. Note that there is
|
||||
no direct failure indication. This is unnecessary since a net client
|
||||
will retry the RPC that resulted in the authorization request until
|
||||
that call succeeds (or until the request is cancelled). The RPC that resulted
|
||||
in the authorization request continues after the reply from the client and may
|
||||
fail with <tt>SANE_STATUS_ACCESS_DENIED</tt>.
|
||||
|
||||
<p><h3><a name="s5.2.11">5.2.11 <tt>SANE_NET_EXIT<a name="i167"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to disconnect a net client from a net server. There
|
||||
are no request or reply arguments in this call. As a result of this
|
||||
call, the connection between the client and the server that was
|
||||
established by the <tt>SANE_NET_INIT</tt> call will be closed.
|
||||
|
||||
<p>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc018.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc016.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
<html><body>
|
||||
<a href="doc019.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc017.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Contact Information</title>
|
||||
<h1><a name="s6">6 Contact Information</a></h1>
|
||||
|
||||
<p>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.
|
||||
<blockquote><a name="i169">
|
||||
<pre>
|
||||
majordomo@mostang.com
|
||||
</pre>
|
||||
</blockquote>
|
||||
To subscribe, send a mail with the body ``<tt>subscribe sane-devel</tt>'' to the
|
||||
above address.
|
||||
|
||||
<p>A complete list of commands supported can be obtained by sending a
|
||||
mail with a subject of ``<tt>help</tt>'' to the above address. The
|
||||
mailing list is archived and available through the SANE home page at
|
||||
URL:
|
||||
<blockquote>
|
||||
<a href="http://www.mostang.com/sane/">http://www.mostang.com/sane/</a>
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
<p><hr>
|
||||
<a href="doc019.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc017.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,207 @@
|
|||
<html><body>
|
||||
<img src=../icons/next_gr.gif border=2 alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc018.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
<h1>Index</h1>
|
||||
|
||||
|
||||
<p><multicol cols=2>
|
||||
<p><a href="doc014.html#i129">analog gamma option</a><br>
|
||||
<a href="doc016.html#i142">array</a><br>
|
||||
|
||||
<p><a href="doc014.html#i124">bit depth option</a><br>
|
||||
<a href="doc014.html#i122">br-x</a><br>
|
||||
<a href="doc014.html#i123">br-y</a><br>
|
||||
|
||||
<p><a href="doc013.html#i113">code flow</a><br>
|
||||
|
||||
<p><a href="doc011.html#i43">device-name</a><br>
|
||||
<a href="doc012.html#i80">domain</a><br>
|
||||
|
||||
<p><a href="doc016.html#i140">enumeration types</a><br>
|
||||
|
||||
<p><a href="doc014.html#i125">gamma table options</a><br>
|
||||
|
||||
<p><a href="doc014.html#i131">hightlight options</a><br>
|
||||
|
||||
<p><a href="doc008.html#i0">image data format</a><br>
|
||||
|
||||
<p><a href="doc014.html#i133">lamp-off option</a><br>
|
||||
<a href="doc014.html#i132">lamp-on option</a><br>
|
||||
|
||||
<p><a href="doc018.html#i169">mailing list</a><br>
|
||||
<a href="doc014.html#i126">mode options</a><br>
|
||||
|
||||
<p><a href="doc017.html#i166">network authorization</a><br>
|
||||
<a href="doc011.html#i26">NUL</a><br>
|
||||
|
||||
<p><a href="doc014.html#i115">option count</a><br>
|
||||
<a href="doc017.html#i155">Option_Descriptor_Array</a><br>
|
||||
|
||||
<p><a href="doc012.html#i82">password</a><br>
|
||||
<a href="doc016.html#i141">pointer</a><br>
|
||||
<a href="doc014.html#i118">preview mode</a><br>
|
||||
|
||||
<p><a href="doc014.html#i117">resolution option</a><br>
|
||||
|
||||
<p><a href="doc012.html#i89">SANE_Action</a><br>
|
||||
<a href="doc012.html#i90">SANE_ACTION_GET_VALUE</a><br>
|
||||
<a href="doc012.html#i92">SANE_ACTION_SET_AUTO</a><br>
|
||||
<a href="doc012.html#i91">SANE_ACTION_SET_VALUE</a><br>
|
||||
<a href="doc012.html#i79">SANE_Authorization_Callback</a><br>
|
||||
<a href="doc011.html#i16">SANE_Bool</a><br>
|
||||
<a href="doc011.html#i14">SANE_Byte</a><br>
|
||||
<a href="doc016.html#i135">SANE_Byte</a><br>
|
||||
<a href="doc012.html#i109">sane_cancel</a><br>
|
||||
<a href="doc011.html#i70">SANE_CAP_ADVANCED</a><br>
|
||||
<a href="doc011.html#i68">SANE_CAP_AUTOMATIC</a><br>
|
||||
<a href="doc011.html#i67">SANE_CAP_EMULATED</a><br>
|
||||
<a href="doc011.html#i65">SANE_CAP_HARD_SELECT</a><br>
|
||||
<a href="doc011.html#i69">SANE_CAP_INACTIVE</a><br>
|
||||
<a href="doc011.html#i66">SANE_CAP_SOFT_DETECT</a><br>
|
||||
<a href="doc011.html#i64">SANE_CAP_SOFT_SELECT</a><br>
|
||||
<a href="doc011.html#i24">SANE_Char</a><br>
|
||||
<a href="doc016.html#i137">SANE_Char</a><br>
|
||||
<a href="doc012.html#i86">sane_close</a><br>
|
||||
<a href="doc011.html#i72">SANE_CONSTRAINT_NONE</a><br>
|
||||
<a href="doc011.html#i73">SANE_CONSTRAINT_RANGE</a><br>
|
||||
<a href="doc011.html#i76">SANE_CONSTRAINT_STRING_LIST</a><br>
|
||||
<a href="doc011.html#i71">SANE_Constraint_Type</a><br>
|
||||
<a href="doc011.html#i75">SANE_CONSTRAINT_WORD_LIST</a><br>
|
||||
<a href="doc012.html#i88">sane_control_option</a><br>
|
||||
<a href="doc010.html#i11">SANE_CURRENT_MAJOR</a><br>
|
||||
<a href="doc011.html#i42">SANE_Device</a><br>
|
||||
<a href="doc012.html#i83">sane_exit</a><br>
|
||||
<a href="doc011.html#i17">SANE_FALSE</a><br>
|
||||
<a href="doc011.html#i22">SANE_FIX</a><br>
|
||||
<a href="doc011.html#i20">SANE_Fixed</a><br>
|
||||
<a href="doc011.html#i21">SANE_FIXED_SCALE_SHIFT</a><br>
|
||||
<a href="doc012.html#i98">SANE_Frame</a><br>
|
||||
<a href="doc008.html#i7">SANE_FRAME_BLUE</a><br>
|
||||
<a href="doc012.html#i103">SANE_FRAME_BLUE</a><br>
|
||||
<a href="doc008.html#i3">SANE_FRAME_GRAY</a><br>
|
||||
<a href="doc012.html#i99">SANE_FRAME_GRAY</a><br>
|
||||
<a href="doc008.html#i6">SANE_FRAME_GREEN</a><br>
|
||||
<a href="doc012.html#i102">SANE_FRAME_GREEN</a><br>
|
||||
<a href="doc008.html#i2">SANE_FRAME_MIME</a><br>
|
||||
<a href="doc008.html#i10">SANE_FRAME_MIME</a><br>
|
||||
<a href="doc012.html#i105">SANE_FRAME_MIME</a><br>
|
||||
<a href="doc008.html#i1">SANE_FRAME_RAW</a><br>
|
||||
<a href="doc008.html#i8">SANE_FRAME_RAW</a><br>
|
||||
<a href="doc008.html#i9">SANE_FRAME_RAW</a><br>
|
||||
<a href="doc012.html#i104">SANE_FRAME_RAW</a><br>
|
||||
<a href="doc008.html#i5">SANE_FRAME_RED</a><br>
|
||||
<a href="doc012.html#i101">SANE_FRAME_RED</a><br>
|
||||
<a href="doc008.html#i4">SANE_FRAME_RGB</a><br>
|
||||
<a href="doc012.html#i100">SANE_FRAME_RGB</a><br>
|
||||
<a href="doc012.html#i84">sane_get_devices</a><br>
|
||||
<a href="doc012.html#i87">sane_get_option_descriptor</a><br>
|
||||
<a href="doc012.html#i96">sane_get_parameters</a><br>
|
||||
<a href="doc012.html#i111">sane_get_select_fd</a><br>
|
||||
<a href="doc011.html#i28">SANE_Handle</a><br>
|
||||
<a href="doc016.html#i139">SANE_Handle</a><br>
|
||||
<a href="doc012.html#i93">SANE_INFO_INEXACT</a><br>
|
||||
<a href="doc012.html#i94">SANE_INFO_RELOAD_OPTIONS</a><br>
|
||||
<a href="doc012.html#i107">SANE_INFO_RELOAD_OPTIONS</a><br>
|
||||
<a href="doc012.html#i95">SANE_INFO_RELOAD_PARAMS</a><br>
|
||||
<a href="doc012.html#i78">sane_init</a><br>
|
||||
<a href="doc011.html#i19">SANE_Int</a><br>
|
||||
<a href="doc017.html#i164">SANE_NET_AUTHORIZE</a><br>
|
||||
<a href="doc017.html#i165">SANE_NET_AUTHORIZE</a><br>
|
||||
<a href="doc017.html#i162">SANE_NET_CANCEL</a><br>
|
||||
<a href="doc017.html#i163">SANE_NET_CANCEL</a><br>
|
||||
<a href="doc017.html#i151">SANE_NET_CLOSE</a><br>
|
||||
<a href="doc017.html#i152">SANE_NET_CLOSE</a><br>
|
||||
<a href="doc017.html#i156">SANE_NET_CONTROL_OPTION</a><br>
|
||||
<a href="doc017.html#i157">SANE_NET_CONTROL_OPTION</a><br>
|
||||
<a href="doc017.html#i167">SANE_NET_EXIT</a><br>
|
||||
<a href="doc017.html#i168">SANE_NET_EXIT</a><br>
|
||||
<a href="doc017.html#i147">SANE_NET_GET_DEVICES</a><br>
|
||||
<a href="doc017.html#i148">SANE_NET_GET_DEVICES</a><br>
|
||||
<a href="doc017.html#i153">SANE_NET_GET_OPTION_DESCRIPTORS</a><br>
|
||||
<a href="doc017.html#i154">SANE_NET_GET_OPTION_DESCRIPTORS</a><br>
|
||||
<a href="doc017.html#i158">SANE_NET_GET_PARAMETERS</a><br>
|
||||
<a href="doc017.html#i159">SANE_NET_GET_PARAMETERS</a><br>
|
||||
<a href="doc017.html#i145">SANE_NET_INIT</a><br>
|
||||
<a href="doc017.html#i146">SANE_NET_INIT</a><br>
|
||||
<a href="doc017.html#i149">SANE_NET_OPEN</a><br>
|
||||
<a href="doc017.html#i150">SANE_NET_OPEN</a><br>
|
||||
<a href="doc017.html#i160">SANE_NET_START</a><br>
|
||||
<a href="doc017.html#i161">SANE_NET_START</a><br>
|
||||
<a href="doc012.html#i85">sane_open</a><br>
|
||||
<a href="doc011.html#i46">SANE_Option_Descriptor</a><br>
|
||||
<a href="doc011.html#i62">SANE_OPTION_IS_ACTIVE</a><br>
|
||||
<a href="doc011.html#i63">SANE_OPTION_IS_SETTABLE</a><br>
|
||||
<a href="doc012.html#i97">SANE_Parameters</a><br>
|
||||
<a href="doc011.html#i74">SANE_Range</a><br>
|
||||
<a href="doc012.html#i108">sane_read</a><br>
|
||||
<a href="doc012.html#i110">sane_set_io_mode</a><br>
|
||||
<a href="doc012.html#i106">sane_start</a><br>
|
||||
<a href="doc011.html#i29">SANE_Status</a><br>
|
||||
<a href="doc011.html#i41">SANE_STATUS_ACCESS_DENIED</a><br>
|
||||
<a href="doc011.html#i32">SANE_STATUS_CANCELLED</a><br>
|
||||
<a href="doc011.html#i38">SANE_STATUS_COVER_OPEN</a><br>
|
||||
<a href="doc011.html#i33">SANE_STATUS_DEVICE_BUSY</a><br>
|
||||
<a href="doc011.html#i35">SANE_STATUS_EOF</a><br>
|
||||
<a href="doc011.html#i30">SANE_STATUS_GOOD</a><br>
|
||||
<a href="doc012.html#i77">SANE_STATUS_GOOD</a><br>
|
||||
<a href="doc011.html#i34">SANE_STATUS_INVAL</a><br>
|
||||
<a href="doc011.html#i39">SANE_STATUS_IO_ERROR</a><br>
|
||||
<a href="doc011.html#i36">SANE_STATUS_JAMMED</a><br>
|
||||
<a href="doc011.html#i37">SANE_STATUS_NO_DOCS</a><br>
|
||||
<a href="doc011.html#i40">SANE_STATUS_NO_MEM</a><br>
|
||||
<a href="doc011.html#i31">SANE_STATUS_UNSUPPORTED</a><br>
|
||||
<a href="doc011.html#i25">SANE_String</a><br>
|
||||
<a href="doc016.html#i138">SANE_String</a><br>
|
||||
<a href="doc011.html#i27">SANE_String_Const</a><br>
|
||||
<a href="doc012.html#i112">sane_strstatus</a><br>
|
||||
<a href="doc011.html#i18">SANE_TRUE</a><br>
|
||||
<a href="doc011.html#i48">SANE_TYPE_BOOL</a><br>
|
||||
<a href="doc011.html#i52">SANE_TYPE_BUTTON</a><br>
|
||||
<a href="doc011.html#i50">SANE_TYPE_FIXED</a><br>
|
||||
<a href="doc011.html#i53">SANE_TYPE_GROUP</a><br>
|
||||
<a href="doc011.html#i49">SANE_TYPE_INT</a><br>
|
||||
<a href="doc011.html#i51">SANE_TYPE_STRING</a><br>
|
||||
<a href="doc011.html#i54">SANE_Unit</a><br>
|
||||
<a href="doc011.html#i23">SANE_UNFIX</a><br>
|
||||
<a href="doc011.html#i57">SANE_UNIT_BIT</a><br>
|
||||
<a href="doc011.html#i59">SANE_UNIT_DPI</a><br>
|
||||
<a href="doc011.html#i61">SANE_UNIT_MICROSECOND</a><br>
|
||||
<a href="doc011.html#i58">SANE_UNIT_MM</a><br>
|
||||
<a href="doc011.html#i55">SANE_UNIT_NONE</a><br>
|
||||
<a href="doc011.html#i60">SANE_UNIT_PERCENT</a><br>
|
||||
<a href="doc011.html#i56">SANE_UNIT_PIXEL</a><br>
|
||||
<a href="doc011.html#i47">SANE_Value_Type</a><br>
|
||||
<a href="doc010.html#i12">SANE_VERSION_CODE</a><br>
|
||||
<a href="doc010.html#i13">SANE_VERSION_MAJOR</a><br>
|
||||
<a href="doc011.html#i15">SANE_Word</a><br>
|
||||
<a href="doc016.html#i136">SANE_Word</a><br>
|
||||
<a href="doc014.html#i119">scan area options</a><br>
|
||||
<a href="doc014.html#i116">scan resolution</a><br>
|
||||
<a href="doc014.html#i134">scanner button options</a><br>
|
||||
<a href="doc014.html#i130">shadow options</a><br>
|
||||
<a href="doc014.html#i127">source options</a><br>
|
||||
<a href="doc016.html#i143">structure</a><br>
|
||||
|
||||
<p><a href="doc014.html#i128">threshold option</a><br>
|
||||
<a href="doc014.html#i120">tl-x</a><br>
|
||||
<a href="doc014.html#i121">tl-y</a><br>
|
||||
<a href="doc011.html#i45">Type Strings</a><br>
|
||||
|
||||
<p><a href="doc016.html#i144">union</a><br>
|
||||
<a href="doc012.html#i81">username</a><br>
|
||||
|
||||
<p><a href="doc011.html#i44">Vendor Strings</a><br>
|
||||
|
||||
<p><a href="doc014.html#i114">well-known options</a><br>
|
||||
</multicol><p><hr>
|
||||
<img src=../icons/next_gr.gif border=2 alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc018.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
<title>Footnotes</title><h1>Footnotes</h1><p>
|
||||
|
||||
<hr><p><b><a href="doc011.html#F1">1</a></b> This is different from ANSI C where
|
||||
any non-zero integer value represents logical TRUE.
|
||||
<hr><p><b><a href="doc017.html#F2">2</a></b> The sane network
|
||||
daemon should be careful not to leak information in the undefined
|
||||
portion of the reply.
|
||||
Plik binarny nie jest wyświetlany.
|
Po Szerokość: | Wysokość: | Rozmiar: 6.8 KiB |
Plik binarny nie jest wyświetlany.
|
Po Szerokość: | Wysokość: | Rozmiar: 1011 B |
Plik binarny nie jest wyświetlany.
|
Po Szerokość: | Wysokość: | Rozmiar: 1.8 KiB |
Plik binarny nie jest wyświetlany.
|
Po Szerokość: | Wysokość: | Rozmiar: 9.3 KiB |
Plik binarny nie jest wyświetlany.
|
Po Szerokość: | Wysokość: | Rozmiar: 2.2 KiB |
|
|
@ -0,0 +1,63 @@
|
|||
<html><body>
|
||||
<a href="doc002.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc000.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
<title>./sane</title>
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
<p>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
<p><center><h1><font size=+4>SANE Standard Version 2.0 proposal 0.07 - rauch/beck</font></h1></center>
|
||||
<center></center>
|
||||
<center>Dec 5, 2002</center>
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
<p><h1><a href="doc002.html">1 Preface</a></h1><h1><a href="doc004.html">2 Introduction</a></h1><h1><a href="doc006.html">3 The SANE Environment</a></h1><h1><a href="doc009.html">4 The SANE Application Programmer Interface (API)</a></h1><h1><a href="doc015.html">5 Network Protocol</a></h1><h1><a href="doc018.html">6 Contact Information</a></h1><p><hr>
|
||||
<a href="doc002.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc000.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
Plik binarny nie jest wyświetlany.
Plik diff jest za duży
Load Diff
Plik diff jest za duży
Load Diff
|
|
@ -0,0 +1,132 @@
|
|||
<html><body>
|
||||
<a href="doc001.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<img src=../icons/up_gr.gif border=2 alt="Previous"></a>
|
||||
<img src=../icons/previous_gr.gif border=2 alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
<title>Contents</title>
|
||||
<h1>Contents</h1><p>
|
||||
|
||||
<table>
|
||||
<tr></tr><tr><td colspan=20>1<tt> </tt><a href="doc002.html#s1"><b>Preface</b></a></td></tr>
|
||||
<tr><td></td><td colspan=20>1.1<tt> </tt><a href="doc003.html#s1.1">About This Document</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>1.1.1<tt> </tt><a href="doc003.html#s1.1.1">Typographic Conventions</a></td></tr>
|
||||
<tr></tr><tr><td colspan=20>2<tt> </tt><a href="doc004.html#s2"><b>Introduction</b></a></td></tr>
|
||||
<tr><td></td><td colspan=20>2.1<tt> </tt><a href="doc005.html#s2.1">Terminology</a></td></tr>
|
||||
<tr></tr><tr><td colspan=20>3<tt> </tt><a href="doc006.html#s3"><b>The SANE Environment</b></a></td></tr>
|
||||
<tr><td></td><td colspan=20>3.1<tt> </tt><a href="doc007.html#s3.1">Attaching to a SANE backend</a></td></tr>
|
||||
<tr><td></td><td colspan=20>3.2<tt> </tt><a href="doc008.html#s3.2">Image Data Format</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>3.2.1<tt> </tt><a href="doc008.html#s3.2.1">Pixel oriented frames</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>3.2.2<tt> </tt><a href="doc008.html#s3.2.2">Arbitrary data frames</a></td></tr>
|
||||
<tr></tr><tr><td colspan=20>4<tt> </tt><a href="doc009.html#s4"><b>The SANE Application Programmer Interface (API)</b></a></td></tr>
|
||||
<tr><td></td><td colspan=20>4.1<tt> </tt><a href="doc010.html#s4.1">Version Control</a></td></tr>
|
||||
<tr><td></td><td colspan=20>4.2<tt> </tt><a href="doc011.html#s4.2">Data Types</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.1<tt> </tt><a href="doc011.html#s4.2.1">Base Types</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.2<tt> </tt><a href="doc011.html#s4.2.2">Boolean Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.3<tt> </tt><a href="doc011.html#s4.2.3">Integer Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.4<tt> </tt><a href="doc011.html#s4.2.4">Fixed-point Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.5<tt> </tt><a href="doc011.html#s4.2.5">Text</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.5.1<tt> </tt><a href="doc011.html#s4.2.5.1">Character Type</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.5.2<tt> </tt><a href="doc011.html#s4.2.5.2">String Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.6<tt> </tt><a href="doc011.html#s4.2.6">Scanner Handle Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.7<tt> </tt><a href="doc011.html#s4.2.7">Status Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.8<tt> </tt><a href="doc011.html#s4.2.8">Device Descriptor Type</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.9<tt> </tt><a href="doc011.html#s4.2.9">Option Descriptor Type</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.1<tt> </tt><a href="doc011.html#s4.2.9.1">Option Name</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.2<tt> </tt><a href="doc011.html#s4.2.9.2">Option Title</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.3<tt> </tt><a href="doc011.html#s4.2.9.3">Option Description</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.4<tt> </tt><a href="doc011.html#s4.2.9.4">Option Value Type</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.5<tt> </tt><a href="doc011.html#s4.2.9.5">Option Value Unit</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.6<tt> </tt><a href="doc011.html#s4.2.9.6">Option Value Size</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.7<tt> </tt><a href="doc011.html#s4.2.9.7">Option Capabilities</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.9.8<tt> </tt><a href="doc011.html#s4.2.9.8">Option Value Constraints</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.2.10<tt> </tt><a href="doc011.html#s4.2.10">Internationalization</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.10.1<tt> </tt><a href="doc011.html#s4.2.10.1">How is a text marked for translation</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.10.2<tt> </tt><a href="doc011.html#s4.2.10.2">Which texts shall be marked for translation?</a></td></tr>
|
||||
<tr><td></td><td></td><td></td><td colspan=20>4.2.10.3<tt> </tt><a href="doc011.html#s4.2.10.3">File formats and translation functions</a></td></tr>
|
||||
<tr><td></td><td colspan=20>4.3<tt> </tt><a href="doc012.html#s4.3">Operations</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.1<tt> </tt><a href="doc012.html#s4.3.1"><tt>sane_init</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.2<tt> </tt><a href="doc012.html#s4.3.2"><tt>sane_exit</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.3<tt> </tt><a href="doc012.html#s4.3.3"><tt>sane_get_devices</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.4<tt> </tt><a href="doc012.html#s4.3.4"><tt>sane_open</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.5<tt> </tt><a href="doc012.html#s4.3.5"><tt>sane_close</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.6<tt> </tt><a href="doc012.html#s4.3.6"><tt>sane_get_option_descriptor</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.7<tt> </tt><a href="doc012.html#s4.3.7"><tt>sane_control_option</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.8<tt> </tt><a href="doc012.html#s4.3.8"><tt>sane_get_parameters</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.9<tt> </tt><a href="doc012.html#s4.3.9"><tt>sane_start</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.10<tt> </tt><a href="doc012.html#s4.3.10"><tt>sane_read</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.11<tt> </tt><a href="doc012.html#s4.3.11"><tt>sane_cancel</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.12<tt> </tt><a href="doc012.html#s4.3.12"><tt>sane_set_io_mode</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.13<tt> </tt><a href="doc012.html#s4.3.13"><tt>sane_get_select_fd</tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.3.14<tt> </tt><a href="doc012.html#s4.3.14"><tt>sane_strstatus</tt></a></td></tr>
|
||||
<tr><td></td><td colspan=20>4.4<tt> </tt><a href="doc013.html#s4.4">Code Flow</a></td></tr>
|
||||
<tr><td></td><td colspan=20>4.5<tt> </tt><a href="doc014.html#s4.5">Well-Known Options</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.1<tt> </tt><a href="doc014.html#s4.5.1">Option Number Count</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.2<tt> </tt><a href="doc014.html#s4.5.2">Scan Resolution Options</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.3<tt> </tt><a href="doc014.html#s4.5.3">Preview Mode Option</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.4<tt> </tt><a href="doc014.html#s4.5.4">Scan Area Options</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.5<tt> </tt><a href="doc014.html#s4.5.5">Depth Option</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.6<tt> </tt><a href="doc014.html#s4.5.6">Scan Mode Options</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.7<tt> </tt><a href="doc014.html#s4.5.7">Scan Source Options</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.8<tt> </tt><a href="doc014.html#s4.5.8">Threshold Option</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.9<tt> </tt><a href="doc014.html#s4.5.9">Gamma Table Options</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.10<tt> </tt><a href="doc014.html#s4.5.10">Analog Gamma</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.11<tt> </tt><a href="doc014.html#s4.5.11">Shadow Option</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.12<tt> </tt><a href="doc014.html#s4.5.12">Highlight Option</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.13<tt> </tt><a href="doc014.html#s4.5.13">Lamp Options</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.14<tt> </tt><a href="doc014.html#s4.5.14">Scanner Button Options</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>4.5.15<tt> </tt><a href="doc014.html#s4.5.15">Batch Scan Options</a></td></tr>
|
||||
<tr></tr><tr><td colspan=20>5<tt> </tt><a href="doc015.html#s5"><b>Network Protocol</b></a></td></tr>
|
||||
<tr><td></td><td colspan=20>5.1<tt> </tt><a href="doc016.html#s5.1">Data Type Encoding</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.1.1<tt> </tt><a href="doc016.html#s5.1.1">Primitive Data Types</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.1.2<tt> </tt><a href="doc016.html#s5.1.2">Type Constructors</a></td></tr>
|
||||
<tr><td></td><td colspan=20>5.2<tt> </tt><a href="doc017.html#s5.2">Remote Procedure Call Requests</a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.1<tt> </tt><a href="doc017.html#s5.2.1"><tt>SANE_NET_INIT<a name="i151"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.2<tt> </tt><a href="doc017.html#s5.2.2"><tt>SANE_NET_GET_DEVICES<a name="i153"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.3<tt> </tt><a href="doc017.html#s5.2.3"><tt>SANE_NET_OPEN<a name="i155"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.4<tt> </tt><a href="doc017.html#s5.2.4"><tt>SANE_NET_CLOSE<a name="i157"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.5<tt> </tt><a href="doc017.html#s5.2.5"><tt>SANE_NET_GET_OPTION_DESCRIPTORS<a name="i159"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.6<tt> </tt><a href="doc017.html#s5.2.6"><tt>SANE_NET_CONTROL_OPTION<a name="i162"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.7<tt> </tt><a href="doc017.html#s5.2.7"><tt>SANE_NET_GET_PARAMETERS<a name="i164"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.8<tt> </tt><a href="doc017.html#s5.2.8"><tt>SANE_NET_START<a name="i166"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.9<tt> </tt><a href="doc017.html#s5.2.9"><tt>SANE_NET_CANCEL<a name="i168"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.10<tt> </tt><a href="doc017.html#s5.2.10"><tt>SANE_NET_AUTHORIZE<a name="i170"></tt></a></td></tr>
|
||||
<tr><td></td><td></td><td colspan=20>5.2.11<tt> </tt><a href="doc017.html#s5.2.11"><tt>SANE_NET_EXIT<a name="i173"></tt></a></td></tr>
|
||||
<tr></tr><tr><td colspan=20>6<tt> </tt><a href="doc018.html#s6"><b>Contact Information</b></a></td></tr>
|
||||
</table>
|
||||
|
||||
<h1>List of Figures</h1>
|
||||
|
||||
<table>
|
||||
<tr><td>1</td><td><a href="doc007.html#f1">Example SANE Hiearchy</a></td></tr>
|
||||
<tr><td>2</td><td><a href="doc008.html#f2">Transfer order of image data bytes</a></td></tr>
|
||||
<tr><td>3</td><td><a href="doc008.html#f3">Bit and byte order of image data</a></td></tr>
|
||||
<tr><td>4</td><td><a href="doc013.html#f4">Code flow</a></td></tr>
|
||||
<tr><td>5</td><td><a href="doc014.html#f5">Scan area options</a></td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
<h1>List of Tables</h1>
|
||||
|
||||
<table>
|
||||
<tr><td>1</td><td><a href="doc011.html#f1">Status Codes</a></td></tr>
|
||||
<tr><td>2</td><td><a href="doc011.html#f2">Predefined Device Information Strings</a></td></tr>
|
||||
<tr><td>3</td><td><a href="doc011.html#f3">Option Value Types (<tt>SANE_Value_Type</tt>)</a></td></tr>
|
||||
<tr><td>4</td><td><a href="doc011.html#f4">Physical Units (<tt>SANE_Unit</tt>)</a></td></tr>
|
||||
<tr><td>5</td><td><a href="doc011.html#f5">Option Capabilities</a></td></tr>
|
||||
<tr><td>6</td><td><a href="doc011.html#f6">Option Value Constraints</a></td></tr>
|
||||
<tr><td>7</td><td><a href="doc012.html#f7">Action Values (<tt>SANE_Action</tt>)</a></td></tr>
|
||||
<tr><td>8</td><td><a href="doc012.html#f8">Additional Information Returned When Setting an Option</a></td></tr>
|
||||
<tr><td>9</td><td><a href="doc012.html#f9">Frame Format (<tt>SANE_Frame</tt>)</a></td></tr>
|
||||
</table>
|
||||
|
||||
<p><hr>
|
||||
<a href="doc001.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<img src=../icons/up_gr.gif border=2 alt="Previous"></a>
|
||||
<img src=../icons/previous_gr.gif border=2 alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
<html><body>
|
||||
<a href="doc002.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc000.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
<title>./sane</title>
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
<p>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
<p><center><h1><font size=+4>SANE Standard Version 2.0 proposal 0.08 - rauch/beck</font></h1></center>
|
||||
<center></center>
|
||||
<center>Dec 8, 2002</center>
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
<p><h1><a href="doc002.html">1 Preface</a></h1><h1><a href="doc004.html">2 Introduction</a></h1><h1><a href="doc006.html">3 The SANE Environment</a></h1><h1><a href="doc009.html">4 The SANE Application Programmer Interface (API)</a></h1><h1><a href="doc015.html">5 Network Protocol</a></h1><h1><a href="doc018.html">6 Contact Information</a></h1><p><hr>
|
||||
<a href="doc002.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc000.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
<html><body>
|
||||
<a href="doc003.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc001.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Preface</title>
|
||||
<h1><a name="s1">1 Preface</a></h1>
|
||||
|
||||
<p>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
|
||||
<a href="doc018.html#s6">6</a>.
|
||||
|
||||
<p>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.
|
||||
|
||||
<p><h2><a href="doc003.html">1.1 About This Document</a></h2><p><hr>
|
||||
<a href="doc003.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc001.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
<html><body>
|
||||
<a href="doc004.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc002.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>About This Document</title>
|
||||
<h2><a name="s1.1">1.1 About This Document</a></h2>
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>The remainder of this document is organized as follows.
|
||||
Chapter <a href="doc004.html#s2">2</a> provides introductional material.
|
||||
Chapter <a href="doc006.html#s3">3</a> presents the environment SANE is designed
|
||||
for. Chapter <a href="doc009.html#s4">4</a> details the SANE Application Programmer
|
||||
Interface. Chapter <a href="doc015.html#s5">5</a> specifies the network protocol that
|
||||
can be used to implement the SANE API in a network transparent
|
||||
fashion. Finally, Chapter <a href="doc018.html#s6">6</a> gives information on how
|
||||
to join the SANE development process.
|
||||
|
||||
<p><h3><a name="s1.1.1">1.1.1 Typographic Conventions</a></h3>
|
||||
|
||||
<p>Changes since the last revision of this document are highlighted
|
||||
like this:
|
||||
|
||||
<p><font color="darkgreen">
|
||||
Paragraphs that changed since the last revision of the documention
|
||||
are marked like this paragraph.
|
||||
</font>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc004.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc002.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
<html><body>
|
||||
<a href="doc005.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc003.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Introduction</title>
|
||||
<h1><a name="s2">2 Introduction</a></h1>
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>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.
|
||||
|
||||
<p><h2><a href="doc005.html">2.1 Terminology</a></h2><p><hr>
|
||||
<a href="doc005.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc003.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
<html><body>
|
||||
<a href="doc006.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc004.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Terminology</title>
|
||||
<h2><a name="s2.1">2.1 Terminology</a></h2>
|
||||
|
||||
<p>An application that uses the SANE interface is called a SANE <em>
|
||||
frontend</em>. A driver that implements the SANE interface is called a
|
||||
SANE <em>backend</em>. A <em>meta backend</em> provides some means to
|
||||
manage one or more other backends.
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc006.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc004.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
<html><body>
|
||||
<a href="doc007.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc005.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>The SANE Environment</title>
|
||||
<h1><a name="s3">3 The SANE Environment</a></h1>
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>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</em>. An option is
|
||||
a self-describing name/value pair. For example, the brightness
|
||||
control of a camera might be represented by an option called
|
||||
<tt>brightness</tt> whose value is an integer in the range from 0 to
|
||||
255.
|
||||
|
||||
<p>With self-describing options, a backend need not be concerned with
|
||||
<em>presentation</em> 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</em> of each option. It simply provides
|
||||
means to present and alter the options defined by the backend.
|
||||
|
||||
<p><h2><a href="doc007.html">3.1 Attaching to a SANE backend</a></h2><h2><a href="doc008.html">3.2 Image Data Format</a></h2><p><hr>
|
||||
<a href="doc007.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc005.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,104 @@
|
|||
<html><body>
|
||||
<a href="doc008.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc006.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Attaching to a SANE backend</title>
|
||||
<h2><a name="s3.1">3.1 Attaching to a SANE backend</a></h2>
|
||||
|
||||
<p>The process through which a SANE frontend connects to a backend is
|
||||
platform dependent. Several possibilities exist:
|
||||
<ul>
|
||||
|
||||
<p><li><b>Static linking:</b> 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 <tt>be</tt>
|
||||
would normally export a function called <tt>sane_read()</tt>. 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 <tt>be</tt> include a
|
||||
header file that has lines of the form:
|
||||
<blockquote>
|
||||
<pre>
|
||||
#define sane_read be_sane_read
|
||||
</pre>
|
||||
</blockquote>
|
||||
With definitions of this kind, backend <tt>be</tt> will export
|
||||
function name <tt>be_sane_read()</tt>. 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.
|
||||
|
||||
<p><li><b>Dynamic linking:</b> 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 <tt>sane_</tt>), 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.
|
||||
|
||||
<p> More importantly, dynamic linking makes it easy to implement a meta
|
||||
backend that loads other backends <em>on demand</em>. This is a
|
||||
powerful mechanism since it allows adding new backends merely by
|
||||
installing a shared library and updating a configuration file.
|
||||
|
||||
<p><li><b>Network connection:</b> 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.
|
||||
|
||||
<p></ul>
|
||||
|
||||
<p><p><a name="f1"></a>
|
||||
<center>
|
||||
|
||||
<img width=780 height=384 src="img000.gif">
|
||||
<p><center>Figure 1: Example SANE Hiearchy</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>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 <a href="doc007.html#f1">1</a>. The figure shows that machine
|
||||
A uses a dynamic-linking based meta backend called <tt>dll</tt> to
|
||||
access the backends called <tt>pnm</tt>, <tt>mustek</tt>, and <tt>net</tt>.
|
||||
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 <tt>saned</tt>. The <tt>saned</tt> in
|
||||
turn has access to the <tt>hp</tt> and <tt>autolum</tt> backends through
|
||||
another instance of the <tt>dll</tt> backend. The <tt>autolum</tt> meta
|
||||
backend is used to automatically adjust the luminance (brightness) of
|
||||
the image data acquired by the camera backend called <tt>qcam</tt>.
|
||||
|
||||
<p>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.
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc008.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc006.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,155 @@
|
|||
<html><body>
|
||||
<a href="doc009.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc007.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Image Data Format</title>
|
||||
<h2><a name="s3.2">3.2 Image Data Format</a></h2><a name="i0">
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>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
|
||||
(preferable quadratic) pixel. A pixel consists of one or more sample values.
|
||||
Each sample value represents one channel (e.g., the red channel).
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>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 and a format
|
||||
descriptor.
|
||||
|
||||
<p><font color="darkgreen">
|
||||
There are two different types of frames: pixel oriented frames
|
||||
<tt>SANE_FRAME_RAW<a name="i1"></tt> and arbitrary data frames
|
||||
<tt>SANE_FRAME_MIME<a name="i2"></tt>. These types are discussed in detail in the
|
||||
following sections. The frame types used by the previous version 1 of this
|
||||
standard (<tt>SANE_FRAME_GRAY<a name="i3"></tt>, <tt>SANE_FRAME_RGB<a name="i4"></tt>,
|
||||
<tt>SANE_FRAME_RED<a name="i5"></tt>, <tt>SANE_FRAME_GREEN<a name="i6"></tt>, and
|
||||
<tt>SANE_FRAME_BLUE<a name="i7"></tt>) are obsolete and superseded by
|
||||
<tt>SANE_FRAME_RAW<a name="i8"></tt>.
|
||||
|
||||
<p> <h3><a name="s3.2.1">3.2.1 Pixel oriented frames</a></h3>
|
||||
|
||||
<p> The type of pixel oriented frames is <tt>SANE_FRAME_RAW<a name="i9"></tt>. The
|
||||
frame contains one or more channels of data in a channel-interleaved format,
|
||||
that represents sample values from a property of the individual pixels that
|
||||
is subject to further description in the <tt>format_desc</tt> member of the
|
||||
<tt>SANE_Parameters</tt> structured type. See section <a href="doc012.html#s4.3.8">4.3.8</a>
|
||||
on page <a href="doc012.html#s4.3.8">4.3.8</a> for details about the format
|
||||
descriptions.
|
||||
</font>
|
||||
|
||||
<p> 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).
|
||||
|
||||
<p><font color="darkgreen">
|
||||
The complete image may consist of several different channels. The number of channels
|
||||
is defined by member <tt>channels_per_image</tt> of <tt>SANE_Parameters</tt>.
|
||||
The image may be transmitted in an arbitrary number of frames which can be
|
||||
determined by watching the <tt>SANE_PFLAG_LAST_FRAME</tt> flag in said type (or by
|
||||
counting the channels). Note: This frame type replaces all frame types of
|
||||
the SANE standard version 1.
|
||||
</font>
|
||||
|
||||
<p>Conceptually, each pixel oriented 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.
|
||||
<blockquote>
|
||||
<center>
|
||||
<b>Backend Implementation Note</b>
|
||||
</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.
|
||||
</blockquote>
|
||||
|
||||
<p><p><a name="f2"></a>
|
||||
<center>
|
||||
|
||||
<img width=390 height=196 src="img001.gif">
|
||||
<p><center>Figure 2: Transfer order of image data bytes</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>The order in which the sample values in a frame are transmitted is illustrated
|
||||
in Figure <a href="doc008.html#f2">2</a>. 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).
|
||||
|
||||
<p>If a frame contains multiple channels, then the channels are transmitted in an
|
||||
interleaved fashion. Figure <a href="doc008.html#f3">3</a> illustrates this for the case
|
||||
where a frame contains a complete red/green/blue image with a bit-depth of 8.
|
||||
|
||||
<p><p><a name="f3"></a>
|
||||
<center>
|
||||
|
||||
<img width=624 height=111 src="img002.gif">
|
||||
<p><center>Figure 3: Bit and byte order of image data</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>For a bit depth of 1, each byte contains 8 sample values of a <em>single</em>
|
||||
channel. In other words, a bit depth 1 frame is transmitted in a byte
|
||||
interleaved fashion. The first sample of each byte is represented by the most
|
||||
significant bit.
|
||||
|
||||
<p><font color="darkgreen">
|
||||
For gray channels at a bit depth of 1 only two sample values are possible: 1
|
||||
represents minimum intensity (black) and 0 represents maximum intensity
|
||||
(white). For all other channel types and bit depths a sample value of 0
|
||||
represents minimum intensity and larger values represent increasing intensity.
|
||||
|
||||
<p><h3><a name="s3.2.2">3.2.2 Arbitrary data frames</a></h3>
|
||||
|
||||
<p>It also is possible to transmit arbitrary (not necessaryly pixel oriented)
|
||||
data. This allows transmission of compressed images like jpeg, tiff, etc.
|
||||
|
||||
<p>The type of arbitrary data frames is <tt>SANE_FRAME_MIME<a name="i10"></tt>.
|
||||
The frame contains arbitrary data of the MIME (see RFC 1521/1522) type that is
|
||||
given in the <tt>format_desc</tt> member of the <tt>SANE_Parameters</tt>
|
||||
structured type (see section <a href="doc012.html#s4.3.8">4.3.8</a> on
|
||||
page <a href="doc012.html#s4.3.8">4.3.8</a>). As such, it is assumed to be
|
||||
incomprehensible to the frontend, except for selected types the frontend is
|
||||
specifically capable of handling internally. The frontend is free to ignore
|
||||
those frames, or employ any appropriate means to otherwise handle this data
|
||||
(like saving them to disk or spawning an external viewer).
|
||||
</font>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc009.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc007.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
<html><body>
|
||||
<a href="doc010.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc008.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>The SANE Application Programmer Interface (API)</title>
|
||||
<h1><a name="s4">4 The SANE Application Programmer Interface (API)</a></h1>
|
||||
|
||||
<p><font color="darkgreen">
|
||||
This Section defines version 2 of the SANE application
|
||||
programmer interface (API). Any SANE frontend must depend on the
|
||||
interface defined in this section only. 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 <tt>sane/sane-2.h</tt>. This file should
|
||||
normally be included via a C pre-processor directive of the form:
|
||||
<pre>
|
||||
#include <sane/sane-2.h>
|
||||
</pre>
|
||||
</font>
|
||||
|
||||
<p><h2><a href="doc010.html">4.1 Version Control</a></h2><h2><a href="doc011.html">4.2 Data Types</a></h2><h2><a href="doc012.html">4.3 Operations</a></h2><h2><a href="doc013.html">4.4 Code Flow</a></h2><h2><a href="doc014.html">4.5 Well-Known Options</a></h2><p><hr>
|
||||
<a href="doc010.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc008.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,77 @@
|
|||
<html><body>
|
||||
<a href="doc011.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc009.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Version Control</title>
|
||||
<h2><a name="s4.1">4.1 Version Control</a></h2>
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>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.
|
||||
|
||||
<p>The SANE API provides the following five macros to manage version
|
||||
numbers.
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_CURRENT_MAJOR<a name="i11"></tt>:<dd> The value of this macro is the
|
||||
number of the SANE standard that the interface implements.
|
||||
|
||||
<p> <dt><tt>SANE_VERSION_CODE<a name="i12">(<i>maj</i>,<i>min</i>,<i>bld</i>)</tt>:<dd>
|
||||
|
||||
This macro can be used to build a monotonically increasing version
|
||||
code. A SANE version code consists of the SANE standard major
|
||||
version number (<i>maj</i>), the minor version number <i>min</i>,
|
||||
and the build revision of a backend (<i>bld</i>). The major and
|
||||
minor version numbers must be in the range 0...255 and the
|
||||
build revision must be in the range 0...65535.
|
||||
|
||||
<p> 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.
|
||||
|
||||
<p> 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.
|
||||
|
||||
<dt><tt>SANE_VERSION_MAJOR<a name="i13">(<i>vc</i>)</tt>:<dd> This macro returns the
|
||||
major version number component of the version code passed in
|
||||
argument <i>vc</i>.
|
||||
<dt><tt>SANE_VERSION_MINOR(<i>vc</i>)</tt>:<dd> This macro returns the
|
||||
minor version number component of the version code passed in
|
||||
argument <i>vc</i>.
|
||||
<dt><tt>SANE_VERSION_BUILD(<i>vc</i>)</tt>:<dd> This macro returns the
|
||||
build revision component of the version code passed in argument
|
||||
<i>vc</i>.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc011.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc009.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
Plik diff jest za duży
Load Diff
|
|
@ -0,0 +1,871 @@
|
|||
<html><body>
|
||||
<a href="doc013.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc011.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Operations</title>
|
||||
<h2><a name="s4.3">4.3 Operations</a></h2>
|
||||
|
||||
<p><h3><a name="s4.3.1">4.3.1 <tt>sane_init</tt></a></h3>
|
||||
|
||||
<p>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 <tt>sane_init</tt> is different from
|
||||
<tt>SANE_STATUS_GOOD<a name="i79"></tt>. The version code of the backend is returned
|
||||
in the value pointed to by <tt>version_code</tt>. If that pointer is
|
||||
<tt>NULL</tt>, no version code is returned. Argument <tt>authorize</tt> is either
|
||||
a pointer to a function that is invoked when the backend requires
|
||||
authentication for a specific resource or <tt>NULL</tt> if the frontend does not
|
||||
support authentication.
|
||||
<blockquote><a name="i80">
|
||||
<pre>
|
||||
SANE_Status sane_init (SANE_Int * version_code,
|
||||
SANE_Authorization_Callback authorize);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>The authorization function may be called by a backend in response to
|
||||
any of the following calls:
|
||||
<blockquote>
|
||||
<tt>sane_open</tt>, <tt>sane_control_option</tt>, <tt>sane_start</tt>
|
||||
</blockquote>
|
||||
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.
|
||||
|
||||
<p>The authentication function type has the following declaration:
|
||||
<blockquote><a name="i81">
|
||||
<a name="i82"><a name="i83"><a name="i84">
|
||||
<pre>
|
||||
#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]);
|
||||
</pre>
|
||||
</blockquote>
|
||||
Three arguments are passed to the authorization function:
|
||||
<tt>resource</tt> 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 <tt>username</tt>
|
||||
and <tt>password</tt> arguments are (pointers to) an array of
|
||||
<tt>SANE_MAX_USERNAME_LEN</tt> and <tt>SANE_MAX_PASSWORD_LEN</tt>
|
||||
characters, respectively. The authorization call should place the
|
||||
entered username and password in these arrays. The returned strings
|
||||
<em>must</em> be ASCII-NUL terminated.
|
||||
|
||||
<p><h3><a name="s4.3.2">4.3.2 <tt>sane_exit</tt></a></h3>
|
||||
|
||||
<p>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 <tt>sane_close()</tt>, but backends are required to release all
|
||||
resources upon a call to this function). After this function returns,
|
||||
no function other than <tt>sane_init()</tt> may be called (regardless
|
||||
of the status value returned by <tt>sane_exit()</tt>. Neglecting to
|
||||
call this function may result in some resources not being released
|
||||
properly.
|
||||
<blockquote><a name="i85">
|
||||
<pre>
|
||||
void sane_exit (void);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.3">4.3.3 <tt>sane_get_devices</tt></a></h3>
|
||||
|
||||
<p>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 <tt>NULL</tt> terminated array of pointers to <tt>SANE_Device</tt>
|
||||
structures in <tt>*device_list</tt>. The returned list is guaranteed
|
||||
to remain unchanged and valid until (a) another call to this function
|
||||
is performed or (b) a call to <tt>sane_exit()</tt> is performed. This
|
||||
function can be called repeatedly to detect when new devices become
|
||||
available. If argument <tt>local_only</tt> 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.
|
||||
<blockquote><a name="i86">
|
||||
<pre>
|
||||
SANE_Status sane_get_devices (const SANE_Device *** device_list,
|
||||
SANE_Bool local_only);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>This function may fail with <tt>SANE_STATUS_NO_MEM</tt> if an
|
||||
insufficient amount of memory is available.
|
||||
|
||||
<p><blockquote>
|
||||
<center>
|
||||
<b>Backend Implementation Note</b>
|
||||
</center>
|
||||
SANE does not require that this function is called before a
|
||||
<tt>sane_open()</tt> 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.
|
||||
<font color="darkgreen">
|
||||
The same information about
|
||||
a device has to be returned when <tt>sane_open</tt> is called.
|
||||
</font>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.4">4.3.4 <tt>sane_open</tt></a></h3>
|
||||
|
||||
<p>This function is used to establish a connection to a particular
|
||||
device. The name of the device to be opened is passed in argument
|
||||
<tt>name</tt>. If the call completes successfully, a handle for the
|
||||
device is returned in <tt>*h</tt>.
|
||||
<font color="darkgreen">
|
||||
The description of the device
|
||||
is returned in <tt>**device_description</tt>. This is the
|
||||
same description that is returned in the list by <tt>sane_get_devices</tt>.
|
||||
The returned data <tt>*h</tt> and <tt>*device_description</tt> is guaranteed
|
||||
to remain unchanged and valid until a call to <tt>sane_close()</tt>
|
||||
is performed.
|
||||
</font>
|
||||
As a special case, specifying a zero-length string as the device requests
|
||||
opening the first available device (if there is such a device).
|
||||
<blockquote><a name="i87">
|
||||
<pre>
|
||||
SANE_Status sane_open (SANE_String_Const name, SANE_Handle * h,
|
||||
const SANE_Device ** device_description);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>This function may fail with one of the following status codes.
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_DEVICE_BUSY</tt>:<dd> The device is currently
|
||||
busy (in use by somebody else).
|
||||
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> The device name is not valid.
|
||||
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occured while
|
||||
communicating with the device.
|
||||
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
||||
is available.
|
||||
<dt><tt>SANE_STATUS_ACCESS_DENIED</tt>:<dd> Access to the device has
|
||||
been denied due to insufficient or invalid authentication.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.5">4.3.5 <tt>sane_close</tt></a></h3>
|
||||
|
||||
<p>This function terminates the association between the device handle
|
||||
passed in argument <tt>h</tt> and the device it represents. If the
|
||||
device is presently active, a call to <tt>sane_cancel()</tt> is
|
||||
performed first. After this function returns, handle <tt>h</tt> must
|
||||
not be used anymore.
|
||||
|
||||
<p><blockquote><a name="i88">
|
||||
<pre>
|
||||
void sane_close (SANE_Handle h);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.6">4.3.6 <tt>sane_get_option_descriptor</tt></a></h3>
|
||||
|
||||
<p>This function is used to access option descriptors. The function
|
||||
returns the option descriptor for option number <tt>n</tt> of the device
|
||||
represented by handle <tt>h</tt>. 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 <tt>h</tt> (the count
|
||||
includes option 0). If n is not a valid option index, the function
|
||||
returns <tt>NULL</tt>. The returned option descriptor is guaranteed to
|
||||
remain valid (and at the returned address) until the device is closed.
|
||||
|
||||
<p><blockquote><a name="i89">
|
||||
<pre>
|
||||
const SANE_Option_Descriptor *
|
||||
sane_get_option_descriptor (SANE_Handle h, SANE_Int n);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.7">4.3.7 <tt>sane_control_option</tt></a></h3>
|
||||
|
||||
<p>This function is used to set or inquire the current value of option
|
||||
number <tt>n</tt> of the device represented by handle <tt>h</tt>. The
|
||||
manner in which the option is controlled is specified by parameter
|
||||
<tt>a</tt>. The possible values of this parameter are described in more
|
||||
detail below. The value of the option is passed through argument
|
||||
<tt>v</tt>. It is a pointer to the memory that holds the option value.
|
||||
The memory area pointed to by <tt>v</tt> must be big enough to hold the
|
||||
entire option value (determined by member <tt>size</tt> 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 <tt>v</tt> may be shorter since the backend will stop
|
||||
reading the option value upon encountering the first <tt>NUL</tt>
|
||||
terminator in the string. If argument <tt>i</tt> is not <tt>NULL</tt>,
|
||||
the value of <tt>*i</tt> 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.
|
||||
<blockquote><a name="i90">
|
||||
<pre>
|
||||
SANE_Status sane_control_option (SANE_Handle h, SANE_Int n,
|
||||
SANE_Action a, void *v,
|
||||
SANE_Int * i);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>The way the option is affected by a call to this function is
|
||||
controlled by parameter <tt>a</tt> which is a value of type
|
||||
<tt>SANE_Action<a name="i91"></tt>. The possible values and their meaning is
|
||||
described in Table <a href="doc012.html#t7">7</a>.
|
||||
|
||||
<p><p><a name="t7"></a>
|
||||
<center>
|
||||
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Code</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
|
||||
<p><tt>SANE_ACTION_GET_VALUE<a name="i92"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 0 </td>
|
||||
<td colspan=1 align=left> Get current option value. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_ACTION_SET_VALUE<a name="i93"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 1 </td>
|
||||
<td colspan=1 align=left> Set option value. The
|
||||
option value passed through argument <tt>v</tt> may be modified by the
|
||||
backend if the value cannot be set exactly. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_ACTION_SET_AUTO<a name="i94"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 2 </td>
|
||||
<td colspan=1 align=left> 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 <tt>v</tt> is completely ignored in this case and
|
||||
may be <tt>NULL</tt>. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
</td></tr>
|
||||
</table>
|
||||
<p><center>Table 7: Action Values (<tt>SANE_Action</tt>)</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>After setting a value via an action value of
|
||||
<tt>SANE_ACTION_SET_VALUE</tt>, additional information on how well the
|
||||
request has been met is returned in <tt>*i</tt> (if <tt>i</tt> is
|
||||
non-<tt>NULL</tt>). The returned value is a bitset that may contain any
|
||||
combination of the values described in Table <a href="doc012.html#t8">8</a>.
|
||||
<p><a name="t8"></a>
|
||||
<center>
|
||||
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Code</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
|
||||
<p><tt>SANE_INFO_INEXACT<a name="i95"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 1 </td>
|
||||
<td colspan=1 align=left> 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 <tt>*i</tt> 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. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_INFO_RELOAD_OPTIONS<a name="i96"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 2 </td>
|
||||
<td colspan=1 align=left>
|
||||
The setting of an option may affect the
|
||||
<font color="darkgreen">
|
||||
value, the availability, or the constraint of one or more <em>
|
||||
other</em> options.
|
||||
</font>
|
||||
When this happens, the SANE backend sets this
|
||||
member in <tt>*i</tt> to indicate that the application should reload
|
||||
all options. This member may be set if and only if at least one
|
||||
option changed. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_INFO_RELOAD_PARAMS<a name="i97"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 4 </td>
|
||||
<td colspan=1 align=left>
|
||||
The setting of an option may affect the parameter values (see
|
||||
<tt>sane_get_parameters()</tt>).
|
||||
If setting an option affects the parameter values, this member will
|
||||
be set in <tt>*i</tt>. 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.
|
||||
</td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p><tt>SANE_INFO_INVALIDATE_PREVIEW<a name="i98"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 8 </td>
|
||||
<td colspan=1 align=left>
|
||||
The setting of an option may affect the validity of the preview that
|
||||
was acquired by the frontend earlier. When the preview image would change
|
||||
significantly if it was scanned again, the SANE backend
|
||||
sets this member in <tt>*i</tt> to indicate that the application should inform the
|
||||
user of the invalidity of the preview. Examples for such option
|
||||
settings may include setting a different scan source or significantly
|
||||
changing the exposure.
|
||||
</td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
</td></tr>
|
||||
</table>
|
||||
<p><center>Table 8: Additional Information Returned When Setting an Option</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>This function may fail with one of the following status codes.
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_UNSUPPORTED</tt>:<dd> The operation is not
|
||||
supported for the specified handle and option number.
|
||||
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> The option value is not valid.
|
||||
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occured while
|
||||
communicating with the device.
|
||||
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
||||
is available.
|
||||
<dt><tt>SANE_STATUS_ACCESS_DENIED</tt>:<dd> Access to the option has
|
||||
been denied due to insufficient or invalid authentication.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.8">4.3.8 <tt>sane_get_parameters</tt></a></h3>
|
||||
|
||||
<p>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 (<tt>sane_start()</tt> 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
|
||||
<tt>sane_start()</tt> 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 <tt>h</tt> of the device for which the
|
||||
parameters should be obtained and a pointer <tt>p</tt> to a parameter
|
||||
structure. The parameter structure is described in more detail below.
|
||||
|
||||
<p><blockquote><a name="i99">
|
||||
<pre>
|
||||
SANE_Status sane_get_parameters (SANE_Handle h,
|
||||
SANE_Parameters * p);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>The scan parameters are returned in a structure of type
|
||||
<tt>SANE_Parameters<a name="i100"></tt>. The C declaration of this structure
|
||||
is given below.
|
||||
<font color="darkgreen">
|
||||
<blockquote>
|
||||
<pre>
|
||||
typedef struct
|
||||
{
|
||||
SANE_Frame format;
|
||||
SANE_Int flags;
|
||||
SANE_Int lines;
|
||||
SANE_Int depth;
|
||||
SANE_Int pixels_per_line;
|
||||
SANE_Int bytes_per_line;
|
||||
SANE_Int channels_per_image;
|
||||
SANE_String format_desc;
|
||||
SANE_String proposed_filename;
|
||||
SANE_String proposed_comment;
|
||||
SANE_Int dpi_x;
|
||||
SANE_Int dpi_y;
|
||||
char reserved[32]; /* 32 bytes for future use */
|
||||
}
|
||||
SANE_Parameters;
|
||||
</pre>
|
||||
</blockquote>
|
||||
</font>
|
||||
|
||||
<p><font color="darkgreen">
|
||||
Member <tt>format</tt> specifies the format of the next frame to be
|
||||
returned. The possible values for type <tt>SANE_Frame<a name="i101"></tt> are
|
||||
described in Table <a href="doc012.html#t9">9</a>. The meaning of these
|
||||
values is described in more detail in section <a href="doc008.html#s3.2">3.2</a>.
|
||||
The frame types used by version 1 of this standard
|
||||
(<tt>SANE_FRAME_GRAY<a name="i102"></tt>, <tt>SANE_FRAME_RGB<a name="i103"></tt>,
|
||||
<tt>SANE_FRAME_RED<a name="i104"></tt>, <tt>SANE_FRAME_GREEN<a name="i105"></tt>, and
|
||||
<tt>SANE_FRAME_BLUE<a name="i106"></tt>) are obsolete and superseded by the
|
||||
frame type <tt>SANE_FRAME_RAW<a name="i107"></tt>.
|
||||
|
||||
<p><p><a name="t9"></a>
|
||||
<center>
|
||||
|
||||
<table cellpadding=0 cellspacing=0 border=1>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Code</b></td>
|
||||
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
|
||||
<p><tt>SANE_FRAME_RAW<a name="i108"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 5 </td>
|
||||
<td colspan=1 align=left nowrap> Arbitrary pixel property transmission. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_FRAME_MIME<a name="i109"></tt> </td>
|
||||
<td colspan=1 align=right nowrap> 6 </td>
|
||||
<td colspan=1 align=left nowrap> Data described by a mime descriptor. </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
|
||||
<p>
|
||||
</td></tr>
|
||||
</table>
|
||||
<p><center>Table 9: Frame Format (<tt>SANE_Frame</tt>)</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>The <tt>flags</tt> member is a 32 bit bitfield, for which up to now 4
|
||||
informational bits are defined, all unused bits have to be set to 0:
|
||||
|
||||
<p><ul>
|
||||
|
||||
<p><li>
|
||||
<tt>SANE_PFLAG_LAST_FRAME</tt> (bit 0, bitvalue 1) is set to 1 if and
|
||||
only if the frame that is currently being acquired (or the frame that
|
||||
will be acquired next if there is no current frame) is the only frame
|
||||
or the last frame
|
||||
of a multi frame image (e.g., the current frame is the blue component
|
||||
of a red, green, blue image).
|
||||
|
||||
<p><li>
|
||||
<tt>SANE_PFLAG_MORE_IMAGES</tt> (bit 1, bitvalue 2) is set to 1 to indicate
|
||||
further pending images. The frontend is expected to call <tt>sane_start</tt>
|
||||
again after the end of the current scan to get more images, e.g.
|
||||
from an automatic document feeder. It is permissible to set that value to 1 ``in good
|
||||
faith'', as it has to be determined at a very early time, where it might
|
||||
not be detectable, if there actually are more images to transfer. E.g.
|
||||
you will usually not know if the document feeder contains further pages
|
||||
when starting to scan the current one. Thus you are allowed to set that
|
||||
bit but later fail at <tt>sane_start()</tt>.
|
||||
|
||||
<p><li>
|
||||
<tt>SANE_PFLAG_NEW_PAGE</tt> (bit 2, bitvalue 4) is set to 1 to indicate
|
||||
that the current frame comes from a new physical page. This bit is of
|
||||
informational character only to help frontends to group multi-image
|
||||
scans.
|
||||
|
||||
<p><li>
|
||||
<tt>SANE_PFLAG_BACKSIDE</tt> (bit 3, bitvalue 8) tells if the current image
|
||||
was acquired from the front (0) or backside (1) of the currently processed
|
||||
sheet. It is of informational character and allows to group and order
|
||||
multi-image transfers regardless of scanner acquisition order (front
|
||||
first/back first).
|
||||
|
||||
<p></ul>
|
||||
|
||||
<p>Note, that <tt>flags</tt> is compatible to member <tt>last_frame</tt> of
|
||||
<tt>SANE_Parameters</tt> of SANE standard version 1 (same size
|
||||
and only bit 0 (bitvalue 1) was used with same function).
|
||||
</font>
|
||||
|
||||
<p>Member <tt>lines</tt> 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 <tt>sane_read()</tt> until it
|
||||
returns a status of <tt>SANE_STATUS_EOF</tt>.
|
||||
<font color="darkgreen">
|
||||
Note, that even when transferring formats that have this information
|
||||
inband, it is recommended to set that member, if available. If
|
||||
unavailable or not applicable, set to -1 as mentioned above.
|
||||
</font>
|
||||
|
||||
<p>Member <tt>bytes_per_line</tt> specifies the number of bytes that comprise one
|
||||
scan line.
|
||||
<font color="darkgreen">
|
||||
If this value is not applicable for image data of type
|
||||
<tt>SANE_FRAME_MIME</tt>, it must be set to -1. In this case the frontend
|
||||
should just call <tt>sane_read</tt> until <tt>SANE_STATUS_EOF</tt> is returned.
|
||||
</font>
|
||||
|
||||
<p>Member <tt>depth</tt> specifies the number of bits per sample.
|
||||
<font color="darkgreen">
|
||||
Note, that only -1 (for not applicable), 1, and multiples of 8 are
|
||||
allowed values. Data with other depths has to be scaled up accordingly.
|
||||
Depth 1 is only allowed if the image consists of a single channel (lineart or
|
||||
halftone modes).
|
||||
</font>
|
||||
|
||||
<p>Member <tt>pixels_per_line</tt> specifies the number of pixels that
|
||||
comprise one scan line.
|
||||
<font color="darkgreen">
|
||||
If unavailable or not applicable, set to -1.
|
||||
</font>
|
||||
|
||||
<p>Assume B is the number of channels in the frame, then the bit depth
|
||||
d (as given by member <tt>depth</tt>) and the number of pixels per
|
||||
line n (as given by this member <tt>pixels_per_line</tt>) are
|
||||
related to c, the number of bytes per line (as given by member
|
||||
<tt>bytes_per_line</tt>) as follows:
|
||||
<font color="darkgreen">
|
||||
|
||||
<p>
|
||||
<center>
|
||||
|
||||
c >= \left{
|
||||
ll
|
||||
\lceil B*n / 8\rceil if d=1
|
||||
</td><td align=right>(1)</td></tr><tr><td align=center>
|
||||
|
||||
B*n *d / 8 if d>1
|
||||
|
||||
\right.
|
||||
</center>
|
||||
<p>
|
||||
</font>
|
||||
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.
|
||||
|
||||
<p><font color="darkgreen">
|
||||
Member <tt>channels_per_image</tt> specifies the number of channels the
|
||||
image consists of. When the image is transmitted in more than one frame
|
||||
<tt>channels_per_image</tt> has to be the same for all frames for this image.
|
||||
|
||||
<p>Member <tt>format_desc</tt> is used to describe the details of the frame
|
||||
formats. Its meaning differs between the two formats:
|
||||
|
||||
<p><ul>
|
||||
<li>
|
||||
<tt>SANE_FRAME_RAW</tt>:
|
||||
The <tt>format_desc</tt> contains a description of the channel data and
|
||||
an optional depth information separated by a colon(:).
|
||||
|
||||
<p>A plane is descibed by one channel, e.g. ``<tt>gray</tt>'' or ``<tt>gray:12</tt>''.
|
||||
|
||||
<p>Channel interleaved data is described by a comma separated list of channel descriptions,
|
||||
for example ``<tt>red,green,blue</tt>'' or ``<tt>red:8,green:8,blue:8</tt>'',
|
||||
the channel data is sent in the given order.
|
||||
|
||||
<p>The depth information does <b>not</b> define the size of the transmitted
|
||||
channel data, it is only an information for the frontend. The channel data has
|
||||
to be sent in the size defined by member <tt>depth</tt>.
|
||||
|
||||
<p>Well known channels are <tt>red</tt>, <tt>green</tt>, <tt>blue</tt> and <tt>gray</tt>.
|
||||
It also is allowed to use other channel descriptions, e.g. if you
|
||||
use an infrared camera or scanner it could be <tt>infrared</tt> or
|
||||
a wavelength description like <tt>1100nm</tt>, but be aware that a
|
||||
frontend may not be able to display such channels with useful colors.
|
||||
|
||||
<p>Note that an image can be sent in single planes, in one interleaved
|
||||
frame that contains all channels or in several frames that contain
|
||||
one or more (interleaved) channels. When an RGB image is sent it
|
||||
is prefered to send the image data in one interleaved frame
|
||||
that consist of red, green and blue data in this order.
|
||||
The number of channels is defined in member <tt>channels_per_image</tt>.
|
||||
|
||||
<p><li>
|
||||
<tt>SANE_FRAME_MIME</tt>:
|
||||
|
||||
<p><tt>format_desc</tt> contains the MIME Content-Type: header field as described
|
||||
in RFC 1521 (section 4) without the prefixing "Content-Type:". MIME Types and
|
||||
subtypes should be either chosen from the RFC or from the list of
|
||||
IANA-approved values. The data stream must be compliant with the corresponding
|
||||
specification.
|
||||
|
||||
<p>When data is transmitted with the frame type <tt>SANE_FRAME_MIME</tt>
|
||||
all data has to be transmitted within one frame, multiple frames
|
||||
are not allowed (so the flag <tt>last_frame</tt> has to be set
|
||||
when using this frame type).
|
||||
|
||||
<p>A SANE backend must be able to at least optionally transmit
|
||||
<tt>SANE_FRAME_RAW</tt> (possibly with the help of a meta backend), if the
|
||||
hardware supports delivering image data at all. For data that doesn't
|
||||
comprise images, it's admisable to only provide MIME frames. As a
|
||||
general principle, if there are several choices in MIME types, the
|
||||
format that is most widely implemented should be used.
|
||||
</ul>
|
||||
|
||||
<p>The member <tt>proposed_filename</tt> can be used to suggest a reasonable
|
||||
default filename or -extension in case the backend can make such a
|
||||
suggestion, like e.g. an image database.
|
||||
If no such suggestion is intended, set the field to ``''.
|
||||
|
||||
<p>In the case of raw frames, <tt>proposed_filename</tt> is expected to hold
|
||||
the basename for the image, with the extension determined by the save function
|
||||
of the frontend, as the frontend can fully understand the data and is thus
|
||||
able to encode it in any format it wishes.
|
||||
|
||||
<p>For MIME frames <tt>proposed_filename</tt> can contain either:
|
||||
|
||||
<p><ul>
|
||||
<li>
|
||||
A name with a leading dot, which is considered to be a proposed
|
||||
filename extension. This could also be gotten from the mime database,
|
||||
but for systems lacking it, this might be convenient. Or:
|
||||
|
||||
<p><li>
|
||||
A complete filename, including extension.
|
||||
</ul>
|
||||
|
||||
<p>Note, that for frontends that are able to parse a given MIME type
|
||||
internally, it is perfectly permissible to ignore the extension
|
||||
part of the proposed filename and only make use of the basename,
|
||||
when using internal save algorithms for different formats.
|
||||
|
||||
<p>The string <tt>proposed_comment</tt> can be used to transmit additional
|
||||
image information, that can be stored in the comment areas several file formats
|
||||
offer. It can contain any textual information the backend wishes to
|
||||
convey to the user, like date/time of exposure, enganged filters,
|
||||
etc. Set to ``'' if unused.
|
||||
|
||||
<p>The members <tt>dpi_x</tt> and <tt>dpi_y</tt> encode the horizontal and vertical
|
||||
resolution. Note, that multiple-image scans may have different resolutions of
|
||||
each image. It is not permissible to change resolution between frames of the
|
||||
same image. If not applicable, set to -1.
|
||||
|
||||
<p>The member <tt>reserved</tt> is an array of 32 bytes (char) to keep
|
||||
the size of the struct unchanged when future extensions are done.
|
||||
The backend has to set the reserved bytes to 0.
|
||||
</font>
|
||||
|
||||
<p><h3><a name="s4.3.9">4.3.9 <tt>sane_start</tt></a></h3>
|
||||
|
||||
<p>This function initiates aquisition of an image from the device
|
||||
represented by handle <tt>h</tt>.
|
||||
<blockquote><a name="i110">
|
||||
<pre>
|
||||
SANE_Status sane_start (SANE_Handle h);
|
||||
</pre>
|
||||
</blockquote>
|
||||
This function may fail with one of the following status codes.
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_CANCELLED</tt>:<dd> The operation was cancelled through
|
||||
a call to <tt>sane_cancel</tt>.
|
||||
<dt><tt>SANE_STATUS_DEVICE_BUSY</tt>:<dd> The device is busy. The
|
||||
operation should be retried later.
|
||||
<dt><tt>SANE_STATUS_JAMMED</tt>:<dd> The document feeder is jammed.
|
||||
<dt><tt>SANE_STATUS_NO_DOCS</tt>:<dd> The document feeder is out of
|
||||
documents.
|
||||
<dt><tt>SANE_STATUS_COVER_OPEN</tt>:<dd> The scanner cover is open.
|
||||
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occurred while communicating
|
||||
with the device.
|
||||
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
||||
is available.
|
||||
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> The scan cannot be started with the current
|
||||
set of options. The frontend should reload the option descriptors, as if
|
||||
<tt>SANE_INFO_RELOAD_OPTIONS<a name="i111"></tt> had been returned from a call to
|
||||
<tt>sane_control_option()</tt>, since the device's capabilities may have
|
||||
changed.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.10">4.3.10 <tt>sane_read</tt></a></h3>
|
||||
|
||||
<p>This function is used to read image data from the device represented
|
||||
by handle <tt>h</tt>. Argument <tt>buf</tt> is a pointer to a memory area
|
||||
that is at least <tt>maxlen</tt> bytes long. The number of bytes
|
||||
returned is stored in <tt>*len</tt>. A backend must set this to zero
|
||||
when a status other than <tt>SANE_STATUS_GOOD</tt> is returned).
|
||||
When the call succeeds, the number of bytes returned can be anywhere in
|
||||
the range from 0 to <tt>maxlen</tt> bytes.
|
||||
<blockquote><a name="i112">
|
||||
<pre>
|
||||
SANE_Status sane_read (SANE_Handle h, SANE_Byte * buf,
|
||||
SANE_Int maxlen, SANE_Int * len);
|
||||
</pre>
|
||||
</blockquote>
|
||||
<font color="darkgreen">
|
||||
For efficiency reasons, medium to large
|
||||
block sizes (in the range of a few kilobytes) should be used.
|
||||
Returning short reads is allowed to allow for small buffers
|
||||
in the backend.
|
||||
</font>
|
||||
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 <tt>h</tt>.
|
||||
<ol>
|
||||
<li>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).
|
||||
|
||||
<p><li>If the device is in non-blocking I/O mode, the call returns
|
||||
immediately with status <tt>SANE_STATUS_GOOD</tt> and with
|
||||
<tt>*len</tt> set to zero.
|
||||
</ol>
|
||||
The I/O mode of handle <tt>h</tt> can be set via a call to
|
||||
<tt>sane_set_io_mode()</tt>.
|
||||
|
||||
<p>This function may fail with one of the following status codes.
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_CANCELLED</tt>:<dd> The operation was cancelled through
|
||||
a call to <tt>sane_cancel</tt>.
|
||||
<dt><tt>SANE_STATUS_EOF</tt>:<dd> No more data is available for the
|
||||
current frame.
|
||||
<font color="darkgreen">
|
||||
If <tt>sane_read</tt> sends back any image data it
|
||||
is not allowed to return with <tt>SANE_STATUS_EOF</tt>.
|
||||
</font>
|
||||
<dt><tt>SANE_STATUS_JAMMED</tt>:<dd> The document feeder is jammed.
|
||||
<dt><tt>SANE_STATUS_NO_DOCS</tt>:<dd> The document feeder is out of
|
||||
documents.
|
||||
<dt><tt>SANE_STATUS_COVER_OPEN</tt>:<dd> The scanner cover is open.
|
||||
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occurred while communicating
|
||||
with the device.
|
||||
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
||||
is available.
|
||||
<dt><tt>SANE_STATUS_ACCESS_DENIED</tt>:<dd> Access to the device has
|
||||
been denied due to insufficient or invalid authentication.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.11">4.3.11 <tt>sane_cancel</tt></a></h3>
|
||||
|
||||
<p>This function is used to immediately or as quickly as possible cancel
|
||||
the currently pending operation of the device represented by handle
|
||||
<tt>h</tt>.
|
||||
<blockquote><a name="i113">
|
||||
<pre>
|
||||
void sane_cancel (SANE_Handle h);
|
||||
</pre>
|
||||
</blockquote>
|
||||
This function can be called at any time (as long as handle <tt>h</tt> 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</em> imply that
|
||||
the currently pending operation has been cancelled. It only
|
||||
guarantees that cancellation has been <em>initiated</em>. Cancellation
|
||||
completes only when the cancelled call returns (typically with a
|
||||
status value of <tt>SANE_STATUS_CANCELLED</tt>). Since the SANE API
|
||||
does not require any other operations to be re-entrant, this implies
|
||||
that a frontend must <em>not</em> call any other operation until the
|
||||
cancelled operation has returned.
|
||||
|
||||
<p><h3><a name="s4.3.12">4.3.12 <tt>sane_set_io_mode</tt></a></h3>
|
||||
|
||||
<p>This function is used to set the I/O mode of handle <tt>h</tt>. The I/O mode
|
||||
can be either blocking or non-blocking. If argument <tt>m</tt> is
|
||||
<tt>SANE_TRUE</tt>, 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
|
||||
<tt>sane_start()</tt> has been performed.
|
||||
<blockquote><a name="i114">
|
||||
<pre>
|
||||
SANE_Status sane_set_io_mode (SANE_Handle h, SANE_Bool m);
|
||||
</pre>
|
||||
</blockquote>
|
||||
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 <tt>SANE_STATUS_UNSUPPORTED</tt> is returned. Blocking
|
||||
I/O must be supported by all backends, so calling this function with
|
||||
argument <tt>m</tt> set to <tt>SANE_FALSE</tt> is guaranteed to complete
|
||||
successfully.
|
||||
|
||||
<p>This function may fail with one of the following status codes:
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> No image acquisition is pending.
|
||||
<dt><tt>SANE_STATUS_UNSUPPORTED</tt>:<dd> The backend does not support
|
||||
the requested I/O mode.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.13">4.3.13 <tt>sane_get_select_fd</tt></a></h3>
|
||||
|
||||
<p>This function is used to obtain a (platform-specific) file-descriptor
|
||||
for handle <tt>h</tt> that is readable if and only if image data is
|
||||
available (i.e., when a call to <tt>sane_read()</tt> will return at
|
||||
least one byte of data). If the call completes successfully, the
|
||||
select file-descriptor is returned in <tt>*fd</tt>.
|
||||
<blockquote><a name="i115">
|
||||
<pre>
|
||||
SANE_Status sane_get_select_fd (SANE_Handle h, SANE_Int *fd);
|
||||
</pre>
|
||||
</blockquote>
|
||||
This function can be called only after a call to <tt>sane_start()</tt>
|
||||
has been performed and the returned file-descriptor is guaranteed to
|
||||
remain valid for the duration of the current image acquisition (i.e.,
|
||||
until <tt>sane_cancel()</tt> or <tt>sane_start()</tt> get called again
|
||||
or until <tt>sane_read()</tt> returns with status
|
||||
<tt>SANE_STATUS_EOF</tt>). Indeed, a backend must guarantee to
|
||||
close the returned select file descriptor at the point when the next
|
||||
<tt>sane_read()</tt> call would return <tt>SANE_STATUS_EOF</tt>.
|
||||
This is necessary to ensure the application can detect when this
|
||||
condition occurs without actually having to call <tt>sane_read()</tt>.
|
||||
|
||||
<p>A backend may elect not to support this operation. In such a case,
|
||||
the function returns with status code
|
||||
<tt>SANE_STATUS_UNSUPPORTED</tt>.
|
||||
|
||||
<p>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 <tt>select()</tt>
|
||||
or <tt>poll()</tt> 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 <tt>sane_read()</tt> 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.
|
||||
|
||||
<p>This function may fail with one of the following status codes:
|
||||
<blockquote>
|
||||
<dl>
|
||||
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> No image acquisition is pending.
|
||||
<dt><tt>SANE_STATUS_UNSUPPORTED</tt>:<dd> The backend does not support
|
||||
this operation.
|
||||
</dl>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s4.3.14">4.3.14 <tt>sane_strstatus</tt></a></h3>
|
||||
|
||||
<p>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 <tt>NULL</tt>.
|
||||
The returned pointer is valid at least until the next call to this
|
||||
function is performed.
|
||||
<blockquote><a name="i116">
|
||||
<pre>
|
||||
SANE_String_Const sane_strstatus (SANE_Status status);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc013.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc011.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,207 @@
|
|||
<html><body>
|
||||
<a href="doc014.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc012.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Code Flow</title>
|
||||
<h2><a name="s4.4">4.4 Code Flow</a></h2><a name="i117">
|
||||
|
||||
<p>The code flow for the SANE API is illustrated in
|
||||
Figure <a href="doc013.html#f4">4</a>. Functions <tt>sane_init()</tt> and
|
||||
<tt>sane_exit()</tt> initialize and exit the backend, respectively.
|
||||
All other calls must be performed after initialization and before
|
||||
exiting the backend.
|
||||
|
||||
<p><p><a name="f4"></a>
|
||||
<center>
|
||||
|
||||
<img width=566 height=510 src="img003.gif">
|
||||
<p><center>Figure 4: Code flow</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>Function <tt>sane_get_devices()</tt> can be called any time after
|
||||
<tt>sane_init()</tt> 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.
|
||||
|
||||
<p>Once a device has been chosen, it is opened using a call to
|
||||
<tt>sane_open()</tt>. 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.
|
||||
|
||||
<p>An opened device can be setup through the corresponding device handle
|
||||
using functions <tt>sane_get_option_descriptor()</tt> and
|
||||
<tt>sane_control_option()</tt>. 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.
|
||||
<font color="darkgreen">
|
||||
However, as options are set, other options may become active or inactive or
|
||||
their constraint may change. Thus, after setting an option, it may be
|
||||
necessary to re-read the descriptors.
|
||||
</font>
|
||||
While
|
||||
setting up the device, it is also admissible to call
|
||||
<tt>sane_get_parameters()</tt> to get an estimate of what the image
|
||||
parameters will look like once image acquisition begins.
|
||||
|
||||
<p>The device handle can be put in blocking or non-blocking mode by a
|
||||
call to <tt>sane_set_io_mode()</tt>. 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.
|
||||
|
||||
<p>After the device is setup properly, image acquisition can be started
|
||||
by a call to <tt>sane_start()</tt>. The backend calculates the exact
|
||||
image parameters at this point. So future calls to
|
||||
<tt>sane_get_parameters()</tt> will return the exact values, rather
|
||||
than estimates. Whether the physical image acquisition starts at this
|
||||
point or during the first call to <tt>sane_read()</tt> 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
|
||||
<tt>sane_set_io_mode()</tt> and/or <tt>sane_get_select_fd()</tt> at
|
||||
this point. Either of these functions may fail if the backend does
|
||||
not support the requested operation.
|
||||
|
||||
<p><font color="darkgreen">
|
||||
Image data is collected by repeatedly calling <tt>sane_read()</tt>
|
||||
until this function will return an end-of-file status
|
||||
(<tt>SANE_STATUS_EOF</tt>). This indicates the end of the current
|
||||
frame. If the frontend expects additional frames (e.g., the
|
||||
individual channels of a red/green/blue image or multiple images),
|
||||
it can call <tt>sane_start()</tt> again.
|
||||
If the <tt>SANE_PFLAG_LAST_FRAME</tt> bit is set in <tt>flags</tt>, the
|
||||
current image is complete. In this case, it should be tested, if
|
||||
<tt>flags</tt> has the <tt>SANE_PFLAG_MORE_IMAGES</tt> bit set.
|
||||
If yes, further calls to <tt>sane_start()</tt> can be made to acquire
|
||||
more images. Please note, that as this bit has to be set at the beginning
|
||||
of a the transmission of the last frame before the new image, it is possible,
|
||||
that no reliable decision can be made at this time. It is thus permissible
|
||||
for a backend to set this bit, and then later at the actual call to
|
||||
<tt>sane_start()</tt> return an error like <tt>SANE_STATUS_NO_DOCS</tt>.
|
||||
Such a sequence is permitted to transmit multiple images from a single
|
||||
page as well as multiple pages. This behaviour should be controlled by
|
||||
backend options as required, to allow single-page scanning as well as
|
||||
ADF-batch-scanning. The frontend should always continue reading all images
|
||||
until a frame with <tt>SANE_PFLAG_LAST_FRAME</tt> on
|
||||
and <tt>SANE_PFLAG_MORE_IMAGES</tt> off is encountered, or an error other
|
||||
than <tt>SANE_STATUS_EOF</tt> occurs in a SANE function.
|
||||
Note that <tt>SANE_STATUS_NO_DOCS</tt> also is an allowed way for the backend
|
||||
to indicate the end of a multiple image scan.
|
||||
|
||||
<p>A frontend may choose to skip frames (e.g. because it cannot parse them),
|
||||
which is accomplished by simply calling <tt>sane_start</tt> again, which will get
|
||||
you to the next frame, without having to read and discard the current one.
|
||||
|
||||
<p>In order to prematurely stop scanning and to reset the backend state,
|
||||
<tt>sane_cancel()</tt> can be called at any time. This call is required
|
||||
as well after normal termination of a multiple image scan as described above.
|
||||
</font>
|
||||
|
||||
<p>When done using the device, the handle should be closed by a call to
|
||||
<tt>sane_close()</tt>. Finally, before exiting the application,
|
||||
function <tt>sane_exit()</tt> 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.
|
||||
|
||||
<p><font color="darkgreen">
|
||||
The following C sample code implements a reference loop for acquiring
|
||||
multiple images:
|
||||
|
||||
<p><pre>
|
||||
SANE_Parameters parms;
|
||||
SANE_Status status;
|
||||
|
||||
do
|
||||
{
|
||||
do
|
||||
{
|
||||
/* Now start acquiring the next frame. */
|
||||
status = sane_start (handle);
|
||||
|
||||
/* if that failed, we have a problem, and no more frames can be
|
||||
* read at this time. Due to SANE_PFLAG_MORE_IMAGES still
|
||||
* being clear, this will break out of _BOTH_ loops.
|
||||
*/
|
||||
if (status != SANE_STATUS_GOOD)
|
||||
break;
|
||||
|
||||
/* Now let us see what the next frame brings. */
|
||||
status = sane_get_parameters (handle, &parms);
|
||||
|
||||
/* This actually should not fail, but maybe the doc feeder
|
||||
* jammed or something, so we break as well, if something
|
||||
* is wrong.
|
||||
*/
|
||||
if (status != SANE_STATUS_GOOD)
|
||||
break;
|
||||
|
||||
/* Now we check the announced parameters, if we can make use
|
||||
* of the frame data. If not, we skip over to the next frame.
|
||||
*/
|
||||
if (do_i_like_that (&parms) == NO)
|
||||
continue;
|
||||
|
||||
/* Set up for reading the data here. Mangle filenames,
|
||||
* allocate memory, rewind multiframe files, ask user
|
||||
* for confirmation, ...
|
||||
*/
|
||||
setup_for_transfer (...);
|
||||
|
||||
/* Now we read in the frame data and process it. This should
|
||||
* return SANE_STATUS_GOOD, until the frame is complete,
|
||||
* what causes SANE_STATUS_EOF to be returned.
|
||||
*/
|
||||
while (SANE_STATUS_GOOD == (status = sane_read (...)))
|
||||
read_in_and_process_data_as_required ();
|
||||
|
||||
/* If transfer was broken due to anything but EOF, break out. */
|
||||
if (status != SANE_STATUS_EOF)
|
||||
break;
|
||||
|
||||
/* Now loop until we have all frames of an image. */
|
||||
}
|
||||
while (!(parms.flag & SANE_PFLAG_LAST_FRAME));
|
||||
|
||||
/* O.K. - we now have a complete image. Fit it together, save it,
|
||||
* flush buffers, transmit it, increment filenames, etc.
|
||||
*/
|
||||
|
||||
/* Now check for more pending images. If we have more, redo from start.
|
||||
* Some backends might cheat here and send us for an extra round which
|
||||
* will fail at sane_start, as they were not able to determine if they
|
||||
* would have more data at the start of the last frame we read.
|
||||
*/
|
||||
}
|
||||
while (parms.flags & SANE_PFLAG_MORE_IMAGES);
|
||||
|
||||
/* No more data. Fine. Reset the backend and go back to option-control
|
||||
* loop.
|
||||
*/
|
||||
|
||||
sane_cancel (handle);
|
||||
</pre>
|
||||
|
||||
<p></font>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc014.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc012.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,486 @@
|
|||
<html><body>
|
||||
<a href="doc015.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc013.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Well-Known Options</title>
|
||||
<h2><a name="s4.5">4.5 Well-Known Options</a></h2><a name="i118">
|
||||
|
||||
<p>While most backend options are completely self-describing, there are
|
||||
cases where a user interface might want to special-case the handling
|
||||
of certain options. For example, the scan area is typically defined
|
||||
by four options that specify the top-left and bottom-right corners of
|
||||
the area. With a graphical user interface, it would be tedious to
|
||||
force the user to type in these four numbers. Instead, most such
|
||||
interfaces will want to present to the user a preview (low-resolution
|
||||
scan of the full scanner surface or a high(er) resolution scan of a subpart
|
||||
of the scanner surface) and let the user pick the scan area by
|
||||
dragging a rectangle into the desired position. For this reason, the
|
||||
SANE API specifies a small number of option names that have
|
||||
well-defined meanings.
|
||||
|
||||
<p><h3><a name="s4.5.1">4.5.1 Option Number Count</a></h3><a name="i119">
|
||||
|
||||
<p>Option number 0 has an empty string as its name. The value of this
|
||||
option is of type <tt>SANE_TYPE_INT</tt> 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
|
||||
<tt>sane_get_option_descriptor()</tt> returns <tt>NULL</tt>, or a
|
||||
frontend can directly read out the value of option number 0.
|
||||
|
||||
<p><h3><a name="s4.5.2">4.5.2 Scan Resolution Options</a></h3><a name="i120"><a name="i121">
|
||||
|
||||
<p>Option <tt>resolution</tt> is used to select the resolution at which an
|
||||
image should be acquired.
|
||||
<font color="darkgreen">
|
||||
When the backend wants to allow different
|
||||
values for x- and y-resolution it has to define the options
|
||||
<tt>x-resolution</tt> and <tt>y-resolution</tt>. Note that only
|
||||
the option <tt>resolution</tt> <b>or</b> the options
|
||||
<tt>x-resolution</tt> <b>and</b> <tt>y-resolution</tt> may be active at the
|
||||
same time.
|
||||
</font>
|
||||
|
||||
<p>The type of this option is either <tt>SANE_TYPE_INT</tt> or
|
||||
<tt>SANE_TYPE_FIXED</tt>. The unit is <tt>SANE_UNIT_DPI</tt> (dots/inch).
|
||||
|
||||
<p>These options are not mandatory, but if a backend does support them, it
|
||||
must implement them in a manner consistent with the above definition.
|
||||
|
||||
<p><h3><a name="s4.5.3">4.5.3 Preview Mode Option</a></h3><a name="i122">
|
||||
|
||||
<p>The boolean option <tt>preview</tt> 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 <tt>SANE_TRUE</tt>,
|
||||
preview mode is in effect, when set to <tt>SANE_FALSE</tt> image
|
||||
acquisition should proceed in normal quality mode. The setting of
|
||||
this option <em>must not</em> 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 <tt>resolution</tt>). A backend is free to override the
|
||||
<tt>resolution</tt> value with its own choice for preview mode, but it
|
||||
is advised to leave this choice to the frontend wherever possible.
|
||||
<font color="darkgreen">
|
||||
When the <tt>preview</tt> option is set the backend should transfer
|
||||
the image in frame type <tt>SANE_FRAME_RAW</tt> if possible.
|
||||
</font>
|
||||
|
||||
<p>This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.
|
||||
|
||||
<p><h3><a name="s4.5.4">4.5.4 Scan Area Options</a></h3><a name="i123">
|
||||
|
||||
<p>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 <a href="doc014.html#f5">5</a>. 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</em> and the bottom-right corner is the
|
||||
corner for which the abscissa and ordinate values are simulatenously
|
||||
the <em>largest</em>. If this coordinate system is not natural for a
|
||||
given device, it is the job of the backend to perform the necessary
|
||||
conversions.
|
||||
<p><a name="f5"></a>
|
||||
<center>
|
||||
|
||||
<img width=330 height=306 src="img004.gif">
|
||||
<p><center>Figure 5: Scan area options</center>
|
||||
|
||||
</center>
|
||||
<p>
|
||||
|
||||
<p>The names of the four options that define the scan area are given in
|
||||
the table below:
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>Name</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>Description</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>tl-x<a name="i124"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> Top-left x coordinate value </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>tl-y<a name="i125"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> Top-left y coordinate value </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>br-x<a name="i126"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> Bottom-right x coordinate value </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>br-y<a name="i127"></tt> </td>
|
||||
<td colspan=1 align=left nowrap> Bottom-right y coordinate value </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
There are several rules that should be followed by front and backends
|
||||
regarding these options:
|
||||
<ul>
|
||||
|
||||
<p><li>Backends must attach a unit of either pixels
|
||||
(<tt>SANE_UNIT_PIXEL</tt>) or millimeters (<tt>SANE_UNIT_MM</tt>) to
|
||||
these options. The unit of all four options must be identical.
|
||||
|
||||
<p><li>Whenever meaningful, a backend should attach a range or a
|
||||
word-list constraint to these options.
|
||||
|
||||
<p><li>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.
|
||||
|
||||
<p><li>A frontend must work properly with any or all of these options
|
||||
missing.
|
||||
|
||||
<font color="darkgreen">
|
||||
<li>A frontend may temporarily set the values in a way that
|
||||
<tt>tl-x</tt> is larger than <tt>br-x</tt> and <tt>tl-y</tt> is larger than
|
||||
<tt>br-y</tt>.
|
||||
</font>
|
||||
|
||||
<p></ul>
|
||||
|
||||
<p><font color="darkgreen">
|
||||
These options are not mandatory, but if a backend does support them, it
|
||||
must implement them in a manner consistent with the above definition.
|
||||
</font>
|
||||
|
||||
<p><font color="darkgreen">
|
||||
<h3><a name="s4.5.5">4.5.5 Depth Option</a></h3><a name="i128">
|
||||
Option <tt>depth</tt> is used to select the image depth in bits/sample
|
||||
in multi bit mode (e.g. for 24 bit RGB mode this value must be 8).
|
||||
The type of this option is <tt>SANE_TYPE_INT</tt>.
|
||||
The unit is <tt>SANE_UNIT_BIT</tt>. For 1 bit modes
|
||||
(Lineart or Halftone) this option has to be inactive.
|
||||
For selection of 1 bit modes (Lineart or Halftone) the
|
||||
backend should use the well-known option <tt>mode</tt>.
|
||||
|
||||
This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.
|
||||
</font>
|
||||
|
||||
<font color="darkgreen">
|
||||
<h3><a name="s4.5.6">4.5.6 Scan Mode Options</a></h3><a name="i129">
|
||||
The option <tt>mode</tt> defines a <tt>SANE_CONSTRAINT_STRING_LIST</tt>
|
||||
of type <tt>SANE_TYPE_STRING</tt>.
|
||||
It is used to select the scanmode (e.g. Color or Gray).
|
||||
Well known modes are: <tt>Color</tt>, <tt>Gray</tt>, <tt>Halftone</tt>
|
||||
and <tt>Lineart</tt>. <tt>Color</tt> and <tt>Gray</tt> are multi bit
|
||||
modes (8 or 16 bits/sample), <tt>Halftone</tt> and <tt>Lineart</tt>
|
||||
are single bit modes. When well-known scan modes are used,
|
||||
a frontend is able to automatically decide which mode is appropriate
|
||||
for a specific task, e.g the mode <tt>Gray</tt>
|
||||
for scanning a fax.
|
||||
|
||||
This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.
|
||||
</font>
|
||||
|
||||
<font color="darkgreen">
|
||||
<h3><a name="s4.5.7">4.5.7 Scan Source Options</a></h3><a name="i130">
|
||||
The option <tt>source</tt> is used to select the scan source
|
||||
(e.g. Automatic Document Feeder).
|
||||
It defines a <tt>SANE_CONSTRAINT_STRING_LIST</tt>
|
||||
of type <tt>SANE_TYPE_STRING</tt>.
|
||||
Well known sources are: <tt>Flatbed</tt>, <tt>Transparancy Adapter</tt> and
|
||||
<tt>Automatic Document Feeder</tt>.
|
||||
|
||||
This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.
|
||||
</font>
|
||||
|
||||
<p><font color="darkgreen">
|
||||
<h3><a name="s4.5.8">4.5.8 Threshold Option</a></h3><a name="i131">
|
||||
The option <tt>threshold</tt> is used to define the threshold
|
||||
for Lineart and maybe Halftone mode. In multi bit modes
|
||||
this option should be set inactive.
|
||||
The type of this option is <tt>SANE_TYPE_FIXED</tt>.
|
||||
The unit is <tt>SANE_UNIT_PERCENT</tt>. The value range
|
||||
should be 0.0...100.0 if possible.
|
||||
It defines the minimum intensity to get a white point / full intensity.
|
||||
|
||||
<p>The backend has to scale the values in the following way:
|
||||
A value of 0.0 means all pixels get white / full intensity. A value of 50.0
|
||||
means intensities brighter than medium gray get white / full intensity. A
|
||||
value of 100.0 means all pixels get black. If the
|
||||
scanner is not able to cover the full range the backend has to define a
|
||||
reduced value range (e.g. 30...70 percent).
|
||||
|
||||
<p>This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.
|
||||
</font>
|
||||
|
||||
<p><font color="darkgreen">
|
||||
<h3><a name="s4.5.9">4.5.9 Gamma Table Options</a></h3><a name="i132">
|
||||
The <tt>gamma-table</tt> option defines a <tt>SANE_CONSTRAINT_RANGE</tt>
|
||||
of the type <tt>SANE_TYPE_INT</tt> which represents the gamma correction
|
||||
table for gray. In color mode the <tt>gamma-table</tt> may be used to set
|
||||
a common gamma correction for red, green and blue. The options
|
||||
<tt>red-gamma-table</tt>, <tt>green-gamma-table</tt> and <tt>blue-gamma-table</tt>
|
||||
are used in color mode to set a gamma correction for each color
|
||||
separately. In color mode the backend is free to use only the
|
||||
<tt>gamma-table</tt> option, only the <tt>red-</tt>, <tt>green-</tt> and
|
||||
<tt>blue-gamma-table</tt> or all four options. When all four options
|
||||
are used then the color tables should do a gamma correction with
|
||||
the same input and output bit depth and the gray gamma table should
|
||||
reduce (if necessary) the bit depth from the scanner internal
|
||||
bit depth to the output bit depth. This should e.g. look like this:
|
||||
<pre>
|
||||
red_value = gamma-table(red-gamma-table(value))
|
||||
green_value = gamma-table(green-gamma-table(value))
|
||||
blue_value = gamma-table(blue-gamma-table(value))
|
||||
</pre>
|
||||
|
||||
<p>The backend should not use the gamma tables to emulate other functions or options
|
||||
like highlight, shadow, contrast, brightness, threshold, analog_gamma.
|
||||
These functions are common for all backends and should be added to the frontend
|
||||
or a meta-backend.
|
||||
|
||||
<p>It is also discouraged to emulate gamma tables in the backend. The backend
|
||||
should disable (or not define) this option when the scanner does not support
|
||||
gamma tables in hardware.
|
||||
|
||||
This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.
|
||||
</font>
|
||||
|
||||
<p><font color="darkgreen">
|
||||
<h3><a name="s4.5.10">4.5.10 Analog Gamma</a></h3><a name="i133">
|
||||
The option <tt>analog-gamma</tt> is used to define the gamma value
|
||||
for an analog gamma function of the scanner in multi bit modes.
|
||||
In 1 bit modes this option should be set inactive.
|
||||
The type of this option is <tt>SANE_TYPE_FIXED</tt>.
|
||||
The unit is <tt>SANE_UNIT_NONE</tt>. The value range
|
||||
can be defined by the backend as supported. The values
|
||||
have to be positive. A gamma value of 1.0 means that
|
||||
the gamma correction has no effect. A value larger than
|
||||
1.0 increases the brightness of the image.
|
||||
In color mode there also can be options <tt>analog-gamma-red</tt>,
|
||||
<tt>analog-gamma-green</tt> and <tt>analog-gamma-blue</tt>.
|
||||
It is not allowed to emulate an analog gamma function by
|
||||
a digital gamma table. The backend has to disable (or not
|
||||
define) this option when the scanner does not support an
|
||||
analog (hardware) gamma function.
|
||||
|
||||
<p>When analog gamma, highlight and shadow functions are available
|
||||
at the same time then the backend author has to care about the order
|
||||
in which the functions are implemented in the scanner hardware.
|
||||
The SANE standard expects that changing the analog gamma value
|
||||
has no effect on the shadow and highlight function. When the
|
||||
analog gamma function is executed in the scanner hardware
|
||||
before the shadow and highlight functions then the backend
|
||||
should do a compensation. For this the shadow and highlight
|
||||
values have to be gamma corrected with the relevant analog gamma value.
|
||||
|
||||
<p>This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.
|
||||
</font>
|
||||
|
||||
<p><font color="darkgreen">
|
||||
<h3><a name="s4.5.11">4.5.11 Shadow Option</a></h3><a name="i134">
|
||||
The option <tt>shadow</tt> is used to define the shadow level / black point level.
|
||||
The type of this option is <tt>SANE_TYPE_FIXED</tt>.
|
||||
The unit is <tt>SANE_UNIT_PERCENT</tt>. The value range
|
||||
should be 0.0...100.0 if possible.
|
||||
It is used to define the maximum intensity level that creates an image data value
|
||||
of 0 (black).
|
||||
|
||||
<p>The backend has to scale the values in the following way:
|
||||
A value of 0.0 means that the sensitivity range is not reduced, only the
|
||||
minimum intensity produces an image data value of 0 (black).
|
||||
A value of 50.0 means that that a medium intensity and everything that is darker
|
||||
produces an image data value of 0 (black).
|
||||
A value of 100.0 means the sensitivity range is reduced to 0, all image
|
||||
data values are 0 (black). If the scanner is not able to
|
||||
cover the full range the backend has to define a reduced
|
||||
value range (e.g. 30...70 percent).
|
||||
In color mode there can be options <tt>shadow-red</tt>, <tt>shadow-green</tt>
|
||||
and <tt>shadow-blue</tt>, in this case the <tt>shadow</tt> function has to be disabled.
|
||||
It is not allowed to emulate a shadow function by
|
||||
a digital gamma table. The backend has to disable (or not
|
||||
define) this option when the scanner does not support an
|
||||
analog (hardware) shadow function.
|
||||
|
||||
<p>This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.
|
||||
</font>
|
||||
|
||||
<p><font color="darkgreen">
|
||||
<h3><a name="s4.5.12">4.5.12 Highlight Option</a></h3><a name="i135">
|
||||
The option <tt>highlight</tt> is used to define the highlight level / white point level.
|
||||
The type of this option is <tt>SANE_TYPE_FIXED</tt>.
|
||||
The unit is <tt>SANE_UNIT_PERCENT</tt>. The value range
|
||||
should be 0.0...100.0 if possible.
|
||||
It is used to define the minimum intensity level that creates the maximum possible
|
||||
image data value (white/full intensity).
|
||||
|
||||
<p>The backend has to scale the values in the following way:
|
||||
A value of 0.0 means the sensitivity range is reduced to 0, all image
|
||||
data have maximum value (white / full intensity).
|
||||
A value of 50.0 means that a medium intensity and everything that is brighter
|
||||
produces the maximum possible image data value (white / full intensity).
|
||||
A value of 100.0 means that the sensitivity range is not reduced, only the
|
||||
maximum intensity produces an image data with maximum possible value (white / full intensity).
|
||||
If the scanner is not able to cover the full range the backend has to define a reduced
|
||||
value range (e.g. 30...70 percent).
|
||||
In color mode there can be options <tt>highlight-red</tt>, <tt>highlight-green</tt>
|
||||
and <tt>highlight-blue</tt>, in this case <tt>highlight</tt> has to be disabled.
|
||||
It is not allowed to emulate a highlight function by
|
||||
a digital gamma table. The backend has to disable (or not
|
||||
define) this option when the scanner does not support an
|
||||
analog (hardware) highlight function.
|
||||
|
||||
<p>This option is not mandatory, but if a backend does support it, it
|
||||
must implement it in a manner consistent with the above definition.
|
||||
</font>
|
||||
|
||||
<p><font color="darkgreen">
|
||||
<h3><a name="s4.5.13">4.5.13 Lamp Options</a></h3><a name="i136"><a name="i137">
|
||||
|
||||
<p>The options <tt>lamp-on</tt> and <tt>lamp-off</tt> are button options
|
||||
(<tt>SANE_TYPE_BUTTON</tt>) and don't have a unit (<tt>SANE_UNIT_NONE</tt>).
|
||||
|
||||
<p>Option <tt>lamp-on</tt> is used to turn on the lamp of the scanner while
|
||||
<tt>lamp-off</tt> turns it off.
|
||||
|
||||
<p>These options are not mandatory, but if a backend does support them, it
|
||||
must implement them in a manner consistent with the above definition.
|
||||
</font>
|
||||
|
||||
<p><font color="darkgreen">
|
||||
<h3><a name="s4.5.14">4.5.14 Scanner Button Options</a></h3><a name="i138">
|
||||
Some scanners have buttons which state can be read by the scanner driver.
|
||||
It is necessary to implement a locking function for the buttons
|
||||
because it is possible that several frontends try to connect to the
|
||||
same backend/scanner at the same time. Imagine what could happen
|
||||
when no locking would be implemented:
|
||||
Five people have started a scanning application which is connected
|
||||
via network to the scanner you want to use. You start a frontend,
|
||||
put a paper to the scanner and press the scan-button on the scanner.
|
||||
The scanner does scan three times (because three frontends asked the
|
||||
button status when you pressed the button). For three people the
|
||||
image is saved to the harddisk, but it is not sure that your
|
||||
frontend did scan the image.
|
||||
|
||||
<p>A backend that does make available the scanner-buttons has to
|
||||
implement the following options:<br>
|
||||
<tt>scanner-buttons-lock</tt> is of type <tt>SANE_TYPE_BOOL</tt>, default = <tt>SANE_FALSE</tt><br>
|
||||
<tt>scanner-buttons-status</tt> is of type <tt>SANE_TYPE_INT</tt>, default = 0<br>
|
||||
<tt>scanner-buttons-status-update</tt> is of type <tt>SANE_TYPE_BUTTON</tt><br>
|
||||
When setting these options the backend does not set <tt>SANE_INFO_RELOAD_OPTIONS</tt>
|
||||
or <tt>SANE_INFO_RELOAD_PARAMS</tt> if not explictly defined.
|
||||
|
||||
<p>A frontend has to disable the usage of the scanner-buttons by default. This is important
|
||||
because other frontends will not be able to use the buttons when the button-functions are locked.
|
||||
Another important thing is that some scanners do not turn off their lamp when the driver
|
||||
does frequently talk to the scanner (what is done when reading the button status from the scanner).
|
||||
|
||||
<p><ul>
|
||||
|
||||
<p><li>
|
||||
A frontend that wants to read the button status has to lock the
|
||||
button functions at first. For this it does set the option
|
||||
<tt>scanner-buttons-lock</tt> to <tt>SANE_TRUE</tt>.
|
||||
While setting the value of option <tt>scanner-buttons-lock</tt> to <tt>SANE_TRUE</tt>
|
||||
the backend does check if a lockfile (e.g. ``backend''-buttons.lock) does exist.
|
||||
The lockfile has to be placed in a directory where every user has read and write access to.
|
||||
|
||||
<p> <ul>
|
||||
<li>
|
||||
If the lockfile does not exist then the backend creates the lockfile and writes the
|
||||
process ID (PID) of the backend to the file. Button access is allowed: the value
|
||||
of option <tt>scanner-buttons-lock</tt> is set to <tt>SANE_TRUE</tt>
|
||||
<li>
|
||||
If the file does exist and the backend PID is not the file PID then the
|
||||
backend has to check if the process with the PID stored in the lockfile
|
||||
still is running. If yes then the button access is not allowed: the value of
|
||||
option <tt>scanner-buttons-lock</tt> is set to <tt>SANE_FALSE</tt>. If not then the lockfile
|
||||
is recreated and the PID of the backend is stored in the lockfile, button
|
||||
access is allowed: the value of option <tt>scanner-buttons-lock</tt> is set to <tt>SANE_TRUE</tt>
|
||||
</ul>
|
||||
|
||||
<p><li>
|
||||
The frontend does read the value of option <tt>scanner-buttons-lock</tt>. If
|
||||
it is <tt>SANE_TRUE</tt> then the frontend has access to the scanner buttons.
|
||||
If it is <tt>SANE_FALSE</tt> then access has been denied.
|
||||
|
||||
<p><li>
|
||||
If the button access is allowed the frontend has to do the following about
|
||||
once per second (while not scanning):
|
||||
<ul>
|
||||
<li>
|
||||
The frontend does set option <tt>scanner-buttons-status-update</tt>.
|
||||
The backend checks if access to the buttons is allowed by comparing
|
||||
the backend PID with the lockfile PID. If access is allowed it
|
||||
does read the button status from the scanner and stores it in
|
||||
the option <tt>scanner-buttons-status</tt>, each bit represents a button, a
|
||||
value of 0 means the button is not pressed, a value of 1 means that the button
|
||||
is pressed. When the scanner is busy the backend must not wait, it has to
|
||||
return immediately and the button state keeps unchanged.
|
||||
The backend has to implement a timeout function. When no button has been pressed
|
||||
within a predefined time (e.g. 15 minutes) then the access permission is lost.
|
||||
In this case the backend does set option <tt>scanner-buttons-lock</tt> to <tt>SANE_FALSE</tt>
|
||||
and does set <tt>SANE_INFO_RELOAD_OPTIONS</tt> to inform the frontend that it has
|
||||
lost permission to access the scanner-button functions.
|
||||
If access is not allowed it does set the <tt>scanner-buttons-status</tt> to 0.
|
||||
|
||||
<p> <li>
|
||||
The frontend does read the value of option <tt>scanner-buttons-status</tt>
|
||||
</ul>
|
||||
|
||||
<p><li>
|
||||
When the frontend does exit or it does not want to use the buttons
|
||||
it does set option <tt>scanner-buttons-lock</tt> to <tt>SANE_FALSE</tt>.
|
||||
The backend does check if the backend PID and the lockfile PID are
|
||||
the same. If this is true then it removes the lockfile and sets the value
|
||||
of <tt>scanner-buttons-lock</tt> to <tt>SANE_FALSE</tt>.
|
||||
|
||||
<p><tt>sane_close()</tt> should do the same as setting option
|
||||
<tt>scanner-buttons-lock</tt> to <tt>SANE_FALSE</tt>.
|
||||
|
||||
<p></ul>
|
||||
</font>
|
||||
|
||||
<p><font color="darkgreen">
|
||||
<h3><a name="s4.5.15">4.5.15 Batch Scan Options</a></h3><a name="i139">
|
||||
|
||||
<p>The batch scan options can be used by a frontend to indicate that more than
|
||||
one image will be scanned in a batch. The backend can optimize for such scans
|
||||
by e.g. avoiding calibration and not moving home the sensor array in this case.
|
||||
The backend provides the options <tt>batch-scan</tt>,
|
||||
<tt>batch-scan-next-tl-x</tt>, <tt>batch-scan-next-tl-y</tt>,
|
||||
<tt>batch-scan-next-br-x</tt>, and <tt>batch-scan-next-br-y</tt>. The option
|
||||
<tt>batch-scan</tt> provides a string list with the values of <tt>No</tt> if
|
||||
batch scanning isn't used, <tt>Start</tt> for the first, <tt>End</tt> for the last
|
||||
and <tt>Loop</tt> for any other (intermediate) image. The batch-scan-next
|
||||
options specify the coordinates of the next scan and follow the same rules as
|
||||
the scan area options (see section <a href="doc014.html#s4.5.4">4.5.4</a>).
|
||||
|
||||
<p>These options are not mandatory, but if a backend does support them, it must
|
||||
implement them in a manner consistent with the above definition. In this
|
||||
case, all options must be implemented.
|
||||
</font>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc015.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc013.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,82 @@
|
|||
<html><body>
|
||||
<a href="doc016.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc014.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Network Protocol</title>
|
||||
<h1><a name="s5">5 Network Protocol</a></h1>
|
||||
|
||||
<p>The SANE interface has been designed to facilitate network access to
|
||||
image acquisition devices. In particular, most SANE implementations
|
||||
are expected to support a network backend (net client) and a
|
||||
corresponding network daemon (net server) that allows accessing image
|
||||
acquisition devices through a network connection. Network access is
|
||||
useful in several situations:
|
||||
<ul>
|
||||
|
||||
<p><li>To provide controlled access to resources that are inaccessible
|
||||
to a regular user. For example, a user may want to access a device
|
||||
on a host where she has no account on. With the network protocol,
|
||||
it is possible to allow certain users to access scanners without
|
||||
giving them full access to the system.
|
||||
|
||||
<p> Controlling access through the network daemon can be useful even in
|
||||
the local case: for example, certain backends may require root
|
||||
privileges to access a device. Rather than installing each frontend
|
||||
as setuid-root, a system administrator could instead install the
|
||||
SANE network daemon as setuid-root. This enables regular users to
|
||||
access the privileged device through the SANE daemon (which,
|
||||
presumably, supports a more fine-grained access control mechanism
|
||||
than the simple setuid approach). This has the added benefit that
|
||||
the system administrator only needs to trust the SANE daemon, not
|
||||
each and every frontend that may need access to the privileged
|
||||
device.
|
||||
|
||||
<p><li>Network access provides a sense of ubiquity of the available
|
||||
image acquisition devices. For example, in a local area network
|
||||
environment, this allows a user to log onto any machine and have
|
||||
convenient access to any resource available to any machine on the
|
||||
network (subject to permission constraints).
|
||||
|
||||
<p><li>For devices that do not require physical access when used (e.g.,
|
||||
video cameras), network access allows a user to control and use
|
||||
these devices without being in physical proximity. Indeed, if such
|
||||
devices are connected to the Internet, access from any place in the
|
||||
world is possible.
|
||||
|
||||
<p></ul>
|
||||
|
||||
<p>The network protocol described in this chapter has been design with
|
||||
the following goals in mind:
|
||||
<ol>
|
||||
|
||||
<p><li>Image transmission should be efficient (have low encoding
|
||||
overhead).
|
||||
|
||||
<p><li>Accessing option descriptors on the client side must be
|
||||
efficient (since this is a very common operation).
|
||||
|
||||
<p><li>Other operations, such as setting or inquiring the value of an
|
||||
option are less performance critical since they typically require
|
||||
explicit user action.
|
||||
|
||||
<p><li>The network protocol should be simple and easy to implement on
|
||||
any host architecture and any programming language.
|
||||
|
||||
<p></ol>
|
||||
The SANE protocol can be run across any transport protocol that
|
||||
provides reliable data delivery. While SANE does not specify a
|
||||
specific transport protocol, it is expected that TCP/IP will be among
|
||||
the most commonly used protocols.
|
||||
|
||||
<p><h2><a href="doc016.html">5.1 Data Type Encoding</a></h2><h2><a href="doc017.html">5.2 Remote Procedure Call Requests</a></h2><p><hr>
|
||||
<a href="doc016.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc014.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,89 @@
|
|||
<html><body>
|
||||
<a href="doc017.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc015.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Data Type Encoding</title>
|
||||
<h2><a name="s5.1">5.1 Data Type Encoding</a></h2>
|
||||
|
||||
<p><h3><a name="s5.1.1">5.1.1 Primitive Data Types</a></h3>
|
||||
|
||||
<p>The four primitive types of the SANE standard are encoded as follows:
|
||||
<dl>
|
||||
|
||||
<p><dt><tt>SANE_Byte<a name="i140"></tt>:<dd> A byte is encoded as an 8 bit value.
|
||||
Since the transport protocol is assumed to be byte-orientd, the bit
|
||||
order is irrelevant.
|
||||
|
||||
<p><dt><tt>SANE_Word<a name="i141"></tt>:<dd> A word is encoded as 4 bytes (32
|
||||
bits). The bytes are ordered from most-significant to
|
||||
least-significant byte (big-endian byte-order).
|
||||
|
||||
<p><dt><tt>SANE_Char<a name="i142"></tt>:<dd> A character is currently encoded as an 8-bit
|
||||
ISO LATIN-1 value. An extension to support wider character sets (16 or 32
|
||||
bits) is planned for the future, but not supported at this point.
|
||||
|
||||
<p><dt><tt>SANE_String<a name="i143"></tt>:<dd> A string pointer is encoded as a
|
||||
<tt>SANE_Char</tt> array. The trailing NUL byte is considered part
|
||||
of the array and a <tt>NULL</tt> pointer is encoded as a zero-length
|
||||
array.
|
||||
|
||||
<dt><tt>SANE_Handle<a name="i144"></tt>:<dd> A handle is encoded like a word.
|
||||
The network backend needs to take care of converting these integer
|
||||
values to the opaque pointer values that are presented to the user
|
||||
of the network backend. Similarly, the SANE daemon needs to take
|
||||
care of converting the opaque pointer values it receives from its
|
||||
backends into 32-bit integers suitable for use for network encoding.
|
||||
|
||||
<p><dt><em>enumeration types<a name="i145"></em>:<dd> Enumeration types are encoded
|
||||
like words.
|
||||
|
||||
<p></dl>
|
||||
|
||||
<p><h3><a name="s5.1.2">5.1.2 Type Constructors</a></h3>
|
||||
|
||||
<p>Closely following the type constructors of the C language, the SANE network
|
||||
protocol supports the following four constructors:
|
||||
<dl>
|
||||
|
||||
<p><dt><em>pointer<a name="i146"></em>:<dd> A pointer is encoded by a word that indicates
|
||||
whether the pointer is a NULL-pointer which is then followed by the
|
||||
value that the pointer points to (in the case of a non-NULL pointer;
|
||||
in the case of a NULL pointer, no bytes are encoded for the pointer
|
||||
value).
|
||||
|
||||
<p><dt><em>array<a name="i147"></em>:<dd> An array is encoded by a word that indicates
|
||||
the length of the array followed by the values of the elements in
|
||||
the array. The length may be zero in which case no bytes are
|
||||
encoded for the element values.
|
||||
|
||||
<p><dt><em>structure<a name="i148"></em>:<dd> A structure is encoded by simply encoding the
|
||||
structure members in the order in which they appear in the
|
||||
corresponding C type declaration.
|
||||
|
||||
<p><dt><em>union<a name="i149"></em>:<dd> A union must always be accompanied by a tag
|
||||
value that indicates which of the union members is the currently the
|
||||
active one. For this reason, the union itself is encoded simply by
|
||||
encoding the value of the currently active member.
|
||||
|
||||
<p></dl>
|
||||
|
||||
<p>Note that for type constructors, the pointer, element, or member
|
||||
values themselves may have a constructed type. Thus, the above rules
|
||||
should be applied recursively until a sequence of primitive types has
|
||||
been found.
|
||||
|
||||
<p>Also SANE had no need for encoding of circular structures. This
|
||||
greatly simplifies the network protocol.
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc017.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc015.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,460 @@
|
|||
<html><body>
|
||||
<a href="doc018.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc016.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Remote Procedure Call Requests</title>
|
||||
<h2><a name="s5.2">5.2 Remote Procedure Call Requests</a></h2>
|
||||
|
||||
<p>The SANE network protocol is a client/server-style remote procedure
|
||||
call (RPC) protocol. This means that all activity is initiated by the
|
||||
client side (the network backend)---a server is restricted to
|
||||
answering request by the client.
|
||||
|
||||
<p><h3><a name="s5.2.1">5.2.1 <tt>SANE_NET_INIT<a name="i150"></tt></a></h3>
|
||||
|
||||
<p>This RPC establishes a connection to a particular SANE network daemon.
|
||||
It must be the first call in a SANE network session. The parameter
|
||||
and reply arguments for this call are shown in the table below:
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word version_code</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_String user_name</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word version_code</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>version_code</tt> argument in the request is the SANE
|
||||
version-code of the network backend that is contacting the network
|
||||
daemon (see Section <a href="doc010.html#s4.1">4.1</a>). The
|
||||
``build-revision'' in the version code is used to hold the network
|
||||
protocol version. The SANE network daemon receiving such a request
|
||||
must make sure that the network protocol version corresponds to a
|
||||
supported version since otherwise the encoding of the network stream
|
||||
may be incompatible (even though the SANE interface itself may be
|
||||
compatible). The <tt>user_name</tt> argument is the name of the user
|
||||
on whose behalf this call is being performed. If the network backend
|
||||
cannot determine a user-name, it passes a <tt>NULL</tt> pointer for this
|
||||
argument. No trust should be placed in the authenticity of this
|
||||
user-name. The intent of this string is to provide more convenience
|
||||
to the user. E.g., it could be used as the default-user name in
|
||||
subsequent authentication calls.
|
||||
|
||||
<p>In the reply, <tt>status</tt> indicates the completion status. If the
|
||||
value is anything other than <tt>SANE_STATUS_SUCCESS</tt>, the
|
||||
remainder of the reply has undefined values.<a name="F2"><a href="footnotes.html#000002"><sup><fontsize=-2>2</font></sup></a></a> The <tt>version_code</tt> argument returns the
|
||||
SANE version-code that the network daemon supports. See the comments
|
||||
in the previous paragraph on the meaning of the build-revision in this
|
||||
version code.
|
||||
|
||||
<p><h3><a name="s5.2.2">5.2.2 <tt>SANE_NET_GET_DEVICES<a name="i152"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to obtain the list of devices accessible by the SANE
|
||||
daemon.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>void</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Device ***device_list</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
There are no arguments in the request for this call.
|
||||
|
||||
<p>In the reply, <tt>status</tt> indicates the completion status. If the
|
||||
value is anything other than <tt>SANE_STATUS_SUCCESS</tt>, the
|
||||
remainder of the reply has undefined values. The <tt>device_list</tt>
|
||||
argument is a pointer to a <tt>NULL</tt>-terminated array of
|
||||
<tt>SANE_Device</tt> pointers.
|
||||
|
||||
<p><h3><a name="s5.2.3">5.2.3 <tt>SANE_NET_OPEN<a name="i154"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to open a connection to a remote SANE device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_String device_name</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word handle</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_String resource</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>device_name</tt> argument specifies the name of the device to
|
||||
open.
|
||||
|
||||
<p>In the reply, <tt>status</tt> indicates the completion status. If the
|
||||
value is anything other than <tt>SANE_STATUS_SUCCESS</tt>, the
|
||||
remainder of the reply has undefined values. The <tt>handle</tt>
|
||||
argument specifies the device handle that uniquely identifies the
|
||||
connection. The <tt>resource</tt> argument is used to request
|
||||
authentication. If it has a non-<tt>NULL</tt> value, the network
|
||||
backend should authenticate the specified resource and then retry this
|
||||
operation (see Section <a href="doc017.html#s5.2.10">5.2.10</a> for details on how to
|
||||
authorize a resource).
|
||||
|
||||
<p><h3><a name="s5.2.4">5.2.4 <tt>SANE_NET_CLOSE<a name="i156"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to close a connection to a remote SANE device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word dummy</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the connection that should be
|
||||
closed.
|
||||
|
||||
<p>In the reply, the <tt>dummy</tt> argument is unused. Its purpose is to
|
||||
ensure proper synchronization (without it, a net client would not be
|
||||
able to determine when the RPC has completed).
|
||||
|
||||
<p><h3><a name="s5.2.5">5.2.5 <tt>SANE_NET_GET_OPTION_DESCRIPTORS<a name="i158"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to obtain <em>all</em> the option descriptors for a
|
||||
remote SANE device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>Option_Descriptor_Array odesc</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the remote device whose option
|
||||
descriptors should be obtained.
|
||||
|
||||
<p>In the reply, the <tt>odesc</tt> argument is used to return the array of
|
||||
option descriptors. The option descriptor array has the following
|
||||
structure:
|
||||
<blockquote><a name="i160">
|
||||
<pre>
|
||||
struct Option_Descriptor_Array
|
||||
{
|
||||
SANE_Word num_options;
|
||||
SANE_Option_Descriptor **desc;
|
||||
};
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p><h3><a name="s5.2.6">5.2.6 <tt>SANE_NET_CONTROL_OPTION<a name="i161"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to control (inquire, set, or set to automatic) a
|
||||
specific option of a remote SANE device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Status status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word option</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word info</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word action</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word value_type</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word value_type</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word value_size</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word value_size</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>void *value</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>void *value</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_String *resource</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the remote device whose option
|
||||
should be controlled. Argument <tt>option</tt> is the number (index) of
|
||||
the option that should be controlled. Argument <tt>action</tt>
|
||||
specifies what action should be taken (get, set, or set automatic).
|
||||
Argument <tt>value_type</tt> specifies the type of the option value
|
||||
(must be one of <tt>SANE_TYPE_BOOL</tt>, <tt>SANE_TYPE_INT</tt>,
|
||||
<tt>SANE_TYPE_FIXED</tt>, <tt>SANE_TYPE_STRING</tt>,
|
||||
<tt>SANE_TYPE_BUTTON</tt>). Argument <tt>value_size</tt> specifies
|
||||
the size of the option value in number of bytes (see
|
||||
Section <a href="doc011.html#s4.2.9.6">4.2.9.6</a> for the precise meaning of this value).
|
||||
Finally, argument <tt>value</tt> is a pointer to the option value. It
|
||||
must be a writeable area that is at least <tt>value_size</tt> bytes
|
||||
large. (Note that this area must be writable even if the action is to
|
||||
set the option value. This is because the backend may not be able to
|
||||
set the exact option value, in which case the option value is used to
|
||||
return the next best value that the backend has chosen.)
|
||||
|
||||
<p>In the reply, argument <tt>resource</tt> is set to the name of the
|
||||
resource that must be authorized before this call can be retried. If
|
||||
this value is non-<tt>NULL</tt>, all other arguments have undefined
|
||||
values (see Section <a href="doc017.html#s5.2.10">5.2.10</a> for details on how to
|
||||
authorize a resource). Argument <tt>status</tt> indicates the
|
||||
completion status. If the value is anything other than
|
||||
<tt>SANE_STATUS_SUCCESS</tt>, the remainder of the reply has undefined
|
||||
values. The <tt>info</tt> argument returns the information on how well
|
||||
the backend was able to satisfy the request. For details, see the
|
||||
description of the corresponding argument in
|
||||
Section <a href="doc012.html#s4.3.7">4.3.7</a>. Arguments <tt>value_type</tt> and
|
||||
<tt>value_size</tt> have the same values as the arguments by the same
|
||||
name in corresponding request. The values are repeated here to ensure
|
||||
that both the request and the reply are self-contained (i.e., they can
|
||||
be encoded and decoded independently). Argument <tt>value</tt> is holds
|
||||
the value of the option that has become effective as a result of this
|
||||
RPC.
|
||||
|
||||
<p><h3><a name="s5.2.7">5.2.7 <tt>SANE_NET_GET_PARAMETERS<a name="i163"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to obtain the scan parameters of a remote SANE
|
||||
device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Status status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Parameters params</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the connection to the remote
|
||||
device whose scan parameters should be returned.
|
||||
|
||||
<p>In the reply, <tt>status</tt> indicates the completion status. If the
|
||||
value is anything other than <tt>SANE_STATUS_SUCCESS</tt>, the
|
||||
remainder of the reply has undefined values. The argument
|
||||
<tt>params</tt> is used to return the scan parameters.
|
||||
|
||||
<p><h3><a name="s5.2.8">5.2.8 <tt>SANE_NET_START<a name="i165"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to start image acquisition (scanning).
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Status status</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word port</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word byte_order</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_String resource</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the connection to the remote
|
||||
device from which the image should be acquired.
|
||||
|
||||
<p>In the reply, argument <tt>resource</tt> is set to the name of the
|
||||
resource that must be authorized before this call can be retried. If
|
||||
this value is non-<tt>NULL</tt>, all other arguments have undefined
|
||||
values (see Section <a href="doc017.html#s5.2.10">5.2.10</a> for details on how to
|
||||
authorize a resource). Argument, <tt>status</tt> indicates the
|
||||
completion status. If the value is anything other than
|
||||
<tt>SANE_STATUS_SUCCESS</tt>, the remainder of the reply has
|
||||
undefined values. The argument <tt>port</tt> returns the port number
|
||||
from which the image data will be available. To read the image data,
|
||||
a network client must connect to the remote host at the indicated port
|
||||
number. Through this port, the image data is transmitted as a
|
||||
sequence of data records. Each record starts with the data length in
|
||||
bytes. The data length is transmitted as a sequence of four bytes.
|
||||
These bytes should be interpreted as an unsigned integer in big-endian
|
||||
format. The four length bytes are followed by the number of data
|
||||
bytes indicated by the length. Except for byte-order, the data is in
|
||||
the same format as defined for <tt>sane_read()</tt>. Since some
|
||||
records may contain no data at all, a length value of zero is
|
||||
perfectly valid. The special length value of <tt>0xffffffff</tt> is
|
||||
used to indicate the end of the data stream. That is, after receiving
|
||||
a record length of <tt>0xffffffff</tt>, the network client should close
|
||||
the data connection and stop reading data.
|
||||
|
||||
<p>Argument <tt>byte_order</tt> specifies the byte-order of the image
|
||||
data. A value of 0x1234 indicates little-endian format, a value of
|
||||
0x4321 indicates big-endian format. All other values are presently
|
||||
undefined and reserved for future enhancements of this protocol. The
|
||||
intent is that a network server sends data in its own byte-order and
|
||||
the client is responsible for adjusting the byte-order, if necessary.
|
||||
This approach causes no unnecessary overheads in the case where the
|
||||
server and client byte-order match and puts the extra burden on the
|
||||
client side when there is a byte-order mismatch. Putting the burden
|
||||
on the client-side improves the scalability properties of this
|
||||
protocol.
|
||||
|
||||
<p><h3><a name="s5.2.9">5.2.9 <tt>SANE_NET_CANCEL<a name="i167"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to cancel the current operation of a remote SANE
|
||||
device.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_Word handle</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word dummy</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>handle</tt> argument identifies the connection whose operation
|
||||
should be cancelled.
|
||||
|
||||
<p>In the reply, the <tt>dummy</tt> argument is unused. Its purpose is to
|
||||
ensure proper synchronization (without it, a net client would not be
|
||||
able to determine when the RPC has completed).
|
||||
|
||||
<p><h3><a name="s5.2.10">5.2.10 <tt>SANE_NET_AUTHORIZE<a name="i169"></tt></a></h3>
|
||||
<a name="i171">
|
||||
|
||||
<p>This RPC is used to pass authorization data from the net client to the
|
||||
net server.
|
||||
<center>
|
||||
<table cellpadding=0 cellspacing=0>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<b>request:</b> </td>
|
||||
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_String resource</tt> </td>
|
||||
<td colspan=1 align=left nowrap> <tt>SANE_Word dummy</tt> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_String username</tt> </td>
|
||||
<td colspan=1 align=left nowrap> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
<tt>SANE_String password</tt> </td>
|
||||
<td colspan=1 align=left nowrap> </td></tr>
|
||||
<tr valign=top>
|
||||
<td colspan=1 align=left nowrap>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
The <tt>resource</tt> argument specifies the name of the resource to be
|
||||
authorized. This argument should be set to the string returned in the
|
||||
<tt>resource</tt> argument of the RPC reply that required this
|
||||
authorization call. The <tt>username</tt> and <tt>password</tt> are the
|
||||
name of the user that is accessing the resource and the password for
|
||||
the specified resource/user pair.
|
||||
|
||||
<p>Since the password is not encrypted during network transmission, it is
|
||||
recommended to use the following extension:
|
||||
|
||||
<p>If the server adds the string `<tt>$MD5$</tt>' to the resource-name followed
|
||||
by a random string not longer then 128 bytes, the client may answer with the
|
||||
MD5 digest of the concatenation of the password and the random string. To
|
||||
differentiate between the MD5 digest and a strange password the client prepends
|
||||
the MD5 digest with the string `<tt>$MD5$</tt>'.
|
||||
|
||||
<p>In the reply, <tt>dummy</tt> is completely unused. Note that there is
|
||||
no direct failure indication. This is unnecessary since a net client
|
||||
will retry the RPC that resulted in the authorization request until
|
||||
that call succeeds (or until the request is cancelled). The RPC that resulted
|
||||
in the authorization request continues after the reply from the client and may
|
||||
fail with <tt>SANE_STATUS_ACCESS_DENIED</tt>.
|
||||
|
||||
<p><h3><a name="s5.2.11">5.2.11 <tt>SANE_NET_EXIT<a name="i172"></tt></a></h3>
|
||||
|
||||
<p>This RPC is used to disconnect a net client from a net server. There
|
||||
are no request or reply arguments in this call. As a result of this
|
||||
call, the connection between the client and the server that was
|
||||
established by the <tt>SANE_NET_INIT</tt> call will be closed.
|
||||
|
||||
<p>
|
||||
|
||||
<p><p><hr>
|
||||
<a href="doc018.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc016.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
<html><body>
|
||||
<a href="doc019.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc017.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
|
||||
<title>Contact Information</title>
|
||||
<h1><a name="s6">6 Contact Information</a></h1>
|
||||
|
||||
<p>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.
|
||||
<blockquote><a name="i174">
|
||||
<pre>
|
||||
sane-devel-request@mostang.com
|
||||
</pre>
|
||||
</blockquote>
|
||||
To subscribe, send a mail with the body ``<tt>subscribe sane-devel</tt>'' to the
|
||||
above address.
|
||||
|
||||
<p>A complete list of commands supported can be obtained by sending a
|
||||
mail with a subject of ``<tt>help</tt>'' to the above address. The
|
||||
mailing list is archived and available through the SANE home page at
|
||||
URL:
|
||||
<blockquote>
|
||||
<a href="http://www.mostang.com/sane/">http://www.mostang.com/sane/</a>
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
<p><hr>
|
||||
<a href="doc019.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc017.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,212 @@
|
|||
<html><body>
|
||||
<img src=../icons/next_gr.gif border=2 alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc018.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
<h1>Index</h1>
|
||||
|
||||
|
||||
<p><multicol cols=2>
|
||||
<p><a href="doc014.html#i133">analog gamma option</a><br>
|
||||
<a href="doc016.html#i147">array</a><br>
|
||||
|
||||
<p><a href="doc014.html#i139">Batch Scan Options</a><br>
|
||||
<a href="doc014.html#i128">bit depth option</a><br>
|
||||
<a href="doc014.html#i126">br-x</a><br>
|
||||
<a href="doc014.html#i127">br-y</a><br>
|
||||
|
||||
<p><a href="doc013.html#i117">code flow</a><br>
|
||||
|
||||
<p><a href="doc011.html#i43">device-name</a><br>
|
||||
<a href="doc012.html#i82">domain</a><br>
|
||||
|
||||
<p><a href="doc016.html#i145">enumeration types</a><br>
|
||||
|
||||
<p><a href="doc014.html#i132">gamma table options</a><br>
|
||||
|
||||
<p><a href="doc014.html#i135">hightlight options</a><br>
|
||||
|
||||
<p><a href="doc008.html#i0">image data format</a><br>
|
||||
|
||||
<p><a href="doc014.html#i137">lamp-off option</a><br>
|
||||
<a href="doc014.html#i136">lamp-on option</a><br>
|
||||
|
||||
<p><a href="doc018.html#i174">mailing list</a><br>
|
||||
<a href="doc014.html#i129">mode options</a><br>
|
||||
|
||||
<p><a href="doc017.html#i171">network authorization</a><br>
|
||||
<a href="doc011.html#i26">NUL</a><br>
|
||||
|
||||
<p><a href="doc014.html#i119">option count</a><br>
|
||||
<a href="doc017.html#i160">Option_Descriptor_Array</a><br>
|
||||
|
||||
<p><a href="doc012.html#i84">password</a><br>
|
||||
<a href="doc016.html#i146">pointer</a><br>
|
||||
<a href="doc014.html#i122">preview mode</a><br>
|
||||
|
||||
<p><a href="doc014.html#i121">resolution option</a><br>
|
||||
|
||||
<p><a href="doc012.html#i91">SANE_Action</a><br>
|
||||
<a href="doc012.html#i92">SANE_ACTION_GET_VALUE</a><br>
|
||||
<a href="doc012.html#i94">SANE_ACTION_SET_AUTO</a><br>
|
||||
<a href="doc012.html#i93">SANE_ACTION_SET_VALUE</a><br>
|
||||
<a href="doc012.html#i81">SANE_Authorization_Callback</a><br>
|
||||
<a href="doc011.html#i16">SANE_Bool</a><br>
|
||||
<a href="doc011.html#i14">SANE_Byte</a><br>
|
||||
<a href="doc016.html#i140">SANE_Byte</a><br>
|
||||
<a href="doc012.html#i113">sane_cancel</a><br>
|
||||
<a href="doc011.html#i70">SANE_CAP_ADVANCED</a><br>
|
||||
<a href="doc011.html#i72">SANE_CAP_ALWAYS_SETTABLE</a><br>
|
||||
<a href="doc011.html#i68">SANE_CAP_AUTOMATIC</a><br>
|
||||
<a href="doc011.html#i67">SANE_CAP_EMULATED</a><br>
|
||||
<a href="doc011.html#i65">SANE_CAP_HARD_SELECT</a><br>
|
||||
<a href="doc011.html#i71">SANE_CAP_HIDDEN</a><br>
|
||||
<a href="doc011.html#i69">SANE_CAP_INACTIVE</a><br>
|
||||
<a href="doc011.html#i66">SANE_CAP_SOFT_DETECT</a><br>
|
||||
<a href="doc011.html#i64">SANE_CAP_SOFT_SELECT</a><br>
|
||||
<a href="doc011.html#i24">SANE_Char</a><br>
|
||||
<a href="doc016.html#i142">SANE_Char</a><br>
|
||||
<a href="doc012.html#i88">sane_close</a><br>
|
||||
<a href="doc011.html#i74">SANE_CONSTRAINT_NONE</a><br>
|
||||
<a href="doc011.html#i75">SANE_CONSTRAINT_RANGE</a><br>
|
||||
<a href="doc011.html#i78">SANE_CONSTRAINT_STRING_LIST</a><br>
|
||||
<a href="doc011.html#i73">SANE_Constraint_Type</a><br>
|
||||
<a href="doc011.html#i77">SANE_CONSTRAINT_WORD_LIST</a><br>
|
||||
<a href="doc012.html#i90">sane_control_option</a><br>
|
||||
<a href="doc010.html#i11">SANE_CURRENT_MAJOR</a><br>
|
||||
<a href="doc011.html#i42">SANE_Device</a><br>
|
||||
<a href="doc012.html#i85">sane_exit</a><br>
|
||||
<a href="doc011.html#i17">SANE_FALSE</a><br>
|
||||
<a href="doc011.html#i22">SANE_FIX</a><br>
|
||||
<a href="doc011.html#i20">SANE_Fixed</a><br>
|
||||
<a href="doc011.html#i21">SANE_FIXED_SCALE_SHIFT</a><br>
|
||||
<a href="doc012.html#i101">SANE_Frame</a><br>
|
||||
<a href="doc008.html#i7">SANE_FRAME_BLUE</a><br>
|
||||
<a href="doc012.html#i106">SANE_FRAME_BLUE</a><br>
|
||||
<a href="doc008.html#i3">SANE_FRAME_GRAY</a><br>
|
||||
<a href="doc012.html#i102">SANE_FRAME_GRAY</a><br>
|
||||
<a href="doc008.html#i6">SANE_FRAME_GREEN</a><br>
|
||||
<a href="doc012.html#i105">SANE_FRAME_GREEN</a><br>
|
||||
<a href="doc008.html#i2">SANE_FRAME_MIME</a><br>
|
||||
<a href="doc008.html#i10">SANE_FRAME_MIME</a><br>
|
||||
<a href="doc012.html#i109">SANE_FRAME_MIME</a><br>
|
||||
<a href="doc008.html#i1">SANE_FRAME_RAW</a><br>
|
||||
<a href="doc008.html#i8">SANE_FRAME_RAW</a><br>
|
||||
<a href="doc008.html#i9">SANE_FRAME_RAW</a><br>
|
||||
<a href="doc012.html#i107">SANE_FRAME_RAW</a><br>
|
||||
<a href="doc012.html#i108">SANE_FRAME_RAW</a><br>
|
||||
<a href="doc008.html#i5">SANE_FRAME_RED</a><br>
|
||||
<a href="doc012.html#i104">SANE_FRAME_RED</a><br>
|
||||
<a href="doc008.html#i4">SANE_FRAME_RGB</a><br>
|
||||
<a href="doc012.html#i103">SANE_FRAME_RGB</a><br>
|
||||
<a href="doc012.html#i86">sane_get_devices</a><br>
|
||||
<a href="doc012.html#i89">sane_get_option_descriptor</a><br>
|
||||
<a href="doc012.html#i99">sane_get_parameters</a><br>
|
||||
<a href="doc012.html#i115">sane_get_select_fd</a><br>
|
||||
<a href="doc011.html#i28">SANE_Handle</a><br>
|
||||
<a href="doc016.html#i144">SANE_Handle</a><br>
|
||||
<a href="doc012.html#i95">SANE_INFO_INEXACT</a><br>
|
||||
<a href="doc012.html#i98">SANE_INFO_INVALIDATE_PREVIEW</a><br>
|
||||
<a href="doc012.html#i96">SANE_INFO_RELOAD_OPTIONS</a><br>
|
||||
<a href="doc012.html#i111">SANE_INFO_RELOAD_OPTIONS</a><br>
|
||||
<a href="doc012.html#i97">SANE_INFO_RELOAD_PARAMS</a><br>
|
||||
<a href="doc012.html#i80">sane_init</a><br>
|
||||
<a href="doc011.html#i19">SANE_Int</a><br>
|
||||
<a href="doc017.html#i169">SANE_NET_AUTHORIZE</a><br>
|
||||
<a href="doc017.html#i170">SANE_NET_AUTHORIZE</a><br>
|
||||
<a href="doc017.html#i167">SANE_NET_CANCEL</a><br>
|
||||
<a href="doc017.html#i168">SANE_NET_CANCEL</a><br>
|
||||
<a href="doc017.html#i156">SANE_NET_CLOSE</a><br>
|
||||
<a href="doc017.html#i157">SANE_NET_CLOSE</a><br>
|
||||
<a href="doc017.html#i161">SANE_NET_CONTROL_OPTION</a><br>
|
||||
<a href="doc017.html#i162">SANE_NET_CONTROL_OPTION</a><br>
|
||||
<a href="doc017.html#i172">SANE_NET_EXIT</a><br>
|
||||
<a href="doc017.html#i173">SANE_NET_EXIT</a><br>
|
||||
<a href="doc017.html#i152">SANE_NET_GET_DEVICES</a><br>
|
||||
<a href="doc017.html#i153">SANE_NET_GET_DEVICES</a><br>
|
||||
<a href="doc017.html#i158">SANE_NET_GET_OPTION_DESCRIPTORS</a><br>
|
||||
<a href="doc017.html#i159">SANE_NET_GET_OPTION_DESCRIPTORS</a><br>
|
||||
<a href="doc017.html#i163">SANE_NET_GET_PARAMETERS</a><br>
|
||||
<a href="doc017.html#i164">SANE_NET_GET_PARAMETERS</a><br>
|
||||
<a href="doc017.html#i150">SANE_NET_INIT</a><br>
|
||||
<a href="doc017.html#i151">SANE_NET_INIT</a><br>
|
||||
<a href="doc017.html#i154">SANE_NET_OPEN</a><br>
|
||||
<a href="doc017.html#i155">SANE_NET_OPEN</a><br>
|
||||
<a href="doc017.html#i165">SANE_NET_START</a><br>
|
||||
<a href="doc017.html#i166">SANE_NET_START</a><br>
|
||||
<a href="doc012.html#i87">sane_open</a><br>
|
||||
<a href="doc011.html#i46">SANE_Option_Descriptor</a><br>
|
||||
<a href="doc011.html#i62">SANE_OPTION_IS_ACTIVE</a><br>
|
||||
<a href="doc011.html#i63">SANE_OPTION_IS_SETTABLE</a><br>
|
||||
<a href="doc012.html#i100">SANE_Parameters</a><br>
|
||||
<a href="doc011.html#i76">SANE_Range</a><br>
|
||||
<a href="doc012.html#i112">sane_read</a><br>
|
||||
<a href="doc012.html#i114">sane_set_io_mode</a><br>
|
||||
<a href="doc012.html#i110">sane_start</a><br>
|
||||
<a href="doc011.html#i29">SANE_Status</a><br>
|
||||
<a href="doc011.html#i41">SANE_STATUS_ACCESS_DENIED</a><br>
|
||||
<a href="doc011.html#i32">SANE_STATUS_CANCELLED</a><br>
|
||||
<a href="doc011.html#i38">SANE_STATUS_COVER_OPEN</a><br>
|
||||
<a href="doc011.html#i33">SANE_STATUS_DEVICE_BUSY</a><br>
|
||||
<a href="doc011.html#i35">SANE_STATUS_EOF</a><br>
|
||||
<a href="doc011.html#i30">SANE_STATUS_GOOD</a><br>
|
||||
<a href="doc012.html#i79">SANE_STATUS_GOOD</a><br>
|
||||
<a href="doc011.html#i34">SANE_STATUS_INVAL</a><br>
|
||||
<a href="doc011.html#i39">SANE_STATUS_IO_ERROR</a><br>
|
||||
<a href="doc011.html#i36">SANE_STATUS_JAMMED</a><br>
|
||||
<a href="doc011.html#i37">SANE_STATUS_NO_DOCS</a><br>
|
||||
<a href="doc011.html#i40">SANE_STATUS_NO_MEM</a><br>
|
||||
<a href="doc011.html#i31">SANE_STATUS_UNSUPPORTED</a><br>
|
||||
<a href="doc011.html#i25">SANE_String</a><br>
|
||||
<a href="doc016.html#i143">SANE_String</a><br>
|
||||
<a href="doc011.html#i27">SANE_String_Const</a><br>
|
||||
<a href="doc012.html#i116">sane_strstatus</a><br>
|
||||
<a href="doc011.html#i18">SANE_TRUE</a><br>
|
||||
<a href="doc011.html#i48">SANE_TYPE_BOOL</a><br>
|
||||
<a href="doc011.html#i52">SANE_TYPE_BUTTON</a><br>
|
||||
<a href="doc011.html#i50">SANE_TYPE_FIXED</a><br>
|
||||
<a href="doc011.html#i53">SANE_TYPE_GROUP</a><br>
|
||||
<a href="doc011.html#i49">SANE_TYPE_INT</a><br>
|
||||
<a href="doc011.html#i51">SANE_TYPE_STRING</a><br>
|
||||
<a href="doc011.html#i54">SANE_Unit</a><br>
|
||||
<a href="doc011.html#i23">SANE_UNFIX</a><br>
|
||||
<a href="doc011.html#i57">SANE_UNIT_BIT</a><br>
|
||||
<a href="doc011.html#i59">SANE_UNIT_DPI</a><br>
|
||||
<a href="doc011.html#i61">SANE_UNIT_MICROSECOND</a><br>
|
||||
<a href="doc011.html#i58">SANE_UNIT_MM</a><br>
|
||||
<a href="doc011.html#i55">SANE_UNIT_NONE</a><br>
|
||||
<a href="doc011.html#i60">SANE_UNIT_PERCENT</a><br>
|
||||
<a href="doc011.html#i56">SANE_UNIT_PIXEL</a><br>
|
||||
<a href="doc011.html#i47">SANE_Value_Type</a><br>
|
||||
<a href="doc010.html#i12">SANE_VERSION_CODE</a><br>
|
||||
<a href="doc010.html#i13">SANE_VERSION_MAJOR</a><br>
|
||||
<a href="doc011.html#i15">SANE_Word</a><br>
|
||||
<a href="doc016.html#i141">SANE_Word</a><br>
|
||||
<a href="doc014.html#i123">scan area options</a><br>
|
||||
<a href="doc014.html#i120">scan resolution</a><br>
|
||||
<a href="doc014.html#i138">scanner button options</a><br>
|
||||
<a href="doc014.html#i134">shadow options</a><br>
|
||||
<a href="doc014.html#i130">source options</a><br>
|
||||
<a href="doc016.html#i148">structure</a><br>
|
||||
|
||||
<p><a href="doc014.html#i131">threshold option</a><br>
|
||||
<a href="doc014.html#i124">tl-x</a><br>
|
||||
<a href="doc014.html#i125">tl-y</a><br>
|
||||
<a href="doc011.html#i45">Type Strings</a><br>
|
||||
|
||||
<p><a href="doc016.html#i149">union</a><br>
|
||||
<a href="doc012.html#i83">username</a><br>
|
||||
|
||||
<p><a href="doc011.html#i44">Vendor Strings</a><br>
|
||||
|
||||
<p><a href="doc014.html#i118">well-known options</a><br>
|
||||
</multicol><p><hr>
|
||||
<img src=../icons/next_gr.gif border=2 alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc018.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
<title>Footnotes</title><h1>Footnotes</h1><p>
|
||||
|
||||
<hr><p><b><a href="doc011.html#F1">1</a></b> This is different from ANSI C where
|
||||
any non-zero integer value represents logical TRUE.
|
||||
<hr><p><b><a href="doc017.html#F2">2</a></b> The sane network
|
||||
daemon should be careful not to leak information in the undefined
|
||||
portion of the reply.
|
||||
Plik binarny nie jest wyświetlany.
|
Po Szerokość: | Wysokość: | Rozmiar: 6.8 KiB |
Plik binarny nie jest wyświetlany.
|
Po Szerokość: | Wysokość: | Rozmiar: 1011 B |
Plik binarny nie jest wyświetlany.
|
Po Szerokość: | Wysokość: | Rozmiar: 1.8 KiB |
Plik binarny nie jest wyświetlany.
|
Po Szerokość: | Wysokość: | Rozmiar: 9.3 KiB |
Plik binarny nie jest wyświetlany.
|
Po Szerokość: | Wysokość: | Rozmiar: 2.2 KiB |
|
|
@ -0,0 +1,63 @@
|
|||
<html><body>
|
||||
<a href="doc002.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc000.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
<title>./sane</title>
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
<p>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
<p><center><h1><font size=+4>SANE Standard Version 2.0 proposal 0.08 - rauch/beck</font></h1></center>
|
||||
<center></center>
|
||||
<center>Dec 8, 2002</center>
|
||||
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
|
||||
<p><h1><a href="doc002.html">1 Preface</a></h1><h1><a href="doc004.html">2 Introduction</a></h1><h1><a href="doc006.html">3 The SANE Environment</a></h1><h1><a href="doc009.html">4 The SANE Application Programmer Interface (API)</a></h1><h1><a href="doc015.html">5 Network Protocol</a></h1><h1><a href="doc018.html">6 Contact Information</a></h1><p><hr>
|
||||
<a href="doc002.html"><img src=../icons/next.gif alt="Next"></a>
|
||||
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
||||
<a href="doc000.html"><img src=../icons/previous.gif alt="Previous"></a>
|
||||
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
||||
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
||||
<hr>
|
||||
</body></html>
|
||||
Plik binarny nie jest wyświetlany.
Plik diff jest za duży
Load Diff
Plik diff jest za duży
Load Diff
|
|
@ -0,0 +1,205 @@
|
|||
Suggestions for changes for sane-api-2 (2002-12-24)
|
||||
|
||||
(x = already included into sane2.tex)
|
||||
|
||||
- SANE_FRAME_*:
|
||||
|
||||
x - SANE_FRAME_RAW, formatdesc="red:8,green:8,blue:8", replaces old SANE_FRAME_* types
|
||||
|
||||
x - SANE_FRAME_MIME, formatdesc=MIME-desciptor, only one frame/image, arbitary data
|
||||
this allows transmission of e.g. jpeg, tiff and any other data format
|
||||
|
||||
x - SANE_FRAME_GRAY/RGB/RED/GREEN/BLUE only allowed for sane-1 backends.
|
||||
|
||||
- remove multi-frame paradigm at all?
|
||||
|
||||
- remove multi-channel 1 Bit mode?
|
||||
|
||||
- define 0 = black for all modes?
|
||||
|
||||
|
||||
- parameter.flags
|
||||
|
||||
x - compatible to sane-1
|
||||
|
||||
x - adds more_images, new_page, front/backside info, 28 more flags available
|
||||
|
||||
x - dpi_x, dpi_y, proposed_filename, formatdesc, channels_per_image
|
||||
|
||||
(x)- 32 bytes for future extension (set to 0)
|
||||
Check how to do this without creating portability nightmares.
|
||||
Keep in mind that the size of SANE_Int is unknown, same is true for
|
||||
SANE_String and even char.
|
||||
|
||||
- define the following well known options:
|
||||
|
||||
x - BIT_DEPTH = Word_List with bits/sample
|
||||
|
||||
x - GAMMA_VECTOR, and GAMMA_VECTOR_[RGB]
|
||||
|
||||
x - RESOLUTION or (X_RESOLUTION and Y_RESOLUTION)
|
||||
|
||||
x - scanmode COLOR, GRAY, LINEART (for frontend defaults, e.g. for fax => Gray)
|
||||
|
||||
x - scansource FLATBED/DOCUMENTFEEDER/TRANSPARENCY
|
||||
|
||||
x - ANALOG_GAMMA
|
||||
|
||||
x - HIGHLIGHT
|
||||
|
||||
x - SHADOW
|
||||
|
||||
x - THRESHOLD
|
||||
|
||||
x - LAMP_CONTROL
|
||||
|
||||
x - Scanner button options and protocol
|
||||
|
||||
- set focus position FOCUS_POS_X, FOCUS_POS_Y
|
||||
|
||||
- multi pass for film scanners
|
||||
- number of passes (either native or EMULATED)
|
||||
SANE_TYPE_INT, word_list or range
|
||||
|
||||
- direct selection of image number?
|
||||
SANE_TYPE_INT
|
||||
|
||||
- exposure time
|
||||
|
||||
x - SANE_CAP_ADVANCED for a group
|
||||
|
||||
x - SANE_CAP_ALWAYS_SETTABLE ??? (xcam/quickcam?)
|
||||
|
||||
x - SANE_CAP_HIDDEN: Don't display option at all
|
||||
|
||||
|
||||
x- add to SANE_Device
|
||||
- email_backend_author (string)
|
||||
- device_location (string)
|
||||
- comment (string)
|
||||
- reserved_string (string)
|
||||
- version_code (integer)
|
||||
- backend_capability_flags (integer)
|
||||
- reserved_int (integer)
|
||||
|
||||
(x)- define recommended file formats for internationalization
|
||||
in sane_i18n definition files:
|
||||
*.po, default translation tables: *.(g)mo
|
||||
|
||||
x- sane_open does return sane_device:
|
||||
A frontend may decide not to call sane_get_devices
|
||||
because it already knows which device shall be
|
||||
opened. In this case it does not get any information
|
||||
about the device (vendor, model, ...). So it makes
|
||||
sense to return the SANE_Device in sane_open
|
||||
|
||||
!- saned or a stand alone "turn lamp off deamon" should get
|
||||
an internal timer to turn off the lamp of some scanners.
|
||||
This has to be defined closer.
|
||||
May be it is necessary to find out how long a scanner
|
||||
has not been used. For this saned needs a function
|
||||
like sane_get_offline_time()...
|
||||
|
||||
!- define a way how multiple scanareas can be handled
|
||||
before the scanning is started:
|
||||
Create well-known options to set the next tl-y
|
||||
|
||||
- define error codes for sane_get_parameters
|
||||
|
||||
x- define return value of sane_init - also necessary for SANE1
|
||||
|
||||
x- define bit order of 1 bit modes - also necessary for SANE1
|
||||
|
||||
!- implementation note for select_fd - also necessary for SANE1
|
||||
|
||||
!- all texts and translations: UTF-8 format
|
||||
(this is used in KDE and gtk+-2.x)
|
||||
may be UTF-8 should be forced as SANE_Char format.
|
||||
|
||||
!- download backend translation and documentation:
|
||||
The Download function does not care about the file
|
||||
format, this propably also has to be defined in the sane standard.
|
||||
- sane_download_backend_file(filename). The backend
|
||||
has to load the file from a fixed directory. The path
|
||||
to the directory has to contain the backend name,
|
||||
e.g: /usr/local/share/sane/sane-umax/
|
||||
The frontend can not change the directory due to security!!!
|
||||
|
||||
!- let backend display a frontend-info or -selection (ok/cancel)
|
||||
dialog-box (e.g. "Calibration in progress: wait 10/9/8/... seconds")
|
||||
this has to be done with a callback, eg.:
|
||||
sane_frontend_dialog_display(**window, text, ok_text, cancel_text, backend_dialog_callback_function)
|
||||
sane_frontend_dialog_close(window)
|
||||
the frontend function has to be implemented in a way that the backend
|
||||
can change the text.
|
||||
A good place to define the callback functions could be sane_init,
|
||||
where already the authorization_callback is defined.
|
||||
|
||||
!- give backend the chance to tell the frontend while/after scan
|
||||
that the options have changed (e.g. film scanner reduces
|
||||
number of available images):
|
||||
may be a flag (comparable to int *i in sane_control_option)
|
||||
Maybe the frontend should reload the decriptors after a scan anyway?
|
||||
|
||||
-- add sane_get_device_info function that allows the frontend
|
||||
to ask for information about all involved backends and meta backends
|
||||
that are used.
|
||||
is this still needed with version_code in sane_device?
|
||||
|
||||
-- sane_extended_call() and sane_extended_callback() ?
|
||||
I don`t like this because it makes it too simple
|
||||
to add proprietary functions that are not defined
|
||||
in the sane standard
|
||||
|
||||
(x)- define what parts in a option_descriptor may be changed after
|
||||
it has been set up and passed to the frontend
|
||||
Maybe add size to list of members that can be changed?
|
||||
Move definition to sane_get_select_fd?
|
||||
|
||||
?- add #define SANE_OPTION_IS_GETTABLE(cap) (((cap) & (SANE_CAP_SOFT_DETECT | SANE_CAP_INACTIVE)) == SANE_CAP_SOFT_DETECT)
|
||||
|
||||
x- define endianess for SANE_FRAME_RAW
|
||||
|
||||
- add a pointer "next" to the device handle to make linked lists instead of arrays(?)
|
||||
|
||||
- when an option is set with sane_control_option that changes the image significantly
|
||||
(e.g. exposure) invalidate the preview by setting SANE_INFO_INVALIDATE_PREVIEW
|
||||
|
||||
x- fix sane_strstatus (remove const)
|
||||
|
||||
- add SANE_String sane_verbose_error(Sane_Handle h), to show backend-specific
|
||||
error messages. The error string always refers to the last error reported by the backend.
|
||||
So the frontend would call this when a SANE API call returned with an error status.
|
||||
E.g. out-of-memory in scanner hardware or "Couldn't open file foo".
|
||||
Check for therad-safety problems. If the handle parameters is used, no errors can
|
||||
be printed before sane_open has succeeded.
|
||||
|
||||
- The network protocoll must be updated to reflect the changes to the SANE standard
|
||||
- there were ideas to use UDP instead of TCP
|
||||
- let the server define a port number for the data port to avoid firewall
|
||||
problems?
|
||||
- maybe it's possible to avoid the data port at all?
|
||||
- add the numbers of the RPCs
|
||||
- check if the callbacks are implemented according to the standard
|
||||
|
||||
- How to name the SANE2 header? sane-2.h or sane2.h?
|
||||
|
||||
- Split sane_cancel and add sane_end()?
|
||||
|
||||
x- Update contact section
|
||||
|
||||
- section with implementation notes (currently in backend-writing.txt).
|
||||
|
||||
- Check grammar & spelling
|
||||
|
||||
- check too long lines
|
||||
|
||||
- check defective references
|
||||
|
||||
- update index
|
||||
|
||||
- Check that all headlines are in capital letters
|
||||
|
||||
x- Changebar for sane_read
|
||||
|
||||
x- check for correct quotation marks
|
||||
Ładowanie…
Reference in New Issue