summaryrefslogtreecommitdiff
path: root/doc/net.tex
diff options
context:
space:
mode:
authorJörg Frings-Fürst <debian@jff-webhosting.net>2014-10-06 14:00:40 +0200
committerJörg Frings-Fürst <debian@jff-webhosting.net>2014-10-06 14:00:40 +0200
commit6e9c41a892ed0e0da326e0278b3221ce3f5713b8 (patch)
tree2e301d871bbeeb44aa57ff9cc070fcf3be484487 /doc/net.tex
Initial import of sane-backends version 1.0.24-1.2
Diffstat (limited to 'doc/net.tex')
-rw-r--r--doc/net.tex479
1 files changed, 479 insertions, 0 deletions
diff --git a/doc/net.tex b/doc/net.tex
new file mode 100644
index 0000000..a29fb75
--- /dev/null
+++ b/doc/net.tex
@@ -0,0 +1,479 @@
+\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: