2019-10-26 04:04:22 +00:00
|
|
|
|
.. _chap:net:
|
|
|
|
|
|
2019-10-19 01:26:47 +00:00
|
|
|
|
Network Protocol
|
|
|
|
|
================
|
|
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
- 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.
|
|
|
|
|
|
|
|
|
|
- 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).
|
|
|
|
|
|
|
|
|
|
- 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.
|
|
|
|
|
|
|
|
|
|
The network protocol described in this chapter has been design with the
|
|
|
|
|
following goals in mind:
|
|
|
|
|
|
|
|
|
|
#. Image transmission should be efficient (have low encoding overhead).
|
|
|
|
|
|
|
|
|
|
#. Accessing option descriptors on the client side must be efficient
|
|
|
|
|
(since this is a very common operation).
|
|
|
|
|
|
|
|
|
|
#. Other operations, such as setting or inquiring the value of an option
|
|
|
|
|
are less performance critical since they typically require explicit
|
|
|
|
|
user action.
|
|
|
|
|
|
|
|
|
|
#. The network protocol should be simple and easy to implement on any
|
|
|
|
|
host architecture and any programming language.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
Data Type Encoding
|
|
|
|
|
------------------
|
|
|
|
|
|
|
|
|
|
Primitive Data Types
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
The four primitive types of the SANE standard are encoded as follows:
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: SANE_Byte
|
|
|
|
|
|
|
|
|
|
:type:`SANE_Byte`
|
2019-10-19 01:26:47 +00:00
|
|
|
|
A byte is encoded as an 8 bit value. Since the transport protocol is
|
2020-02-15 08:26:19 +00:00
|
|
|
|
assumed to be byte-oriented, the bit order is irrelevant.
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: SANE_Word
|
|
|
|
|
|
|
|
|
|
:type:`SANE_Word`
|
2019-10-19 01:26:47 +00:00
|
|
|
|
A word is encoded as 4 bytes (32 bits). The bytes are ordered from
|
|
|
|
|
most-significant to least-significant byte (big-endian byte-order).
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: SANE_Char
|
|
|
|
|
|
|
|
|
|
:type:`SANE_Char`
|
2019-10-19 01:26:47 +00:00
|
|
|
|
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.
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: SANE_String
|
|
|
|
|
|
|
|
|
|
:type:`SANE_String`
|
|
|
|
|
A string pointer is encoded as a :type:`SANE_Char`
|
2019-10-19 01:26:47 +00:00
|
|
|
|
array. The trailing NUL byte is considered part of the array and a
|
2019-10-18 10:29:36 +00:00
|
|
|
|
:macro:`NULL` pointer is encoded as a zero-length array.
|
|
|
|
|
|
|
|
|
|
.. index:: SANE_Handle
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
:type:`SANE_Handle`
|
2019-10-19 01:26:47 +00:00
|
|
|
|
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.
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: enumeration types
|
|
|
|
|
|
|
|
|
|
*enumeration types*
|
2019-10-19 01:26:47 +00:00
|
|
|
|
Enumeration types are encoded like words.
|
|
|
|
|
|
|
|
|
|
Type Constructors
|
|
|
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
Closely following the type constructors of the C language, the SANE
|
|
|
|
|
network protocol supports the following four constructors:
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: pointer
|
|
|
|
|
|
|
|
|
|
*pointer*
|
2019-10-19 01:26:47 +00:00
|
|
|
|
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).
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: array
|
|
|
|
|
|
|
|
|
|
*array*
|
2019-10-19 01:26:47 +00:00
|
|
|
|
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.
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: structure
|
|
|
|
|
|
|
|
|
|
*structure*
|
2019-10-19 01:26:47 +00:00
|
|
|
|
A structure is encoded by simply encoding the structure members in
|
|
|
|
|
the order in which they appear in the corresponding C type
|
|
|
|
|
declaration.
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: union
|
|
|
|
|
|
|
|
|
|
*union*
|
2019-10-19 01:26:47 +00:00
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
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
|
2020-01-28 12:23:49 +00:00
|
|
|
|
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 :macro:`SANE_WORD`), followed by arguments defined in
|
|
|
|
|
the **request** column below. The format of the server's answer is
|
|
|
|
|
given in the **reply** column.
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: SANE_NET_INIT
|
|
|
|
|
|
|
|
|
|
:data:`SANE_NET_INIT`
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2020-01-28 12:23:49 +00:00
|
|
|
|
RPC Code: 0
|
|
|
|
|
|
2019-10-19 01:26:47 +00:00
|
|
|
|
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:
|
|
|
|
|
|
2019-10-21 04:40:08 +00:00
|
|
|
|
.. table::
|
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
|
|
+----------------------------------------+----------------------------------------+
|
|
|
|
|
| request | reply |
|
|
|
|
|
+========================================+========================================+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_Word` `version_code` | :type:`SANE_Word` `status` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+----------------------------------------+----------------------------------------+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_String` `user_name` | :type:`SANE_Word` `version_code` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+----------------------------------------+----------------------------------------+
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
The `version_code` argument in the request is the SANE
|
2019-10-19 01:26:47 +00:00
|
|
|
|
version-code of the network backend that is contacting the network
|
2019-10-26 04:04:22 +00:00
|
|
|
|
daemon (see Section :numref:`sec:saneversioncode`). The
|
2019-10-19 01:26:47 +00:00
|
|
|
|
“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).
|
2023-10-13 04:42:40 +00:00
|
|
|
|
The `user_name` argument is the name of the user on
|
2019-10-19 01:26:47 +00:00
|
|
|
|
whose behalf this call is being performed. If the network backend cannot
|
2019-10-18 10:29:36 +00:00
|
|
|
|
determine a user-name, it passes a :macro:`NULL` pointer for
|
2019-10-19 01:26:47 +00:00
|
|
|
|
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.
|
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
In the reply, `status` indicates the completion
|
2019-10-19 01:26:47 +00:00
|
|
|
|
status. If the value is anything other than
|
2020-01-31 11:26:16 +00:00
|
|
|
|
:macro:`SANE_STATUS_GOOD`, the remainder of the reply has
|
2023-10-13 04:42:40 +00:00
|
|
|
|
undefined values. [1]_ The `version_code` argument
|
2019-10-19 01:26:47 +00:00
|
|
|
|
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.
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: SANE_NET_GET_DEVICES
|
|
|
|
|
|
|
|
|
|
:data:`SANE_NET_GET_DEVICES`
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2020-01-28 12:23:49 +00:00
|
|
|
|
RPC Code: 1
|
|
|
|
|
|
2019-10-19 01:26:47 +00:00
|
|
|
|
This RPC is used to obtain the list of devices accessible by the SANE
|
|
|
|
|
daemon.
|
|
|
|
|
|
2019-10-21 04:40:08 +00:00
|
|
|
|
.. table::
|
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
|
|
+--------------+--------------------------------------------+
|
|
|
|
|
| request | reply |
|
|
|
|
|
+==============+============================================+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| `void` | :type:`SANE_Word` `status` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+--------------+--------------------------------------------+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| | :type:`SANE_Device` `***device_list` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+--------------+--------------------------------------------+
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
|
|
|
|
There are no arguments in the request for this call.
|
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
In the reply, `status` indicates the completion
|
2019-10-19 01:26:47 +00:00
|
|
|
|
status. If the value is anything other than
|
2020-01-31 11:26:16 +00:00
|
|
|
|
:macro:`SANE_STATUS_GOOD`, the remainder of the reply has
|
2023-10-13 04:42:40 +00:00
|
|
|
|
undefined values. The `device_list` argument is a
|
2019-10-18 10:29:36 +00:00
|
|
|
|
pointer to a :macro:`NULL`-terminated array of
|
|
|
|
|
:type:`SANE_Device` pointers.
|
|
|
|
|
|
|
|
|
|
.. index:: SANE_NET_OPEN
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
:data:`SANE_NET_OPEN`
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2020-01-28 12:23:49 +00:00
|
|
|
|
RPC Code: 2
|
|
|
|
|
|
2019-10-19 01:26:47 +00:00
|
|
|
|
This RPC is used to open a connection to a remote SANE device.
|
|
|
|
|
|
2019-10-21 04:40:08 +00:00
|
|
|
|
.. table::
|
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
|
|
+-----------------------------------------+--------------------------------------+
|
|
|
|
|
| request | reply |
|
|
|
|
|
+=========================================+======================================+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_String` `device_name` | :type:`SANE_Word` `status` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+-----------------------------------------+--------------------------------------+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| | :type:`SANE_Word` `handle` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+-----------------------------------------+--------------------------------------+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| | :type:`SANE_String` `resource` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+-----------------------------------------+--------------------------------------+
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
The `device_name` argument specifies the name of the
|
2019-10-19 01:26:47 +00:00
|
|
|
|
device to open.
|
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
In the reply, `status` indicates the completion
|
2019-10-19 01:26:47 +00:00
|
|
|
|
status. If the value is anything other than
|
2020-01-31 11:26:16 +00:00
|
|
|
|
:macro:`SANE_STATUS_GOOD`, the remainder of the reply has
|
2023-10-13 04:42:40 +00:00
|
|
|
|
undefined values. The `handle` argument specifies the
|
2019-10-19 01:26:47 +00:00
|
|
|
|
device handle that uniquely identifies the connection. The
|
2019-10-18 10:29:36 +00:00
|
|
|
|
:data:`resource` argument is used to request authentication.
|
|
|
|
|
If it has a non-:macro:`NULL` value, the network backend
|
2019-10-19 01:26:47 +00:00
|
|
|
|
should authenticate the specified resource and then retry this operation
|
2019-10-26 04:04:22 +00:00
|
|
|
|
(see Section :numref:`sec:authorization` for details on how to
|
2019-10-19 01:26:47 +00:00
|
|
|
|
authorize a resource).
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: SANE_NET_CLOSE
|
|
|
|
|
|
|
|
|
|
:data:`SANE_NET_CLOSE`
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2020-01-28 12:23:49 +00:00
|
|
|
|
RPC Code: 3
|
|
|
|
|
|
2019-10-19 01:26:47 +00:00
|
|
|
|
This RPC is used to close a connection to a remote SANE device.
|
|
|
|
|
|
2019-10-21 04:40:08 +00:00
|
|
|
|
.. table::
|
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
|
|
+----------------------------------+---------------------------------+
|
|
|
|
|
| request | reply |
|
|
|
|
|
+==================================+=================================+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_Word` `handle` | :type:`SANE_Word` `dummy` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+----------------------------------+---------------------------------+
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
The `handle` argument identifies the connection that
|
2019-10-19 01:26:47 +00:00
|
|
|
|
should be closed.
|
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
In the reply, the `dummy` argument is unused. Its
|
2019-10-19 01:26:47 +00:00
|
|
|
|
purpose is to ensure proper synchronization (without it, a net client
|
|
|
|
|
would not be able to determine when the RPC has completed).
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: SANE_NET_GET_OPTION_DESCRIPTORS
|
|
|
|
|
|
|
|
|
|
:data:`SANE_NET_GET_OPTION_DESCRIPTORS`
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2020-01-28 12:23:49 +00:00
|
|
|
|
RPC Code: 4
|
|
|
|
|
|
2019-10-19 01:26:47 +00:00
|
|
|
|
This RPC is used to obtain *all* the option descriptors for a remote
|
|
|
|
|
SANE device.
|
|
|
|
|
|
2019-10-21 04:40:08 +00:00
|
|
|
|
.. table::
|
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
|
|
+----------------------------------+-----------------------------------------------+
|
|
|
|
|
| request | reply |
|
|
|
|
|
+==================================+===============================================+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_Word` `handle` | :type:`Option_Descriptor_Array` `odesc` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+----------------------------------+-----------------------------------------------+
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
The `handle` argument identifies the remote device
|
2019-10-19 01:26:47 +00:00
|
|
|
|
whose option descriptors should be obtained.
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: Option_Descriptor_Array
|
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
In the reply, the `odesc` argument is used to return
|
2019-10-19 01:26:47 +00:00
|
|
|
|
the array of option descriptors. The option descriptor array has the
|
|
|
|
|
following structure:
|
|
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
|
|
struct Option_Descriptor_Array
|
|
|
|
|
{
|
|
|
|
|
SANE_Word num_options;
|
|
|
|
|
SANE_Option_Descriptor **desc;
|
|
|
|
|
};
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: SANE_NET_CONTROL_OPTION
|
|
|
|
|
|
|
|
|
|
:data:`SANE_NET_CONTROL_OPTION`
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2020-01-28 12:23:49 +00:00
|
|
|
|
RPC Code: 5
|
|
|
|
|
|
2019-10-19 01:26:47 +00:00
|
|
|
|
This RPC is used to control (inquire, set, or set to automatic) a
|
|
|
|
|
specific option of a remote SANE device.
|
|
|
|
|
|
2019-10-21 04:40:08 +00:00
|
|
|
|
.. table::
|
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
|
|
+--------------------------------------+---------------------------------------+
|
|
|
|
|
| request | reply |
|
|
|
|
|
+======================================+=======================================+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_Word` `handle` | :type:`SANE_Status` `status` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+--------------------------------------+---------------------------------------+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_Word` `option` | :type:`SANE_Word` `info` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+--------------------------------------+---------------------------------------+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_Word` `action` | :type:`SANE_Word` `value_type` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+--------------------------------------+---------------------------------------+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_Word` `value_type` | :type:`SANE_Word` `value_size` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+--------------------------------------+---------------------------------------+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_Word` `value_size` | `void` `*value` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+--------------------------------------+---------------------------------------+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| `void` `*value` | :type:`SANE_String` `*resource` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+--------------------------------------+---------------------------------------+
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
The `handle` argument identifies the remote device
|
|
|
|
|
whose option should be controlled. Argument `option`
|
2019-10-19 01:26:47 +00:00
|
|
|
|
is the number (index) of the option that should be controlled. Argument
|
2019-10-18 10:29:36 +00:00
|
|
|
|
:data:`action` specifies what action should be taken (get,
|
2023-10-13 04:42:40 +00:00
|
|
|
|
set, or set automatic). Argument `value_type`
|
2019-10-19 01:26:47 +00:00
|
|
|
|
specifies the type of the option value (must be one of
|
2019-10-18 10:29:36 +00:00
|
|
|
|
:macro:`SANE_TYPE_BOOL`, :macro:`SANE_TYPE_INT`,
|
|
|
|
|
:macro:`SANE_TYPE_FIXED`,
|
|
|
|
|
:macro:`SANE_TYPE_STRING`,
|
|
|
|
|
:macro:`SANE_TYPE_BUTTON`). Argument
|
|
|
|
|
:data:`value_size` specifies the size of the option value in
|
2019-10-26 04:04:22 +00:00
|
|
|
|
number of bytes (see Section :numref:`sec:valuesize` for the
|
2019-10-19 01:26:47 +00:00
|
|
|
|
precise meaning of this value). Finally, argument
|
2019-10-18 10:29:36 +00:00
|
|
|
|
:data:`value` is a pointer to the option value. It must be a
|
2023-10-13 04:42:40 +00:00
|
|
|
|
writable area that is at least `value_size` bytes
|
2019-10-19 01:26:47 +00:00
|
|
|
|
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.)
|
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
In the reply, argument `resource` is set to the name
|
2019-10-19 01:26:47 +00:00
|
|
|
|
of the resource that must be authorized before this call can be retried.
|
2019-10-18 10:29:36 +00:00
|
|
|
|
If this value is non-:macro:`NULL`, all other arguments have
|
2019-10-26 04:04:22 +00:00
|
|
|
|
undefined values (see Section :numref:`sec:authorization` for
|
2019-10-19 01:26:47 +00:00
|
|
|
|
details on how to authorize a resource). Argument
|
2019-10-18 10:29:36 +00:00
|
|
|
|
:data:`status` indicates the completion status. If the value
|
2020-01-31 11:26:16 +00:00
|
|
|
|
is anything other than :macro:`SANE_STATUS_GOOD`, the
|
2019-10-19 01:26:47 +00:00
|
|
|
|
remainder of the reply has undefined values. The
|
2019-10-18 10:29:36 +00:00
|
|
|
|
:data:`info` argument returns the information on how well
|
2019-10-19 01:26:47 +00:00
|
|
|
|
the backend was able to satisfy the request. For details, see the
|
|
|
|
|
description of the corresponding argument in
|
2019-10-26 04:04:22 +00:00
|
|
|
|
Section :numref:`sec:control`. Arguments
|
2023-10-13 04:42:40 +00:00
|
|
|
|
:data:`value_type` and `value_size` have
|
2019-10-19 01:26:47 +00:00
|
|
|
|
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
|
2023-10-13 04:42:40 +00:00
|
|
|
|
independently). Argument `value` is holds the value of
|
2019-10-19 01:26:47 +00:00
|
|
|
|
the option that has become effective as a result of this RPC.
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: SANE_NET_GET_PARAMETERS
|
|
|
|
|
|
|
|
|
|
:data:`SANE_NET_GET_PARAMETERS`
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2020-01-28 12:23:49 +00:00
|
|
|
|
RPC Code: 6
|
|
|
|
|
|
2019-10-19 01:26:47 +00:00
|
|
|
|
This RPC is used to obtain the scan parameters of a remote SANE device.
|
|
|
|
|
|
2019-10-21 04:40:08 +00:00
|
|
|
|
.. table::
|
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
|
|
+----------------------------------+----------------------------------------+
|
|
|
|
|
| request | reply |
|
|
|
|
|
+==================================+========================================+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_Word` `handle` | :type:`SANE_Status` `status` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+----------------------------------+----------------------------------------+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| | :type:`SANE_Parameters` `params` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+----------------------------------+----------------------------------------+
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
The `handle` argument identifies the connection to the
|
2019-10-19 01:26:47 +00:00
|
|
|
|
remote device whose scan parameters should be returned.
|
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
In the reply, `status` indicates the completion
|
2019-10-19 01:26:47 +00:00
|
|
|
|
status. If the value is anything other than
|
2020-01-31 11:27:52 +00:00
|
|
|
|
:macro:`SANE_STATUS_GOOD`, the remainder of the reply
|
2023-10-13 04:42:40 +00:00
|
|
|
|
has undefined values. The argument `params` is used to
|
2019-10-19 01:26:47 +00:00
|
|
|
|
return the scan parameters.
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: SANE_NET_START
|
|
|
|
|
|
|
|
|
|
:data:`SANE_NET_START`
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2020-01-28 12:23:49 +00:00
|
|
|
|
RPC Code: 7
|
|
|
|
|
|
2019-10-19 01:26:47 +00:00
|
|
|
|
This RPC is used to start image acquisition (scanning).
|
|
|
|
|
|
2019-10-21 04:40:08 +00:00
|
|
|
|
.. table::
|
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
|
|
+----------------------------------+--------------------------------------+
|
|
|
|
|
| request | reply |
|
|
|
|
|
+==================================+======================================+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_Word` `handle` | :type:`SANE_Status` `status` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+----------------------------------+--------------------------------------+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| | :type:`SANE_Word` `port` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+----------------------------------+--------------------------------------+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| | :type:`SANE_Word` `byte_order` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+----------------------------------+--------------------------------------+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| | :type:`SANE_String` `resource` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+----------------------------------+--------------------------------------+
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
The `handle` argument identifies the connection to the
|
2019-10-19 01:26:47 +00:00
|
|
|
|
remote device from which the image should be acquired.
|
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
In the reply, argument `resource` is set to the name
|
2019-10-19 01:26:47 +00:00
|
|
|
|
of the resource that must be authorized before this call can be retried.
|
2019-10-18 10:29:36 +00:00
|
|
|
|
If this value is non-:macro:`NULL`, all other arguments have
|
2019-10-26 04:04:22 +00:00
|
|
|
|
undefined values (see Section :numref:`sec:authorization` for
|
2019-10-19 01:26:47 +00:00
|
|
|
|
details on how to authorize a resource). Argument,
|
2019-10-18 10:29:36 +00:00
|
|
|
|
:data:`status` indicates the completion status. If the value
|
2020-01-31 11:26:16 +00:00
|
|
|
|
is anything other than :macro:`SANE_STATUS_GOOD`, the
|
2019-10-19 01:26:47 +00:00
|
|
|
|
remainder of the reply has undefined values. The argument
|
2019-10-18 10:29:36 +00:00
|
|
|
|
:data:`port` returns the port number from which the image
|
2019-10-19 01:26:47 +00:00
|
|
|
|
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
|
2019-10-18 10:29:36 +00:00
|
|
|
|
:func:`sane_read()`. Since some records may contain no data
|
2019-10-19 01:26:47 +00:00
|
|
|
|
at all, a length value of zero is perfectly valid. The special length
|
2019-10-18 10:29:36 +00:00
|
|
|
|
value of ``0xffffffff`` is used to indicate the end of
|
2019-10-19 01:26:47 +00:00
|
|
|
|
the data stream. That is, after receiving a record length of
|
2019-10-18 10:29:36 +00:00
|
|
|
|
``0xffffffff``, the network client should close the data
|
2019-10-19 01:26:47 +00:00
|
|
|
|
connection and stop reading data.
|
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
Argument `byte_order` specifies the byte-order of the
|
2019-10-19 01:26:47 +00:00
|
|
|
|
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.
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: SANE_NET_CANCEL
|
|
|
|
|
|
|
|
|
|
:data:`SANE_NET_CANCEL`
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2020-01-28 12:23:49 +00:00
|
|
|
|
RPC Code: 8
|
|
|
|
|
|
2019-10-19 01:26:47 +00:00
|
|
|
|
This RPC is used to cancel the current operation of a remote SANE
|
|
|
|
|
device.
|
|
|
|
|
|
2019-10-21 04:40:08 +00:00
|
|
|
|
.. table::
|
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
|
|
+----------------------------------+---------------------------------+
|
|
|
|
|
| request | reply |
|
|
|
|
|
+==================================+=================================+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_Word` `handle` | :type:`SANE_Word` `dummy` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+----------------------------------+---------------------------------+
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
The `handle` argument identifies the connection whose
|
2019-10-19 01:26:47 +00:00
|
|
|
|
operation should be cancelled.
|
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
In the reply, the `dummy` argument is unused. Its
|
2019-10-19 01:26:47 +00:00
|
|
|
|
purpose is to ensure proper synchronization (without it, a net client
|
|
|
|
|
would not be able to determine when the RPC has completed).
|
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: SANE_NET_AUTHORIZE, network authorization
|
2019-10-26 04:04:22 +00:00
|
|
|
|
.. _sec:authorization:
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
:data:`SANE_NET_AUTHORIZE`
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2020-01-28 12:23:49 +00:00
|
|
|
|
RPC Code: 9
|
|
|
|
|
|
2019-10-19 01:26:47 +00:00
|
|
|
|
This RPC is used to pass authorization data from the net client to the
|
|
|
|
|
net server.
|
|
|
|
|
|
2019-10-21 04:40:08 +00:00
|
|
|
|
.. table::
|
|
|
|
|
:align: center
|
|
|
|
|
|
|
|
|
|
+--------------------------------------+---------------------------------+
|
|
|
|
|
| request | reply |
|
|
|
|
|
+======================================+=================================+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_String` `resource` | :type:`SANE_Word` `dummy` |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+--------------------------------------+---------------------------------+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_String` `username` | |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+--------------------------------------+---------------------------------+
|
2023-10-13 04:42:40 +00:00
|
|
|
|
| :type:`SANE_String` `password` | |
|
2019-10-21 04:40:08 +00:00
|
|
|
|
+--------------------------------------+---------------------------------+
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
The `resource` argument specifies the name of the
|
2019-10-19 01:26:47 +00:00
|
|
|
|
resource to be authorized. This argument should be set to the string
|
2023-10-13 04:42:40 +00:00
|
|
|
|
returned in the `resource` argument of the RPC reply
|
|
|
|
|
that required this authorization call. The `username`
|
|
|
|
|
and `password` are the name of the user that is
|
2019-10-19 01:26:47 +00:00
|
|
|
|
accessing the resource and the password for the specified resource/user
|
2019-11-30 03:12:39 +00:00
|
|
|
|
pair.
|
|
|
|
|
|
|
|
|
|
Since the password is not encrypted during network transmission, it is
|
|
|
|
|
recommended to use the following extension:
|
|
|
|
|
|
|
|
|
|
If the server adds the string ``$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 ``$MD5$``.
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2023-10-13 04:42:40 +00:00
|
|
|
|
In the reply, `dummy` is completely unused. Note that
|
2019-10-19 01:26:47 +00:00
|
|
|
|
there is no direct failure indication. This is unnecessary since a net
|
|
|
|
|
client will retry the RPC that resulted in the authorization request
|
2019-11-30 03:12:39 +00:00
|
|
|
|
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 :macro:`SANE_STATUS_ACCESS_DENIED`.
|
|
|
|
|
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2019-10-18 10:29:36 +00:00
|
|
|
|
.. index:: SANE_NET_EXIT
|
|
|
|
|
|
|
|
|
|
:data:`SANE_NET_EXIT`
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2020-01-28 12:23:49 +00:00
|
|
|
|
RPC Code: 10
|
|
|
|
|
|
2019-10-19 01:26:47 +00:00
|
|
|
|
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
|
2023-10-13 04:42:40 +00:00
|
|
|
|
the `SANE_NET_INIT` call will be closed.
|
2019-10-19 01:26:47 +00:00
|
|
|
|
|
2019-10-29 11:56:06 +00:00
|
|
|
|
.. [1]
|
2019-10-19 01:26:47 +00:00
|
|
|
|
The username and password should be encrypted before network
|
|
|
|
|
transmission but currently they are always in plain text.
|