kopia lustrzana https://gitlab.com/sane-project/website
2722 wiersze
111 KiB
TeX
2722 wiersze
111 KiB
TeX
\documentclass[11pt,DVIps]{report}
|
|
|
|
\usepackage{times,epsfig,changebar,html}
|
|
|
|
\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 2.0 proposal 0.08 - rauch/beck}
|
|
\author{}
|
|
\date{Dec 8, 2002}
|
|
|
|
\makeindex
|
|
|
|
\begin{document}
|
|
|
|
\newcommand{\filename}[1]{{\tt #1}}
|
|
\newcommand{\code}[1]{{\tt #1}}
|
|
\newcommand{\var}[1]{{\it #1}}
|
|
\newcommand{\defn}[1]{#1\index{#1}}
|
|
|
|
\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
|
|
(preferable quadratic) pixel. A pixel consists of one or more sample values.
|
|
Each sample value represents one channel (e.g., the red channel).
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
\begin{changebar}
|
|
There are two different types of frames: pixel oriented frames
|
|
\code{\defn{SANE\_FRAME\_RAW}} and arbitrary data frames
|
|
\code{\defn{SANE\_FRAME\_MIME}}. These types are discussed in detail in the
|
|
following sections. The frame types used by the previous version~1 of this
|
|
standard (\code{\defn{SANE\_FRAME\_GRAY}}, \code{\defn{SANE\_FRAME\_RGB}},
|
|
\code{\defn{SANE\_FRAME\_RED}}, \code{\defn{SANE\_FRAME\_GREEN}}, and
|
|
\code{\defn{SANE\_FRAME\_BLUE}}) are obsolete and superseded by
|
|
\code{\defn{SANE\_FRAME\_RAW}}.
|
|
|
|
\subsection{Pixel oriented frames}
|
|
|
|
The type of pixel oriented frames is \code{\defn{SANE\_FRAME\_RAW}}. 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 \code{format\_desc} member of the
|
|
\code{SANE\_Parameters} structured type. See section~\ref{sec:sanegetparameters}
|
|
on page~\pageref{sec:sanegetparameters} for details about the format
|
|
descriptions.
|
|
\end{changebar}
|
|
|
|
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).
|
|
|
|
\begin{changebar}
|
|
The complete image may consist of several different channels. The number of channels
|
|
is defined by member \code{channels\_per\_image} of \code{SANE\_Parameters}.
|
|
The image may be transmitted in an arbitrary number of frames which can be
|
|
determined by watching the \code{SANE\_PFLAG\_LAST\_FRAME} flag in said type (or by
|
|
counting the channels). Note: This frame type replaces all frame types of
|
|
the SANE standard version 1.
|
|
\end{changebar}
|
|
|
|
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.
|
|
\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.
|
|
|
|
\begin{figure}[htbp]
|
|
\begin{center}
|
|
\leavevmode
|
|
\psfig{file=figs/image-data.eps,width=0.8\textwidth}
|
|
\caption{Bit and byte order of image data}
|
|
\label{fig:pixels}
|
|
\end{center}
|
|
\end{figure}
|
|
|
|
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. The first sample of each byte is represented by the most
|
|
significant bit.
|
|
|
|
\begin{changebar}
|
|
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.
|
|
|
|
\subsection{Arbitrary data frames}
|
|
|
|
It also is possible to transmit arbitrary (not necessaryly pixel oriented)
|
|
data. This allows transmission of compressed images like jpeg, tiff, etc.
|
|
|
|
The type of arbitrary data frames is \code{\defn{SANE\_FRAME\_MIME}}.
|
|
The frame contains arbitrary data of the MIME (see RFC 1521/1522) type that is
|
|
given in the \code{format\_desc} member of the \code{SANE\_Parameters}
|
|
structured type (see section~\ref{sec:sanegetparameters} on
|
|
page~\pageref{sec:sanegetparameters}). 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).
|
|
\end{changebar}
|
|
|
|
\chapter{The SANE Application Programmer Interface (API)}\label{chap:api}
|
|
|
|
\begin{changebar}
|
|
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 \filename{sane/sane-2.h}. This file should
|
|
normally be included via a C pre-processor directive of the form:
|
|
\begin{verbatim}
|
|
#include <sane/sane-2.h>
|
|
\end{verbatim}
|
|
\end{changebar}
|
|
|
|
|
|
\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}
|
|
\begin{changebar}
|
|
|
|
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_String_Const email_backend_author;
|
|
SANE_String_Const backend_website;
|
|
SANE_String_Const device_location;
|
|
SANE_String_Const comment;
|
|
SANE_String_Const reserved_string;
|
|
SANE_Int backend_version_code;
|
|
SANE_Int backend_capablity_flags;
|
|
SANE_Int reserved_int;
|
|
}
|
|
SANE_Device;
|
|
\end{verbatim}
|
|
\end{quote}
|
|
\end{changebar}
|
|
\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 next three 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{Mustek} \\
|
|
\code{Apple} & \code{NEC} \\
|
|
\code{Artec} & \code{Nikon} \\
|
|
\code{Avision} & \code{Plustek} \\
|
|
\code{CANON} & \code{Polaroid} \\
|
|
\code{Connectix} & \code{Ricoh} \\
|
|
\code{Epson} & \code{Sharp} \\
|
|
\code{Fujitsu} & \code{Siemens} \\
|
|
\code{Hewlett-Packard} & \code{Tamarack} \\
|
|
\code{IBM} & \code{UMAX} \\
|
|
\code{Kodak} & \code{Noname} \\
|
|
\code{Logitech} & \\
|
|
\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.
|
|
|
|
\begin{changebar}
|
|
The backend has to set up the string \code{email\_backend\_author}
|
|
with the name and the email address of the backend author or a contact person
|
|
in the format:
|
|
\begin{verbatim}
|
|
Firstname Lastname <name@domain.org>
|
|
\end{verbatim}
|
|
|
|
The string \code{backend\_website} should be set up by the backend
|
|
with the website or ftp address of the backend in the format:
|
|
\begin{verbatim}
|
|
http://www.domain.org/sane-hello/index.html
|
|
\end{verbatim}
|
|
|
|
The backend should fill the string \code{device\_location} with a
|
|
text that describes where a user can find this device. The text
|
|
should be configurable by the administrator. This could e.g. look
|
|
like this:
|
|
\begin{verbatim}
|
|
building 93, 2nd plane, room 2124
|
|
\end{verbatim}
|
|
|
|
The string \code{comment} can be used to display any comment about the device
|
|
to the user. The text should be configurable by the administrator.
|
|
|
|
The string \code{reserved\_string} is unused currently but planned for
|
|
future use.
|
|
|
|
All unused strings must be set to ``'' by the backend.
|
|
|
|
With member \code{backend\_version\_code} a frontend can find
|
|
out the version of a backend it is connected to via one or more meta
|
|
backends.
|
|
|
|
The member \code{backend\_capability\_flags} contains 32 bits that
|
|
are planned to give the backend the chance to inform the frontend about
|
|
its capabilities. The meaning of the flags will be defined when there
|
|
is the need for it. The backend has to set all not defined bits
|
|
(in the moment all 32 bits) to 0.
|
|
|
|
The member \code{reserved\_int} is planned for future use, the backend has
|
|
to set the value of the integer to 0.
|
|
\end{changebar}
|
|
|
|
\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''.
|
|
\begin{changebar}
|
|
If this capability is set for an option of type
|
|
\code{SANE\_TYPE\_GROUP}, all options belonging to the group are also
|
|
advanced, even if they don't set the capabilty themselves.
|
|
\end{changebar}
|
|
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).
|
|
\\
|
|
|
|
\code{\defn{SANE\_CAP\_HIDDEN}} & 128 &
|
|
\begin{changebar}
|
|
If set, this capability indicates that the option shouldn't be
|
|
displayed to and used by the user directly. Instead a hidden option
|
|
is supposed to be automatically used by the frontend, like e.g. the
|
|
``preview'' option.
|
|
If this capability is set for an option of type
|
|
\code{SANE\_TYPE\_GROUP}, all options belonging to the group are also
|
|
hidden, even if they don't set the capabilty themselves.
|
|
A frontend typically doesn't display such options by default but there
|
|
should be a way to override this default behaviour.
|
|
\end{changebar}
|
|
\\
|
|
|
|
\code{\defn{SANE\_CAP\_ALWAYS\_SETTABLE}} & 256 &
|
|
\begin{changebar}
|
|
If set, this capability indicates that the option may be at any time between
|
|
\code{sane\_open()} and \code{sane\_close()}. I.e. it's allowed to set it
|
|
even while an image is acquired.
|
|
\end{changebar}
|
|
\\
|
|
|
|
\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}
|
|
|
|
|
|
\subsection{Internationalization}\label{sec:i18n}
|
|
\begin{changebar}
|
|
All backend texts should be written in english.
|
|
Localization (translation of backend texts) has to be done
|
|
in the frontend. To automatically prepare translation tables
|
|
(e.g. english to german) it is necessary to mark the texts
|
|
that shall be translated.
|
|
|
|
\subsubsection{How is a text marked for translation}
|
|
|
|
The keyword \code{SANE\_I18N} is used to mark a text for translation.
|
|
\code{SANE\_I18N} has to be defined as a dummy prototype:
|
|
|
|
\begin{quote}
|
|
\begin{verbatim}
|
|
#ifndef SANE_I18N
|
|
# define SANE_I18N(text) text
|
|
#endif
|
|
\end{verbatim}
|
|
\end{quote}
|
|
|
|
You should not mark prototypes or variables with \code{SANE\_I18N}
|
|
because it is not possible (or very hard) to find out the
|
|
texts that are covered by prototypes (\verb|SANE_I18N(START_SCAN_TEXT)|) and
|
|
variables (\verb|SANE_I18N(option[7].name)|).
|
|
|
|
A correct marked text can look like this:\\
|
|
\verb|snprintf(buf, sizeof(buf), SANE_I18N("Start scan")|\\
|
|
or\\
|
|
\verb|#define START_SCAN_TEXT SANE_I18N("Start scan")|.\\
|
|
It also is allowed to mark texts in structs because the
|
|
prototype \code{SANE\_I18N} has no effect to the compiler.
|
|
|
|
\subsubsection{Which texts shall be marked for translation?}
|
|
All option texts that are visible for the user should be marked for
|
|
translation. This is:
|
|
\begin{itemize}
|
|
\item
|
|
member \code{title}
|
|
\item
|
|
member \code{desc}
|
|
\item
|
|
member \code{string\_list}
|
|
\end{itemize}
|
|
of \code{SANE\_Option\_Descriptor}.
|
|
|
|
It is not allowed to mark/translate member \code{name}.
|
|
Please also do not mark any error or debug messages that are
|
|
displayed by the backend.
|
|
|
|
\subsubsection{File formats and translation functions}
|
|
The recommended file formats for translation tables are the \code{po} files
|
|
and \code{mo} or \code{gmo} files.
|
|
The po file contains the original text marked with the keyword \code{msgid}
|
|
and the translated text marked with the keyword \code{msgstr}.
|
|
A \code{po} file that contains all needed \code{msgid}s can be created
|
|
e.g. by the gnu gettext tool \verb|xgettext| with the option
|
|
\verb|-k SANE_I18N|.
|
|
The translator adds the translated texts to the \code{po} files.
|
|
The gettext tool \code{msgfmt} converts the \code{po} files to the
|
|
\code{mo} or \code{gmo} files.\\
|
|
|
|
Translation is done in the frontend. A backend has nothing
|
|
to do with the translation of texts.
|
|
The frontend should use the function \code{gettext}
|
|
to translate the texts. This e.g. can look like this:\\
|
|
\verb|snprintf(buf, sizeof(buf), gettext("english text"));|
|
|
|
|
If a frontend author decides to use translation functions that
|
|
need different translation tables, then the frontend is
|
|
responsible to create/convert the translation tables.
|
|
In this case it should use the \code{po} files to create its
|
|
own translation tables from it.\\
|
|
|
|
Note that it is strongly recommended to use the gettext tools.
|
|
\end{changebar}
|
|
|
|
|
|
\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.
|
|
\begin{changebar}
|
|
The same information about
|
|
a device has to be returned when \code{sane\_open} is called.
|
|
\end{changebar}
|
|
\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}.
|
|
\begin{changebar}
|
|
The description of the device
|
|
is returned in \code{**device\_description}. This is the
|
|
same description that is returned in the list by \code{sane\_get\_devices}.
|
|
The returned data \code{*h} and \code{*device\_description} is guaranteed
|
|
to remain unchanged and valid until a call to \code{sane\_close()}
|
|
is performed.
|
|
\end{changebar}
|
|
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,
|
|
const SANE_Device ** device_description);
|
|
\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
|
|
\begin{changebar}
|
|
value, the availability, or the constraint of one or more {\em
|
|
other\/} options.
|
|
\end{changebar}
|
|
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.
|
|
\\
|
|
|
|
\code{\defn{SANE\_INFO\_INVALIDATE\_PREVIEW}} & 8 &
|
|
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 \code{*i} 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.
|
|
\\
|
|
|
|
|
|
\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}\label{sec:sanegetparameters}}
|
|
|
|
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{changebar}
|
|
\begin{quote}
|
|
\begin{verbatim}
|
|
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;
|
|
\end{verbatim}
|
|
\end{quote}
|
|
\end{changebar}
|
|
|
|
\begin{changebar}
|
|
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}.
|
|
The frame types used by version~1 of this standard
|
|
(\code{\defn{SANE\_FRAME\_GRAY}}, \code{\defn{SANE\_FRAME\_RGB}},
|
|
\code{\defn{SANE\_FRAME\_RED}}, \code{\defn{SANE\_FRAME\_GREEN}}, and
|
|
\code{\defn{SANE\_FRAME\_BLUE}}) are obsolete and superseded by the
|
|
frame type \code{\defn{SANE\_FRAME\_RAW}}.
|
|
|
|
\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\_RAW}} & 5 & Arbitrary pixel property transmission. \\
|
|
\code{\defn{SANE\_FRAME\_MIME}} & 6 & Data described by a mime descriptor. \\
|
|
|
|
\hline
|
|
\end{tabular}
|
|
\caption{Frame Format (\code{SANE\_Frame})}
|
|
\label{tab:frameformat}
|
|
\end{center}
|
|
\end{table}
|
|
|
|
The \code{flags} 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:
|
|
|
|
\begin{itemize}
|
|
|
|
\item
|
|
\code{SANE\_PFLAG\_LAST\_FRAME} (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).
|
|
|
|
\item
|
|
\code{SANE\_PFLAG\_MORE\_IMAGES} (bit 1, bitvalue 2) is set to 1 to indicate
|
|
further pending images. The frontend is expected to call \code{sane\_start}
|
|
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 \code{sane\_start()}.
|
|
|
|
\item
|
|
\code{SANE\_PFLAG\_NEW\_PAGE} (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.
|
|
|
|
\item
|
|
\code{SANE\_PFLAG\_BACKSIDE} (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).
|
|
|
|
\end{itemize}
|
|
|
|
Note, that \code{flags} is compatible to member \code{last\_frame} of
|
|
\code{SANE\_Parameters} of SANE standard version 1 (same size
|
|
and only bit 0 (bitvalue 1) was used with same function).
|
|
\end{changebar}
|
|
|
|
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}.
|
|
\begin{changebar}
|
|
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.
|
|
\end{changebar}
|
|
|
|
Member \code{bytes\_per\_line} specifies the number of bytes that comprise one
|
|
scan line.
|
|
\begin{changebar}
|
|
If this value is not applicable for image data of type
|
|
\code{SANE\_FRAME\_MIME}, it must be set to -1. In this case the frontend
|
|
should just call \code{sane\_read} until \code{SANE\_STATUS\_EOF} is returned.
|
|
\end{changebar}
|
|
|
|
Member \code{depth} specifies the number of bits per sample.
|
|
\begin{changebar}
|
|
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).
|
|
\end{changebar}
|
|
|
|
Member \code{pixels\_per\_line} specifies the number of pixels that
|
|
comprise one scan line.
|
|
\begin{changebar}
|
|
If unavailable or not applicable, set to -1.
|
|
\end{changebar}
|
|
|
|
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:
|
|
\begin{changebar}
|
|
\[
|
|
c >= \left\{
|
|
\begin{array}{ll}
|
|
\lceil B\cdot n / 8\rceil & \mbox{if $d=1$}\\
|
|
B\cdot n \cdot d / 8 & \mbox{if $d>1$}
|
|
\end{array}
|
|
\right.
|
|
\]
|
|
\end{changebar}
|
|
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.
|
|
|
|
\begin{changebar}
|
|
Member \code{channels\_per\_image} specifies the number of channels the
|
|
image consists of. When the image is transmitted in more than one frame
|
|
\code{channels\_per\_image} has to be the same for all frames for this image.
|
|
|
|
Member \code{format\_desc} is used to describe the details of the frame
|
|
formats. Its meaning differs between the two formats:
|
|
|
|
\begin{itemize}
|
|
\item
|
|
\code{SANE\_FRAME\_RAW}:
|
|
The \code{format\_desc} contains a description of the channel data and
|
|
an optional depth information separated by a colon(:).
|
|
|
|
A plane is descibed by one channel, e.g. ``\code{gray}'' or ``\code{gray:12}''.
|
|
|
|
Channel interleaved data is described by a comma separated list of channel descriptions,
|
|
for example ``\code{red,green,blue}'' or ``\code{red:8,green:8,blue:8}'',
|
|
the channel data is sent in the given order.
|
|
|
|
The depth information does {\bf not} 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 \code{depth}.
|
|
|
|
Well known channels are \code{red}, \code{green}, \code{blue} and \code{gray}.
|
|
It also is allowed to use other channel descriptions, e.g. if you
|
|
use an infrared camera or scanner it could be \code{infrared} or
|
|
a wavelength description like \code{1100nm}, but be aware that a
|
|
frontend may not be able to display such channels with useful colors.
|
|
|
|
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 \code{channels\_per\_image}.
|
|
|
|
\item
|
|
\code{SANE\_FRAME\_MIME}:
|
|
|
|
\code{format\_desc} 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.
|
|
|
|
When data is transmitted with the frame type \code{SANE\_FRAME\_MIME}
|
|
all data has to be transmitted within one frame, multiple frames
|
|
are not allowed (so the flag \code{last\_frame} has to be set
|
|
when using this frame type).
|
|
|
|
A SANE backend must be able to at least optionally transmit
|
|
\code{SANE\_FRAME\_RAW} (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.
|
|
\end{itemize}
|
|
|
|
The member \code{proposed\_filename} 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 ``''.
|
|
|
|
In the case of raw frames, \code{proposed\_filename} 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.
|
|
|
|
For MIME frames \code{proposed\_filename} can contain either:
|
|
|
|
\begin{itemize}
|
|
\item
|
|
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:
|
|
|
|
\item
|
|
A complete filename, including extension.
|
|
\end{itemize}
|
|
|
|
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.
|
|
|
|
The string \code{proposed\_comment} 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.
|
|
|
|
The members \code{dpi\_x} and \code{dpi\_y} 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.
|
|
|
|
The member \code{reserved} 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.
|
|
\end{changebar}
|
|
|
|
|
|
\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}
|
|
\begin{changebar}
|
|
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.
|
|
\end{changebar}
|
|
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.
|
|
\begin{changebar}
|
|
If \code{sane\_read} sends back any image data it
|
|
is not allowed to return with \code{SANE\_STATUS\_EOF}.
|
|
\end{changebar}
|
|
\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}
|
|
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.
|
|
\begin{changebar}
|
|
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.
|
|
\end{changebar}
|
|
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.
|
|
|
|
\begin{changebar}
|
|
Image data is collected by repeatedly calling \code{sane\_read()}
|
|
until 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 of a red/green/blue image or multiple images),
|
|
it can call \code{sane\_start()} again.
|
|
If the \code{SANE\_PFLAG\_LAST\_FRAME} bit is set in \code{flags}, the
|
|
current image is complete. In this case, it should be tested, if
|
|
\code{flags} has the \code{SANE\_PFLAG\_MORE\_IMAGES} bit set.
|
|
If yes, further calls to \code{sane\_start()} 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
|
|
\code{sane\_start()} return an error like \code{SANE\_STATUS\_NO\_DOCS}.
|
|
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 \code{SANE\_PFLAG\_LAST\_FRAME} on
|
|
and \code{SANE\_PFLAG\_MORE\_IMAGES} off is encountered, or an error other
|
|
than \code{SANE\_STATUS\_EOF} occurs in a SANE function.
|
|
Note that \code{SANE\_STATUS\_NO\_DOCS} also is an allowed way for the backend
|
|
to indicate the end of a multiple image scan.
|
|
|
|
A frontend may choose to skip frames (e.g. because it cannot parse them),
|
|
which is accomplished by simply calling \code{sane\_start} again, which will get
|
|
you to the next frame, without having to read and discard the current one.
|
|
|
|
In order to prematurely stop scanning and to reset the backend state,
|
|
\code{sane\_cancel()} can be called at any time. This call is required
|
|
as well after normal termination of a multiple image scan as described above.
|
|
\end{changebar}
|
|
|
|
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.
|
|
|
|
\begin{changebar}
|
|
The following C sample code implements a reference loop for acquiring
|
|
multiple images:
|
|
|
|
\begin{verbatim}
|
|
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);
|
|
\end{verbatim}
|
|
|
|
\end{changebar}
|
|
|
|
|
|
\section{Well-Known Options}\index{well-known options}
|
|
|
|
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.
|
|
|
|
\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 Options}\index{scan resolution}\index{resolution option}
|
|
|
|
Option \code{resolution} is used to select the resolution at which an
|
|
image should be acquired.
|
|
\begin{changebar}
|
|
When the backend wants to allow different
|
|
values for x- and y-resolution it has to define the options
|
|
\code{x-resolution} and \code{y-resolution}. Note that only
|
|
the option \code{resolution} {\bf or} the options
|
|
\code{x-resolution} {\bf and} \code{y-resolution} may be active at the
|
|
same time.
|
|
\end{changebar}
|
|
|
|
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).
|
|
|
|
These options are not mandatory, but if a backend does support them, it
|
|
must implement them 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.
|
|
\begin{changebar}
|
|
When the \code{preview} option is set the backend should transfer
|
|
the image in frame type \code{SANE\_FRAME\_RAW} if possible.
|
|
\end{changebar}
|
|
|
|
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\label{subsec:scanarea}}\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.
|
|
|
|
\begin{changebar}
|
|
\item A frontend may temporarily set the values in a way that
|
|
\code{tl-x} is larger than \code{br-x} and \code{tl-y} is larger than
|
|
\code{br-y}.
|
|
\end{changebar}
|
|
|
|
\end{itemize}
|
|
|
|
\begin{changebar}
|
|
These options are not mandatory, but if a backend does support them, it
|
|
must implement them in a manner consistent with the above definition.
|
|
\end{changebar}
|
|
|
|
\begin{changebar}
|
|
\subsection{Depth Option}\index{bit depth option}
|
|
Option \code{depth} 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 \code{SANE\_TYPE\_INT}.
|
|
The unit is \code{SANE\_UNIT\_BIT}. 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 \code{mode}.
|
|
|
|
This option is not mandatory, but if a backend does support it, it
|
|
must implement it in a manner consistent with the above definition.
|
|
\end{changebar}
|
|
|
|
\begin{changebar}
|
|
\subsection{Scan Mode Options}\index{mode options}
|
|
The option \code{mode} defines a \code{SANE\_CONSTRAINT\_STRING\_LIST}
|
|
of type \code{SANE\_TYPE\_STRING}.
|
|
It is used to select the scanmode (e.g. Color or Gray).
|
|
Well known modes are: \code{Color}, \code{Gray}, \code{Halftone}
|
|
and \code{Lineart}. \code{Color} and \code{Gray} are multi bit
|
|
modes (8 or 16 bits/sample), \code{Halftone} and \code{Lineart}
|
|
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 \code{Gray}
|
|
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.
|
|
\end{changebar}
|
|
|
|
\begin{changebar}
|
|
\subsection{Scan Source Options}\index{source options}
|
|
The option \code{source} is used to select the scan source
|
|
(e.g. Automatic Document Feeder).
|
|
It defines a \code{SANE\_CONSTRAINT\_STRING\_LIST}
|
|
of type \code{SANE\_TYPE\_STRING}.
|
|
Well known sources are: \code{Flatbed}, \code{Transparancy Adapter} and
|
|
\code{Automatic Document Feeder}.
|
|
|
|
This option is not mandatory, but if a backend does support it, it
|
|
must implement it in a manner consistent with the above definition.
|
|
\end{changebar}
|
|
|
|
\begin{changebar}
|
|
\subsection{Threshold Option}\index{threshold option}
|
|
The option \code{threshold} 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 \code{SANE\_TYPE\_FIXED}.
|
|
The unit is \code{SANE\_UNIT\_PERCENT}. The value range
|
|
should be 0.0\ldots100.0 if possible.
|
|
It defines the minimum intensity to get a white point / full intensity.
|
|
|
|
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\ldots70 percent).
|
|
|
|
This option is not mandatory, but if a backend does support it, it
|
|
must implement it in a manner consistent with the above definition.
|
|
\end{changebar}
|
|
|
|
\begin{changebar}
|
|
\subsection{Gamma Table Options}\index{gamma table options}
|
|
The \code{gamma-table} option defines a \code{SANE\_CONSTRAINT\_RANGE}
|
|
of the type \code{SANE\_TYPE\_INT} which represents the gamma correction
|
|
table for gray. In color mode the \code{gamma-table} may be used to set
|
|
a common gamma correction for red, green and blue. The options
|
|
\code{red-gamma-table}, \code{green-gamma-table} and \code{blue-gamma-table}
|
|
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
|
|
\code{gamma-table} option, only the \code{red-}, \code{green-} and
|
|
\code{blue-gamma-table} 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:
|
|
\begin{verbatim}
|
|
red_value = gamma-table(red-gamma-table(value))
|
|
green_value = gamma-table(green-gamma-table(value))
|
|
blue_value = gamma-table(blue-gamma-table(value))
|
|
\end{verbatim}
|
|
|
|
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.
|
|
|
|
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.
|
|
\end{changebar}
|
|
|
|
\begin{changebar}
|
|
\subsection{Analog Gamma}\index{analog gamma option}
|
|
The option \code{analog-gamma} 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 \code{SANE\_TYPE\_FIXED}.
|
|
The unit is \code{SANE\_UNIT\_NONE}. 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 \code{analog-gamma-red},
|
|
\code{analog-gamma-green} and \code{analog-gamma-blue}.
|
|
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.
|
|
|
|
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.
|
|
|
|
This option is not mandatory, but if a backend does support it, it
|
|
must implement it in a manner consistent with the above definition.
|
|
\end{changebar}
|
|
|
|
|
|
\begin{changebar}
|
|
\subsection{Shadow Option}\index{shadow options}
|
|
The option \code{shadow} is used to define the shadow level / black point level.
|
|
The type of this option is \code{SANE\_TYPE\_FIXED}.
|
|
The unit is \code{SANE\_UNIT\_PERCENT}. The value range
|
|
should be 0.0\ldots100.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:
|
|
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\ldots70 percent).
|
|
In color mode there can be options \code{shadow-red}, \code{shadow-green}
|
|
and \code{shadow-blue}, in this case the \code{shadow} 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.
|
|
|
|
This option is not mandatory, but if a backend does support it, it
|
|
must implement it in a manner consistent with the above definition.
|
|
\end{changebar}
|
|
|
|
|
|
\begin{changebar}
|
|
\subsection{Highlight Option}\index{hightlight options}
|
|
The option \code{highlight} is used to define the highlight level / white point level.
|
|
The type of this option is \code{SANE\_TYPE\_FIXED}.
|
|
The unit is \code{SANE\_UNIT\_PERCENT}. The value range
|
|
should be 0.0\ldots100.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:
|
|
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\ldots70 percent).
|
|
In color mode there can be options \code{highlight-red}, \code{highlight-green}
|
|
and \code{highlight-blue}, in this case \code{highlight} 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.
|
|
|
|
This option is not mandatory, but if a backend does support it, it
|
|
must implement it in a manner consistent with the above definition.
|
|
\end{changebar}
|
|
|
|
|
|
\begin{changebar}
|
|
\subsection{Lamp Options}\index{lamp-on option}\index{lamp-off option}
|
|
|
|
The options \code{lamp-on} and \code{lamp-off} are button options
|
|
(\code{SANE\_TYPE\_BUTTON}) and don't have a unit (\code{SANE\_UNIT\_NONE}).
|
|
|
|
Option \code{lamp-on} is used to turn on the lamp of the scanner while
|
|
\code{lamp-off} turns it off.
|
|
|
|
These options are not mandatory, but if a backend does support them, it
|
|
must implement them in a manner consistent with the above definition.
|
|
\end{changebar}
|
|
|
|
|
|
\begin{changebar}
|
|
\subsection{Scanner Button Options}\index{scanner button options}
|
|
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.
|
|
|
|
A backend that does make available the scanner-buttons has to
|
|
implement the following options:\\
|
|
\code{scanner-buttons-lock} is of type \code{SANE\_TYPE\_BOOL}, default = \code{SANE\_FALSE}\\
|
|
\code{scanner-buttons-status} is of type \code{SANE\_TYPE\_INT}, default = 0\\
|
|
\code{scanner-buttons-status-update} is of type \code{SANE\_TYPE\_BUTTON}\\
|
|
When setting these options the backend does not set \code{SANE\_INFO\_RELOAD\_OPTIONS}
|
|
or \code{SANE\_INFO\_RELOAD\_PARAMS} if not explictly defined.
|
|
|
|
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).
|
|
|
|
\begin{itemize}
|
|
|
|
\item
|
|
A frontend that wants to read the button status has to lock the
|
|
button functions at first. For this it does set the option
|
|
\code{scanner-buttons-lock} to \code{SANE\_TRUE}.
|
|
While setting the value of option \code{scanner-buttons-lock} to \code{SANE\_TRUE}
|
|
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.
|
|
|
|
\begin{itemize}
|
|
\item
|
|
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 \code{scanner-buttons-lock} is set to \code{SANE\_TRUE}
|
|
\item
|
|
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 \code{scanner-buttons-lock} is set to \code{SANE\_FALSE}. 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 \code{scanner-buttons-lock} is set to \code{SANE\_TRUE}
|
|
\end{itemize}
|
|
|
|
\item
|
|
The frontend does read the value of option \code{scanner-buttons-lock}. If
|
|
it is \code{SANE\_TRUE} then the frontend has access to the scanner buttons.
|
|
If it is \code{SANE\_FALSE} then access has been denied.
|
|
|
|
\item
|
|
If the button access is allowed the frontend has to do the following about
|
|
once per second (while not scanning):
|
|
\begin{itemize}
|
|
\item
|
|
The frontend does set option \code{scanner-buttons-status-update}.
|
|
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 \code{scanner-buttons-status}, 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 \code{scanner-buttons-lock} to \code{SANE\_FALSE}
|
|
and does set \code{SANE\_INFO\_RELOAD\_OPTIONS} to inform the frontend that it has
|
|
lost permission to access the scanner-button functions.
|
|
If access is not allowed it does set the \code{scanner-buttons-status} to 0.
|
|
|
|
\item
|
|
The frontend does read the value of option \code{scanner-buttons-status}
|
|
\end{itemize}
|
|
|
|
\item
|
|
When the frontend does exit or it does not want to use the buttons
|
|
it does set option \code{scanner-buttons-lock} to \code{SANE\_FALSE}.
|
|
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 \code{scanner-buttons-lock} to \code{SANE\_FALSE}.
|
|
|
|
\code{sane\_close()} should do the same as setting option
|
|
\code{scanner-buttons-lock} to \code{SANE\_FALSE}.
|
|
|
|
\end{itemize}
|
|
\end{changebar}
|
|
|
|
\begin{changebar}
|
|
\subsection{Batch Scan Options}\index{Batch Scan Options}
|
|
|
|
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 \code{batch-scan},
|
|
\code{batch-scan-next-tl-x}, \code{batch-scan-next-tl-y},
|
|
\code{batch-scan-next-br-x}, and \code{batch-scan-next-br-y}. The option
|
|
\code{batch-scan} provides a string list with the values of \code{No} if
|
|
batch scanning isn't used, \code{Start} for the first, \code{End} for the last
|
|
and \code{Loop} 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 \ref{subsec:scanarea}).
|
|
|
|
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.
|
|
\end{changebar}
|
|
|
|
|
|
|
|
|
|
\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@mostang.com
|
|
\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.mostang.com/sane/}
|
|
\end{quote}
|
|
|
|
\newpage
|
|
\input{sane.ind}
|
|
|
|
\end{document}
|