From 058f50370271f153c2fec6259e011e8ba716f058 Mon Sep 17 00:00:00 2001 From: John Millikin Date: Fri, 13 Oct 2023 04:42:40 +0000 Subject: [PATCH] Fix CI test jobs for SANE standard --- .gitlab-ci.yml | 18 ++++++- api.rst | 144 ++++++++++++++++++++++++------------------------- net.rst | 118 ++++++++++++++++++++-------------------- 3 files changed, 148 insertions(+), 132 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index a960cdd..9b86cdc 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -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 diff --git a/api.rst b/api.rst index 8c416f2..0c7f936 100644 --- a/api.rst +++ b/api.rst @@ -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`. :: diff --git a/net.rst b/net.rst index 0b5f0ca..2ca35ce 100644 --- a/net.rst +++ b/net.rst @@ -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