sane-project-website/html/doc017.html

488 wiersze
19 KiB
HTML

<html><body>
<a href="doc018.html"><img src=../icons/next.gif alt="Next"></a>
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
<a href="doc016.html"><img src=../icons/previous.gif alt="Previous"></a>
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
<hr>
<title>Remote Procedure Call Requests</title>
<h2><a name="s5.2">5.2 Remote Procedure Call Requests</a></h2>
<p>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.
<p>The data transferred from the client to the server is comprised of the RPC code
(as a <tt>SANE_WORD</tt>), followed by arguments defined in the <b>request</b>
column below. The format of the server's answer is given in the <b>reply</b>
column.
<p><h3><a name="s5.2.1">5.2.1 <tt>SANE_NET_INIT<a name="i127"></tt></a></h3>
<p>RPC Code: 0
<p>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:
<center>
<table cellpadding=0 cellspacing=0>
<tr valign=top>
<td colspan=1 align=left nowrap>
<b>request:</b> </td>
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_Word version_code</tt> </td>
<td colspan=1 align=left nowrap> <tt>SANE_Word status</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_String user_name</tt> </td>
<td colspan=1 align=left nowrap> <tt>SANE_Word version_code</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td></tr>
</table>
</center>
The <tt>version_code</tt> argument in the request is the SANE
version-code of the network backend that is contacting the network
daemon (see Section <a href="doc010.html#s4.1">4.1</a>). 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 <tt>user_name</tt> 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 <tt>NULL</tt> 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.
<p>In the reply, <tt>status</tt> indicates the completion status. If the
value is anything other than <tt>SANE_STATUS_GOOD</tt>, the
remainder of the reply has undefined values.<a name="F2"><a href="footnotes.html#000002"><sup><fontsize=-2>2</font></sup></a></a> The <tt>version_code</tt> 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.
<p><h3><a name="s5.2.2">5.2.2 <tt>SANE_NET_GET_DEVICES<a name="i129"></tt></a></h3>
<p>RPC Code: 1
<p>This RPC is used to obtain the list of devices accessible by the SANE
daemon.
<center>
<table cellpadding=0 cellspacing=0>
<tr valign=top>
<td colspan=1 align=left nowrap>
<b>request:</b> </td>
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>void</tt> </td>
<td colspan=1 align=left nowrap> <tt>SANE_Word status</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td>
<td colspan=1 align=left nowrap> <tt>SANE_Device ***device_list</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td></tr>
</table>
</center>
There are no arguments in the request for this call.
<p>In the reply, <tt>status</tt> indicates the completion status. If the
value is anything other than <tt>SANE_STATUS_GOOD</tt>, the
remainder of the reply has undefined values. The <tt>device_list</tt>
argument is a pointer to a <tt>NULL</tt>-terminated array of
<tt>SANE_Device</tt> pointers.
<p><h3><a name="s5.2.3">5.2.3 <tt>SANE_NET_OPEN<a name="i131"></tt></a></h3>
<p>RPC Code: 2
<p>This RPC is used to open a connection to a remote SANE device.
<center>
<table cellpadding=0 cellspacing=0>
<tr valign=top>
<td colspan=1 align=left nowrap>
<b>request:</b> </td>
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_String device_name</tt> </td>
<td colspan=1 align=left nowrap> <tt>SANE_Word status</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td>
<td colspan=1 align=left nowrap> <tt>SANE_Word handle</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td>
<td colspan=1 align=left nowrap> <tt>SANE_String resource</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td></tr>
</table>
</center>
The <tt>device_name</tt> argument specifies the name of the device to
open.
<p>In the reply, <tt>status</tt> indicates the completion status. If the
value is anything other than <tt>SANE_STATUS_GOOD</tt>, the
remainder of the reply has undefined values. The <tt>handle</tt>
argument specifies the device handle that uniquely identifies the
connection. The <tt>resource</tt> argument is used to request
authentication. If it has a non-<tt>NULL</tt> value, the network
backend should authenticate the specified resource and then retry this
operation (see Section <a href="doc017.html#s5.2.10">5.2.10</a> for details on how to
authorize a resource).
<p><h3><a name="s5.2.4">5.2.4 <tt>SANE_NET_CLOSE<a name="i133"></tt></a></h3>
<p>RPC Code: 3
<p>This RPC is used to close a connection to a remote SANE device.
<center>
<table cellpadding=0 cellspacing=0>
<tr valign=top>
<td colspan=1 align=left nowrap>
<b>request:</b> </td>
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_Word handle</tt> </td>
<td colspan=1 align=left nowrap> <tt>SANE_Word dummy</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td></tr>
</table>
</center>
The <tt>handle</tt> argument identifies the connection that should be
closed.
<p>In the reply, the <tt>dummy</tt> 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).
<p><h3><a name="s5.2.5">5.2.5 <tt>SANE_NET_GET_OPTION_DESCRIPTORS<a name="i135"></tt></a></h3>
<p>RPC Code: 4
<p>This RPC is used to obtain <em>all</em> the option descriptors for a
remote SANE device.
<center>
<table cellpadding=0 cellspacing=0>
<tr valign=top>
<td colspan=1 align=left nowrap>
<b>request:</b> </td>
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_Word handle</tt> </td>
<td colspan=1 align=left nowrap> <tt>Option_Descriptor_Array odesc</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td></tr>
</table>
</center>
The <tt>handle</tt> argument identifies the remote device whose option
descriptors should be obtained.
<p>In the reply, the <tt>odesc</tt> argument is used to return the array of
option descriptors. The option descriptor array has the following
structure:
<blockquote><a name="i137">
<pre>
struct Option_Descriptor_Array
{
SANE_Word num_options;
SANE_Option_Descriptor **desc;
};
</pre>
</blockquote>
<p><h3><a name="s5.2.6">5.2.6 <tt>SANE_NET_CONTROL_OPTION<a name="i138"></tt></a></h3>
<p>RPC Code: 5
<p>This RPC is used to control (inquire, set, or set to automatic) a
specific option of a remote SANE device.
<center>
<table cellpadding=0 cellspacing=0>
<tr valign=top>
<td colspan=1 align=left nowrap>
<b>request:</b> </td>
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_Word handle</tt> </td>
<td colspan=1 align=left nowrap> <tt>SANE_Status status</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_Word option</tt> </td>
<td colspan=1 align=left nowrap> <tt>SANE_Word info</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_Word action</tt> </td>
<td colspan=1 align=left nowrap> <tt>SANE_Word value_type</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_Word value_type</tt> </td>
<td colspan=1 align=left nowrap> <tt>SANE_Word value_size</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_Word value_size</tt> </td>
<td colspan=1 align=left nowrap> <tt>void *value</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>void *value</tt> </td>
<td colspan=1 align=left nowrap> <tt>SANE_String *resource</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td></tr>
</table>
</center>
The <tt>handle</tt> argument identifies the remote device whose option
should be controlled. Argument <tt>option</tt> is the number (index) of
the option that should be controlled. Argument <tt>action</tt>
specifies what action should be taken (get, set, or set automatic).
Argument <tt>value_type</tt> specifies the type of the option value
(must be one of <tt>SANE_TYPE_BOOL</tt>, <tt>SANE_TYPE_INT</tt>,
<tt>SANE_TYPE_FIXED</tt>, <tt>SANE_TYPE_STRING</tt>,
<tt>SANE_TYPE_BUTTON</tt>). Argument <tt>value_size</tt> specifies
the size of the option value in number of bytes (see
Section <a href="doc011.html#s4.2.9.6">4.2.9.6</a> for the precise meaning of this value).
Finally, argument <tt>value</tt> is a pointer to the option value. It
must be a writeable area that is at least <tt>value_size</tt> 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.)
<p>In the reply, argument <tt>resource</tt> is set to the name of the
resource that must be authorized before this call can be retried. If
this value is non-<tt>NULL</tt>, all other arguments have undefined
values (see Section <a href="doc017.html#s5.2.10">5.2.10</a> for details on how to
authorize a resource). Argument <tt>status</tt> indicates the
completion status. If the value is anything other than
<tt>SANE_STATUS_GOOD</tt>, the remainder of the reply has undefined
values. The <tt>info</tt> 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 <a href="doc012.html#s4.3.7">4.3.7</a>. Arguments <tt>value_type</tt> and
<tt>value_size</tt> 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 <tt>value</tt> is holds
the value of the option that has become effective as a result of this
RPC.
<p><h3><a name="s5.2.7">5.2.7 <tt>SANE_NET_GET_PARAMETERS<a name="i140"></tt></a></h3>
<p>RPC Code: 6
<p>This RPC is used to obtain the scan parameters of a remote SANE
device.
<center>
<table cellpadding=0 cellspacing=0>
<tr valign=top>
<td colspan=1 align=left nowrap>
<b>request:</b> </td>
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_Word handle</tt> </td>
<td colspan=1 align=left nowrap> <tt>SANE_Status status</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td>
<td colspan=1 align=left nowrap> <tt>SANE_Parameters params</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td></tr>
</table>
</center>
The <tt>handle</tt> argument identifies the connection to the remote
device whose scan parameters should be returned.
<p>In the reply, <tt>status</tt> indicates the completion status. If the
value is anything other than <tt>SANE_STATUS_GOOD</tt>, the
remainder of the reply has undefined values. The argument
<tt>params</tt> is used to return the scan parameters.
<p><h3><a name="s5.2.8">5.2.8 <tt>SANE_NET_START<a name="i142"></tt></a></h3>
<p>RPC Code: 7
<p>This RPC is used to start image acquisition (scanning).
<center>
<table cellpadding=0 cellspacing=0>
<tr valign=top>
<td colspan=1 align=left nowrap>
<b>request:</b> </td>
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_Word handle</tt> </td>
<td colspan=1 align=left nowrap> <tt>SANE_Status status</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td>
<td colspan=1 align=left nowrap> <tt>SANE_Word port</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td>
<td colspan=1 align=left nowrap> <tt>SANE_Word byte_order</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td>
<td colspan=1 align=left nowrap> <tt>SANE_String resource</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td></tr>
</table>
</center>
The <tt>handle</tt> argument identifies the connection to the remote
device from which the image should be acquired.
<p>In the reply, argument <tt>resource</tt> is set to the name of the
resource that must be authorized before this call can be retried. If
this value is non-<tt>NULL</tt>, all other arguments have undefined
values (see Section <a href="doc017.html#s5.2.10">5.2.10</a> for details on how to
authorize a resource). Argument, <tt>status</tt> indicates the
completion status. If the value is anything other than
<tt>SANE_STATUS_GOOD</tt>, the remainder of the reply has
undefined values. The argument <tt>port</tt> 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 <tt>sane_read()</tt>. Since some
records may contain no data at all, a length value of zero is
perfectly valid. The special length value of <tt>0xffffffff</tt> is
used to indicate the end of the data stream. That is, after receiving
a record length of <tt>0xffffffff</tt>, the network client should close
the data connection and stop reading data.
<p>Argument <tt>byte_order</tt> 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.
<p><h3><a name="s5.2.9">5.2.9 <tt>SANE_NET_CANCEL<a name="i144"></tt></a></h3>
<p>RPC Code: 8
<p>This RPC is used to cancel the current operation of a remote SANE
device.
<center>
<table cellpadding=0 cellspacing=0>
<tr valign=top>
<td colspan=1 align=left nowrap>
<b>request:</b> </td>
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_Word handle</tt> </td>
<td colspan=1 align=left nowrap> <tt>SANE_Word dummy</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td></tr>
</table>
</center>
The <tt>handle</tt> argument identifies the connection whose operation
should be cancelled.
<p>In the reply, the <tt>dummy</tt> 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).
<p><h3><a name="s5.2.10">5.2.10 <tt>SANE_NET_AUTHORIZE<a name="i146"></tt></a></h3>
<a name="i148">
<p>RPC Code: 9
<p>This RPC is used to pass authorization data from the net client to the
net server.
<center>
<table cellpadding=0 cellspacing=0>
<tr valign=top>
<td colspan=1 align=left nowrap>
<b>request:</b> </td>
<td colspan=1 align=left nowrap> <b>reply:</b> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_String resource</tt> </td>
<td colspan=1 align=left nowrap> <tt>SANE_Word dummy</tt> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_String username</tt> </td>
<td colspan=1 align=left nowrap> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
<tt>SANE_String password</tt> </td>
<td colspan=1 align=left nowrap> </td></tr>
<tr valign=top>
<td colspan=1 align=left nowrap>
</td></tr>
</table>
</center>
The <tt>resource</tt> argument specifies the name of the resource to be
authorized. This argument should be set to the string returned in the
<tt>resource</tt> argument of the RPC reply that required this
authorization call. The <tt>username</tt> and <tt>password</tt> are the
name of the user that is accessing the resource and the password for
the specified resource/user pair.
<p>Since the password is not encrypted during network transmission, it is
recommended to use the following extension:
<p>If the server adds the string `<tt>$MD5$</tt>' 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 `<tt>$MD5$</tt>'.
<p>In the reply, <tt>dummy</tt> 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 <tt>SANE_STATUS_ACCESS_DENIED</tt>.
<p><h3><a name="s5.2.11">5.2.11 <tt>SANE_NET_EXIT<a name="i149"></tt></a></h3>
<p>RPC Code: 10
<p>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 <tt>SANE_NET_INIT</tt> call will be closed.
<p>
<p><p><hr>
<a href="doc018.html"><img src=../icons/next.gif alt="Next"></a>
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
<a href="doc016.html"><img src=../icons/previous.gif alt="Previous"></a>
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
<hr>
</body></html>