diff options
Diffstat (limited to 'doc/sane.tex')
| -rw-r--r-- | doc/sane.tex | 1894 |
1 files changed, 1894 insertions, 0 deletions
diff --git a/doc/sane.tex b/doc/sane.tex new file mode 100644 index 0000000..1132576 --- /dev/null +++ b/doc/sane.tex @@ -0,0 +1,1894 @@ +\documentclass[11pt,DVIps]{report} + +\usepackage{times,epsfig,html} +% Not Currently using changebar package so comment out to reduce +% external dependencies. +%\usepackage{changebar} + +\setlength{\parindent}{0pt} +\setlength{\parskip}{1.5ex plus 0.5ex minus 0.5ex} +\setlength{\textwidth}{6.5in} +\setlength{\textheight}{8.5in} +\setlength{\marginparwidth}{0pt} +\setlength{\oddsidemargin}{0pt} +\setlength{\evensidemargin}{0pt} +\setlength{\marginparsep}{0pt} +\addtolength{\topmargin}{-0.75in} + +\title{\huge SANE Standard Version 1.05} +\author{} +\date{2006-04-02} + +\makeindex + +\begin{document} + +\newcommand{\filename}[1]{{\tt #1}} +\newcommand{\code}[1]{{\tt #1}} +\newcommand{\var}[1]{{\it #1}} +\newcommand{\defn}[1]{#1\index{#1}} + +% Uncomment if adding changebars to text +%\begin{latexonly} +% \setcounter{changebargrey}{0} % black change bars +%\end{latexonly} + +\maketitle +\tableofcontents +\listoffigures +\listoftables + + +\chapter{Preface} + +The SANE standard is being developed by a group of free-software +developers. The process is open to the public and comments as well as +suggestions for improvements are welcome. Information on how to join +the SANE development process can be found in Chapter +\ref{chap:contact}. + +The SANE standard is intended to streamline software development by +providing a standard application programming interface to access +raster scanner hardware. This should reduce the number of different +driver implementations, thereby reducing the need for reimplementing +similar code. + + +\section{About This Document} + +This document is intended for developers who are creating either an +application that requires access to raster scanner hardware and for +developers who are implementing a SANE driver. It does not cover +specific implementations of SANE components. Its sole purpose is to +describe and define the SANE application interface that will enable +any application on any platform to interoperate with any SANE backend +for that platform. + +The remainder of this document is organized as follows. +Chapter~\ref{chap:intro} provides introductional material. +Chapter~\ref{chap:environ} presents the environment SANE is designed +for. Chapter~\ref{chap:api} details the SANE Application Programmer +Interface. Chapter~\ref{chap:net} specifies the network protocol that +can be used to implement the SANE API in a network transparent +fashion. Finally, Chapter~\ref{chap:contact} gives information on how +to join the SANE development process. + +\subsection{Typographic Conventions} + +Changes since the last revision of this document are highlighted +like this: + +% \begin{changebar} +% Paragraphs that changed since the last revision of the documention +% are marked like this paragraph. +% \end{changebar} + +\chapter{Introduction}\label{chap:intro} + +SANE is an application programming interface (API) that provides +standardized access to any raster image scanner hardware. The +standardized interface allows to write just one driver for each +scanner device instead of one driver for each scanner and application. +The reduction in the number of required drivers provides significant +savings in development time. More importantly, SANE raises the level +at which applications can work. As such, it will enable applications +that were previously unheard of in the UNIX world. While SANE is +primarily targeted at a UNIX environment, the standard has been +carefully designed to make it possible to implement the API on +virtually any hardware or operating system. + +SANE is an acronym for ``Scanner Access Now Easy.'' Also, the hope is +that SANE is sane in the sense that it will allow easy implementation +of the API while accommodating all features required by today's +scanner hardware and applications. Specifically, SANE should be broad +enough to accommodate devices such as scanners, digital still and +video cameras, as well as virtual devices like image file filters. + +\section{Terminology} + +An application that uses the SANE interface is called a SANE {\em + frontend}. A driver that implements the SANE interface is called a +SANE {\em backend}. A {\em meta backend\/} provides some means to +manage one or more other backends. + + +\chapter{The SANE Environment}\label{chap:environ} + +SANE is defined as a C-callable library interface. Accessing a raster +scanner device typically consists of two phases: first, various +controls of the scanner need to be setup or queried. In the second +phase, one or more images are acquired. + +Since the device controls are widely different from device to device, +SANE provides a generic interface that makes it easy for a frontend to +give a user access to all controls without having to understand each +and every device control. The design principle used here is to +abstract each device control into a SANE {\em option\/}. An option is +a self-describing name/value pair. For example, the brightness +control of a camera might be represented by an option called +\code{brightness} whose value is an integer in the range from 0 to +255. + +With self-describing options, a backend need not be concerned with +{\em presentation\/} issues: the backend simply provides a list of +options that describe all the controls available in the device. +Similarly, there are benefits to the frontend: it need not be +concerned with the {\em meaning\/} of each option. It simply provides +means to present and alter the options defined by the backend. + + +\section{Attaching to a SANE backend} + +The process through which a SANE frontend connects to a backend is +platform dependent. Several possibilities exist: +\begin{itemize} + +\item {\bf Static linking:} A SANE backend may be linked directly into + a frontend. While the simplest method of attaching to a backend, it + is somewhat limited in functionality since the available devices is + limited to the ones for which support has been linked in when the + frontend was built. But even so static linking can be quite useful, + particularly when combined with a backend that can access scanners + via a network. Also, it is possible to support multiple backends + simultaneously by implementing a meta backend that manages several + backends that have been compiled in such a manner that they export + unique function names. For example, a backend called \code{be} + would normally export a function called \code{sane\_read()}. If + each backend would provide such a function, static linking would + fail due to multiple conflicting definitions of the same symbol. + This can be resolved by having backend \code{be} include a + header file that has lines of the form: + \begin{quote} +\begin{verbatim} +#define sane_read be_sane_read +\end{verbatim} + \end{quote} + With definitions of this kind, backend \code{be} will export + function name \code{be\_sane\_read()}. Thus, all backends will + export unique names. As long as a meta backend knows about these + names, it is possible to combine several backends at link time and + select and use them dynamically at runtime. + +\item {\bf Dynamic linking:} A simpler yet more powerful way to + support multiple backends is to exploit dynamic linking on platforms + that support it. In this case, a frontend is linked against a + shared library that implements any SANE backend. Since each + dynamically linked backend exports the same set of global symbols + (all starting with the prefix \code{sane\_}), the dynamic library + that gets loaded at runtime does not necessarily have to be the same + one as one the frontend got linked against. In other words, it is + possible to switch the backend by installing the appropriate backend + dynamic library. + + More importantly, dynamic linking makes it easy to implement a meta + backend that loads other backends {\em on demand}. This is a + powerful mechanism since it allows adding new backends merely by + installing a shared library and updating a configuration file. + +\item {\bf Network connection:} Arguably the ultimate way to attach to + a scanner is by using the network to connect to a backend on a + remote machine. This makes it possible to scan images from any host + in the universe, as long as there is a network connection to that + host and provided the user is permitted to access that scanner. + +\end{itemize} + +\begin{figure}[htbp] + \begin{center} + \leavevmode + \psfig{file=figs/hierarchy.eps,angle=270,width=\textwidth} + \caption{Example SANE Hiearchy} + \label{fig:hierarchy} + \end{center} +\end{figure} + +The above discussion lists just a few ways for frontends to attach to +a backend. It is of course possible to combine these solutions to +provide an entire hierarchy of SANE backends. Such a hierarchy is +depicted in Figure~\ref{fig:hierarchy}. The figure shows that machine +A uses a dynamic-linking based meta backend called \code{dll} to +access the backends called \code{pnm}, \code{mustek}, and \code{net}. +The first two are real backends, whereas the last one is a meta +backend that provides network transparent access to remote scanners. +In the figure, machine B provides non-local access to its scanners +through the SANE frontend called \code{saned}. The \code{saned} in +turn has access to the \code{hp} and \code{autolum} backends through +another instance of the \code{dll} backend. The \code{autolum} meta +backend is used to automatically adjust the luminance (brightness) of +the image data acquired by the camera backend called \code{qcam}. + +Note that a meta backend really is both a frontend and a backend at +the same time. It is a frontend from the viewpoint of the backends +that it manages and a backend from the viewpoint of the frontends that +access it. The name ``meta backend'' was chosen primarily because the +SANE standard describes the interface from the viewpoint of a (real) +frontend. + + +\section{Image Data Format}\label{sec:imageformat}\index{image data format} + +Arguably the most important aspect of an image acquisition system is +how images are represented. The SANE approach is to define a simple +yet powerful representation that is sufficient for vast majority of +applications and devices. While the representation is simple, the +interface has been defined carefully to allow extending it in the +future without breaking backwards compatibility. Thus, it will be +possible to accommodate future applications or devices that were not +anticipated at the time this standard was created. + +A SANE image is a rectangular area. The rectangular area is +subdivided into a number of rows and columns. At the intersection of +each row and column is a quadratic pixel. A pixel consists of one or +more sample values. Each sample value represents one channel (e.g., +the red channel). Each sample value has a certain bit depth. The bit +depth is fixed for the entire image and can be as small as one bit. +Valid bit depths are 1, 8, or 16 bits per sample. If a device's +natural bit depth is something else, it is up to the driver to scale +the sample values appropriately (e.g., a 4 bit sample could be scaled +by a factor of four to represent a sample value of depth 8). + +\subsection{Image Transmission} + +The SANE API transmits an image as a sequence of frames. Each frame +covers the same rectangular area as the entire image, but may contain +only a subset of the channels in the final image. For example, a +red/green/blue image could either be transmitted as a single frame +that contains the sample values for all three channels or it could be +transmitted as a sequence of three frames: the first frame containing +the red channel, the second the green channel, and the third the blue +channel. + +Conceptually, each frame is transmitted a byte at a time. Each byte +may contain 8 sample values (for an image bit depth of 1), one full +sample value (for an image bit depth of 8), or a partial sample value +(for an image bit depth of 16 or bigger). In the latter case, the +bytes of each sample value are transmitted in the machine's native +byte order. For depth 1, the leftmost pixel is stored in the most +significant bit, and the rightmost pixel in the least significant bit. +\begin{quote} + \begin{center} + {\bf Backend Implementation Note} + \end{center} + A network-based meta backend will have to ensure that the byte order + in image data is adjusted appropriately if necessary. For example, + when the meta backend attaches to the server proxy, the proxy may + inform the backend of the server's byte order. The backend can then + apply the adjustment if necessary. In essence, this implements a + ``receiver-makes-right'' approach. +\end{quote} + +\begin{figure}[htbp] + \begin{center} + \leavevmode + \psfig{file=figs/xfer.eps,width=0.5\textwidth} + \caption{Transfer order of image data bytes} + \label{fig:xfer} + \end{center} +\end{figure} + +The order in which the sample values in a frame are transmitted is +illustrated in Figure~\ref{fig:xfer}. As can be seen, the values are +transmitted row by row and each row is transmitted from left-most to +right-most column. The left-to-right, top-to-bottom transmission +order applies when the image is viewed in its normal orientation (as +it would be displayed on a screen, for example). + +If a frame contains multiple channels, then the channels are +transmitted in an interleaved fashion. Figure~\ref{fig:pixels} +illustrates this for the case where a frame contains a complete +red/green/blue image with a bit-depth of 8. For a bit depth of 1, +each byte contains 8 sample values of a {\em single\/} channel. In +other words, a bit depth 1 frame is transmitted in a byte interleaved +fashion. + +\begin{figure}[htbp] + \begin{center} + \leavevmode + \psfig{file=figs/image-data.eps,width=0.8\textwidth} + \caption{Bit and byte order or image data} + \label{fig:pixels} + \end{center} +\end{figure} + +When transmitting an image frame by frame, the frontend needs to know +what part of the image a frame represents (and how many frames it +should expect). For that purpose, the SANE API tags every frame with +a type. This version of the SANE standard supports the following +frame types: +\begin{quote} +\begin{description} + +\item[\code{\defn{SANE\_FRAME\_GRAY}}:] The frame contains a single + channel of data that represents sample values from a spectral band + that covers the human visual range. The image consists of this + frame only. + +\item[\code{\defn{SANE\_FRAME\_RGB}}:] The frame contains three + channels of data that represent sample values from the red, green, + and blue spectral bands. The sample values are interleaved in the + order red, green, and blue. The image consists of this frame only. + +\item[\code{\defn{SANE\_FRAME\_RED}}:] The frame contains one channel + of data that represents sample values from the red spectral band. + The complete image consists of three frames: + \code{SANE\_\-FRA\-ME\_RED}, \code{SANE\_FRAME\_GREEN}, and + \code{SANE\_FRAME\_BLUE}. The order in which the frames are + transmitted chosen by the backend. + +\item[\code{\defn{SANE\_FRAME\_GREEN}}:] The frame contains one + channel of data that represents sample values from the green + spectral band. The complete image consists of three frames: + \code{SANE\_\-FRA\-ME\_RED}, \code{SANE\_FRAME\_GREEN}, and + \code{SANE\_FRAME\_BLUE}. The order in which the frames are + transmitted chosen by the backend. + +\item[\code{\defn{SANE\_FRAME\_BLUE}}:] The frame contains one channel + of data that represents sample values from the blue spectral band. + The complete image consists of three frames: + \code{SANE\_\-FRA\-ME\_RED}, \code{SANE\_FRAME\_GREEN}, and + \code{SANE\_FRAME\_BLUE}. The order in which the frames are + transmitted chosen by the backend. + +\end{description} +\end{quote} + +In frames of type \code{SANE\_FRAME\_GRAY}, when the bit depth is 1 there are +only two sample values possible, 1 represents minimum intensity +(black) and 0 represents maximum intensity (white). For all other bit +depth and frame type combinations, a sample value of 0 represents +minimum intensity and larger values represent increasing intensity. + +The combination of bit depth 1 and \code{SANE\_FRAME\_RGB} (or +\code{SANE\_FRAME\_RED}, \code{SANE\_FRAME\_GREEN}, \code{SANE\_FRAME\_BLUE}) +is rarely used and may not be supported by every frontend. + +\chapter{The SANE Application Programmer Interface (API)}\label{chap:api} + +This Section defines version 1 of the SANE application +programmer interface (API). Any SANE frontend must depend on the +interface defined in this section only. Converseley, any SANE backend +must implement its functionality in accordance with this +specification. The interface as documented here is declared as a C +callable interface in a file called \filename{sane/sane.h}. This file should +normally be included via a C pre-processor directive of the form: +\begin{verbatim} + #include <sane/sane.h> +\end{verbatim} + + +\section{Version Control} + +The SANE standard is expected to evolve over time. Whenever a change +to the SANE standard is made that may render an existing frontend or +backend incompatible with the new standard, the major version number +must be increased. Thus, any frontend/backend pair is compatible +provided the major version number of the SANE standard they implement +is the same. A frontend may implement backwards compatiblity by +allowing major numbers that are smaller than the expected major number +(provided the frontend really can cope with the older version). In +contrast, a backend always provides support for one and only one +version of the standard. If a specific application does require that +two different versions of the same backend are accessible at the same +time, it is possible to do so by installing the two versions under +different names. + +SANE version control also includes a minor version number and a build +revision. While control of these numbers remains with the implementor +of a backend, the recommended use is as follows. The minor version is +incremented with each official release of a backend. The build +revision is increased with each build of a backend. + +The SANE API provides the following five macros to manage version +numbers. +\begin{quote} + \begin{description} + \item[\code{\defn{SANE\_CURRENT\_MAJOR}}:] The value of this macro is the + number of the SANE standard that the interface implements. + + \item[\code{\defn{SANE\_VERSION\_CODE}(\var{maj},\var{min},\var{bld})}:] + \label{sec:saneversioncode} + This macro can be used to build a monotonically increasing version + code. A SANE version code consists of the SANE standard major + version number (\var{maj}), the minor version number \var{min}, + and the build revision of a backend (\var{bld}). The major and + minor version numbers must be in the range 0\ldots255 and the + build revision must be in the range 0\ldots65535. + + Version codes are monotonic in the sense that it is possible to + apply relational operators (e.g., equality or less-than test) + directly on the version code rather than individually on the three + components of the version code. + + Note that the major version number alone determines whether a + frontend/backend pair is compatible. The minor version and the + build revision are used for informational and bug-fixing purposes + only. + + \item[\code{\defn{SANE\_VERSION\_MAJOR}(\var{vc})}:] This macro returns the + major version number component of the version code passed in + argument \var{vc}. + \item[\code{SANE\_VERSION\_MINOR(\var{vc})}:] This macro returns the + minor version number component of the version code passed in + argument \var{vc}. + \item[\code{SANE\_VERSION\_BUILD(\var{vc})}:] This macro returns the + build revision component of the version code passed in argument + \var{vc}. + \end{description} +\end{quote} + + +\section{Data Types} + +\subsection{Base Types} + +The SANE standard is based on just two SANE-specific base types: the +SANE byte and word. +\begin{quote} + \code{typedef \var{some-scalar-type\/} \defn{SANE\_Byte};} \\ + \code{typedef \var{some-scalar-type\/} \defn{SANE\_Word};} +\end{quote} +\verb|SANE_Byte| must correspond to some scalar C type that is capable +of holding values in the range 0 to 255. \verb|SANE_Word| must be +capable of holding any of the following: +\begin{itemize} + \item the truth values \verb|SANE_FALSE| and \verb|SANE_TRUE| + \item signed integers in the range $-2^{31}\ldots2^{31}-1$ + \item fixed point values in the range $-32768\ldots32767.9999$ with + a resolution of $1/65536$ + \item 32 bits (for bit sets) +\end{itemize} +Note that the SANE standard does not define what C type +\verb|SANE_Byte| and \verb|SANE_Word| map to. For example, on some +platforms, the latter may map to \verb|long int| whereas on others it +may map to \verb|int|. A portable SANE frontend or backend must +therefore not depend on a particular mapping. + +\subsection{Boolean Type} + +\code{\defn{SANE\_Bool}} is used for variables that can take one of +the two truth values \code{\defn{SANE\_FALSE}} and +\code{\defn{SANE\_TRUE}}. The former value is defined to be 0, +whereas the latter is 1.\footnote{This is different from ANSI C where + any non-zero integer value represents logical TRUE.} The C +declarations for this type are given below. +\begin{quote} +\begin{verbatim} +#define SANE_FALSE 0 +#define SANE_TRUE 1 +typedef SANE_Word SANE_Bool; +\end{verbatim} +\end{quote} +Note that \verb|SANE_Bool| is simply an alias of \verb|SANE_Word|. It +is therefore always legal to use the latter type in place of the +former. However, for clarity, it is recommended to use +\verb|SANE_Bool| whenever a given variable or formal argument has a +fixed interpretation as a boolean object. + +\subsection{Integer Type} + +\code{\defn{SANE\_Int}} is used for variables that can take integer +values in the range $-2^{32}$ to $2^{31}-1$. Its C declaration is +given below. +\begin{quote} +\begin{verbatim} +typedef SANE_Word SANE_Int; +\end{verbatim} +\end{quote} +Note that \verb|SANE_Int| is simply an alias of \verb|SANE_Word|. It +is therefore always legal to use the latter type in place of the +former. However, for clarity, it is recommended to use +\verb|SANE_Int| whenever a given variable or formal argument has a +fixed interpretation as an integer object. + + +\subsection{Fixed-point Type} + +\code{\defn{SANE\_Fixed}} is used for variables that can take fixed +point values in the range $-32768$ to $32767.9999$ with a resolution +of $1/65535$. The C declarations relating to this type are given +below. +\begin{quote} +\begin{verbatim} +#define SANE_FIXED_SCALE_SHIFT 16 +typedef SANE_Word SANE_Fixed; +\end{verbatim} +\end{quote} +The macro \code{\defn{SANE\_FIXED\_SCALE\_SHIFT}} gives the location +of the fixed binary point. This standard defines that value to be 16, +which yields a resolution of $1/65536$. + +Note that \verb|SANE_Fixed| is simply an alias of \verb|SANE_Word|. +It is therefore always legal to use the latter type in place of the +former. However, for clarity, it is recommended to use +\verb|SANE_Fixed| whenever a given variable or formal argument has a +fixed interpretation as a fixed-point object. + +For convenience, SANE also defines two macros that convert fixed-point +values to and from C double floating point values. +\begin{quote} + \begin{description} + + \item[\code{\defn{SANE\_FIX}(\var{d})}:] Returns the largest SANE + fixed-point value that is smaller than the double value \var{d}. + No range checking is performed. If the value of \var{d} is out of + range, the result is undefined. + + \item[\code{\defn{SANE\_UNFIX}(\var{w})}:] Returns the nearest + double machine number that corresponds to fixed-point value + \var{w}. + + \end{description} +\end{quote} +SANE does {\em not\/} require that the following two expressions hold +true (even if the values of \var{w} and \var{d} are in range): +\begin{quote} +\begin{verbatim} +SANE_UNFIX(SANE_FIX(d)) == d +SANE_FIX(SANE_UNFIX(w)) == w +\end{verbatim} +\end{quote} +In other words, conversion between fixed and double values may be +lossy. It is therefore recommended to avoid repeated conversions +between the two representations. + + +\subsection{Text} + +\subsubsection{Character Type} + +Type \code{\defn{SANE\_Char}} represents a single text character or +symbol. At present, this type maps directly to the underlying C +\verb|char| type (typically one byte). The encoding for such +characters is currently fixed as ISO LATIN-1. Future versions of this +standard may map this type to a wider type and allow multi-byte +encodings to support internationalization. As a result of this, care +should be taken to avoid the assumption that +\verb|sizeof(SANE_Char)==sizeof(char)|. +\begin{quote} +\begin{verbatim} +typedef char SANE_Char; +\end{verbatim} +\end{quote} + +\subsubsection{String Type} + +Type \code{\defn{SANE\_String}} represents a text string as a sequence +of C \verb|char| values. The end of the sequence is indicated by a +\verb|'\0'| (\defn{NUL}) character. +\begin{quote} +\begin{verbatim} +typedef SANE_Char *SANE_String; +typedef const SANE_Char *SANE_String_Const; +\end{verbatim} +\end{quote} +The type \code{\defn{SANE\_String\_Const}} is provided by SANE to +enable declaring strings whose contents is unchangable. Note that in +ANSI C, the declaration +\begin{quote} +\begin{verbatim} +const SANE_String str; +\end{verbatim} +\end{quote} +declares a string pointer that is constant (not a string pointer that +points to a constant value). + + +\subsection{Scanner Handle Type} + +Access to a scanner is provided through an opaque type called +\code{\defn{SANE\_Handle}}. The C declaration of this type is given +below. +\begin{quote} +\begin{verbatim} +typedef void *SANE_Handle; +\end{verbatim} +\end{quote} +While this type is declared to be a void pointer, an application must +not attempt to interpret the value of a \verb|SANE_Handle|. In +particular, SANE does not require that a value of this type is a legal +pointer value. + + +\subsection{Status Type} + +Most SANE operations return a value of type \code{\defn{SANE\_Status}} +to indicate whether the completion status of the operation. If an +operation completes successfully, \verb|SANE_STATUS_GOOD| is returned. +In case of an error, a value is returned that indicates the nature of +the problem. The complete list of available status codes is listed in +Table \ref{tab:status}. It is recommended to use function +\code{sane\_strstatus()} to convert status codes into a legible +string. + +\begin{table}[htbp] + \begin{center} + \begin{tabular}{|l|r|l|} + \hline + \multicolumn{1}{|c|}{\bf Symbol} & \multicolumn{1}{c|}{\bf Code} & + \multicolumn{1}{c|}{\bf Description} \\ + \hline\hline +\code{\defn{SANE\_STATUS\_GOOD}} + & 0 & Operation completed succesfully. \\ +\code{\defn{SANE\_STATUS\_UNSUPPORTED}} + & 1 & Operation is not supported. \\ +\code{\defn{SANE\_STATUS\_CANCELLED}} + & 2 & Operation was cancelled. \\ +\code{\defn{SANE\_STATUS\_DEVICE\_BUSY}} + & 3 & Device is busy---retry later. \\ +\code{\defn{SANE\_STATUS\_INVAL}} + & 4 & Data or argument is invalid. \\ +\code{\defn{SANE\_STATUS\_EOF}} + & 5 & No more data available (end-of-file). \\ +\code{\defn{SANE\_STATUS\_JAMMED}} + & 6 & Document feeder jammed. \\ +\code{\defn{SANE\_STATUS\_NO\_DOCS}} + & 7 & Document feeder out of documents. \\ +\code{\defn{SANE\_STATUS\_COVER\_OPEN}} + & 8 & Scanner cover is open. \\ +\code{\defn{SANE\_STATUS\_IO\_ERROR}} + & 9 & Error during device I/O. \\ +\code{\defn{SANE\_STATUS\_NO\_MEM}} + & 10 & Out of memory. \\ +\code{\defn{SANE\_STATUS\_ACCESS\_DENIED}} + & 11 & Access to resource has been denied. \\ + \hline + \end{tabular} + \caption{Status Codes}\label{tab:status} + \end{center} +\end{table} + + +\subsection{Device Descriptor Type} + +Each SANE device is represented by a structure of type +\code{\defn{SANE\_Device}}. The C declaration of this type is given +below. +\begin{quote} +\begin{verbatim} +typedef struct + { + SANE_String_Const name; + SANE_String_Const vendor; + SANE_String_Const model; + SANE_String_Const type; + } +SANE_Device; +\end{verbatim} +\end{quote} +\index{device-name} +The structure provides the unique name of the scanner in member +\code{name}. It is this unique name that should be passed in a call +to \code{sane\_open()}. The format of this name is completely up to +the backend. The only constraints are that the name is unique among +all devices supported by the backend and that the name is a legal SANE +text string. To simplify presentation of unique names, their length +should not be excessive. It is {\em recommended\/} that backends keep +unique names below 32 characters in length. However, applications +{\em must\/} be able to cope with arbitrary length unique names. + +The remaining members in the device structure provide additional +information on the device corresponding to the unique name. +Specifically, members \code{vendor}, \code{model}, and \code{type} are +single-line strings that give information on the vendor +(manufacturer), model, and the type of the device. For consistency's +sake, the following strings should be used when appropriate (the lists +will be expanded as need arises): + +\begin{table}[htbp] + \begin{center} + \leavevmode + \hspace{\fill} + \begin{tabular}[t]{|ll|} + \hline + \multicolumn{2}{|c|}{\bf \defn{Vendor Strings}} \\ + \hline\hline + \code{AGFA} & \code{Microtek} \\ + \code{Abaton} & \code{Minolta} \\ + \code{Acer} & \code{Mitsubishi} \\ + \code{Apple} & \code{Mustek} \\ + \code{Artec} & \code{NEC} \\ + \code{Avision} & \code{Nikon} \\ + \code{CANON} & \code{Plustek} \\ + \code{Connectix} & \code{Polaroid} \\ + \code{Epson} & \code{Relisys} \\ + \code{Fujitsu} & \code{Ricoh} \\ + \code{Hewlett-Packard} & \code{Sharp} \\ + \code{IBM} & \code{Siemens} \\ + \code{Kodak} & \code{Tamarack} \\ + \code{Lexmark} & \code{UMAX} \\ + \code{Logitech} & \code{Noname} \\ + \hline + \end{tabular} + \hspace{\fill} + \begin{tabular}[t]{|l|} + \hline + \multicolumn{1}{|c|}{\bf \defn{Type Strings}} \\ + \hline\hline + \code{film scanner} \\ + \code{flatbed scanner} \\ + \code{frame grabber} \\ + \code{handheld scanner} \\ + \code{multi-function peripheral} \\ + \code{sheetfed scanner} \\ + \code{still camera} \\ + \code{video camera} \\ + \code{virtual device} \\ + \hline + \end{tabular} + \hspace{\fill} + \caption{Predefined Device Information Strings} + \label{tab:devinfo} + \end{center} +\end{table} +Note that vendor string \code{Noname} can be used for virtual devices +that have no physical vendor associated. Also, there are no +predefined model name strings since those are vendor specific and +therefore completely under control of the respective backends. + + +\subsection{Option Descriptor Type}\label{sec:odesc} + +Option descriptors are at the same time the most intricate and +powerful type in the SANE standard. Options are used to control +virtually all aspects of device operation. Much of the power of the +SANE API stems from the fact that most device controls are completely +described by their respective option descriptor. Thus, a frontend can +control a scanner abstractly, without requiring knowledge as to what +the purpose of any given option is. Conversely, a scanner can +describe its controls without requiring knowledge of how the frontend +operates. The C declaration of the +\code{\defn{SANE\_Option\_Descriptor}} type is given below. +\begin{quote} +\begin{verbatim} +typedef struct + { + SANE_String_Const name; + SANE_String_Const title; + SANE_String_Const desc; + SANE_Value_Type type; + SANE_Unit unit; + SANE_Int size; + SANE_Int cap; + SANE_Constraint_Type constraint_type; + union + { + const SANE_String_Const *string_list; + const SANE_Word *word_list; + const SANE_Range *range; + } + constraint; + } +SANE_Option_Descriptor; +\end{verbatim} +\end{quote} + +\subsubsection{Option Name} + +Member \code{name} is a string that uniquely identifies the option. +The name must be unique for a given device (i.e., the option names +across different backends or devices need not be unique). The option +name must consist of lower-case ASCII letters (\code{a}--\code{z}), +digits (\code{0}--\code{9}), or the dash character (\code{-}) only. +The first character must be a lower-case ASCII character (i.e., not a +digit or a dash). + +\subsubsection{Option Title} + +Member \code{title} is a single-line string that can be used by the +frontend as a title string. This should typically be a short (one or +two-word) string that is chosen based on the function of the option. + +\subsubsection{Option Description} + +Member \code{desc} is a (potentially very) long string that can be +used as a help text to describe the option. It is the responsibility +of the frontend to break the string into managable-length lines. +Newline characters in this string should be interpreted as paragraph +breaks. + +\subsubsection{Option Value Type} + +Member \code{type} specifies the type of the option value. The +possible values for type \code{\defn{SANE\_Value\_Type}} are described +in Table \ref{tab:valuetype}. + +\begin{table}[htbp] + \begin{center} + \leavevmode + \begin{tabular}{|l|l|p{0.6\textwidth}|} +\hline +\multicolumn{1}{|c|}{\bf Symbol} & +\multicolumn{1}{c|}{\bf Code} & +\multicolumn{1}{c|}{\bf Description} \\ +\hline\hline + +\code{\defn{SANE\_TYPE\_BOOL}} & 0 & Option value is of type + \verb|SANE_Bool|. \\ + +\code{\defn{SANE\_TYPE\_INT}} & 1 & Option value is of type + \verb|SANE_Int|. \\ + +\code{\defn{SANE\_TYPE\_FIXED}}&2 & Option value is of type + \verb|SANE_Fixed|. \\ + +\code{\defn{SANE\_TYPE\_STRING}}&3 & Option value is of type + \verb|SANE_String|. \\ + +\code{\defn{SANE\_TYPE\_BUTTON}} & 4 & An option of this type has no value. +Instead, setting an option of this type has an option-specific +side-effect. For example, a button-typed option could be used by a +backend to provide a means to select default values or to the tell an +automatic document feeder to advance to the next sheet of paper. \\ + +\code{\defn{SANE\_TYPE\_GROUP}} & 5 & An option of this type has no value. +This type is used to group logically related options. A group option +is in effect up to the point where another group option is encountered +(or up to the end of the option list, if there are no other group +options). For group options, only members \code{title} and +\code{type} are valid in the option descriptor. \\ + + \hline + \end{tabular} + \caption{Option Value Types (\code{SANE\_Value\_Type})} + \label{tab:valuetype} + \end{center} +\end{table} + +\subsubsection{Option Value Unit} + +Member \code{unit} specifies what the physical unit of the option +value is. The possible values for type \code{\defn{SANE\_U\-nit}} are +described in Table \ref{tab:units}. Note that the specified unit is +what the SANE backend expects. It is entirely up to a frontend as to +how these units a presented to the user. For example, SANE expresses +all lengths in millimeters. A frontend is generally expected to +provide appropriate conversion routines so that a user can express +quantities in a customary unit (e.g., inches or centimeters). + +\begin{table}[htbp] + \begin{center} + \leavevmode + \begin{tabular}{|l|l|l|} +\hline +\multicolumn{1}{|c|}{\bf Symbol} & +\multicolumn{1}{|c|}{\bf Code} & +\multicolumn{1}{|c|}{\bf Description} \\ + +\hline\hline + +\code{\defn{SANE\_UNIT\_NONE}} & 0 & Value is unit-less (e.g., page count).\\ +\code{\defn{SANE\_UNIT\_PIXEL}} & 1 & Value is in number of pixels. \\ +\code{\defn{SANE\_UNIT\_BIT}} & 2 & Value is in number of bits. \\ +\code{\defn{SANE\_UNIT\_MM}} & 3 & Value is in millimeters. \\ +\code{\defn{SANE\_UNIT\_DPI}} & 4 & Value is a resolution in dots/inch. \\ +\code{\defn{SANE\_UNIT\_PERCENT}}& 5 & Value is a percentage. \\ +\code{\defn{SANE\_UNIT\_MICROSECOND}}& 6 & Value is time in $\mu$-seconds. \\ + +\hline + \end{tabular} + \caption{Physical Units (\code{SANE\_Unit})} + \label{tab:units} + \end{center} +\end{table} + +\subsubsection{Option Value Size}\label{sec:valuesize} + +Member \code{size} specifies the size of the option value (in bytes). +This member has a slightly different interpretation depending on the +type of the option value: +\begin{quote} + \begin{description} + \item[\code{SANE\_TYPE\_STRING}:] The size is the maximum size of + the string. For the purpose of string size calcuations, the + terminating \code{NUL} character is considered to be part of the + string. Note that the terminating \code{NUL} character must + always be present in string option values. + \item[\code{SANE\_TYPE\_INT}, \code{SANE\_TYPE\_FIXED}:] The size + must be a positive integer multiple of the size of a + \verb|SANE_Word|. The option value is a vector of length + \[ \code{size}/\code{sizeof(SANE\_Word)}. \] + \item[\code{SANE\_TYPE\_BOOL}:] The size must be set to + \code{sizeof(SANE\_Word)}. + \item[\code{SANE\_TYPE\_BUTTON}, \code{SANE\_TYPE\_GROUP}:] The + option size is ignored. + \end{description} +\end{quote} + +\subsubsection{Option Capabilities} + +Member \code{cap} describes what capabilities the option posseses. +This is a bitset that is formed as the inclusive logical OR of the +capabilities described in Table \ref{tab:capabilities}. The SANE API +provides the following to macros to test certain features of a given +capability bitset: +\begin{quote} + \begin{description} + + \item[\code{\defn{SANE\_OPTION\_IS\_ACTIVE}(\var{cap})}:] This macro + returns \code{SANE\_TRUE} if and only if the option with the + capability set \var{cap} is currently active. + + \item[\code{\defn{SANE\_OPTION\_IS\_SETTABLE}(\var{cap})}:] This + macro returns \code{SANE\_TRUE} if and only if the option with the + capability set \var{cap} is software settable. + \end{description} +\end{quote} + +\begin{table}[htbp] + \begin{center} + \leavevmode + \begin{tabular}{|l|r|p{0.59\textwidth}|} +\hline +\multicolumn{1}{|c|}{\bf Symbol} & +\multicolumn{1}{c|}{\bf Code} & +\multicolumn{1}{c|}{\bf Description} \\ +\hline\hline + +\code{\defn{SANE\_CAP\_SOFT\_SELECT}} & 1 & The option + value can be set by a call to \code{sane\_con\-trol\_opt\-ion()}.\\ + +\code{\defn{SANE\_CAP\_HARD\_SELECT}} & 2 & The option value can be set by + user-intervention (e.g., by flipping a switch). The user-interface + should prompt the user to execute the appropriate action to set such + an option. This capability is mutually exclusive with + SANE\_CAP\_SOFT\_SELECT (either one of them can be set, but not both + simultaneously). \\ + +\code{\defn{SANE\_CAP\_SOFT\_DETECT}} & 4 & The option + value can be detected by software. If + \code{SANE\_\-CAP\_\-SO\-FT\_SEL\-ECT} is set, this capability {\em must\/} + be set. If \code{SANE\_CAP\_HARD\_SELECT} is set, this capability + may or may not be set. If this capability is set but neither + \code{SANE\_CAP\_SO\-FT\_SEL\-ECT} nor \code{SANE\_CAP\_HA\-RD\_SEL\-ECT} + are, then there is no way to control the option. That is, the + option provides read-out of the current value only. \\ + +\code{\defn{SANE\_CAP\_EMULATED}} & 8 & If set, this capability indicates + that an option is not directly supported by the device and is + instead emulated in the backend. A sophisticated frontend may + elect to use its own (presumably better) emulation in lieu of an emulated + option. \\ + +\code{\defn{SANE\_CAP\_AUTOMATIC}} & 16 & If set, this capability indicates + that the backend (or the device) is capable to picking a reasonable + option value automatically. For such options, it is possible to + select automatic operation by calling \code{sane\_control\_option()} + with an action value of \code{SANE\_ACTION\_SET\_AUTO}. \\ + +\code{\defn{SANE\_CAP\_INACTIVE}} & 32 & If set, this capability indicates + that the option is not currently active (e.g., because it's + meaningful only if another option is set to some other value). \\ + +\code{\defn{SANE\_CAP\_ADVANCED}} & 64 & + If set, this capability indicates that the option should be + considered an ``advanced user option.'' A frontend typically + displays such options in a less conspicuous way than regular options + (e.g., a command line interface may list such options last or a + graphical interface may make them available in a seperate ``advanced + settings'' dialog). + \\ + +\hline + \end{tabular} + \caption{Option Capabilities} + \label{tab:capabilities} + \end{center} +\end{table} + +\subsubsection{Option Value Constraints} + +It is often useful to constrain the values that an option can take. +For example, constraints can be used by a frontend to determine how to +represent a given option. Member \code{constraint\_type} indicates +what constraint is in effect for the option. The constrained values +that are allowed for the option are described by one of the union +members of member \code{constraint}. The possible values of type +\code{\defn{SANE\_Constraint\_Type}} and the interpretation of the +\code{constraint} union is described in Table~\ref{tab:constraints}. + +\begin{table}[htbp] + \begin{center} + \leavevmode + \begin{tabular}{|l|r|p{0.5\textwidth}|} +\hline +\multicolumn{1}{|c|}{\bf Symbol} & +\multicolumn{1}{|c|}{\bf Code} & +\multicolumn{1}{|c|}{\bf Description} \\ + +\hline\hline + +\code{\defn{SANE\_CONSTRAINT\_NONE}} & 0 & The value is unconstrained. + The option can take any of the values possible for the option's + type. \\ + + \code{\defn{SANE\_CONSTRAINT\_RANGE}} & 1 & This constraint is + applicable to integer and fixed-point valued options only. It + constrains the option value to a possibly quantized range of + numbers. Option descriptor member \code{constraint.range} points to + a range of the type \code{\defn{SANE\_Range}}. This type is illustrated + below: + \begin{quote} +\begin{verbatim} +typedef struct + { + SANE_Word min; + SANE_Word max; + SANE_Word quant; + } +SANE_Range; +\end{verbatim} + \end{quote} + All three members in this structure are interpreted according to the + option value type (\verb|SANE_TYPE_INT| or \verb|SANE_TYPE_FIXED|). + Members \code{min} and \code{max} specify the minimum and maximum + values, respectively. If member \code{quant} is non-zero, it + specifies the quantization value. If $l$ is the minimum value, $u$ + the maximum value and $q$ the (non-zero) quantization of a range, + then the legal values are $v=k\cdot q+l$ for all non-negative + integer values of $k$ such that $v<=u$. \\ + +\code{\defn{SANE\_CONSTRAINT\_WORD\_LIST}} & 2 & This constraint is applicable + to integer and fixed-point valued options only. It constrains the + option value to a list of numeric values. Option descriptor member + \code{constraint.word\_list} points to a list of words that + enumerates the legal values. The first element in that list is an + integer (\verb|SANE_Int|) that specifies the length of the list (not + counting the length itself). The remaining elements in the list are + interpreted according to the type of the option value + (\verb|SANE_TYPE_INT| or \verb|SANE_TYPE_FIXED|). \\ + +\code{\defn{SANE\_CONSTRAINT\_STRING\_LIST}} & 3 & This constraint is + applicable to string-valued options only. It constrains the option + value to a list of strings. The option descriptor member + \code{con\-strai\-nt.str\-ing\_list} points to a \code{NULL} terminated + list of strings that enumerate the legal values for the option + value. +\\\hline + \end{tabular} + \caption{Option Value Constraints} + \label{tab:constraints} + \end{center} +\end{table} + + +\section{Operations} + +\subsection{\code{sane\_init}} + +This function must be called before any other SANE function can be called. +The behavior of a SANE backend is undefined if this function is not called +first or if the status code returned by \code{sane\_init} is different from +\code{\defn{SANE\_STATUS\_GOOD}}. The version code of the backend is returned +in the value pointed to by \code{version\_code}. If that pointer is +\code{NULL}, no version code is returned. Argument \code{authorize} is either +a pointer to a function that is invoked when the backend requires +authentication for a specific resource or \code{NULL} if the frontend does not +support authentication. +\begin{quote}\index{sane\_init} +\begin{verbatim} +SANE_Status sane_init (SANE_Int * version_code, + SANE_Authorization_Callback authorize); +\end{verbatim} +\end{quote} + +The authorization function may be called by a backend in response to +any of the following calls: +\begin{quote} + \code{sane\_open}, \code{sane\_control\_option}, \code{sane\_start} +\end{quote} +If a backend was initialized without authorization function, then +authorization requests that cannot be handled by the backend itself +will fail automatically and the user may be prevented from accessing +protected resources. Backends are encouraged to implement means of +authentication that do not require user assistance. E.g., on a +multi-user system that authenticates users through a login process a +backend could automatically lookup the apporpriate password based on +resource- and user-name. + +The authentication function type has the following declaration: +\begin{quote}\index{SANE\_Authorization\_Callback} + \index{domain}\index{username}\index{password} +\begin{verbatim} +#define SANE_MAX_USERNAME_LEN 128 +#define SANE_MAX_PASSWORD_LEN 128 + +typedef void (*SANE_Authorization_Callback) + (SANE_String_Const resource, + SANE_Char username[SANE_MAX_USERNAME_LEN], + SANE_Char password[SANE_MAX_PASSWORD_LEN]); +\end{verbatim} +\end{quote} +Three arguments are passed to the authorization function: +\code{resource} is a string specifying the name of the resource that +requires authorization. A frontend should use this string to build a +user-prompt requesting a username and a password. The \code{username} +and \code{password} arguments are (pointers to) an array of +\code{SANE\_MAX\_USERNAME\_LEN} and \code{SANE\_MAX\_PASSWORD\_LEN} +characters, respectively. The authorization call should place the +entered username and password in these arrays. The returned strings +{\em must\/} be ASCII-NUL terminated. + +\subsection{\code{sane\_exit}} + +This function must be called to terminate use of a backend. The +function will first close all device handles that still might be open +(it is recommended to close device handles explicitly through a call +to \code{sane\_clo\-se()}, but backends are required to release all +resources upon a call to this function). After this function returns, +no function other than \code{sane\_init()} may be called (regardless +of the status value returned by \code{sane\_exit()}. Neglecting to +call this function may result in some resources not being released +properly. +\begin{quote}\index{sane\_exit} +\begin{verbatim} +void sane_exit (void); +\end{verbatim} +\end{quote} + + +\subsection{\code{sane\_get\_devices}} + +This function can be used to query the list of devices that are +available. If the function executes successfully, it stores a pointer +to a \code{NULL} terminated array of pointers to \verb|SANE_Device| +structures in \code{*device\_list}. The returned list is guaranteed +to remain unchanged and valid until (a) another call to this function +is performed or (b) a call to \code{sane\_exit()} is performed. This +function can be called repeatedly to detect when new devices become +available. If argument \code{local\_only} is true, only local devices +are returned (devices directly attached to the machine that SANE is +running on). If it is false, the device list includes all remote +devices that are accessible to the SANE library. +\begin{quote}\index{sane\_get\_devices} +\begin{verbatim} +SANE_Status sane_get_devices (const SANE_Device *** device_list, + SANE_Bool local_only); +\end{verbatim} +\end{quote} + +This function may fail with \code{SANE\_STATUS\_NO\_MEM} if an +insufficient amount of memory is available. + +\begin{quote} + \begin{center} + {\bf Backend Implementation Note} + \end{center} + SANE does not require that this function is called before a + \code{sane\_open()} call is performed. A device name may be + specified explicitly by a user which would make it unnecessary and + undesirable to call this function first. +\end{quote} + + +\subsection{\code{sane\_open}} + +This function is used to establish a connection to a particular +device. The name of the device to be opened is passed in argument +\code{name}. If the call completes successfully, a handle for the +device is returned in \code{*h}. As a special case, specifying a +zero-length string as the device requests opening the first available +device (if there is such a device). +\begin{quote}\index{sane\_open} +\begin{verbatim} +SANE_Status sane_open (SANE_String_Const name, SANE_Handle * h); +\end{verbatim} +\end{quote} + +This function may fail with one of the following status codes. +\begin{quote} +\begin{description} +\item[\code{SANE\_STATUS\_DEVICE\_BUSY}:] The device is currently + busy (in use by somebody else). +\item[\code{SANE\_STATUS\_INVAL}:] The device name is not valid. +\item[\code{SANE\_STATUS\_IO\_ERROR}:] An error occured while + communicating with the device. +\item[\code{SANE\_STATUS\_NO\_MEM}:] An insufficent amount of memory + is available. +\item[\code{SANE\_STATUS\_ACCESS\_DENIED}:] Access to the device has + been denied due to insufficient or invalid authentication. +\end{description} +\end{quote} + + +\subsection{\code{sane\_close}} + +This function terminates the association between the device handle +passed in argument \code{h} and the device it represents. If the +device is presently active, a call to \code{sane\_cancel()} is +performed first. After this function returns, handle \code{h} must +not be used anymore. + +\begin{quote}\index{sane\_close} +\begin{verbatim} +void sane_close (SANE_Handle h); +\end{verbatim} +\end{quote} + +\subsection{\code{sane\_get\_option\_descriptor}} + +This function is used to access option descriptors. The function +returns the option descriptor for option number \code{n} of the device +represented by handle \code{h}. Option number 0 is guaranteed to be a +valid option. Its value is an integer that specifies the number of +options that are available for device handle \code{h} (the count +includes option 0). If $n$ is not a valid option index, the function +returns \code{NULL}. The returned option descriptor is guaranteed to +remain valid (and at the returned address) until the device is closed. + +\begin{quote}\index{sane\_get\_option\_descriptor} +\begin{verbatim} +const SANE_Option_Descriptor * + sane_get_option_descriptor (SANE_Handle h, SANE_Int n); +\end{verbatim} +\end{quote} + +\subsection{\code{sane\_control\_option}}\label{sec:control} + +This function is used to set or inquire the current value of option +number \code{n} of the device represented by handle \code{h}. The +manner in which the option is controlled is specified by parameter +\code{a}. The possible values of this parameter are described in more +detail below. The value of the option is passed through argument +\code{v}. It is a pointer to the memory that holds the option value. +The memory area pointed to by \code{v} must be big enough to hold the +entire option value (determined by member \code{size} in the +corresponding option descriptor). The only exception to this rule is +that when setting the value of a string option, the string pointed to +by argument \code{v} may be shorter since the backend will stop +reading the option value upon encountering the first \code{NUL} +terminator in the string. If argument \code{i} is not \code{NULL}, +the value of \code{*i} will be set to provide details on how well the +request has been met. The meaning of this argument is described in +more detail below. +\begin{quote}\index{sane\_control\_option} +\begin{verbatim} +SANE_Status sane_control_option (SANE_Handle h, SANE_Int n, + SANE_Action a, void *v, + SANE_Int * i); +\end{verbatim} +\end{quote} + +The way the option is affected by a call to this function is +controlled by parameter \code{a} which is a value of type +\code{\defn{SANE\_Action}}. The possible values and their meaning is +described in Table~\ref{tab:actions}. + +\begin{table}[h] + \begin{center} + \leavevmode + \begin{tabular}{|l|r|p{0.5\textwidth}|} +\hline +\multicolumn{1}{|c|}{\bf Symbol} & +\multicolumn{1}{|c|}{\bf Code} & +\multicolumn{1}{|c|}{\bf Description} \\ + +\hline\hline + +\code{\defn{SANE\_ACTION\_GET\_VALUE}} & 0 & Get current option value. \\ + +\code{\defn{SANE\_ACTION\_SET\_VALUE}} & 1 & Set option value. The + option value passed through argument \code{v} may be modified by the + backend if the value cannot be set exactly. \\ + +\code{\defn{SANE\_ACTION\_SET\_AUTO}} & 2 & Turn on automatic mode. Backend + or device will automatically select an appropriate value. This mode + remains effective until overridden by an explicit set value request. + The value of parameter \code{v} is completely ignored in this case and + may be \code{NULL}. \\ + +\hline + \end{tabular} + \caption{Action Values (\code{SANE\_Action})} + \label{tab:actions} + \end{center} +\end{table} + +After setting a value via an action value of +\verb|SANE_ACTION_SET_VALUE|, additional information on how well the +request has been met is returned in \code{*i} (if \code{i} is +non-\code{NULL}). The returned value is a bitset that may contain any +combination of the values described in Table~\ref{tab:info}. +\begin{table}[htbp] + \begin{center} + \leavevmode + \begin{tabular}{|l|r|p{0.5\textwidth}|} +\hline +\multicolumn{1}{|c|}{\bf Symbol} & +\multicolumn{1}{|c|}{\bf Code} & +\multicolumn{1}{|c|}{\bf Description} \\ + +\hline\hline + +\code{\defn{SANE\_INFO\_INEXACT}} & 1 & This value is returned when + setting an option value resulted in a value being selected that does + not exactly match the requested value. For example, if a scanner + can adjust the resolution in increments of 30dpi only, setting the + resolution to 307dpi may result in an actual setting of 300dpi. + When this happens, the bitset returned in \code{*i} has this member + set. In addition, the option value is modified to reflect the + actual (rounded) value that was used by the backend. Note that + inexact values are admissible for strings as well. A backend may + choose to ``round'' a string to the closest matching legal string + for a constrained string value. \\ + + \code{\defn{SANE\_INFO\_RELOAD\_OPTIONS}} & 2 & The setting of an + option may affect the value or availability of one or more {\em + other\/} options. When this happens, the SANE backend sets this + member in \code{*i} to indicate that the application should reload + all options. This member may be set if and only if at least one + option changed. \\ + +\code{\defn{SANE\_INFO\_RELOAD\_PARAMS}} & 4 & The setting of an option may + affect the parameter values (see \code{sane\_get\_parameters()}). + If setting an option affects the parameter values, this member will + be set in \code{*i}. Note that this member may be set even if the + parameters did not actually change. However, it is guaranteed that + the parameters never change without this member being set. \\ + +\hline + \end{tabular} + \caption{Additional Information Returned When Setting an Option} + \label{tab:info} + \end{center} +\end{table} + +This function may fail with one of the following status codes. +\begin{quote} +\begin{description} +\item[\code{SANE\_STATUS\_UNSUPPORTED}:] The operation is not + supported for the specified handle and option number. +\item[\code{SANE\_STATUS\_INVAL}:] The option value is not valid. +\item[\code{SANE\_STATUS\_IO\_ERROR}:] An error occured while + communicating with the device. +\item[\code{SANE\_STATUS\_NO\_MEM}:] An insufficent amount of memory + is available. +\item[\code{SANE\_STATUS\_ACCESS\_DENIED}:] Access to the option has + been denied due to insufficient or invalid authentication. +\end{description} +\end{quote} + + + +\subsection{\code{sane\_get\_parameters}} + +This function is used to obtain the current scan parameters. The +returned parameters are guaranteed to be accurate between the time a +scan has been started (\code{sane\_start()} has been called) and the +completion of that request. Outside of that window, the returned +values are best-effort estimates of what the parameters will be when +\code{sane\_start()} gets invoked. Calling this function before a +scan has actually started allows, for example, to get an estimate of +how big the scanned image will be. The parameters passed to this +function are the handle \code{h} of the device for which the +parameters should be obtained and a pointer \code{p} to a parameter +structure. The parameter structure is described in more detail below. + +\begin{quote}\index{sane\_get\_parameters} +\begin{verbatim} +SANE_Status sane_get_parameters (SANE_Handle h, + SANE_Parameters * p); +\end{verbatim} +\end{quote} + +The scan parameters are returned in a structure of type +\code{\defn{SANE\_Parameters}}. The C declaration of this structure +is given below. +\begin{quote} +\begin{verbatim} +typedef struct + { + SANE_Frame format; + SANE_Bool last_frame; + SANE_Int bytes_per_line; + SANE_Int pixels_per_line; + SANE_Int lines; + SANE_Int depth; + } +SANE_Parameters; +\end{verbatim} +\end{quote} + +Member \code{format} specifies the format of the next frame to be +returned. The possible values for type \code{\defn{SANE\_Frame}} are +described in Table~\ref{tab:frameformat}. The meaning of these +values is described in more detail in Section~\ref{sec:imageformat}. +\begin{table}[htbp] + \begin{center} + \leavevmode + \begin{tabular}{|l|r|l|} +\hline +\multicolumn{1}{|c|}{\bf Symbol} & +\multicolumn{1}{|c|}{\bf Code} & +\multicolumn{1}{|c|}{\bf Description} \\ + +\hline\hline + +\code{\defn{SANE\_FRAME\_GRAY}} & 0 & Band covering human visual range. \\ +\code{\defn{SANE\_FRAME\_RGB}} & 1 & Pixel-interleaved red/green/blue bands. \\ +\code{\defn{SANE\_FRAME\_RED}} & 2 & Red band of a red/green/blue image. \\ +\code{\defn{SANE\_FRAME\_GREEN}} & 3 & Green band of a red/green/blue image. \\ +\code{\defn{SANE\_FRAME\_BLUE}} & 4 & Blue band of a red/green/blue image. \\ + +\hline + \end{tabular} + \caption{Frame Format (\code{SANE\_Frame})} + \label{tab:frameformat} + \end{center} +\end{table} + +Member \code{last\_frame} is set to \code{SANE\_TRUE} if and only if +the frame that is currently being acquired (or the frame that will be +acquired next if there is no current frame) is the last frame of a +multi frame image (e.g., the current frame is the blue component of a +red, green, blue image). + +Member \code{lines} specifies how many scan lines the frame is +comprised of. If this value is -1, the number of lines is not known a +priori and the frontend should call \code{sane\_read()} until it +returns a status of \code{SANE\_STATUS\_EOF}. + +Member \code{bytes\_per\_line} specifies the number of bytes that +comprise one scan line. + +Member \code{depth} specifies the number of bits per sample. + +Member \code{pixels\_per\_line} specifies the number of pixels that +comprise one scan line. + +Assume $B$ is the number of channels in the frame, then the bit depth +$d$ (as given by member \code{depth}) and the number of pixels per +line $n$ (as given by this member \code{pixels\_per\_line}) are +related to $c$, the number of bytes per line (as given by member +\code{bytes\_per\_line}) as follows: +\[ + c >= \left\{ + \begin{array}{ll} + B\cdot \lfloor (n + 7) / 8\rfloor & \mbox{if $d=1$}\\ + B\cdot n \cdot d / 8 & \mbox{if $d>1$} + \end{array} + \right. +\] +Note that the number of bytes per line can be larger than the minimum +value imposed by the right side of this equation. A frontend must be +able to properly cope with such ``padded'' image formats. + + +\subsection{\code{sane\_start}} + +This function initiates aquisition of an image from the device +represented by handle \code{h}. +\begin{quote}\index{sane\_start} +\begin{verbatim} +SANE_Status sane_start (SANE_Handle h); +\end{verbatim} +\end{quote} +This function may fail with one of the following status codes. +\begin{quote} +\begin{description} +\item[\code{SANE\_STATUS\_CANCELLED}:] The operation was cancelled through + a call to \code{sane\_cancel}. +\item[\code{SANE\_STATUS\_DEVICE\_BUSY}:] The device is busy. The + operation should be retried later. +\item[\code{SANE\_STATUS\_JAMMED}:] The document feeder is jammed. +\item[\code{SANE\_STATUS\_NO\_DOCS}:] The document feeder is out of + documents. +\item[\code{SANE\_STATUS\_COVER\_OPEN}:] The scanner cover is open. +\item[\code{SANE\_STATUS\_IO\_ERROR}:] An error occurred while communicating + with the device. +\item[\code{SANE\_STATUS\_NO\_MEM}:] An insufficent amount of memory + is available. +\item[\code{SANE\_STATUS\_INVAL}:] The scan cannot be started with the current + set of options. The frontend should reload the option descriptors, as if + \code{\defn{SANE\_INFO\_RELOAD\_OPTIONS}} had been returned from a call to + \code{sane\_control\_option()}, since the device's capabilities may have + changed. +\end{description} +\end{quote} + + +\subsection{\code{sane\_read}} + +This function is used to read image data from the device represented +by handle \code{h}. Argument \code{buf} is a pointer to a memory area +that is at least \code{maxlen} bytes long. The number of bytes +returned is stored in \code{*len}. A backend must set this to zero +when a status other than \code{SANE\_STA\-TUS\_GOOD} is returned. +When the call succeeds, the number of bytes returned can be anywhere in +the range from 0 to \code{maxlen} bytes. +\begin{quote}\index{sane\_read} +\begin{verbatim} +SANE_Status sane_read (SANE_Handle h, SANE_Byte * buf, + SANE_Int maxlen, SANE_Int * len); +\end{verbatim} +\end{quote} +If this function is called when no data is available, one of two +things may happen, depending on the I/O mode that is in effect for +handle \code{h}. +\begin{enumerate} +\item If the device is in blocking I/O mode (the default mode), the + call blocks until at least one data byte is available (or until some + error occurs). + +\item If the device is in non-blocking I/O mode, the call returns + immediately with status \code{SANE\_STA\-TUS\_GOOD} and with + \code{*len} set to zero. +\end{enumerate} +The I/O mode of handle \code{h} can be set via a call to +\code{sane\_set\_io\_mode()}. + +This function may fail with one of the following status codes. +\begin{quote} +\begin{description} +\item[\code{SANE\_STATUS\_CANCELLED}:] The operation was cancelled through + a call to \code{sane\_cancel}. +\item[\code{SANE\_STATUS\_EOF}:] No more data is available for the + current frame. +\item[\code{SANE\_STATUS\_JAMMED}:] The document feeder is jammed. +\item[\code{SANE\_STATUS\_NO\_DOCS}:] The document feeder is out of + documents. +\item[\code{SANE\_STATUS\_COVER\_OPEN}:] The scanner cover is open. +\item[\code{SANE\_STATUS\_IO\_ERROR}:] An error occurred while communicating + with the device. +\item[\code{SANE\_STATUS\_NO\_MEM}:] An insufficent amount of memory + is available. +\item[\code{SANE\_STATUS\_ACCESS\_DENIED}:] Access to the device has + been denied due to insufficient or invalid authentication. +\end{description} +\end{quote} + + +\subsection{\code{sane\_cancel}} + +This function is used to immediately or as quickly as possible cancel +the currently pending operation of the device represented by handle +\code{h}. +\begin{quote}\index{sane\_cancel} +\begin{verbatim} +void sane_cancel (SANE_Handle h); +\end{verbatim} +\end{quote} +This function can be called at any time (as long as handle \code{h} is +a valid handle) but usually affects long-running operations only (such +as image is acquisition). It is safe to call this function +asynchronously (e.g., from within a signal handler). It is important +to note that completion of this operaton does {\em not\/} imply that +the currently pending operation has been cancelled. It only +guarantees that cancellation has been {\em initiated}. Cancellation +completes only when the cancelled call returns (typically with a +status value of \code{SANE\_STATUS\_CANCELLED}). Since the SANE API +does not require any other operations to be re-entrant, this implies +that a frontend must {\em not\/} call any other operation until the +cancelled operation has returned. + + +\subsection{\code{sane\_set\_io\_mode}} + +This function is used to set the I/O mode of handle \code{h}. The I/O mode +can be either blocking or non-blocking. If argument \code{m} is +\code{SANE\_TRUE}, the mode is set to non-blocking mode, otherwise it's set to +blocking mode. This function can be called only after a call to +\code{sane\_start()} has been performed. +\begin{quote}\index{sane\_set\_io\_mode} +\begin{verbatim} +SANE_Status sane_set_io_mode (SANE_Handle h, SANE_Bool m); +\end{verbatim} +\end{quote} +By default, newly opened handles operate in blocking mode. A backend +may elect not to support non-blocking I/O mode. In such a case the +status value \code{SANE\_STATUS\_UNSUPPORTED} is returned. Blocking +I/O must be supported by all backends, so calling this function with +argument \code{m} set to \code{SANE\_FALSE} is guaranteed to complete +successfully. + +This function may fail with one of the following status codes: +\begin{quote} +\begin{description} +\item[\code{SANE\_STATUS\_INVAL}:] No image acquisition is pending. +\item[\code{SANE\_STATUS\_UNSUPPORTED}:] The backend does not support + the requested I/O mode. +\end{description} +\end{quote} + + +\subsection{\code{sane\_get\_select\_fd}} + +This function is used to obtain a (platform-specific) file-descriptor +for handle \code{h} that is readable if and only if image data is +available (i.e., when a call to \code{sane\_read()} will return at +least one byte of data). If the call completes successfully, the +select file-descriptor is returned in \code{*fd}. +\begin{quote}\index{sane\_get\_select\_fd} +\begin{verbatim} +SANE_Status sane_get_select_fd (SANE_Handle h, SANE_Int *fd); +\end{verbatim} +\end{quote} +This function can be called only after a call to \code{sane\_start()} +has been performed and the returned file-descriptor is guaranteed to +remain valid for the duration of the current image acquisition (i.e., +until \code{sane\_cancel()} or \code{sane\_start()} get called again +or until \code{sane\_read()} returns with status +\code{SANE\_STA\-TUS\_EOF}). Indeed, a backend must guarantee to +close the returned select file descriptor at the point when the next +\code{sane\_read()} call would return \code{SANE\_STA\-TUS\_EOF}. +This is necessary to ensure the application can detect when this +condition occurs without actually having to call \code{sane\_read()}. + +A backend may elect not to support this operation. In such a case, +the function returns with status code +\code{SANE\_STATUS\_UNSUPPORTED}. + +Note that the only operation supported by the returned file-descriptor +is a host operating-system dependent test whether the file-descriptor +is readable (e.g., this test can be implemented using \code{select()} +or \code{poll()} under UNIX). If any other operation is performed on +the file descriptor, the behavior of the backend becomes +unpredictable. Once the file-descriptor signals ``readable'' status, +it will remain in that state until a call to \code{sane\_read()} is +performed. Since many input devices are very slow, support for this +operation is strongly encouraged as it permits an application to do +other work while image acquisition is in progress. + +This function may fail with one of the following status codes: +\begin{quote} +\begin{description} +\item[\code{SANE\_STATUS\_INVAL}:] No image acquisition is pending. +\item[\code{SANE\_STATUS\_UNSUPPORTED}:] The backend does not support + this operation. +\end{description} +\end{quote} + + +\subsection{\code{sane\_strstatus}} + +This function can be used to translate a SANE status code into a +printable string. The returned string is a single line of text that +forms a complete sentence, but without the trailing period +(full-stop). The function is guaranteed to never return \code{NULL}. +The returned pointer is valid at least until the next call to this +function is performed. +\begin{quote}\index{sane\_strstatus} +\begin{verbatim} +const SANE_String_Const sane_strstatus (SANE_Status status); +\end{verbatim} +\end{quote} + +\section{Code Flow}\index{code flow} + +The code flow for the SANE API is illustrated in +Figure~\ref{fig:flow}. Functions \code{sane\_init()} and +\code{sane\_exit()} initialize and exit the backend, respectively. +All other calls must be performed after initialization and before +exiting the backend. + +\begin{figure}[htb] + \begin{center} + \leavevmode + \psfig{file=figs/flow.eps,height=0.5\textheight} + \caption{Code flow} + \label{fig:flow} + \end{center} +\end{figure} + +Function \code{sane\_get\_devices()} can be called any time after +\code{sane\_init()} has been called. It returns the list of the +devices that are known at the time of the call. This list may change +over time since some devices may be turned on or off or a remote host +may boot or shutdown between different calls. It should be noted that +this operation may be relatively slow since it requires contacting all +configured devices (some of which may be on remote hosts). A frontend +may therefore want to provide the ability for a user to directly +select a desired device without requiring a call to this function. + +Once a device has been chosen, it is opened using a call to +\code{sane\_open()}. Multiple devices can be open at any given time. +A SANE backend must not impose artificial constraints on how many +devices can be open at any given time. + +An opened device can be setup through the corresponding device handle +using functions \code{sane\_get\_opt\-ion\_desc\-riptor()} and +\code{sane\_control\_option()}. While setting up a device, obtaining +option descriptors and setting and reading of option values can be +mixed freely. It is typical for a frontend to read out all available +options at the beginning and then build a dialog (either graphical or +a command-line oriented option list) that allows to control the +available options. It should be noted that the number of options is +fixed for a given handle. However, as options are set, other options +may become active or inactive. Thus, after setting an option, it +maybe necessary to re-read some or all option descriptors. While +setting up the device, it is also admissible to call +\code{sane\_get\_parameters()} to get an estimate of what the image +parameters will look like once image acquisition begins. + +The device handle can be put in blocking or non-blocking mode by a +call to \code{sane\_set\_io\_mode()}. Devices are required to support +blocking mode (which is the default mode), but support for +non-blocking I/O is strongly encouraged for operating systems such as +UNIX. + +After the device is setup properly, image acquisition can be started +by a call to \code{sane\_start()}. The backend calculates the exact +image parameters at this point. So future calls to +\code{sane\_get\_parameters()} will return the exact values, rather +than estimates. Whether the physical image acquisition starts at this +point or during the first call to \code{sane\_read()} is unspecified +by the SANE API. If non-blocking I/O and/or a select-style interface +is desired, the frontend may attempt to call +\code{sane\_set\_io\_mode()} and/or \code{sane\_get\_select\_fd()} at +this point. Either of these functions may fail if the backend does +not support the requested operation. + +Image data is collected by repeatedly calling \code{sane\_read()}. +Eventually, this function will return an end-of-file status +(\code{SANE\_STATUS\_EOF}). This indicates the end of the current +frame. If the frontend expects additional frames (e.g., the +individual channels in of a red/green/blue image or multiple images), +it can call \code{sane\_start()} again. Once all desired frames have +been acquired, function \code{sane\_cancel()} must be called. This +operation can also be called at any other time to cancel a pending +operation. Note that \code{sane\_cancel()} must be called even if the +last read operation returned \code{SANE\_STATUS\_EOF}. + +When done using the device, the handle should be closed by a call to +\code{sane\_close()}. Finally, before exiting the application, +function \code{sane\_exit()} must be called. It is important not to +forget to call this function since otherwise some resources (e.g., +temporary files or locks) may remain unclaimed. + + +\section{Well-Known Options}\index{well-known options} + +While most backend options are completely self-describing, there are a +cases where a user interface might want to special-case the handling +of certain options. For example, the scan area is typically defined +by four options that specify the top-left and bottom-right corners of +the area. With a graphical user interface, it would be tedious to +force the user to type in these four numbers. Instead, most such +interfaces will want to present to the user a preview (low-resolution +scan) of the scanner surface and let the user pick the scan area by +dragging a rectangle into the desired position. For this reason, the +SANE API specifies a small number of option names that have +well-defined meanings. + +\subsection{Option Number Count}\index{option count} + +Option number 0 has an empty string as its name. The value of this +option is of type \code{SANE\_TYPE\_INT} and it specifies the total +number of options available for a given device (the count includes +option number 0). This means that there are two ways of counting the +number of options available: a frontend can either cycle through all +option numbers starting at one until +\code{sane\_get\_option\_descriptor()} returns \code{NULL}, or a +frontend can directly read out the value of option number 0. + +\subsection{Scan Resolution Option}\index{scan resolution}\index{resolution option} + +Option \code{resolution} is used to select the resolution at which an +image should be acquired. The type of this option is either +\code{SANE\_TYPE\_INT} or \code{SANE\_TYPE\_FIXED}. The unit is +\code{SANE\_UNIT\_DPI} (dots/inch). + +This option is not mandatory, but if a backend does support it, it +must implement it in a manner consistent with the above definition. + +\subsection{Preview Mode Option}\index{preview mode} + +The boolean option \code{preview} is used by a frontend to inform the +backend when image acquisition should be optimized for speed, rather +than quality (``preview mode''). When set to \code{SANE\_TRUE}, +preview mode is in effect, when set to \code{SANE\_FALSE} image +acquisition should proceed in normal quality mode. The setting of +this option \emph{must not\/} affect any other option. That is, as +far as the other options are concerned, the preview mode is completely +side effect free. A backend can assume that the frontend will take +care of appropriately setting the scan resolution for preview mode +(through option \code{resolution}). A backend is free to override the +\code{resolution} value with its own choice for preview mode, but it +is advised to leave this choice to the frontend wherever possible. + +This option is not mandatory, but if a backend does support it, it +must implement it in a manner consistent with the above definition. + +\subsection{Scan Area Options}\index{scan area options} + +The four most important well-known options are the ones that define +the scan area. The scan area is defined by two points (x/y coordinate +pairs) that specify the top-left and the bottom-right corners. This +is illustrated in Figure~\ref{fig:area}. Note that the origin of the +coordinate system is at the top-left corner of the scan surface as +seen by the sensor (which typically is a mirror image of the scan +surface seen by the user). For this reason, the top-left corner is +the corner for which the abscissa and ordinate values are +simultaneously the {\em smallest} and the bottom-right corner is the +corner for which the abscissa and ordinate values are simulatenously +the {\em largest}. If this coordinate system is not natural for a +given device, it is the job of the backend to perform the necessary +conversions. +\begin{figure}[tbp] + \begin{center} + \leavevmode + \psfig{file=figs/area.eps,height=0.3\textheight} + \caption{Scan area options} + \label{fig:area} + \end{center} +\end{figure} + +The names of the four options that define the scan area are given in +the table below: +\begin{center} +\begin{tabular}{ll} +{\bf Name} & {\bf Description} \\ +\code{\defn{tl-x}} & Top-left $x$ coordinate value \\ +\code{\defn{tl-y}} & Top-left $y$ coordinate value \\ +\code{\defn{br-x}} & Bottom-right $x$ coordinate value \\ +\code{\defn{br-y}} & Bottom-right $y$ coordinate value \\ +\end{tabular} +\end{center} +There are several rules that should be followed by front and backends +regarding these options: +\begin{itemize} + +\item Backends must attach a unit of either pixels + (\code{SANE\_UNIT\_PIXEL}) or millimeters (\code{SANE\_UNIT\_MM}) to + these options. The unit of all four options must be identical. + +\item Whenever meaningful, a backend should attach a range or a + word-list constraint to these options. + +\item A frontend can determine the size of the scan surface by first + checking that the options have range constraints associated. If a + range or word-list constraints exist, the frontend can take the + minimum and maximum values of one of the x and y option + range-constraints to determine the scan surface size. + +\item A frontend must work properly with any or all of these options + missing. + +\end{itemize} + +\input{net.tex} + +\chapter{Contact Information}\label{chap:contact} + +The SANE standard is discussed and evolved via a mailing list. +Anybody with email access to the Internet can automatically join and +leave the discussion group by sending mail to the following address. +\begin{quote}\index{mailing list} +\begin{verbatim} +sane-devel-request@lists.alioth.debian.org +\end{verbatim} +\end{quote} +To subscribe, send a mail with the body ``\verb|subscribe sane-devel|'' to the +above address. + +A complete list of commands supported can be obtained by sending a +mail with a subject of ``\code{help}'' to the above address. The +mailing list is archived and available through the SANE home page at +URL: +\begin{quote} +\url{http://www.sane-project.org/} +\end{quote} + +\newpage +\input{sane.ind} + +\end{document} |