kopia lustrzana https://gitlab.com/sane-project/standard
Fix spelling issues
Although "cancelled" was flagged as misspelled it has been kept with double l for consistency with `SANE_STATUS_CANCELLED`.draft-2
rodzic
bd38480d9f
commit
0e07f5dc12
44
api.rst
44
api.rst
|
@ -5,11 +5,11 @@ The SANE Application Programmer Interface (API)
|
||||||
|
|
||||||
This Section defines version 1 of the SANE application
|
This Section defines version 1 of the SANE application
|
||||||
programmer interface (API). Any SANE frontend must depend on the
|
programmer interface (API). Any SANE frontend must depend on the
|
||||||
interface defined in this section only. Converseley, any SANE backend
|
interface defined in this section only. Conversely, any SANE backend
|
||||||
must implement its functionality in accordance with this specification.
|
must implement its functionality in accordance with this specification.
|
||||||
The interface as documented here is declared as a C callable interface
|
The interface as documented here is declared as a C callable interface
|
||||||
in a file called ``sane/sane.h``. This file should
|
in a file called ``sane/sane.h``. This file should
|
||||||
normally be included via a C pre-processor directive of the form:
|
normally be included via a C preprocessor directive of the form:
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
|
@ -25,7 +25,7 @@ the SANE standard is made that may render an existing frontend or
|
||||||
backend incompatible with the new standard, the major version number
|
backend incompatible with the new standard, the major version number
|
||||||
must be increased. Thus, any frontend/backend pair is compatible
|
must be increased. Thus, any frontend/backend pair is compatible
|
||||||
provided the major version number of the SANE standard they implement is
|
provided the major version number of the SANE standard they implement is
|
||||||
the same. A frontend may implement backwards compatiblity by allowing
|
the same. A frontend may implement backwards compatibility by allowing
|
||||||
major numbers that are smaller than the expected major number (provided
|
major numbers that are smaller than the expected major number (provided
|
||||||
the frontend really can cope with the older version). In contrast, a
|
the frontend really can cope with the older version). In contrast, a
|
||||||
backend always provides support for one and only one version of the
|
backend always provides support for one and only one version of the
|
||||||
|
@ -34,7 +34,7 @@ versions of the same backend are accessible at the same time, it is
|
||||||
possible to do so by installing the two versions under different names.
|
possible to do so by installing the two versions under different names.
|
||||||
|
|
||||||
SANE version control also includes a minor version number and a build
|
SANE version control also includes a minor version number and a build
|
||||||
revision. While control of these numbers remains with the implementor of
|
revision. While control of these numbers remains with the implementer of
|
||||||
a backend, the recommended use is as follows. The minor version is
|
a backend, the recommended use is as follows. The minor version is
|
||||||
incremented with each official release of a backend. The build revision
|
incremented with each official release of a backend. The build revision
|
||||||
is increased with each build of a backend.
|
is increased with each build of a backend.
|
||||||
|
@ -139,7 +139,7 @@ Note that :type:`SANE_Bool` is simply an alias of :type:`SANE_Word`. It is
|
||||||
therefore always legal to use the latter type in place of the former.
|
therefore always legal to use the latter type in place of the former.
|
||||||
However, for clarity, it is recommended to use :type:`SANE_Bool` whenever a
|
However, for clarity, it is recommended to use :type:`SANE_Bool` whenever a
|
||||||
given variable or formal argument has a fixed interpretation as a
|
given variable or formal argument has a fixed interpretation as a
|
||||||
boolean object.
|
Boolean object.
|
||||||
|
|
||||||
.. index:: SANE_Int
|
.. index:: SANE_Int
|
||||||
|
|
||||||
|
@ -249,7 +249,7 @@ a ``'\0'`` (:data:`NUL`) character.
|
||||||
typedef const SANE_Char *SANE_String_Const;
|
typedef const SANE_Char *SANE_String_Const;
|
||||||
|
|
||||||
The type :type:`SANE_String_Const` is provided by
|
The type :type:`SANE_String_Const` is provided by
|
||||||
SANE to enable declaring strings whose contents is unchangable. Note
|
SANE to enable declaring strings whose contents is unchangeable. Note
|
||||||
that in ANSI C, the declaration
|
that in ANSI C, the declaration
|
||||||
|
|
||||||
::
|
::
|
||||||
|
@ -300,7 +300,7 @@ legible string.
|
||||||
+--------------------------------------+------+---------------------------------------+
|
+--------------------------------------+------+---------------------------------------+
|
||||||
| Symbol | Code | Description |
|
| Symbol | Code | Description |
|
||||||
+======================================+======+=======================================+
|
+======================================+======+=======================================+
|
||||||
| .. macro:: SANE_STATUS_GOOD | 0 | Operation completed succesfully. |
|
| .. macro:: SANE_STATUS_GOOD | 0 | Operation completed successfully. |
|
||||||
+--------------------------------------+------+---------------------------------------+
|
+--------------------------------------+------+---------------------------------------+
|
||||||
| .. macro:: SANE_STATUS_UNSUPPORTED | 1 | Operation is not supported. |
|
| .. macro:: SANE_STATUS_UNSUPPORTED | 1 | Operation is not supported. |
|
||||||
+--------------------------------------+------+---------------------------------------+
|
+--------------------------------------+------+---------------------------------------+
|
||||||
|
@ -501,7 +501,7 @@ Option Description
|
||||||
|
|
||||||
Member :member:`desc` is a (potentially very) long string that
|
Member :member:`desc` is a (potentially very) long string that
|
||||||
can be used as a help text to describe the option. It is the
|
can be used as a help text to describe the option. It is the
|
||||||
responsibility of the frontend to break the string into managable-length
|
responsibility of the frontend to break the string into manageable-length
|
||||||
lines. Newline characters in this string should be interpreted as
|
lines. Newline characters in this string should be interpreted as
|
||||||
paragraph breaks.
|
paragraph breaks.
|
||||||
|
|
||||||
|
@ -594,7 +594,7 @@ 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 calcuations, the terminating :data:`NUL`
|
string size calculations, the terminating :data:`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 :data:`NUL` character must always be
|
||||||
present in string option values.
|
present in string option values.
|
||||||
|
@ -614,7 +614,7 @@ Option Capabilities
|
||||||
^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Member :member:`cap` describes what capabilities the option
|
Member :member:`cap` describes what capabilities the option
|
||||||
posseses. This is a bitset that is formed as the inclusive logical OR of
|
possesses. This is a bitset that is formed as the inclusive logical OR of
|
||||||
the capabilities described in :numref:`tab:capabilities`.
|
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:
|
||||||
|
@ -679,7 +679,7 @@ of a given capability bitset:
|
||||||
| | | considered an "advanced user option." A frontend typically |
|
| | | considered an "advanced user option." A frontend typically |
|
||||||
| | | displays such options in a less conspicuous way than regular options |
|
| | | displays such options in a less conspicuous way than regular options |
|
||||||
| | | (e.g., a command line interface may list such options last or a |
|
| | | (e.g., a command line interface may list such options last or a |
|
||||||
| | | graphical interface may make them available in a seperate "advanced |
|
| | | graphical interface may make them available in a separate "advanced |
|
||||||
| | | settings" dialog). |
|
| | | settings" dialog). |
|
||||||
+---------------------------------+------+---------------------------------------------------------------------------+
|
+---------------------------------+------+---------------------------------------------------------------------------+
|
||||||
|
|
||||||
|
@ -791,7 +791,7 @@ fail automatically and the user may be prevented from accessing
|
||||||
protected resources. Backends are encouraged to implement means of
|
protected resources. Backends are encouraged to implement means of
|
||||||
authentication that do not require user assistance. E.g., on a
|
authentication that do not require user assistance. E.g., on a
|
||||||
multi-user system that authenticates users through a login process a
|
multi-user system that authenticates users through a login process a
|
||||||
backend could automatically lookup the apporpriate password based on
|
backend could automatically lookup the appropriate password based on
|
||||||
resource- and user-name.
|
resource- and user-name.
|
||||||
|
|
||||||
.. index:: SANE_Authorization_Callback, domain, username, password
|
.. index:: SANE_Authorization_Callback, domain, username, password
|
||||||
|
@ -895,10 +895,10 @@ This function may fail with one of the following status codes.
|
||||||
The device name is not valid.
|
The device name is not valid.
|
||||||
|
|
||||||
:macro:`SANE_STATUS_IO_ERROR`:
|
:macro:`SANE_STATUS_IO_ERROR`:
|
||||||
An error occured while communicating with the device.
|
An error occurred while communicating with the device.
|
||||||
|
|
||||||
:macro:`SANE_STATUS_NO_MEM`:
|
:macro:`SANE_STATUS_NO_MEM`:
|
||||||
An insufficent amount of memory is available.
|
An insufficient amount of memory is available.
|
||||||
|
|
||||||
:macro:`SANE_STATUS_ACCESS_DENIED`:
|
:macro:`SANE_STATUS_ACCESS_DENIED`:
|
||||||
Access to the device has been denied due to insufficient or
|
Access to the device has been denied due to insufficient or
|
||||||
|
@ -1049,10 +1049,10 @@ This function may fail with one of the following status codes.
|
||||||
The option value is not valid.
|
The option value is not valid.
|
||||||
|
|
||||||
:macro:`SANE_STATUS_IO_ERROR`:
|
:macro:`SANE_STATUS_IO_ERROR`:
|
||||||
An error occured while communicating with the device.
|
An error occurred while communicating with the device.
|
||||||
|
|
||||||
:macro:`SANE_STATUS_NO_MEM`:
|
:macro:`SANE_STATUS_NO_MEM`:
|
||||||
An insufficent amount of memory is available.
|
An insufficient amount of memory is available.
|
||||||
|
|
||||||
:macro:`SANE_STATUS_ACCESS_DENIED`:
|
:macro:`SANE_STATUS_ACCESS_DENIED`:
|
||||||
Access to the option has been denied due to insufficient or
|
Access to the option has been denied due to insufficient or
|
||||||
|
@ -1172,7 +1172,7 @@ able to properly cope with such “padded” image formats.
|
||||||
:func:`sane_start`
|
:func:`sane_start`
|
||||||
~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
This function initiates aquisition of an image from the device
|
This function initiates acquisition of an image from the device
|
||||||
represented by handle :data:`h`.
|
represented by handle :data:`h`.
|
||||||
|
|
||||||
::
|
::
|
||||||
|
@ -1201,7 +1201,7 @@ This function may fail with one of the following status codes.
|
||||||
An error occurred while communicating with the device.
|
An error occurred while communicating with the device.
|
||||||
|
|
||||||
:macro:`SANE_STATUS_NO_MEM`:
|
:macro:`SANE_STATUS_NO_MEM`:
|
||||||
An insufficent amount of memory is available.
|
An insufficient amount of memory is available.
|
||||||
|
|
||||||
:macro:`SANE_STATUS_INVAL`:
|
:macro:`SANE_STATUS_INVAL`:
|
||||||
The scan cannot be started with the current set of options. The
|
The scan cannot be started with the current set of options. The
|
||||||
|
@ -1267,7 +1267,7 @@ This function may fail with one of the following status codes.
|
||||||
An error occurred while communicating with the device.
|
An error occurred while communicating with the device.
|
||||||
|
|
||||||
:macro:`SANE_STATUS_NO_MEM`:
|
:macro:`SANE_STATUS_NO_MEM`:
|
||||||
An insufficent amount of memory is available.
|
An insufficient amount of memory is available.
|
||||||
|
|
||||||
:macro:`SANE_STATUS_ACCESS_DENIED`:
|
:macro:`SANE_STATUS_ACCESS_DENIED`:
|
||||||
Access to the device has been denied due to insufficient or
|
Access to the device has been denied due to insufficient or
|
||||||
|
@ -1290,7 +1290,7 @@ This function can be called at any time (as long as handle
|
||||||
:data:`h` is a valid handle) but usually affects
|
:data:`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 operaton does
|
handler). It is important to note that completion of this operation does
|
||||||
*not* imply that the currently pending operation has been cancelled. It
|
*not* imply that the currently pending operation has been cancelled. It
|
||||||
only guarantees that cancellation has been *initiated*. Cancellation
|
only guarantees that cancellation has been *initiated*. Cancellation
|
||||||
completes only when the cancelled call returns (typically with a status
|
completes only when the cancelled call returns (typically with a status
|
||||||
|
@ -1536,7 +1536,7 @@ implement it in a manner consistent with the above definition.
|
||||||
Preview Mode Option
|
Preview Mode Option
|
||||||
~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
The boolean option ``preview`` is used by a frontend to
|
The Boolean option ``preview`` is used by a frontend to
|
||||||
inform the backend when image acquisition should be optimized for speed,
|
inform the backend when image acquisition should be optimized for speed,
|
||||||
rather than quality (“preview mode”). When set to
|
rather than quality (“preview mode”). When set to
|
||||||
:macro:`SANE_TRUE`, preview mode is in effect, when set to
|
:macro:`SANE_TRUE`, preview mode is in effect, when set to
|
||||||
|
@ -1567,7 +1567,7 @@ as seen by the sensor (which typically is a mirror image of the scan
|
||||||
surface seen by the user). For this reason, the top-left corner is the
|
surface seen by the user). For this reason, the top-left corner is the
|
||||||
corner for which the abscissa and ordinate values are simultaneously the
|
corner for which the abscissa and ordinate values are simultaneously the
|
||||||
*smallest* and the bottom-right corner is the corner for which the
|
*smallest* and the bottom-right corner is the corner for which the
|
||||||
abscissa and ordinate values are simulatenously the *largest*. If this
|
abscissa and ordinate values are simultaneously the *largest*. If this
|
||||||
coordinate system is not natural for a given device, it is the job of
|
coordinate system is not natural for a given device, it is the job of
|
||||||
the backend to perform the necessary conversions.
|
the backend to perform the necessary conversions.
|
||||||
|
|
||||||
|
|
|
@ -84,7 +84,7 @@ platform dependent. Several possibilities exist:
|
||||||
:scale: 100%
|
:scale: 100%
|
||||||
:align: center
|
:align: center
|
||||||
|
|
||||||
Example SANE Hiearchy
|
Example SANE Hierarchy
|
||||||
|
|
||||||
The above discussion lists just a few ways for frontends to attach to a
|
The above discussion lists just a few ways for frontends to attach to a
|
||||||
backend. It is of course possible to combine these solutions to provide
|
backend. It is of course possible to combine these solutions to provide
|
||||||
|
|
4
net.rst
4
net.rst
|
@ -71,7 +71,7 @@ The four primitive types of the SANE standard are encoded as follows:
|
||||||
|
|
||||||
:type:`SANE_Byte`
|
:type:`SANE_Byte`
|
||||||
A byte is encoded as an 8 bit value. Since the transport protocol is
|
A byte is encoded as an 8 bit value. Since the transport protocol is
|
||||||
assumed to be byte-orientd, the bit order is irrelevant.
|
assumed to be byte-oriented, the bit order is irrelevant.
|
||||||
|
|
||||||
.. index:: SANE_Word
|
.. index:: SANE_Word
|
||||||
|
|
||||||
|
@ -380,7 +380,7 @@ 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
|
||||||
writeable area that is at least :data:`value_size` bytes
|
writable area that is at least :data:`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
|
||||||
|
|
|
@ -25,7 +25,7 @@ application on any platform to interoperate with any SANE backend for
|
||||||
that platform.
|
that platform.
|
||||||
|
|
||||||
The remainder of this document is organized as follows.
|
The remainder of this document is organized as follows.
|
||||||
Chapter :numref:`chap:intro` provides introductional material.
|
Chapter :numref:`chap:intro` provides introductory material.
|
||||||
Chapter :numref:`chap:environ` presents the environment SANE is
|
Chapter :numref:`chap:environ` presents the environment SANE is
|
||||||
designed for. Chapter :numref:`chap:api` details the SANE
|
designed for. Chapter :numref:`chap:api` details the SANE
|
||||||
Application Programmer Interface. Chapter :numref:`chap:net`
|
Application Programmer Interface. Chapter :numref:`chap:net`
|
||||||
|
|
|
@ -0,0 +1,19 @@
|
||||||
|
backend
|
||||||
|
backends
|
||||||
|
bitset
|
||||||
|
cancelled
|
||||||
|
endian
|
||||||
|
frontend
|
||||||
|
frontends
|
||||||
|
interoperate
|
||||||
|
lossy
|
||||||
|
luminance
|
||||||
|
prepends
|
||||||
|
preprocessor
|
||||||
|
priori
|
||||||
|
quantize
|
||||||
|
quantized
|
||||||
|
reimplementing
|
||||||
|
runtime
|
||||||
|
scalability
|
||||||
|
setuid
|
Ładowanie…
Reference in New Issue