Merge branch 'release/debian/1.0.31-1_experimental1' into masterdebian/1.0.31-1_experimental1

1 files changed, 0 insertions, 479 deletions

diff --git a/doc/net.tex b/doc/net.tex
deleted file mode 100644
index d6bc110..0000000
--- a/doc/net.tex
+++ /dev/null
@@ -1,479 +0,0 @@
-\chapter{Network Protocol}\label{chap:net}
-
-The SANE interface has been designed to facilitate network access to
-image acquisition devices.  In particular, most SANE implementations
-are expected to support a network backend (net client) and a
-corresponding network daemon (net server) that allows accessing image
-acquisition devices through a network connection.  Network access is
-useful in several situations:
-\begin{itemize}
-
-\item To provide controlled access to resources that are inaccessible
-  to a regular user.  For example, a user may want to access a device
-  on a host where she has no account on.  With the network protocol,
-  it is possible to allow certain users to access scanners without
-  giving them full access to the system.
-
-  Controlling access through the network daemon can be useful even in
-  the local case: for example, certain backends may require root
-  privileges to access a device.  Rather than installing each frontend
-  as setuid-root, a system administrator could instead install the
-  SANE network daemon as setuid-root.  This enables regular users to
-  access the privileged device through the SANE daemon (which,
-  presumably, supports a more fine-grained access control mechanism
-  than the simple setuid approach).  This has the added benefit that
-  the system administrator only needs to trust the SANE daemon, not
-  each and every frontend that may need access to the privileged
-  device.
-
-\item Network access provides a sense of ubiquity of the available
-  image acquisition devices.  For example, in a local area network
-  environment, this allows a user to log onto any machine and have
-  convenient access to any resource available to any machine on the
-  network (subject to permission constraints).
-
-\item For devices that do not require physical access when used (e.g.,
-  video cameras), network access allows a user to control and use
-  these devices without being in physical proximity.  Indeed, if such
-  devices are connected to the Internet, access from any place in the
-  world is possible.
-
-\end{itemize}
-
-The network protocol described in this chapter has been design with
-the following goals in mind:
-\begin{enumerate}
-
-\item Image transmission should be efficient (have low encoding
-  overhead).
-
-\item Accessing option descriptors on the client side must be
-  efficient (since this is a very common operation).
-
-\item Other operations, such as setting or inquiring the value of an
-  option are less performance critical since they typically require
-  explicit user action.
-
-\item The network protocol should be simple and easy to implement on
-  any host architecture and any programming language.
-
-\end{enumerate}
-The SANE protocol can be run across any transport protocol that
-provides reliable data delivery.  While SANE does not specify a
-specific transport protocol, it is expected that TCP/IP will be among
-the most commonly used protocols.
-
-\section{Data Type Encoding}
-
-\subsection{Primitive Data Types}
-
-The four primitive types of the SANE standard are encoded as follows:
-\begin{description}
-
-\item[\code{\defn{SANE\_Byte}}:] A byte is encoded as an 8 bit value.
-  Since the transport protocol is assumed to be byte-orientd, the bit
-  order is irrelevant.
-
-\item[\code{\defn{SANE\_Word}}:] A word is encoded as 4 bytes (32
-  bits).  The bytes are ordered from most-significant to
-  least-significant byte (big-endian byte-order).
-
-\item[\code{\defn{SANE\_Char}}:] A character is currently encoded as an 8-bit
-  ISO LATIN-1 value.  An extension to support wider character sets (16 or 32
-  bits) is planned for the future, but not supported at this point.
-
-\item[\code{\defn{SANE\_String}}:] A string pointer is encoded as a
-  \code{SANE\_Char} array.  The trailing NUL byte is considered part
-  of the array and a \code{NULL} pointer is encoded as a zero-length
-  array.
-
-\item[\code{\defn{SANE\_Handle}}:] A handle is encoded like a word.
-  The network backend needs to take care of converting these integer
-  values to the opaque pointer values that are presented to the user
-  of the network backend.  Similarly, the SANE daemon needs to take
-  care of converting the opaque pointer values it receives from its
-  backends into 32-bit integers suitable for use for network encoding.
-
-\item[{\em\defn{enumeration types}}:] Enumeration types are encoded
-  like words.
-
-\end{description}
-
-\subsection{Type Constructors}
-
-Closely following the type constructors of the C language, the SANE network
-protocol supports the following four constructors:
-\begin{description}
-
-\item[{\em\defn{pointer}}:] A pointer is encoded by a word that indicates
-  whether the pointer is a NULL-pointer which is then followed by the
-  value that the pointer points to (in the case of a non-NULL pointer;
-  in the case of a NULL pointer, no bytes are encoded for the pointer
-  value).
-
-\item[{\em\defn{array}}:] An array is encoded by a word that indicates
-  the length of the array followed by the values of the elements in
-  the array.  The length may be zero in which case no bytes are
-  encoded for the element values.
-
-\item[{\em\defn{structure}}:] A structure is encoded by simply encoding the
-  structure members in the order in which they appear in the
-  corresponding C type declaration.
-
-\item[{\em\defn{union}}:] A union must always be accompanied by a tag
-  value that indicates which of the union members is the currently the
-  active one.  For this reason, the union itself is encoded simply by
-  encoding the value of the currently active member.
-
-\end{description}
-
-Note that for type constructors, the pointer, element, or member
-values themselves may have a constructed type.  Thus, the above rules
-should be applied recursively until a sequence of primitive types has
-been found.
-
-Also SANE had no need for encoding of circular structures.  This
-greatly simplifies the network protocol.
-
-\section{Remote Procedure Call Requests}
-
-The SANE network protocol is a client/server-style remote procedure
-call (RPC) protocol.  This means that all activity is initiated by the
-client side (the network backend)---a server is restricted to
-answering requests sent by the client.
-
-The data transferred from the client to the server is comprised of the RPC code
-(as a \code{SANE\_WORD}), followed by arguments defined in the {\bf request}
-column below.  The format of the server's answer is given in the {\bf reply}
-column.
-
-\subsection{\code{\defn{SANE\_NET\_INIT}}}
-
-RPC Code: 0
-
-This RPC establishes a connection to a particular SANE network daemon.
-It must be the first call in a SANE network session.  The parameter
-and reply arguments for this call are shown in the table below:
-\begin{center}
-\begin{tabular}{ll}
-  {\bf request:} & {\bf reply:} \\
-  \code{SANE\_Word version\_code} & \code{SANE\_Word status} \\
-  \code{SANE\_String user\_name}   & \code{SANE\_Word version\_code} \\
-\end{tabular}
-\end{center}
-The \code{version\_code} argument in the request is the SANE
-version-code of the network backend that is contacting the network
-daemon (see Section~\ref{sec:saneversioncode}).  The
-``build-revision'' in the version code is used to hold the network
-protocol version.  The SANE network daemon receiving such a request
-must make sure that the network protocol version corresponds to a
-supported version since otherwise the encoding of the network stream
-may be incompatible (even though the SANE interface itself may be
-compatible).  The \code{user\_name} argument is the name of the user
-on whose behalf this call is being performed.  If the network backend
-cannot determine a user-name, it passes a \code{NULL} pointer for this
-argument.  No trust should be placed in the authenticity of this
-user-name.  The intent of this string is to provide more convenience
-to the user.  E.g., it could be used as the default-user name in
-subsequent authentication calls.
-
-In the reply, \code{status} indicates the completion status.  If the
-value is anything other than \code{SANE\_STA\-TUS\_GOOD}, the
-remainder of the reply has undefined values.\footnote{The sane network
-  daemon should be careful not to leak information in the undefined
-  portion of the reply.} The \code{version\_code} argument returns the
-SANE version-code that the network daemon supports.  See the comments
-in the previous paragraph on the meaning of the build-revision in this
-version code.
-
-\subsection{\code{\defn{SANE\_NET\_GET\_DEVICES}}}
-
-RPC Code: 1
-
-This RPC is used to obtain the list of devices accessible by the SANE
-daemon.
-\begin{center}
-\begin{tabular}{ll}
-  {\bf request:} & {\bf reply:} \\
-  \code{void} & \code{SANE\_Word status} \\
-              & \code{SANE\_Device ***device\_list} \\
-\end{tabular}
-\end{center}
-There are no arguments in the request for this call.
-
-In the reply, \code{status} indicates the completion status.  If the
-value is anything other than \code{SANE\_STA\-TUS\_GOOD}, the
-remainder of the reply has undefined values.  The \code{device\_list}
-argument is a pointer to a \code{NULL}-terminated array of
-\code{SANE\_Device} pointers.
-
-\subsection{\code{\defn{SANE\_NET\_OPEN}}}
-
-RPC Code: 2
-
-This RPC is used to open a connection to a remote SANE device.
-\begin{center}
-\begin{tabular}{ll}
-  {\bf request:} & {\bf reply:} \\
-  \code{SANE\_String device\_name} & \code{SANE\_Word status} \\
-                                   & \code{SANE\_Word handle} \\
-                                   & \code{SANE\_String resource} \\
-\end{tabular}
-\end{center}
-The \code{device\_name} argument specifies the name of the device to
-open.
-
-In the reply, \code{status} indicates the completion status.  If the
-value is anything other than \code{SANE\_STA\-TUS\_GOOD}, the
-remainder of the reply has undefined values.  The \code{handle}
-argument specifies the device handle that uniquely identifies the
-connection.  The \code{resource} argument is used to request
-authentication.  If it has a non-\code{NULL} value, the network
-backend should authenticate the specified resource and then retry this
-operation (see Section~\ref{sec:authorization} for details on how to
-authorize a resource).
-
-\subsection{\code{\defn{SANE\_NET\_CLOSE}}}
-
-RPC Code: 3
-
-This RPC is used to close a connection to a remote SANE device.
-\begin{center}
-\begin{tabular}{ll}
-  {\bf request:} & {\bf reply:} \\
-  \code{SANE\_Word handle} & \code{SANE\_Word dummy} \\
-\end{tabular}
-\end{center}
-The \code{handle} argument identifies the connection that should be
-closed.
-
-In the reply, the \code{dummy} argument is unused.  Its purpose is to
-ensure proper synchronization (without it, a net client would not be
-able to determine when the RPC has completed).
-
-\subsection{\code{\defn{SANE\_NET\_GET\_OPTION\_DESCRIPTORS}}}
-
-RPC Code: 4
-
-This RPC is used to obtain {\em all\/} the option descriptors for a
-remote SANE device.
-\begin{center}
-\begin{tabular}{ll}
-  {\bf request:} & {\bf reply:} \\
-  \code{SANE\_Word handle} & \code{Option\_Descriptor\_Array odesc} \\
-\end{tabular}
-\end{center}
-The \code{handle} argument identifies the remote device whose option
-descriptors should be obtained.
-
-In the reply, the \code{odesc} argument is used to return the array of
-option descriptors.  The option descriptor array has the following
-structure:
-\begin{quote}\index{Option\_Descriptor\_Array}
-\begin{verbatim}
-struct Option_Descriptor_Array
-  {
-    SANE_Word num_options;
-    SANE_Option_Descriptor **desc;
-  };
-\end{verbatim}
-\end{quote}
-
-
-\subsection{\code{\defn{SANE\_NET\_CONTROL\_OPTION}}}
-
-RPC Code: 5
-
-This RPC is used to control (inquire, set, or set to automatic) a
-specific option of a remote SANE device.
-\begin{center}
-\begin{tabular}{ll}
-  {\bf request:} & {\bf reply:} \\
-  \code{SANE\_Word handle}      & \code{SANE\_Status status} \\
-  \code{SANE\_Word option}      & \code{SANE\_Word info} \\
-  \code{SANE\_Word action}      & \code{SANE\_Word value\_type} \\
-  \code{SANE\_Word value\_type} & \code{SANE\_Word value\_size} \\
-  \code{SANE\_Word value\_size} & \code{void *value} \\
-  \code{void *value}            & \code{SANE\_String *resource} \\
-\end{tabular}
-\end{center}
-The \code{handle} argument identifies the remote device whose option
-should be controlled.  Argument \code{option} is the number (index) of
-the option that should be controlled.  Argument \code{action}
-specifies what action should be taken (get, set, or set automatic).
-Argument \code{value\_type} specifies the type of the option value
-(must be one of \code{SANE\_TYPE\_BOOL}, \code{SANE\_TYPE\_INT},
-\code{SANE\_TYPE\_FIXED}, \code{SANE\_TYPE\_STR\-ING},
-\code{SANE\_TYPE\_BUTTON}).  Argument \code{value\_size} specifies
-the size of the option value in number of bytes (see
-Section~\ref{sec:valuesize} for the precise meaning of this value).
-Finally, argument \code{value} is a pointer to the option value.  It
-must be a writeable area that is at least \code{value\_size} bytes
-large. (Note that this area must be writable even if the action is to
-set the option value.  This is because the backend may not be able to
-set the exact option value, in which case the option value is used to
-return the next best value that the backend has chosen.)
-
-In the reply, argument \code{resource} is set to the name of the
-resource that must be authorized before this call can be retried.  If
-this value is non-\code{NULL}, all other arguments have undefined
-values (see Section~\ref{sec:authorization} for details on how to
-authorize a resource).  Argument \code{status} indicates the
-completion status.  If the value is anything other than
-\code{SANE\_STA\-TUS\_GOOD}, the remainder of the reply has undefined
-values.  The \code{info} argument returns the information on how well
-the backend was able to satisfy the request.  For details, see the
-description of the corresponding argument in
-Section~\ref{sec:control}.  Arguments \code{value\_type} and
-\code{value\_size} have the same values as the arguments by the same
-name in corresponding request.  The values are repeated here to ensure
-that both the request and the reply are self-contained (i.e., they can
-be encoded and decoded independently).  Argument \code{value} is holds
-the value of the option that has become effective as a result of this
-RPC.
-
-
-\subsection{\code{\defn{SANE\_NET\_GET\_PARAMETERS}}}
-
-RPC Code: 6
-
-This RPC is used to obtain the scan parameters of a remote SANE
-device.
-\begin{center}
-\begin{tabular}{ll}
-  {\bf request:} & {\bf reply:} \\
-  \code{SANE\_Word handle} & \code{SANE\_Status status} \\
-                           & \code{SANE\_Parameters params} \\
-\end{tabular}
-\end{center}
-The \code{handle} argument identifies the connection to the remote
-device whose scan parameters should be returned.
-
-In the reply, \code{status} indicates the completion status.  If the
-value is anything other than \code{SANE\_STA\-TUS\_GOOD}, the
-remainder of the reply has undefined values.  The argument
-\code{params} is used to return the scan parameters.
-
-\subsection{\code{\defn{SANE\_NET\_START}}}
-
-RPC Code: 7
-
-This RPC is used to start image acquisition (scanning).
-\begin{center}
-\begin{tabular}{ll}
-  {\bf request:} & {\bf reply:} \\
-  \code{SANE\_Word handle} & \code{SANE\_Status status} \\
-                           & \code{SANE\_Word port} \\
-                           & \code{SANE\_Word byte\_order} \\
-                           & \code{SANE\_String resource} \\
-\end{tabular}
-\end{center}
-The \code{handle} argument identifies the connection to the remote
-device from which the image should be acquired.
-
-In the reply, argument \code{resource} is set to the name of the
-resource that must be authorized before this call can be retried.  If
-this value is non-\code{NULL}, all other arguments have undefined
-values (see Section~\ref{sec:authorization} for details on how to
-authorize a resource).  Argument, \code{status} indicates the
-completion status.  If the value is anything other than
-\code{SANE\_STA\-TUS\_GOOD}, the remainder of the reply has
-undefined values.  The argument \code{port} returns the port number
-from which the image data will be available.  To read the image data,
-a network client must connect to the remote host at the indicated port
-number.  Through this port, the image data is transmitted as a
-sequence of data records.  Each record starts with the data length in
-bytes.  The data length is transmitted as a sequence of four bytes.
-These bytes should be interpreted as an unsigned integer in big-endian
-format.  The four length bytes are followed by the number of data
-bytes indicated by the length.  Except for byte-order, the data is in
-the same format as defined for \code{sane\_read()}.  Since some
-records may contain no data at all, a length value of zero is
-perfectly valid.  The special length value of \code{0xffffffff} is
-used to indicate the end of the data stream.  That is, after receiving
-a record length of \code{0xffffffff}, the network client should close
-the data connection and stop reading data.
-
-Argument \code{byte\_order} specifies the byte-order of the image
-data.  A value of 0x1234 indicates little-endian format, a value of
-0x4321 indicates big-endian format.  All other values are presently
-undefined and reserved for future enhancements of this protocol.  The
-intent is that a network server sends data in its own byte-order and
-the client is responsible for adjusting the byte-order, if necessary.
-This approach causes no unnecessary overheads in the case where the
-server and client byte-order match and puts the extra burden on the
-client side when there is a byte-order mismatch.  Putting the burden
-on the client-side improves the scalability properties of this
-protocol.
-
-\subsection{\code{\defn{SANE\_NET\_CANCEL}}}
-
-RPC Code: 8
-
-This RPC is used to cancel the current operation of a remote SANE
-device.
-\begin{center}
-\begin{tabular}{ll}
-  {\bf request:} & {\bf reply:} \\
-  \code{SANE\_Word handle} & \code{SANE\_Word dummy} \\
-\end{tabular}
-\end{center}
-The \code{handle} argument identifies the connection whose operation
-should be cancelled.
-
-In the reply, the \code{dummy} argument is unused.  Its purpose is to
-ensure proper synchronization (without it, a net client would not be
-able to determine when the RPC has completed).
-
-\subsection{\code{\defn{SANE\_NET\_AUTHORIZE}}}\label{sec:authorization}
-\index{network authorization}
-
-RPC Code: 9
-
-This RPC is used to pass authorization data from the net client to the
-net server.
-\begin{center}
-\begin{tabular}{ll}
-  {\bf request:} & {\bf reply:} \\
-  \code{SANE\_String resource} & \code{SANE\_Word dummy} \\
-  \code{SANE\_String username} & \\
-  \code{SANE\_String password} & \\
-\end{tabular}
-\end{center}
-The \code{resource} argument specifies the name of the resource to be
-authorized.  This argument should be set to the string returned in the
-\code{resource} argument of the RPC reply that required this
-authorization call.  The \code{username} and \code{password} are the
-name of the user that is accessing the resource and the password for
-the specified resource/user pair.
-
-Since the password is not encrypted during network transmission, it is
-recommended to use the following extension:
-
-If the server adds the string `\code{\$MD5\$}' to the resource-name followed
-by a random string not longer then 128 bytes, the client may answer with the
-MD5 digest of the concatenation of the password and the random string. To
-differentiate between the MD5 digest and a strange password the client prepends
-the MD5 digest with the string `\code{\$MD5\$}'.
-
-In the reply, \code{dummy} is completely unused.  Note that there is
-no direct failure indication.  This is unnecessary since a net client
-will retry the RPC that resulted in the authorization request until
-that call succeeds (or until the request is cancelled). The RPC that resulted
-in the authorization request continues after the reply from the client and may
-fail with \code{SANE\_STATUS\_ACCESS\_DENIED}.
-
-
-\subsection{\code{\defn{SANE\_NET\_EXIT}}}
-
-RPC Code: 10
-
-This RPC is used to disconnect a net client from a net server.  There
-are no request or reply arguments in this call.  As a result of this
-call, the connection between the client and the server that was
-established by the \code{SANE\_NET\_INIT} call will be closed.
-
-% Local Variables:
-% mode: latex
-% TeX-master: "sane.tex"
-% End: