kopia lustrzana https://gitlab.com/sane-project/standard
Massage LaTex content for upcoming pandoc conversion
This - comments out custom commands to preserve semantic context - changes \input to \incl to preserve the inclusion of net.tex - removes LaTeX escaping of underscores (via 's/\\_/_/g') - removes LaTeX hyphenation markers (via 's/\\-//g')draft-2
Olaf Meeuwissen
rodzic
e873a7a3da
commit
0bed8edb9d
130
net.tex
130
net.tex
|
|
@ -70,24 +70,24 @@ the most commonly used protocols.
|
|||
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.
|
||||
\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
|
||||
\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
|
||||
\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
|
||||
\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.
|
||||
\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
|
||||
|
|
@ -142,7 +142,7 @@ call (RPC) protocol. This means that all activity is initiated by the
|
|||
client side (the network backend)---a server is restricted to
|
||||
answering request by the client.
|
||||
|
||||
\subsection{\code{\defn{SANE\_NET\_INIT}}}
|
||||
\subsection{\code{\defn{SANE_NET_INIT}}}
|
||||
|
||||
This RPC establishes a connection to a particular SANE network daemon.
|
||||
It must be the first call in a SANE network session. The parameter
|
||||
|
|
@ -150,11 +150,11 @@ 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} \\
|
||||
\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
|
||||
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
|
||||
|
|
@ -162,7 +162,7 @@ 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
|
||||
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
|
||||
|
|
@ -171,49 +171,49 @@ 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\_SUCCESS}, the
|
||||
value is anything other than \code{SANE_STATUS_SUCCESS}, 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
|
||||
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}}}
|
||||
\subsection{\code{\defn{SANE_NET_GET_DEVICES}}}
|
||||
|
||||
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} \\
|
||||
\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\_SUCCESS}, the
|
||||
remainder of the reply has undefined values. The \code{device\_list}
|
||||
value is anything other than \code{SANE_STATUS_SUCCESS}, 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.
|
||||
\code{SANE_Device} pointers.
|
||||
|
||||
\subsection{\code{\defn{SANE\_NET\_OPEN}}}
|
||||
\subsection{\code{\defn{SANE_NET_OPEN}}}
|
||||
|
||||
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} \\
|
||||
\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
|
||||
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\_SUCCESS}, the
|
||||
value is anything other than \code{SANE_STATUS_SUCCESS}, 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
|
||||
|
|
@ -222,13 +222,13 @@ 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}}}
|
||||
\subsection{\code{\defn{SANE_NET_CLOSE}}}
|
||||
|
||||
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} \\
|
||||
\code{SANE_Word handle} & \code{SANE_Word dummy} \\
|
||||
\end{tabular}
|
||||
\end{center}
|
||||
The \code{handle} argument identifies the connection that should be
|
||||
|
|
@ -238,14 +238,14 @@ 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}}}
|
||||
\subsection{\code{\defn{SANE_NET_GET_OPTION_DESCRIPTORS}}}
|
||||
|
||||
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} \\
|
||||
\code{SANE_Word handle} & \code{Option_Descriptor_Array odesc} \\
|
||||
\end{tabular}
|
||||
\end{center}
|
||||
The \code{handle} argument identifies the remote device whose option
|
||||
|
|
@ -254,7 +254,7 @@ 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{quote}\index{Option_Descriptor_Array}
|
||||
\begin{verbatim}
|
||||
struct Option_Descriptor_Array
|
||||
{
|
||||
|
|
@ -265,33 +265,33 @@ struct Option_Descriptor_Array
|
|||
\end{quote}
|
||||
|
||||
|
||||
\subsection{\code{\defn{SANE\_NET\_CONTROL\_OPTION}}}
|
||||
\subsection{\code{\defn{SANE_NET_CONTROL_OPTION}}}
|
||||
|
||||
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} \\
|
||||
\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
|
||||
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_STRING},
|
||||
\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
|
||||
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
|
||||
|
|
@ -303,12 +303,12 @@ 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\_SUCCESS}, the remainder of the reply has undefined
|
||||
\code{SANE_STATUS_SUCCESS}, 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
|
||||
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
|
||||
|
|
@ -316,35 +316,35 @@ the value of the option that has become effective as a result of this
|
|||
RPC.
|
||||
|
||||
|
||||
\subsection{\code{\defn{SANE\_NET\_GET\_PARAMETERS}}}
|
||||
\subsection{\code{\defn{SANE_NET_GET_PARAMETERS}}}
|
||||
|
||||
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} \\
|
||||
\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\_SUC\-CESS}, the
|
||||
value is anything other than \code{SANE_STATUS_SUCCESS}, 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}}}
|
||||
\subsection{\code{\defn{SANE_NET_START}}}
|
||||
|
||||
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} \\
|
||||
\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
|
||||
|
|
@ -356,7 +356,7 @@ 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\_SUCCESS}, the remainder of the reply has
|
||||
\code{SANE_STATUS_SUCCESS}, 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
|
||||
|
|
@ -366,14 +366,14 @@ 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
|
||||
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
|
||||
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
|
||||
|
|
@ -385,14 +385,14 @@ 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}}}
|
||||
\subsection{\code{\defn{SANE_NET_CANCEL}}}
|
||||
|
||||
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} \\
|
||||
\code{SANE_Word handle} & \code{SANE_Word dummy} \\
|
||||
\end{tabular}
|
||||
\end{center}
|
||||
The \code{handle} argument identifies the connection whose operation
|
||||
|
|
@ -402,7 +402,7 @@ 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}
|
||||
\subsection{\code{\defn{SANE_NET_AUTHORIZE}}}\label{sec:authorization}
|
||||
\index{network authorization}
|
||||
|
||||
This RPC is used to pass authorization data from the net client to the
|
||||
|
|
@ -410,9 +410,9 @@ 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} & \\
|
||||
\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
|
||||
|
|
@ -430,12 +430,12 @@ will retry the RPC that resulted in the authorization request until
|
|||
that call succeeds (or until the request is cancelled).
|
||||
|
||||
|
||||
\subsection{\code{\defn{SANE\_NET\_EXIT}}}
|
||||
\subsection{\code{\defn{SANE_NET_EXIT}}}
|
||||
|
||||
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.
|
||||
established by the \code{SANE_NET_INIT} call will be closed.
|
||||
|
||||
% Local Variables:
|
||||
% mode: latex
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue