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: stages:
- test - test
@ -9,10 +9,19 @@ test:
before_script: before_script:
- apt-get update -qq - apt-get update -qq
- apt-get install -qqy --no-install-recommends - apt-get install -qqy --no-install-recommends
git
python3-enchant python3-enchant
python3-pip
python3-setuptools python3-setuptools
python3-wheel python3-wheel
git
- pip3 --quiet install -r requirements.txt - 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: script:
# Prevent versioning support from kicking in as that breaks # Prevent versioning support from kicking in as that breaks
# sphinx-build invocations. # sphinx-build invocations.
@ -29,10 +38,17 @@ pages:
- apt-get update -qq - apt-get update -qq
- apt-get install -qqy --no-install-recommends - apt-get install -qqy --no-install-recommends
python3-enchant python3-enchant
python3-pip
python3-setuptools python3-setuptools
python3-wheel python3-wheel
git git
- pip3 --quiet install -r requirements.txt - 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: script:
- sphinx-versioning build -w master -w draft-2 - sphinx-versioning build -w master -w draft-2
--show-banner --banner-main-ref 1.06 --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 value of this macro is the number of the SANE standard that
the interface implements. the interface implements.
.. function:: SANE_VERSION_CODE(maj, min, bld) .. macro:: SANE_VERSION_CODE(maj, min, bld)
This macro can be used This macro can be used
to build a monotonically increasing version code. A SANE version to build a monotonically increasing version code. A SANE version
code consists of the SANE standard major version number code consists of the SANE standard major version number
(:data:`maj`), the minor version number (`maj`), the minor version number
:data:`min`, and the build revision of a backend `min`, and the build revision of a backend
(:data:`bld`). The major and minor version numbers (`bld`). The major and minor version numbers
must be in the range 0…255 and the build revision must be in the must be in the range 0…255 and the build revision must be in the
range 0…65535. range 0…65535.
@ -68,20 +68,20 @@ numbers.
build revision are used for informational and bug-fixing build revision are used for informational and bug-fixing
purposes only. purposes only.
.. function:: SANE_VERSION_MAJOR(vc) .. macro:: SANE_VERSION_MAJOR(vc)
This macro returns the major version number component of the 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 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 This macro returns the build revision component of the version
code passed in argument :data:`vc`. code passed in argument `vc`.
Data Types 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` 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 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 SANE frontend or backend must therefore not depend on a particular
mapping. mapping.
@ -188,20 +188,20 @@ fixed-point object.
For convenience, SANE also defines two macros that convert fixed-point For convenience, SANE also defines two macros that convert fixed-point
values to and from C double floating point values. 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 Returns the largest SANE fixed-point value that is smaller than
the double value :data:`d`. No range checking is the double value `d`. No range checking is
performed. If the value of :data:`d` is out of range, performed. If the value of `d` is out of range,
the result is undefined. the result is undefined.
.. function:: SANE_UNFIX(w) .. macro:: SANE_UNFIX(w)
Returns the nearest double machine number that corresponds to 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 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): in range):
:: ::
@ -223,7 +223,7 @@ Character Type
Type :type:`SANE_Char` represents a single text Type :type:`SANE_Char` represents a single text
character or symbol. At present, this type maps directly to the 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 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 standard may map this type to a wider type and allow multi-byte
encodings to support internationalization. As a result of this, care 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 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 sequence of C `char` values. The end of the sequence is indicated by
a ``'\0'`` (:data:`NUL`) character. a ``'\0'`` (`NUL`) character.
:: ::
@ -594,9 +594,9 @@ depending on the type of the option value:
:macro:`SANE_TYPE_STRING`: :macro:`SANE_TYPE_STRING`:
The size is the maximum size of the string. For the purpose of 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 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. present in string option values.
:macro:`SANE_TYPE_INT`, :macro:`SANE_TYPE_FIXED`: :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 The SANE API provides the following to macros to test certain features
of a given capability bitset: 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 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. currently active.
.. function:: SANE_OPTION_IS_SETTABLE(cap) .. macro:: SANE_OPTION_IS_SETTABLE(cap)
This macro returns :macro:`SANE_TRUE` if and only if 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. software settable.
.. tabularcolumns:: |\X{12}{32}|r|\X{16}{32}| .. 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 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()` 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 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. 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 invoked when the backend requires authentication for a specific
resource or :macro:`NULL` if the frontend does not support resource or :macro:`NULL` if the frontend does not support
authentication. authentication.
@ -809,10 +809,10 @@ The authentication function type has the following declaration:
SANE_Char password[SANE_MAX_PASSWORD_LEN]); SANE_Char password[SANE_MAX_PASSWORD_LEN]);
Three arguments are passed to the authorization function: 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 resource that requires authorization. A frontend should use this string
to build a user-prompt requesting a username and a password. The 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` are (pointers to) an array of :macro:`SANE_MAX_USERNAME_LEN`
and :macro:`SANE_MAX_PASSWORD_LEN` characters, respectively. and :macro:`SANE_MAX_PASSWORD_LEN` characters, respectively.
The authorization call should place the entered username and password in 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 This function can be used to query the list of devices that are
available. If the function executes successfully, it stores a pointer to available. If the function executes successfully, it stores a pointer to
a :macro:`NULL` terminated array of pointers 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) returned list is guaranteed to remain unchanged and valid until (a)
another call to this function is performed or (b) a call to another call to this function is performed or (b) a call to
:func:`sane_exit()` is performed. This function can be :func:`sane_exit()` is performed. This function can be
called repeatedly to detect when new devices become available. If 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 returned (devices directly attached to the machine that SANE is running
on). If it is false, the device list includes all remote devices that on). If it is false, the device list includes all remote devices that
are accessible to the SANE library. 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. This function is used to establish a connection to a particular device.
The name of the device to be opened is passed in argument The name of the device to be opened is passed in argument
:data:`name`. If the call completes successfully, a handle `name`. If the call completes successfully, a handle
for the device is returned in :data:`*h`. As a special case, for the device is returned in `*h`. As a special case,
specifying a zero-length string as the device requests opening the first specifying a zero-length string as the device requests opening the first
available device (if there is such a device). 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 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 If the device is presently active, a call to
:func:`sane_cancel()` is performed first. After this :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 This function is used to access option descriptors. The function returns
the option descriptor for option number :data:`n` of the the option descriptor for option number `n` of the
device represented by handle :data:`h`. Option number 0 is device represented by handle `h`. Option number 0 is
guaranteed to be a valid option. Its value is an integer that specifies guaranteed to be a valid option. Its value is an integer that specifies
the number of options that are available for device handle 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 a valid option index, the function returns :macro:`NULL`. The
returned option descriptor is guaranteed to remain valid (and at the returned option descriptor is guaranteed to remain valid (and at the
returned address) until the device is closed. 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 This function is used to set or inquire the current value of option
number :data:`n` of the device represented by handle number `n` of the device represented by handle
:data:`h`. The manner in which the option is controlled is `h`. The manner in which the option is controlled is
specified by parameter :data:`a`. The possible values of specified by parameter `a`. The possible values of
this parameter are described in more detail below. The value of the 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 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 (determined by member :member:`size` in the corresponding
option descriptor). The only exception to this rule is that when setting option descriptor). The only exception to this rule is that when setting
the value of a string option, the string pointed to by argument the value of a string option, the string pointed to by argument
:data:`v` may be shorter since the backend will stop reading `v` may be shorter since the backend will stop reading
the option value upon encountering the first :data:`NUL` the option value upon encountering the first `NUL`
terminator in the string. If argument :data:`i` is not terminator in the string. If argument `i` is not
:macro:`NULL`, the value of :data:`*i` will be :macro:`NULL`, the value of `*i` will be
set to provide details on how well the request has been met. The meaning set to provide details on how well the request has been met. The meaning
of this argument is described in more detail below. 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 .. index:: SANE_Action
The way the option is affected by a call to this function is controlled 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 :type:`SANE_Action`. The possible values and their
meaning is described in :numref:`tab:actions`. 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_GET_VALUE | 0 | Get current option value. |
+----------------------------------+------+-------------------------------------------------------------------------+ +----------------------------------+------+-------------------------------------------------------------------------+
| .. macro:: SANE_ACTION_SET_VALUE | 1 | Set option value. The | | .. 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. | | | | backend if the value cannot be set exactly. |
+----------------------------------+------+-------------------------------------------------------------------------+ +----------------------------------+------+-------------------------------------------------------------------------+
| .. macro:: SANE_ACTION_SET_AUTO | 2 | Turn on automatic mode. Backend | | .. macro:: SANE_ACTION_SET_AUTO | 2 | Turn on automatic mode. Backend |
| | | or device will automatically select an appropriate value. This mode | | | | or device will automatically select an appropriate value. This mode |
| | | remains effective until overridden by an explicit set value request. | | | | 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`. | | | | may be :macro:`NULL`. |
+----------------------------------+------+-------------------------------------------------------------------------+ +----------------------------------+------+-------------------------------------------------------------------------+
After setting a value via an action value of :macro:`SANE_ACTION_SET_VALUE`, 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 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 non-:macro:`NULL`). The returned value is a bitset that may
contain any combination of the values described in contain any combination of the values described in
:numref:`tab:info`. :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 | | | | not exactly match the requested value. For example, if a scanner |
| | | can adjust the resolution in increments of 30dpi only, setting the | | | | can adjust the resolution in increments of 30dpi only, setting the |
| | | resolution to 307dpi may result in an actual setting of 300dpi. | | | | 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 | | | | set. In addition, the option value is modified to reflect the |
| | | actual (rounded) value that was used by the backend. Note that | | | | actual (rounded) value that was used by the backend. Note that |
| | | inexact values are admissible for strings as well. A backend may | | | | 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 | | .. macro:: SANE_INFO_RELOAD_OPTIONS | 2 | The setting of an |
| | | option may affect the value or availability of one or more | | | | option may affect the value or availability of one or more |
| | | *other* options. When this happens, the SANE backend sets this | | | | *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 | | | | all options. This member may be set if and only if at least one |
| | | option changed. | | | | option changed. |
+-------------------------------------+------+----------------------------------------------------------------------+ +-------------------------------------+------+----------------------------------------------------------------------+
| .. macro:: SANE_INFO_RELOAD_PARAMS | 4 | The setting of an option may | | .. macro:: SANE_INFO_RELOAD_PARAMS | 4 | The setting of an option may |
| | | affect the parameter values (see :func:`sane_get_parameters()`). | | | | affect the parameter values (see :func:`sane_get_parameters()`). |
| | | If setting an option affects the parameter values, this member will | | | | 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 | | | | parameters did not actually change. However, it is guaranteed that |
| | | the parameters never change without this member being set. | | | | 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 :func:`sane_start()` gets invoked. Calling this function
before a scan has actually started allows, for example, to get an 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 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 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. 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 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 This function is used to read image data from the device represented by
handle :data:`h`. Argument :data:`buf` is a handle `h`. Argument `buf` is a
pointer to a memory area that is at least :data:`maxlen` pointer to a memory area that is at least `maxlen`
bytes long. The number of bytes returned is stored in 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 a status other than
:macro:`SANE_STATUS_GOOD` is returned). When the call :macro:`SANE_STATUS_GOOD` is returned). When the call
succeeds, the number of bytes returned can be anywhere in the range from 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 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 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 #. 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 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 #. If the device is in non-blocking I/O mode, the call returns
immediately with status :macro:`SANE_STATUS_GOOD` and 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()`. :func:`sane_set_io_mode()`.
This function may fail with one of the following status codes. 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 This function is used to immediately or as quickly as possible cancel
the currently pending operation of the device represented by handle the currently pending operation of the device represented by handle
:data:`h`. `h`.
:: ::
void sane_cancel (SANE_Handle h); void sane_cancel (SANE_Handle h);
This function can be called at any time (as long as handle 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 long-running operations only (such as image is acquisition). It is safe
to call this function asynchronously (e.g., from within a signal to call this function asynchronously (e.g., from within a signal
handler). It is important to note that completion of this operation does 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 This function is used to set the I/O mode of handle
:data:`h`. The I/O mode can be either blocking or `h`. The I/O mode can be either blocking or
non-blocking. If argument :data:`m` is non-blocking. If argument `m` is
:macro:`SANE_TRUE`, the mode is set to non-blocking mode, :macro:`SANE_TRUE`, the mode is set to non-blocking mode,
otherwise it's set to blocking mode. otherwise it's set to blocking mode.
This function can be called only after a call to 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 elect not to support non-blocking I/O mode. In such a case the status
value :macro:`SANE_STATUS_UNSUPPORTED` is returned. Blocking value :macro:`SANE_STATUS_UNSUPPORTED` is returned. Blocking
I/O must be supported by all backends, so calling this function with 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. guaranteed to complete successfully.
This function may fail with one of the following status codes: 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 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()` data is available (i.e., when a call to :func:`sane_read()`
will return at least one byte of data). If the call completes will return at least one byte of data). If the call completes
successfully, the select file-descriptor is returned in 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 | | 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 version-code of the network backend that is contacting the network
daemon (see Section :numref:`sec:saneversioncode`). The daemon (see Section :numref:`sec:saneversioncode`). The
“build-revision” in the version code is used to hold the network “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 make sure that the network protocol version corresponds to a supported
version since otherwise the encoding of the network stream may be version since otherwise the encoding of the network stream may be
incompatible (even though the SANE interface itself may be compatible). 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 whose behalf this call is being performed. If the network backend cannot
determine a user-name, it passes a :macro:`NULL` pointer for determine a user-name, it passes a :macro:`NULL` pointer for
this argument. No trust should be placed in the authenticity of this 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 the user. E.g., it could be used as the default-user name in subsequent
authentication calls. 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 status. If the value is anything other than
:macro:`SANE_STATUS_GOOD`, the remainder of the reply has :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 returns the SANE version-code that the network daemon supports. See the
comments in the previous paragraph on the meaning of the build-revision comments in the previous paragraph on the meaning of the build-revision
in this version code. in this version code.
@ -226,17 +226,17 @@ daemon.
+--------------+--------------------------------------------+ +--------------+--------------------------------------------+
| request | reply | | 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. 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 status. If the value is anything other than
:macro:`SANE_STATUS_GOOD`, the remainder of the reply has :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 pointer to a :macro:`NULL`-terminated array of
:type:`SANE_Device` pointers. :type:`SANE_Device` pointers.
@ -255,20 +255,20 @@ This RPC is used to open a connection to a remote SANE device.
+-----------------------------------------+--------------------------------------+ +-----------------------------------------+--------------------------------------+
| request | reply | | 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. 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 status. If the value is anything other than
:macro:`SANE_STATUS_GOOD`, the remainder of the reply has :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 device handle that uniquely identifies the connection. The
:data:`resource` argument is used to request authentication. :data:`resource` argument is used to request authentication.
If it has a non-:macro:`NULL` value, the network backend 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 | | 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. 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 purpose is to ensure proper synchronization (without it, a net client
would not be able to determine when the RPC has completed). would not be able to determine when the RPC has completed).
@ -317,15 +317,15 @@ SANE device.
+----------------------------------+-----------------------------------------------+ +----------------------------------+-----------------------------------------------+
| request | reply | | 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. whose option descriptors should be obtained.
.. index:: Option_Descriptor_Array .. 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 the array of option descriptors. The option descriptor array has the
following structure: following structure:
@ -353,24 +353,24 @@ specific option of a remote SANE device.
+--------------------------------------+---------------------------------------+ +--------------------------------------+---------------------------------------+
| request | reply | | 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 The `handle` argument identifies the remote device
whose option should be controlled. Argument :data:`option` whose option should be controlled. Argument `option`
is the number (index) of the option that should be controlled. Argument is the number (index) of the option that should be controlled. Argument
:data:`action` specifies what action should be taken (get, :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 specifies the type of the option value (must be one of
:macro:`SANE_TYPE_BOOL`, :macro:`SANE_TYPE_INT`, :macro:`SANE_TYPE_BOOL`, :macro:`SANE_TYPE_INT`,
:macro:`SANE_TYPE_FIXED`, :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 number of bytes (see Section :numref:`sec:valuesize` for the
precise meaning of this value). Finally, argument precise meaning of this value). Finally, argument
:data:`value` is a pointer to the option value. It must be a :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 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 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 exact option value, in which case the option value is used to return
the next best value that the backend has chosen.) 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. of the resource that must be authorized before this call can be retried.
If this value is non-:macro:`NULL`, all other arguments have If this value is non-:macro:`NULL`, all other arguments have
undefined values (see Section :numref:`sec:authorization` for 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 the backend was able to satisfy the request. For details, see the
description of the corresponding argument in description of the corresponding argument in
Section :numref:`sec:control`. Arguments 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 the same values as the arguments by the same name in corresponding
request. The values are repeated here to ensure that both the request 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 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. the option that has become effective as a result of this RPC.
.. index:: SANE_NET_GET_PARAMETERS .. 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 | | 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. 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 status. If the value is anything other than
:macro:`SANE_STATUS_GOOD`, the remainder of the reply :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. return the scan parameters.
.. index:: SANE_NET_START .. index:: SANE_NET_START
@ -449,19 +449,19 @@ This RPC is used to start image acquisition (scanning).
+----------------------------------+--------------------------------------+ +----------------------------------+--------------------------------------+
| request | reply | | 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. 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. of the resource that must be authorized before this call can be retried.
If this value is non-:macro:`NULL`, all other arguments have If this value is non-:macro:`NULL`, all other arguments have
undefined values (see Section :numref:`sec:authorization` for 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 ``0xffffffff``, the network client should close the data
connection and stop reading 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 image data. A value of 0x1234 indicates little-endian format, a value of
0x4321 indicates big-endian format. All other values are presently 0x4321 indicates big-endian format. All other values are presently
undefined and reserved for future enhancements of this protocol. The undefined and reserved for future enhancements of this protocol. The
@ -512,13 +512,13 @@ device.
+----------------------------------+---------------------------------+ +----------------------------------+---------------------------------+
| request | reply | | 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. 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 purpose is to ensure proper synchronization (without it, a net client
would not be able to determine when the RPC has completed). would not be able to determine when the RPC has completed).
@ -539,18 +539,18 @@ net server.
+--------------------------------------+---------------------------------+ +--------------------------------------+---------------------------------+
| request | reply | | 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 resource to be authorized. This argument should be set to the string
returned in the :data:`resource` argument of the RPC reply returned in the `resource` argument of the RPC reply
that required this authorization call. The :data:`username` that required this authorization call. The `username`
and :data:`password` are the name of the user that is and `password` are the name of the user that is
accessing the resource and the password for the specified resource/user accessing the resource and the password for the specified resource/user
pair. 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 random string. To differentiate between the MD5 digest and a strange
password the client prepends the MD5 digest with the string ``$MD5$``. 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 there is no direct failure indication. This is unnecessary since a net
client will retry the RPC that resulted in the authorization request client will retry the RPC that resulted in the authorization request
until that call succeeds (or until the request is cancelled). The RPC 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 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, 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 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] .. [1]
The username and password should be encrypted before network The username and password should be encrypted before network