mirror
/
sane-project-standard
kopia lustrzana https://gitlab.com/sane-project/standard
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

Fix CI test jobs for SANE standard

master
John Millikin 2023-10-13 04:42:40 +00:00 zatwierdzone przez Ralph Little
rodzic 9949b3735a
commit 058f503702
3 zmienionych plików z 148 dodań i 132 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

18
.gitlab-ci.yml
Wyświetl plik

@ -1,4 +1,4 @@
image: registry.gitlab.com/paddy-hack/sphinx/debian/pdf:7.2.6
image: registry.gitlab.com/paddy-hack/sphinx/debian:7.2.6
stages:
- test
@ -9,10 +9,19 @@ test:
before_script:
- apt-get update -qq
- apt-get install -qqy --no-install-recommends
git
python3-enchant
python3-pip
python3-setuptools
python3-wheel
git
- pip3 --quiet install -r requirements.txt
- apt-get install -qqy --no-install-recommends
latexmk
texlive-latex-base
texlive-latex-recommended
texlive-fonts-recommended
texlive-latex-extra
script:
# Prevent versioning support from kicking in as that breaks
# sphinx-build invocations.
@ -29,10 +38,17 @@ pages:
- apt-get update -qq
- apt-get install -qqy --no-install-recommends
python3-enchant
python3-pip
python3-setuptools
python3-wheel
git
- pip3 --quiet install -r requirements.txt
- apt-get install -qqy --no-install-recommends
latexmk
texlive-latex-base
texlive-latex-recommended
texlive-fonts-recommended
texlive-latex-extra
script:
- sphinx-versioning build -w master -w draft-2
--show-banner --banner-main-ref 1.06

144
api.rst
Wyświetl plik

@ -47,14 +47,14 @@ numbers.
The value of this macro is the number of the SANE standard that
the interface implements.
.. function:: SANE_VERSION_CODE(maj, min, bld)
.. macro:: SANE_VERSION_CODE(maj, min, bld)
This macro can be used
to build a monotonically increasing version code. A SANE version
code consists of the SANE standard major version number
(:data:`maj`), the minor version number
:data:`min`, and the build revision of a backend
(:data:`bld`). The major and minor version numbers
(`maj`), the minor version number
`min`, and the build revision of a backend
(`bld`). The major and minor version numbers
must be in the range 0…255 and the build revision must be in the
range 0…65535.
@ -68,20 +68,20 @@ numbers.
build revision are used for informational and bug-fixing
purposes only.
.. function:: SANE_VERSION_MAJOR(vc)
.. macro:: SANE_VERSION_MAJOR(vc)
This macro returns the major version number component of the
version code passed in argument :data:`vc`.
version code passed in argument `vc`.
.. function:: SANE_VERSION_MINOR(vc)
.. macro:: SANE_VERSION_MINOR(vc)
This macro returns the minor version number component of the
version code passed in argument :data:`vc`.
version code passed in argument `vc`.
.. function:: SANE_VERSION_BUILD(vc)
.. macro:: SANE_VERSION_BUILD(vc)
This macro returns the build revision component of the version
code passed in argument :data:`vc`.
code passed in argument `vc`.
Data Types
----------
@ -114,7 +114,7 @@ holding any of the following:
Note that the SANE standard does not define what C type :type:`SANE_Byte`
and :type:`SANE_Word` map to. For example, on some platforms, the latter may
map to :type:`long int` whereas on others it may map to :type:`int`. A portable
map to `long int` whereas on others it may map to `int`. A portable
SANE frontend or backend must therefore not depend on a particular
mapping.
@ -188,20 +188,20 @@ fixed-point object.
For convenience, SANE also defines two macros that convert fixed-point
values to and from C double floating point values.
.. function:: SANE_FIX(d)
.. macro:: SANE_FIX(d)
Returns the largest SANE fixed-point value that is smaller than
the double value :data:`d`. No range checking is
performed. If the value of :data:`d` is out of range,
the double value `d`. No range checking is
performed. If the value of `d` is out of range,
the result is undefined.
.. function:: SANE_UNFIX(w)
.. macro:: SANE_UNFIX(w)
Returns the nearest double machine number that corresponds to
fixed-point value :data:`w`.
fixed-point value `w`.
SANE does *not* require that the following two expressions hold true
(even if the values of :data:`w` and :data:`d` are
(even if the values of `w` and `d` are
in range):
::
@ -223,7 +223,7 @@ Character Type
Type :type:`SANE_Char` represents a single text
character or symbol. At present, this type maps directly to the
underlying C :type:`char` type (typically one byte). The encoding for such
underlying C `char` type (typically one byte). The encoding for such
characters is currently fixed as ISO LATIN-1. Future versions of this
standard may map this type to a wider type and allow multi-byte
encodings to support internationalization. As a result of this, care
@ -240,8 +240,8 @@ String Type
^^^^^^^^^^^
Type :type:`SANE_String` represents a text string as
a sequence of C :type:`char` values. The end of the sequence is indicated by
a ``'\0'`` (:data:`NUL`) character.
a sequence of C `char` values. The end of the sequence is indicated by
a ``'\0'`` (`NUL`) character.
::
@ -594,9 +594,9 @@ depending on the type of the option value:
:macro:`SANE_TYPE_STRING`:
The size is the maximum size of the string. For the purpose of
string size calculations, the terminating :data:`NUL`
string size calculations, the terminating `NUL`
character is considered to be part of the string. Note that the
terminating :data:`NUL` character must always be
terminating `NUL` character must always be
present in string option values.
:macro:`SANE_TYPE_INT`, :macro:`SANE_TYPE_FIXED`:
@ -619,16 +619,16 @@ the capabilities described in :numref:`tab:capabilities`.
The SANE API provides the following to macros to test certain features
of a given capability bitset:
.. function:: SANE_OPTION_IS_ACTIVE(cap)
.. macro:: SANE_OPTION_IS_ACTIVE(cap)
This macro returns :macro:`SANE_TRUE` if and only if
the option with the capability set :data:`cap` is
the option with the capability set `cap` is
currently active.
.. function:: SANE_OPTION_IS_SETTABLE(cap)
.. macro:: SANE_OPTION_IS_SETTABLE(cap)
This macro returns :macro:`SANE_TRUE` if and only if
the option with the capability set :data:`cap` is
the option with the capability set `cap` is
software settable.
.. tabularcolumns:: |\X{12}{32}|r|\X{16}{32}|
@ -766,9 +766,9 @@ This function must be called before any other SANE function can be
called. The behavior of a SANE backend is undefined if this function is
not called first or if the status code returned by :func:`sane_init()`
is different from :macro:`SANE_STATUS_GOOD`. The version code of the
backend is returned in the value pointed to by :data:`version_code`.
backend is returned in the value pointed to by `version_code`.
If that pointer is :macro:`NULL`, no version code is returned.
Argument :data:`authorize` is either a pointer to a function that is
Argument `authorize` is either a pointer to a function that is
invoked when the backend requires authentication for a specific
resource or :macro:`NULL` if the frontend does not support
authentication.
@ -809,10 +809,10 @@ The authentication function type has the following declaration:
SANE_Char password[SANE_MAX_PASSWORD_LEN]);
Three arguments are passed to the authorization function:
:data:`resource` is a string specifying the name of the
`resource` is a string specifying the name of the
resource that requires authorization. A frontend should use this string
to build a user-prompt requesting a username and a password. The
:data:`username` and :data:`password` arguments
`username` and `password` arguments
are (pointers to) an array of :macro:`SANE_MAX_USERNAME_LEN`
and :macro:`SANE_MAX_PASSWORD_LEN` characters, respectively.
The authorization call should place the entered username and password in
@ -845,12 +845,12 @@ result in some resources not being released properly.
This function can be used to query the list of devices that are
available. If the function executes successfully, it stores a pointer to
a :macro:`NULL` terminated array of pointers to
:type:`SANE_Device` structures in :data:`*device_list`. The
:type:`SANE_Device` structures in `*device_list`. The
returned list is guaranteed to remain unchanged and valid until (a)
another call to this function is performed or (b) a call to
:func:`sane_exit()` is performed. This function can be
called repeatedly to detect when new devices become available. If
argument :data:`local_only` is true, only local devices are
argument `local_only` is true, only local devices are
returned (devices directly attached to the machine that SANE is running
on). If it is false, the device list includes all remote devices that
are accessible to the SANE library.
@ -877,8 +877,8 @@ insufficient amount of memory is available.
This function is used to establish a connection to a particular device.
The name of the device to be opened is passed in argument
:data:`name`. If the call completes successfully, a handle
for the device is returned in :data:`*h`. As a special case,
`name`. If the call completes successfully, a handle
for the device is returned in `*h`. As a special case,
specifying a zero-length string as the device requests opening the first
available device (if there is such a device).
@ -910,10 +910,10 @@ This function may fail with one of the following status codes.
~~~~~~~~~~~~~~~~~~
This function terminates the association between the device handle
passed in argument :data:`h` and the device it represents.
passed in argument `h` and the device it represents.
If the device is presently active, a call to
:func:`sane_cancel()` is performed first. After this
function returns, handle :data:`h` must not be used anymore.
function returns, handle `h` must not be used anymore.
::
@ -925,11 +925,11 @@ function returns, handle :data:`h` must not be used anymore.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This function is used to access option descriptors. The function returns
the option descriptor for option number :data:`n` of the
device represented by handle :data:`h`. Option number 0 is
the option descriptor for option number `n` of the
device represented by handle `h`. Option number 0 is
guaranteed to be a valid option. Its value is an integer that specifies
the number of options that are available for device handle
:data:`h` (the count includes option 0). If :math:`n` is not
`h` (the count includes option 0). If :math:`n` is not
a valid option index, the function returns :macro:`NULL`. The
returned option descriptor is guaranteed to remain valid (and at the
returned address) until the device is closed.
@ -946,20 +946,20 @@ returned address) until the device is closed.
~~~~~~~~~~~~~~~~~~~~~~~~~~~
This function is used to set or inquire the current value of option
number :data:`n` of the device represented by handle
:data:`h`. The manner in which the option is controlled is
specified by parameter :data:`a`. The possible values of
number `n` of the device represented by handle
`h`. The manner in which the option is controlled is
specified by parameter `a`. The possible values of
this parameter are described in more detail below. The value of the
option is passed through argument :data:`v`. It is a pointer
option is passed through argument `v`. It is a pointer
to the memory that holds the option value. The memory area pointed to by
:data:`v` must be big enough to hold the entire option value
`v` must be big enough to hold the entire option value
(determined by member :member:`size` in the corresponding
option descriptor). The only exception to this rule is that when setting
the value of a string option, the string pointed to by argument
:data:`v` may be shorter since the backend will stop reading
the option value upon encountering the first :data:`NUL`
terminator in the string. If argument :data:`i` is not
:macro:`NULL`, the value of :data:`*i` will be
`v` may be shorter since the backend will stop reading
the option value upon encountering the first `NUL`
terminator in the string. If argument `i` is not
:macro:`NULL`, the value of `*i` will be
set to provide details on how well the request has been met. The meaning
of this argument is described in more detail below.
@ -972,7 +972,7 @@ of this argument is described in more detail below.
.. index:: SANE_Action
The way the option is affected by a call to this function is controlled
by parameter :data:`a` which is a value of type
by parameter `a` which is a value of type
:type:`SANE_Action`. The possible values and their
meaning is described in :numref:`tab:actions`.
@ -987,19 +987,19 @@ meaning is described in :numref:`tab:actions`.
| .. macro:: SANE_ACTION_GET_VALUE | 0 | Get current option value. |
+----------------------------------+------+-------------------------------------------------------------------------+
| .. macro:: SANE_ACTION_SET_VALUE | 1 | Set option value. The |
| | | option value passed through argument :data:`v` may be modified by the |
| | | option value passed through argument `v` may be modified by the |
| | | backend if the value cannot be set exactly. |
+----------------------------------+------+-------------------------------------------------------------------------+
| .. macro:: SANE_ACTION_SET_AUTO | 2 | Turn on automatic mode. Backend |
| | | or device will automatically select an appropriate value. This mode |
| | | remains effective until overridden by an explicit set value request. |
| | | The value of parameter :data:`v` is completely ignored in this case and |
| | | The value of parameter `v` is completely ignored in this case and |
| | | may be :macro:`NULL`. |
+----------------------------------+------+-------------------------------------------------------------------------+
After setting a value via an action value of :macro:`SANE_ACTION_SET_VALUE`,
additional information on how well the request has been met is returned
in :data:`*i` (if :data:`i` is
in `*i` (if `i` is
non-:macro:`NULL`). The returned value is a bitset that may
contain any combination of the values described in
:numref:`tab:info`.
@ -1017,7 +1017,7 @@ contain any combination of the values described in
| | | not exactly match the requested value. For example, if a scanner |
| | | can adjust the resolution in increments of 30dpi only, setting the |
| | | resolution to 307dpi may result in an actual setting of 300dpi. |
| | | When this happens, the bitset returned in :data:`*i` has this member |
| | | When this happens, the bitset returned in `*i` has this member |
| | | set. In addition, the option value is modified to reflect the |
| | | actual (rounded) value that was used by the backend. Note that |
| | | inexact values are admissible for strings as well. A backend may |
@ -1027,14 +1027,14 @@ contain any combination of the values described in
| .. macro:: SANE_INFO_RELOAD_OPTIONS | 2 | The setting of an |
| | | option may affect the value or availability of one or more |
| | | *other* options. When this happens, the SANE backend sets this |
| | | member in :data:`*i` to indicate that the application should reload |
| | | member in `*i` to indicate that the application should reload |
| | | all options. This member may be set if and only if at least one |
| | | option changed. |
+-------------------------------------+------+----------------------------------------------------------------------+
| .. macro:: SANE_INFO_RELOAD_PARAMS | 4 | The setting of an option may |
| | | affect the parameter values (see :func:`sane_get_parameters()`). |
| | | If setting an option affects the parameter values, this member will |
| | | be set in :data:`*i`. Note that this member may be set even if the |
| | | be set in `*i`. Note that this member may be set even if the |
| | | parameters did not actually change. However, it is guaranteed that |
| | | the parameters never change without this member being set. |
+-------------------------------------+------+----------------------------------------------------------------------+
@ -1071,9 +1071,9 @@ values are best-effort estimates of what the parameters will be when
:func:`sane_start()` gets invoked. Calling this function
before a scan has actually started allows, for example, to get an
estimate of how big the scanned image will be. The parameters passed to
this function are the handle :data:`h` of the device for
this function are the handle `h` of the device for
which the parameters should be obtained and a pointer
:data:`p` to a parameter structure. The parameter structure
`p` to a parameter structure. The parameter structure
is described in more detail below.
::
@ -1173,7 +1173,7 @@ able to properly cope with such “padded” image formats.
~~~~~~~~~~~~~~~~~~
This function initiates acquisition of an image from the device
represented by handle :data:`h`.
represented by handle `h`.
::
@ -1216,14 +1216,14 @@ This function may fail with one of the following status codes.
~~~~~~~~~~~~~~~~~
This function is used to read image data from the device represented by
handle :data:`h`. Argument :data:`buf` is a
pointer to a memory area that is at least :data:`maxlen`
handle `h`. Argument `buf` is a
pointer to a memory area that is at least `maxlen`
bytes long. The number of bytes returned is stored in
:data:`*len`. A backend must set this to zero when
`*len`. A backend must set this to zero when
a status other than
:macro:`SANE_STATUS_GOOD` is returned). When the call
succeeds, the number of bytes returned can be anywhere in the range from
0 to :data:`maxlen` bytes.
0 to `maxlen` bytes.
::
@ -1232,7 +1232,7 @@ succeeds, the number of bytes returned can be anywhere in the range from
If this function is called when no data is available, one of two things
may happen, depending on the I/O mode that is in effect for handle
:data:`h`.
`h`.
#. If the device is in blocking I/O mode (the default mode), the call
blocks until at least one data byte is available (or until some error
@ -1240,9 +1240,9 @@ may happen, depending on the I/O mode that is in effect for handle
#. If the device is in non-blocking I/O mode, the call returns
immediately with status :macro:`SANE_STATUS_GOOD` and
with :data:`*len` set to zero.
with `*len` set to zero.
The I/O mode of handle :data:`h` can be set via a call to
The I/O mode of handle `h` can be set via a call to
:func:`sane_set_io_mode()`.
This function may fail with one of the following status codes.
@ -1280,14 +1280,14 @@ This function may fail with one of the following status codes.
This function is used to immediately or as quickly as possible cancel
the currently pending operation of the device represented by handle
:data:`h`.
`h`.
::
void sane_cancel (SANE_Handle h);
This function can be called at any time (as long as handle
:data:`h` is a valid handle) but usually affects
`h` is a valid handle) but usually affects
long-running operations only (such as image is acquisition). It is safe
to call this function asynchronously (e.g., from within a signal
handler). It is important to note that completion of this operation does
@ -1305,8 +1305,8 @@ operation has returned.
~~~~~~~~~~~~~~~~~~~~~~~~
This function is used to set the I/O mode of handle
:data:`h`. The I/O mode can be either blocking or
non-blocking. If argument :data:`m` is
`h`. The I/O mode can be either blocking or
non-blocking. If argument `m` is
:macro:`SANE_TRUE`, the mode is set to non-blocking mode,
otherwise it's set to blocking mode.
This function can be called only after a call to
@ -1320,7 +1320,7 @@ By default, newly opened handles operate in blocking mode. A backend may
elect not to support non-blocking I/O mode. In such a case the status
value :macro:`SANE_STATUS_UNSUPPORTED` is returned. Blocking
I/O must be supported by all backends, so calling this function with
argument :data:`m` set to :macro:`SANE_FALSE` is
argument `m` set to :macro:`SANE_FALSE` is
guaranteed to complete successfully.
This function may fail with one of the following status codes:
@ -1337,11 +1337,11 @@ This function may fail with one of the following status codes:
~~~~~~~~~~~~~~~~~~~~~~~~~~
This function is used to obtain a (platform-specific) file-descriptor
for handle :data:`h` that is readable if and only if image
for handle `h` that is readable if and only if image
data is available (i.e., when a call to :func:`sane_read()`
will return at least one byte of data). If the call completes
successfully, the select file-descriptor is returned in
:data:`*fd`.
`*fd`.
::

118
net.rst
Wyświetl plik

@ -181,12 +181,12 @@ reply arguments for this call are shown in the table below:
+----------------------------------------+----------------------------------------+
| request | reply |
+========================================+========================================+
| :type:`SANE_Word` :data:`version_code` | :type:`SANE_Word` :data:`status` |
| :type:`SANE_Word` `version_code` | :type:`SANE_Word` `status` |
+----------------------------------------+----------------------------------------+
| :type:`SANE_String` :data:`user_name` | :type:`SANE_Word` :data:`version_code` |
| :type:`SANE_String` `user_name` | :type:`SANE_Word` `version_code` |
+----------------------------------------+----------------------------------------+
The :data:`version_code` argument in the request is the SANE
The `version_code` argument in the request is the SANE
version-code of the network backend that is contacting the network
daemon (see Section :numref:`sec:saneversioncode`). The
“build-revision” in the version code is used to hold the network
@ -194,7 +194,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 :data:`user_name` argument is the name of the user on
The `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 :macro:`NULL` pointer for
this argument. No trust should be placed in the authenticity of this
@ -202,10 +202,10 @@ 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, :data:`status` indicates the completion
In the reply, `status` indicates the completion
status. If the value is anything other than
:macro:`SANE_STATUS_GOOD`, the remainder of the reply has
undefined values. [1]_ The :data:`version_code` argument
undefined values. [1]_ The `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.
@ -226,17 +226,17 @@ daemon.
+--------------+--------------------------------------------+
| request | reply |
+==============+============================================+
| :type:`void` | :type:`SANE_Word` :data:`status` |
| `void` | :type:`SANE_Word` `status` |
+--------------+--------------------------------------------+
| | :type:`SANE_Device` :data:`***device_list` |
| | :type:`SANE_Device` `***device_list` |
+--------------+--------------------------------------------+
There are no arguments in the request for this call.
In the reply, :data:`status` indicates the completion
In the reply, `status` indicates the completion
status. If the value is anything other than
:macro:`SANE_STATUS_GOOD`, the remainder of the reply has
undefined values. The :data:`device_list` argument is a
undefined values. The `device_list` argument is a
pointer to a :macro:`NULL`-terminated array of
:type:`SANE_Device` pointers.
@ -255,20 +255,20 @@ This RPC is used to open a connection to a remote SANE device.
+-----------------------------------------+--------------------------------------+
| request | reply |
+=========================================+======================================+
| :type:`SANE_String` :data:`device_name` | :type:`SANE_Word` :data:`status` |
| :type:`SANE_String` `device_name` | :type:`SANE_Word` `status` |
+-----------------------------------------+--------------------------------------+
| | :type:`SANE_Word` :data:`handle` |
| | :type:`SANE_Word` `handle` |
+-----------------------------------------+--------------------------------------+
| | :type:`SANE_String` :data:`resource` |
| | :type:`SANE_String` `resource` |
+-----------------------------------------+--------------------------------------+
The :data:`device_name` argument specifies the name of the
The `device_name` argument specifies the name of the
device to open.
In the reply, :data:`status` indicates the completion
In the reply, `status` indicates the completion
status. If the value is anything other than
:macro:`SANE_STATUS_GOOD`, the remainder of the reply has
undefined values. The :data:`handle` argument specifies the
undefined values. The `handle` argument specifies the
device handle that uniquely identifies the connection. The
:data:`resource` argument is used to request authentication.
If it has a non-:macro:`NULL` value, the network backend
@ -291,13 +291,13 @@ This RPC is used to close a connection to a remote SANE device.
+----------------------------------+---------------------------------+
| request | reply |
+==================================+=================================+
| :type:`SANE_Word` :data:`handle` | :type:`SANE_Word` :data:`dummy` |
| :type:`SANE_Word` `handle` | :type:`SANE_Word` `dummy` |
+----------------------------------+---------------------------------+
The :data:`handle` argument identifies the connection that
The `handle` argument identifies the connection that
should be closed.
In the reply, the :data:`dummy` argument is unused. Its
In the reply, the `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).
@ -317,15 +317,15 @@ SANE device.
+----------------------------------+-----------------------------------------------+
| request | reply |
+==================================+===============================================+
| :type:`SANE_Word` :data:`handle` | :type:`Option_Descriptor_Array` :data:`odesc` |
| :type:`SANE_Word` `handle` | :type:`Option_Descriptor_Array` `odesc` |
+----------------------------------+-----------------------------------------------+
The :data:`handle` argument identifies the remote device
The `handle` argument identifies the remote device
whose option descriptors should be obtained.
.. index:: Option_Descriptor_Array
In the reply, the :data:`odesc` argument is used to return
In the reply, the `odesc` argument is used to return
the array of option descriptors. The option descriptor array has the
following structure:
@ -353,24 +353,24 @@ specific option of a remote SANE device.
+--------------------------------------+---------------------------------------+
| request | reply |
+======================================+=======================================+
| :type:`SANE_Word` :data:`handle` | :type:`SANE_Status` :data:`status` |
| :type:`SANE_Word` `handle` | :type:`SANE_Status` `status` |
+--------------------------------------+---------------------------------------+
| :type:`SANE_Word` :data:`option` | :type:`SANE_Word` :data:`info` |
| :type:`SANE_Word` `option` | :type:`SANE_Word` `info` |
+--------------------------------------+---------------------------------------+
| :type:`SANE_Word` :data:`action` | :type:`SANE_Word` :data:`value_type` |
| :type:`SANE_Word` `action` | :type:`SANE_Word` `value_type` |
+--------------------------------------+---------------------------------------+
| :type:`SANE_Word` :data:`value_type` | :type:`SANE_Word` :data:`value_size` |
| :type:`SANE_Word` `value_type` | :type:`SANE_Word` `value_size` |
+--------------------------------------+---------------------------------------+
| :type:`SANE_Word` :data:`value_size` | :type:`void` :data:`*value` |
| :type:`SANE_Word` `value_size` | `void` `*value` |
+--------------------------------------+---------------------------------------+
| :type:`void` :data:`*value` | :type:`SANE_String` :data:`*resource` |
| `void` `*value` | :type:`SANE_String` `*resource` |
+--------------------------------------+---------------------------------------+
The :data:`handle` argument identifies the remote device
whose option should be controlled. Argument :data:`option`
The `handle` argument identifies the remote device
whose option should be controlled. Argument `option`
is the number (index) of the option that should be controlled. Argument
:data:`action` specifies what action should be taken (get,
set, or set automatic). Argument :data:`value_type`
set, or set automatic). Argument `value_type`
specifies the type of the option value (must be one of
:macro:`SANE_TYPE_BOOL`, :macro:`SANE_TYPE_INT`,
:macro:`SANE_TYPE_FIXED`,
@ -380,13 +380,13 @@ specifies the type of the option value (must be one of
number of bytes (see Section :numref:`sec:valuesize` for the
precise meaning of this value). Finally, argument
:data:`value` is a pointer to the option value. It must be a
writable area that is at least :data:`value_size` bytes
writable area that is at least `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 :data:`resource` is set to the name
In the reply, argument `resource` is set to the name
of the resource that must be authorized before this call can be retried.
If this value is non-:macro:`NULL`, all other arguments have
undefined values (see Section :numref:`sec:authorization` for
@ -398,11 +398,11 @@ remainder of the reply has undefined values. The
the backend was able to satisfy the request. For details, see the
description of the corresponding argument in
Section :numref:`sec:control`. Arguments
:data:`value_type` and :data:`value_size` have
:data:`value_type` and `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 :data:`value` is holds the value of
independently). Argument `value` is holds the value of
the option that has become effective as a result of this RPC.
.. index:: SANE_NET_GET_PARAMETERS
@ -420,18 +420,18 @@ This RPC is used to obtain the scan parameters of a remote SANE device.
+----------------------------------+----------------------------------------+
| request | reply |
+==================================+========================================+
| :type:`SANE_Word` :data:`handle` | :type:`SANE_Status` :data:`status` |
| :type:`SANE_Word` `handle` | :type:`SANE_Status` `status` |
+----------------------------------+----------------------------------------+
| | :type:`SANE_Parameters` :data:`params` |
| | :type:`SANE_Parameters` `params` |
+----------------------------------+----------------------------------------+
The :data:`handle` argument identifies the connection to the
The `handle` argument identifies the connection to the
remote device whose scan parameters should be returned.
In the reply, :data:`status` indicates the completion
In the reply, `status` indicates the completion
status. If the value is anything other than
:macro:`SANE_STATUS_GOOD`, the remainder of the reply
has undefined values. The argument :data:`params` is used to
has undefined values. The argument `params` is used to
return the scan parameters.
.. index:: SANE_NET_START
@ -449,19 +449,19 @@ This RPC is used to start image acquisition (scanning).
+----------------------------------+--------------------------------------+
| request | reply |
+==================================+======================================+
| :type:`SANE_Word` :data:`handle` | :type:`SANE_Status` :data:`status` |
| :type:`SANE_Word` `handle` | :type:`SANE_Status` `status` |
+----------------------------------+--------------------------------------+
| | :type:`SANE_Word` :data:`port` |
| | :type:`SANE_Word` `port` |
+----------------------------------+--------------------------------------+
| | :type:`SANE_Word` :data:`byte_order` |
| | :type:`SANE_Word` `byte_order` |
+----------------------------------+--------------------------------------+
| | :type:`SANE_String` :data:`resource` |
| | :type:`SANE_String` `resource` |
+----------------------------------+--------------------------------------+
The :data:`handle` argument identifies the connection to the
The `handle` argument identifies the connection to the
remote device from which the image should be acquired.
In the reply, argument :data:`resource` is set to the name
In the reply, argument `resource` is set to the name
of the resource that must be authorized before this call can be retried.
If this value is non-:macro:`NULL`, all other arguments have
undefined values (see Section :numref:`sec:authorization` for
@ -485,7 +485,7 @@ the data stream. That is, after receiving a record length of
``0xffffffff``, the network client should close the data
connection and stop reading data.
Argument :data:`byte_order` specifies the byte-order of the
Argument `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
@ -512,13 +512,13 @@ device.
+----------------------------------+---------------------------------+
| request | reply |
+==================================+=================================+
| :type:`SANE_Word` :data:`handle` | :type:`SANE_Word` :data:`dummy` |
| :type:`SANE_Word` `handle` | :type:`SANE_Word` `dummy` |
+----------------------------------+---------------------------------+
The :data:`handle` argument identifies the connection whose
The `handle` argument identifies the connection whose
operation should be cancelled.
In the reply, the :data:`dummy` argument is unused. Its
In the reply, the `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).
@ -539,18 +539,18 @@ net server.
+--------------------------------------+---------------------------------+
| request | reply |
+======================================+=================================+
| :type:`SANE_String` :data:`resource` | :type:`SANE_Word` :data:`dummy` |
| :type:`SANE_String` `resource` | :type:`SANE_Word` `dummy` |
+--------------------------------------+---------------------------------+
| :type:`SANE_String` :data:`username` | |
| :type:`SANE_String` `username` | |
+--------------------------------------+---------------------------------+
| :type:`SANE_String` :data:`password` | |
| :type:`SANE_String` `password` | |
+--------------------------------------+---------------------------------+
The :data:`resource` argument specifies the name of the
The `resource` argument specifies the name of the
resource to be authorized. This argument should be set to the string
returned in the :data:`resource` argument of the RPC reply
that required this authorization call. The :data:`username`
and :data:`password` are the name of the user that is
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
accessing the resource and the password for the specified resource/user
pair.
@ -563,7 +563,7 @@ 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$``.
In the reply, :data:`dummy` is completely unused. Note that
In the reply, `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
@ -581,7 +581,7 @@ 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 :data:`SANE_NET_INIT` call will be closed.
the `SANE_NET_INIT` call will be closed.
.. [1]
The username and password should be encrypted before network