From f00209535aa1bf17588f60052c795ca5fbcdd701 Mon Sep 17 00:00:00 2001 From: Olaf Meeuwissen Date: Fri, 18 Oct 2019 19:29:36 +0900 Subject: [PATCH] Convert :raw-latex: markers to Sphinx reStructuredText First pass. This converts everything except LaTeX formatting/layout commands, tables, figures and chapter/section cross-references. --- conf.py | 4 + net.rst | 238 ++++++++------- sane.rst | 867 +++++++++++++++++++++++++++++-------------------------- 3 files changed, 597 insertions(+), 512 deletions(-) diff --git a/conf.py b/conf.py index 542ed69..fc32200 100644 --- a/conf.py +++ b/conf.py @@ -44,8 +44,12 @@ exclude_patterns = ['_build', '.git', 'public', 'Thumbs.db', '.DS_Store'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] +primary_domain = 'c' + today_fmt = '%Y-%m-%d' +highlight_language = 'c' + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/net.rst b/net.rst index bcd2082..8ebff44 100644 --- a/net.rst +++ b/net.rst @@ -65,25 +65,35 @@ Primitive Data Types The four primitive types of the SANE standard are encoded as follows: -:raw-latex:`\code{\defn{SANE_Byte}}`: +.. index:: SANE_Byte + +:type:`SANE_Byte` A byte is encoded as an 8 bit value. Since the transport protocol is assumed to be byte-orientd, the bit order is irrelevant. -:raw-latex:`\code{\defn{SANE_Word}}`: +.. index:: SANE_Word + +:type:`SANE_Word` A word is encoded as 4 bytes (32 bits). The bytes are ordered from most-significant to least-significant byte (big-endian byte-order). -:raw-latex:`\code{\defn{SANE_Char}}`: +.. index:: SANE_Char + +:type:`SANE_Char` A character is currently encoded as an 8-bit ISO LATIN-1 value. An extension to support wider character sets (16 or 32 bits) is planned for the future, but not supported at this point. -:raw-latex:`\code{\defn{SANE_String}}`: - A string pointer is encoded as a :raw-latex:`\code{SANE_Char}` - array. The trailing NUL byte is considered part of the array and a - :raw-latex:`\code{NULL}` pointer is encoded as a zero-length array. +.. index:: SANE_String -:raw-latex:`\code{\defn{SANE_Handle}}`: +:type:`SANE_String` + A string pointer is encoded as a :type:`SANE_Char` + array. The trailing NUL byte is considered part of the array and a + :macro:`NULL` pointer is encoded as a zero-length array. + +.. index:: SANE_Handle + +:type:`SANE_Handle` A handle is encoded like a word. The network backend needs to take care of converting these integer values to the opaque pointer values that are presented to the user of the network backend. Similarly, @@ -91,7 +101,9 @@ The four primitive types of the SANE standard are encoded as follows: values it receives from its backends into 32-bit integers suitable for use for network encoding. -*:raw-latex:`\defn{enumeration types}`*: +.. index:: enumeration types + +*enumeration types* Enumeration types are encoded like words. Type Constructors @@ -100,23 +112,31 @@ Type Constructors Closely following the type constructors of the C language, the SANE network protocol supports the following four constructors: -*:raw-latex:`\defn{pointer}`*: +.. index:: pointer + +*pointer* A pointer is encoded by a word that indicates whether the pointer is a NULL-pointer which is then followed by the value that the pointer points to (in the case of a non-NULL pointer; in the case of a NULL pointer, no bytes are encoded for the pointer value). -*:raw-latex:`\defn{array}`*: +.. index:: array + +*array* An array is encoded by a word that indicates the length of the array followed by the values of the elements in the array. The length may be zero in which case no bytes are encoded for the element values. -*:raw-latex:`\defn{structure}`*: +.. index:: structure + +*structure* A structure is encoded by simply encoding the structure members in the order in which they appear in the corresponding C type declaration. -*:raw-latex:`\defn{union}`*: +.. index:: union + +*union* A union must always be accompanied by a tag value that indicates which of the union members is the currently the active one. For this reason, the union itself is encoded simply by encoding the value of @@ -137,8 +157,10 @@ The SANE network protocol is a client/server-style remote procedure call side (the network backend)—a server is restricted to answering request by the client. -:raw-latex:`\code{\defn{SANE_NET_INIT}}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: SANE_NET_INIT + +:data:`SANE_NET_INIT` +~~~~~~~~~~~~~~~~~~~~~ This RPC establishes a connection to a particular SANE network daemon. It must be the first call in a SANE network session. The parameter and @@ -152,7 +174,7 @@ reply arguments for this call are shown in the table below: | :raw-latex:`\code{SANE_String user_name}` | :raw-latex:`\code{SANE_Word version_code}` | +----------------------------------------------+----------------------------------------------+ -The :raw-latex:`\code{version_code}` argument in the request is the SANE +The :data:`version_code` argument in the request is the SANE version-code of the network backend that is contacting the network daemon (see Section :raw-latex:`\ref{sec:saneversioncode}`). The “build-revision” in the version code is used to hold the network @@ -160,24 +182,26 @@ 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 :raw-latex:`\code{user_name}` argument is the name of the user on +The :data:`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 :raw-latex:`\code{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 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, :raw-latex:`\code{status}` indicates the completion +In the reply, :data:`status` indicates the completion status. If the value is anything other than -:raw-latex:`\code{SANE_STATUS_SUCCESS}`, the remainder of the reply has -undefined values. [1]_ The :raw-latex:`\code{version_code}` argument +:macro:`SANE_STATUS_SUCCESS`, the remainder of the reply has +undefined values. [3]_ The :data:`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. -:raw-latex:`\code{\defn{SANE_NET_GET_DEVICES}}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: SANE_NET_GET_DEVICES + +:data:`SANE_NET_GET_DEVICES` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This RPC is used to obtain the list of devices accessible by the SANE daemon. @@ -192,15 +216,17 @@ daemon. There are no arguments in the request for this call. -In the reply, :raw-latex:`\code{status}` indicates the completion +In the reply, :data:`status` indicates the completion status. If the value is anything other than -:raw-latex:`\code{SANE_STATUS_SUCCESS}`, the remainder of the reply has -undefined values. The :raw-latex:`\code{device_list}` argument is a -pointer to a :raw-latex:`\code{NULL}`-terminated array of -:raw-latex:`\code{SANE_Device}` pointers. +:macro:`SANE_STATUS_SUCCESS`, the remainder of the reply has +undefined values. The :data:`device_list` argument is a +pointer to a :macro:`NULL`-terminated array of +:type:`SANE_Device` pointers. -:raw-latex:`\code{\defn{SANE_NET_OPEN}}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: SANE_NET_OPEN + +:data:`SANE_NET_OPEN` +~~~~~~~~~~~~~~~~~~~~~ This RPC is used to open a connection to a remote SANE device. @@ -214,22 +240,24 @@ This RPC is used to open a connection to a remote SANE device. | | :raw-latex:`\code{SANE_String resource}` | +-----------------------------------------------+--------------------------------------------+ -The :raw-latex:`\code{device_name}` argument specifies the name of the +The :data:`device_name` argument specifies the name of the device to open. -In the reply, :raw-latex:`\code{status}` indicates the completion +In the reply, :data:`status` indicates the completion status. If the value is anything other than -:raw-latex:`\code{SANE_STATUS_SUCCESS}`, the remainder of the reply has -undefined values. The :raw-latex:`\code{handle}` argument specifies the +:macro:`SANE_STATUS_SUCCESS`, the remainder of the reply has +undefined values. The :data:`handle` argument specifies the device handle that uniquely identifies the connection. The -:raw-latex:`\code{resource}` argument is used to request authentication. -If it has a non-:raw-latex:`\code{NULL}` value, the network backend +:data:`resource` argument is used to request authentication. +If it has a non-:macro:`NULL` value, the network backend should authenticate the specified resource and then retry this operation (see Section :raw-latex:`\ref{sec:authorization}` for details on how to authorize a resource). -:raw-latex:`\code{\defn{SANE_NET_CLOSE}}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: SANE_NET_CLOSE + +:data:`SANE_NET_CLOSE` +~~~~~~~~~~~~~~~~~~~~~~ This RPC is used to close a connection to a remote SANE device. @@ -239,15 +267,17 @@ This RPC is used to close a connection to a remote SANE device. | :raw-latex:`\code{SANE_Word handle}` | :raw-latex:`\code{SANE_Word dummy}` | +----------------------------------------+---------------------------------------+ -The :raw-latex:`\code{handle}` argument identifies the connection that +The :data:`handle` argument identifies the connection that should be closed. -In the reply, the :raw-latex:`\code{dummy}` argument is unused. Its +In the reply, the :data:`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). -:raw-latex:`\code{\defn{SANE_NET_GET_OPTION_DESCRIPTORS}}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: SANE_NET_GET_OPTION_DESCRIPTORS + +:data:`SANE_NET_GET_OPTION_DESCRIPTORS` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This RPC is used to obtain *all* the option descriptors for a remote SANE device. @@ -258,15 +288,15 @@ SANE device. | :raw-latex:`\code{SANE_Word handle}` | :raw-latex:`\code{Option_Descriptor_Array odesc}` | +----------------------------------------+-----------------------------------------------------+ -The :raw-latex:`\code{handle}` argument identifies the remote device +The :data:`handle` argument identifies the remote device whose option descriptors should be obtained. -In the reply, the :raw-latex:`\code{odesc}` argument is used to return +.. index:: Option_Descriptor_Array + +In the reply, the :data:`odesc` argument is used to return the array of option descriptors. The option descriptor array has the following structure: - :raw-latex:`\index{Option_Descriptor_Array}` - :: struct Option_Descriptor_Array @@ -275,8 +305,10 @@ following structure: SANE_Option_Descriptor **desc; }; -:raw-latex:`\code{\defn{SANE_NET_CONTROL_OPTION}}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: SANE_NET_CONTROL_OPTION + +:data:`SANE_NET_CONTROL_OPTION` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This RPC is used to control (inquire, set, or set to automatic) a specific option of a remote SANE device. @@ -297,47 +329,49 @@ specific option of a remote SANE device. | :raw-latex:`\code{void *value}` | :raw-latex:`\code{SANE_String *resource}` | +--------------------------------------------+---------------------------------------------+ -The :raw-latex:`\code{handle}` argument identifies the remote device -whose option should be controlled. Argument :raw-latex:`\code{option}` +The :data:`handle` argument identifies the remote device +whose option should be controlled. Argument :data:`option` is the number (index) of the option that should be controlled. Argument -:raw-latex:`\code{action}` specifies what action should be taken (get, -set, or set automatic). Argument :raw-latex:`\code{value_type}` +:data:`action` specifies what action should be taken (get, +set, or set automatic). Argument :data:`value_type` specifies the type of the option value (must be one of -:raw-latex:`\code{SANE_TYPE_BOOL}`, :raw-latex:`\code{SANE_TYPE_INT}`, -:raw-latex:`\code{SANE_TYPE_FIXED}`, -:raw-latex:`\code{SANE_TYPE_STRING}`, -:raw-latex:`\code{SANE_TYPE_BUTTON}`). Argument -:raw-latex:`\code{value_size}` specifies the size of the option value in +:macro:`SANE_TYPE_BOOL`, :macro:`SANE_TYPE_INT`, +:macro:`SANE_TYPE_FIXED`, +:macro:`SANE_TYPE_STRING`, +:macro:`SANE_TYPE_BUTTON`). Argument +:data:`value_size` specifies the size of the option value in number of bytes (see Section :raw-latex:`\ref{sec:valuesize}` for the precise meaning of this value). Finally, argument -:raw-latex:`\code{value}` is a pointer to the option value. It must be a -writeable area that is at least :raw-latex:`\code{value_size}` bytes +:data:`value` is a pointer to the option value. It must be a +writeable area that is at least :data:`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 :raw-latex:`\code{resource}` is set to the name +In the reply, argument :data:`resource` is set to the name of the resource that must be authorized before this call can be retried. -If this value is non-:raw-latex:`\code{NULL}`, all other arguments have +If this value is non-:macro:`NULL`, all other arguments have undefined values (see Section :raw-latex:`\ref{sec:authorization}` for details on how to authorize a resource). Argument -:raw-latex:`\code{status}` indicates the completion status. If the value -is anything other than :raw-latex:`\code{SANE_STATUS_SUCCESS}`, the +:data:`status` indicates the completion status. If the value +is anything other than :macro:`SANE_STATUS_SUCCESS`, the remainder of the reply has undefined values. The -:raw-latex:`\code{info}` argument returns the information on how well +:data:`info` argument returns the information on how well the backend was able to satisfy the request. For details, see the description of the corresponding argument in Section :raw-latex:`\ref{sec:control}`. Arguments -:raw-latex:`\code{value_type}` and :raw-latex:`\code{value_size}` have +:data:`value_type` and :data:`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 :raw-latex:`\code{value}` is holds the value of +independently). Argument :data:`value` is holds the value of the option that has become effective as a result of this RPC. -:raw-latex:`\code{\defn{SANE_NET_GET_PARAMETERS}}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: SANE_NET_GET_PARAMETERS + +:data:`SANE_NET_GET_PARAMETERS` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This RPC is used to obtain the scan parameters of a remote SANE device. @@ -349,17 +383,19 @@ This RPC is used to obtain the scan parameters of a remote SANE device. | | :raw-latex:`\code{SANE_Parameters params}` | +----------------------------------------+----------------------------------------------+ -The :raw-latex:`\code{handle}` argument identifies the connection to the +The :data:`handle` argument identifies the connection to the remote device whose scan parameters should be returned. -In the reply, :raw-latex:`\code{status}` indicates the completion +In the reply, :data:`status` indicates the completion status. If the value is anything other than -:raw-latex:`\code{SANE_STATUS_SUCCESS}`, the remainder of the reply has -undefined values. The argument :raw-latex:`\code{params}` is used to +:macro:`SANE_STATUS_SUCCESS`, the remainder of the reply +has undefined values. The argument :data:`params` is used to return the scan parameters. -:raw-latex:`\code{\defn{SANE_NET_START}}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: SANE_NET_START + +:data:`SANE_NET_START` +~~~~~~~~~~~~~~~~~~~~~~ This RPC is used to start image acquisition (scanning). @@ -375,18 +411,18 @@ This RPC is used to start image acquisition (scanning). | | :raw-latex:`\code{SANE_String resource}` | +----------------------------------------+--------------------------------------------+ -The :raw-latex:`\code{handle}` argument identifies the connection to the +The :data:`handle` argument identifies the connection to the remote device from which the image should be acquired. -In the reply, argument :raw-latex:`\code{resource}` is set to the name +In the reply, argument :data:`resource` is set to the name of the resource that must be authorized before this call can be retried. -If this value is non-:raw-latex:`\code{NULL}`, all other arguments have +If this value is non-:macro:`NULL`, all other arguments have undefined values (see Section :raw-latex:`\ref{sec:authorization}` for details on how to authorize a resource). Argument, -:raw-latex:`\code{status}` indicates the completion status. If the value -is anything other than :raw-latex:`\code{SANE_STATUS_SUCCESS}`, the +:data:`status` indicates the completion status. If the value +is anything other than :macro:`SANE_STATUS_SUCCESS`, the remainder of the reply has undefined values. The argument -:raw-latex:`\code{port}` returns the port number from which the image +:data:`port` returns the port number from which the image data will be available. To read the image data, a network client must connect to the remote host at the indicated port number. Through this port, the image data is transmitted as a sequence of data records. Each @@ -395,14 +431,14 @@ transmitted as a sequence of four bytes. These bytes should be interpreted as an unsigned integer in big-endian format. The four length bytes are followed by the number of data bytes indicated by the length. Except for byte-order, the data is in the same format as defined for -:raw-latex:`\code{sane_read()}`. Since some records may contain no data +:func:`sane_read()`. Since some records may contain no data at all, a length value of zero is perfectly valid. The special length -value of :raw-latex:`\code{0xffffffff}` is used to indicate the end of +value of ``0xffffffff`` is used to indicate the end of the data stream. That is, after receiving a record length of -:raw-latex:`\code{0xffffffff}`, the network client should close the data +``0xffffffff``, the network client should close the data connection and stop reading data. -Argument :raw-latex:`\code{byte_order}` specifies the byte-order of the +Argument :data:`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 @@ -413,8 +449,10 @@ and client byte-order match and puts the extra burden on the client side when there is a byte-order mismatch. Putting the burden on the client-side improves the scalability properties of this protocol. -:raw-latex:`\code{\defn{SANE_NET_CANCEL}}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: SANE_NET_CANCEL + +:data:`SANE_NET_CANCEL` +~~~~~~~~~~~~~~~~~~~~~~~ This RPC is used to cancel the current operation of a remote SANE device. @@ -425,17 +463,17 @@ device. | :raw-latex:`\code{SANE_Word handle}` | :raw-latex:`\code{SANE_Word dummy}` | +----------------------------------------+---------------------------------------+ -The :raw-latex:`\code{handle}` argument identifies the connection whose +The :data:`handle` argument identifies the connection whose operation should be cancelled. -In the reply, the :raw-latex:`\code{dummy}` argument is unused. Its +In the reply, the :data:`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). -:raw-latex:`\code{\defn{SANE_NET_AUTHORIZE}}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: SANE_NET_AUTHORIZE, network authorization -:raw-latex:`\index{network authorization}` +:data:`SANE_NET_AUTHORIZE` +~~~~~~~~~~~~~~~~~~~~~~~~~~ This RPC is used to pass authorization data from the net client to the net server. @@ -450,26 +488,28 @@ net server. | :raw-latex:`\code{SANE_String password}` | | +--------------------------------------------+---------------------------------------+ -The :raw-latex:`\code{resource}` argument specifies the name of the +The :data:`resource` argument specifies the name of the resource to be authorized. This argument should be set to the string -returned in the :raw-latex:`\code{resource}` argument of the RPC reply -that required this authorization call. The :raw-latex:`\code{username}` -and :raw-latex:`\code{password}` are the name of the user that is +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 accessing the resource and the password for the specified resource/user pair. [2]_ -In the reply, :raw-latex:`\code{dummy}` is completely unused. Note that +In the reply, :data:`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). -:raw-latex:`\code{\defn{SANE_NET_EXIT}}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: SANE_NET_EXIT + +:data:`SANE_NET_EXIT` +~~~~~~~~~~~~~~~~~~~~~ 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 :raw-latex:`\code{SANE_NET_INIT}` call will be closed. +the :data:`SANE_NET_INIT` call will be closed. .. [2] The sane network daemon should be careful not to leak information in diff --git a/sane.rst b/sane.rst index e450f65..9ff8eef 100644 --- a/sane.rst +++ b/sane.rst @@ -96,7 +96,7 @@ give a user access to all controls without having to understand each and every device control. The design principle used here is to abstract each device control into a SANE *option*. An option is a self-describing name/value pair. For example, the brightness control of a camera might -be represented by an option called :raw-latex:`\code{brightness}` whose +be represented by an option called ``brightness`` whose value is an integer in the range from 0 to 255. With self-describing options, a backend need not be concerned with @@ -122,19 +122,19 @@ platform dependent. Several possibilities exist: simultaneously by implementing a meta backend that manages several backends that have been compiled in such a manner that they export unique function names. For example, a backend called - :raw-latex:`\code{be}` would normally export a function called - :raw-latex:`\code{sane_read()}`. If each backend would provide such a + ``be`` would normally export a function called + :func:`sane_read()`. If each backend would provide such a function, static linking would fail due to multiple conflicting definitions of the same symbol. This can be resolved by having - backend :raw-latex:`\code{be}` include a header file that has lines + backend ``be`` include a header file that has lines of the form: :: #define sane_read be_sane_read - With definitions of this kind, backend :raw-latex:`\code{be}` will - export function name :raw-latex:`\code{be_sane_read()}`. Thus, all + With definitions of this kind, backend ``be`` will + export function name ``be_sane_read()``. Thus, all backends will export unique names. As long as a meta backend knows about these names, it is possible to combine several backends at link time and select and use them dynamically at runtime. @@ -144,7 +144,7 @@ platform dependent. Several possibilities exist: support it. In this case, a frontend is linked against a shared library that implements any SANE backend. Since each dynamically linked backend exports the same set of global symbols (all starting - with the prefix :raw-latex:`\code{sane_}`), the dynamic library that + with the prefix ``sane_``), the dynamic library that gets loaded at runtime does not necessarily have to be the same one as one the frontend got linked against. In other words, it is possible to switch the backend by installing the appropriate backend @@ -168,18 +168,18 @@ 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 an entire hierarchy of SANE backends. Such a hierarchy is depicted in Figure :raw-latex:`\ref{fig:hierarchy}`. The figure shows that machine A -uses a dynamic-linking based meta backend called :raw-latex:`\code{dll}` -to access the backends called :raw-latex:`\code{pnm}`, -:raw-latex:`\code{mustek}`, and :raw-latex:`\code{net}`. The first two +uses a dynamic-linking based meta backend called ``dll`` +to access the backends called ``pnm``, +``mustek``, and ``net``. The first two are real backends, whereas the last one is a meta backend that provides network transparent access to remote scanners. In the figure, machine B provides non-local access to its scanners through the SANE frontend -called :raw-latex:`\code{saned}`. The :raw-latex:`\code{saned}` in turn -has access to the :raw-latex:`\code{hp}` and :raw-latex:`\code{autolum}` -backends through another instance of the :raw-latex:`\code{dll}` -backend. The :raw-latex:`\code{autolum}` meta backend is used to +called ``saned``. The ``saned`` in turn +has access to the ``hp`` and ``autolum`` +backends through another instance of the ``dll`` +backend. The ``autolum`` meta backend is used to automatically adjust the luminance (brightness) of the image data -acquired by the camera backend called :raw-latex:`\code{qcam}`. +acquired by the camera backend called ``qcam``. Note that a meta backend really is both a frontend and a backend at the same time. It is a frontend from the viewpoint of the backends that it @@ -188,11 +188,11 @@ it. The name “meta backend” was chosen primarily because the SANE standard describes the interface from the viewpoint of a (real) frontend. +.. index:: image data format + Image Data Format ----------------- -:raw-latex:`\index{image data format}` - Arguably the most important aspect of an image acquisition system is how images are represented. The SANE approach is to define a simple yet powerful representation that is sufficient for vast majority of @@ -265,40 +265,40 @@ what part of the image a frame represents (and how many frames it should expect). For that purpose, the SANE API tags every frame with a type. This version of the SANE standard supports the following frame types: - :raw-latex:`\code{\defn{SANE_FRAME_GRAY}}`: - The frame contains a single channel of data that represents - sample values from a spectral band that covers the human visual - range. The image consists of this frame only. + :macro:`SANE_FRAME_GRAY`: + The frame contains a single channel of data that represents + sample values from a spectral band that covers the human visual + range. The image consists of this frame only. - :raw-latex:`\code{\defn{SANE_FRAME_RGB}}`: - The frame contains three channels of data that represent sample - values from the red, green, and blue spectral bands. The sample - values are interleaved in the order red, green, and blue. The - image consists of this frame only. + :macro:`SANE_FRAME_RGB`: + The frame contains three channels of data that represent sample + values from the red, green, and blue spectral bands. The sample + values are interleaved in the order red, green, and blue. The + image consists of this frame only. - :raw-latex:`\code{\defn{SANE_FRAME_RED}}`: - The frame contains one channel of data that represents sample - values from the red spectral band. The complete image consists - of three frames: :raw-latex:`\code{SANE_FRAME_RED}`, - :raw-latex:`\code{SANE_FRAME_GREEN}`, and - :raw-latex:`\code{SANE_FRAME_BLUE}`. The order in which the - frames are transmitted chosen by the backend. + :macro:`SANE_FRAME_RED`: + The frame contains one channel of data that represents sample + values from the red spectral band. The complete image consists + of three frames: :macro:`SANE_FRAME_RED`, + :macro:`SANE_FRAME_GREEN`, and + :macro:`SANE_FRAME_BLUE`. The order in which the + frames are transmitted chosen by the backend. - :raw-latex:`\code{\defn{SANE_FRAME_GREEN}}`: - The frame contains one channel of data that represents sample - values from the green spectral band. The complete image consists - of three frames: :raw-latex:`\code{SANE_FRAME_RED}`, - :raw-latex:`\code{SANE_FRAME_GREEN}`, and - :raw-latex:`\code{SANE_FRAME_BLUE}`. The order in which the - frames are transmitted chosen by the backend. + :macro:`SANE_FRAME_GREEN`: + The frame contains one channel of data that represents sample + values from the green spectral band. The complete image consists + of three frames: :macro:`SANE_FRAME_RED`, + :macro:`SANE_FRAME_GREEN`, and + :macro:`SANE_FRAME_BLUE`. The order in which the + frames are transmitted chosen by the backend. - :raw-latex:`\code{\defn{SANE_FRAME_BLUE}}`: - The frame contains one channel of data that represents sample - values from the blue spectral band. The complete image consists - of three frames: :raw-latex:`\code{SANE_FRAME_RED}`, - :raw-latex:`\code{SANE_FRAME_GREEN}`, and - :raw-latex:`\code{SANE_FRAME_BLUE}`. The order in which the - frames are transmitted chosen by the backend. + :macro:`SANE_FRAME_BLUE`: + The frame contains one channel of data that represents sample + values from the blue spectral band. The complete image consists + of three frames: :macro:`SANE_FRAME_RED`, + :macro:`SANE_FRAME_GREEN`, and + :macro:`SANE_FRAME_BLUE`. The order in which the + frames are transmitted chosen by the backend. The SANE Application Programmer Interface (API) =============================================== @@ -308,7 +308,7 @@ programmer interface (API). Any SANE frontend must depend on the interface defined in this section only. Converseley, any SANE backend must implement its functionality in accordance with this specification. The interface as documented here is declared as a C callable interface -in a file called :raw-latex:`\filename{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: :: @@ -340,17 +340,19 @@ is increased with each build of a backend. The SANE API provides the following five macros to manage version numbers. - :raw-latex:`\code{\defn{SANE_CURRENT_MAJOR}}`: + .. macro:: SANE_CURRENT_MAJOR + The value of this macro is the number of the SANE standard that the interface implements. - :raw-latex:`\code{\defn{SANE_VERSION_CODE}(\var{maj},\var{min},\var{bld})}`: + .. function:: SANE_VERSION_CODE(maj, min, bld) + :raw-latex:`\label{sec:saneversioncode}` This macro can be used to build a monotonically increasing version code. A SANE version code consists of the SANE standard major version number - (:raw-latex:`\var{maj}`), the minor version number - :raw-latex:`\var{min}`, and the build revision of a backend - (:raw-latex:`\var{bld}`). The major and minor version numbers + (:data:`maj`), the minor version number + :data:`min`, and the build revision of a backend + (:data:`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. @@ -364,35 +366,42 @@ numbers. build revision are used for informational and bug-fixing purposes only. - :raw-latex:`\code{\defn{SANE_VERSION_MAJOR}(\var{vc})}`: + .. function:: SANE_VERSION_MAJOR(vc) + This macro returns the major version number component of the - version code passed in argument :raw-latex:`\var{vc}`. + version code passed in argument :data:`vc`. + + .. function:: SANE_VERSION_MINOR(vc) - :raw-latex:`\code{SANE_VERSION_MINOR(\var{vc})}`: This macro returns the minor version number component of the - version code passed in argument :raw-latex:`\var{vc}`. + version code passed in argument :data:`vc`. + + .. function:: SANE_VERSION_BUILD(vc) - :raw-latex:`\code{SANE_VERSION_BUILD(\var{vc})}`: This macro returns the build revision component of the version - code passed in argument :raw-latex:`\var{vc}`. + code passed in argument :data:`vc`. Data Types ---------- +.. index:: SANE_Byte, SANE_Word + Base Types ~~~~~~~~~~ The SANE standard is based on just two SANE-specific base types: the SANE byte and word. - | :raw-latex:`\code{typedef \var{some-scalar-type\/} \defn{SANE_Byte};}` - | :raw-latex:`\code{typedef \var{some-scalar-type\/} \defn{SANE_Word};}` + :: -``SANE_Byte`` must correspond to some scalar C type that is capable of -holding values in the range 0 to 255. ``SANE_Word`` must be capable of + typedef some-scalar-type SANE_Byte; + typedef some-scalar-type SANE_Word; + +:type:`SANE_Byte` must correspond to some scalar C type that is capable of +holding values in the range 0 to 255. :type:`SANE_Word` must be capable of holding any of the following: -- the truth values ``SANE_FALSE`` and ``SANE_TRUE`` +- the truth values :macro:`SANE_FALSE` and :macro:`SANE_TRUE` - signed integers in the range :math:`-2^{31}\ldots2^{31}-1` @@ -401,18 +410,20 @@ holding any of the following: - 32 bits (for bit sets) -Note that the SANE standard does not define what C type ``SANE_Byte`` -and ``SANE_Word`` map to. For example, on some platforms, the latter may -map to ``long int`` whereas on others it may map to ``int``. A portable +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 SANE frontend or backend must therefore not depend on a particular mapping. +.. index:: SANE_Bool, SANE_FALSE, SANE_TRUE + Boolean Type ~~~~~~~~~~~~ -:raw-latex:`\code{\defn{SANE_Bool}}` is used for variables that can take -one of the two truth values :raw-latex:`\code{\defn{SANE_FALSE}}` and -:raw-latex:`\code{\defn{SANE_TRUE}}`. The former value is defined to be +:type:`SANE_Bool` is used for variables that can take +one of the two truth values :macro:`SANE_FALSE` and +:macro:`SANE_TRUE`. The former value is defined to be 0, whereas the latter is 1. [1]_ The C declarations for this type are given below. @@ -422,16 +433,18 @@ given below. #define SANE_TRUE 1 typedef SANE_Word SANE_Bool; -Note that ``SANE_Bool`` is simply an alias of ``SANE_Word``. It is +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. -However, for clarity, it is recommended to use ``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 boolean object. +.. index:: SANE_Int + Integer Type ~~~~~~~~~~~~ -:raw-latex:`\code{\defn{SANE_Int}}` is used for variables that can take +:type:`SANE_Int` is used for variables that can take integer values in the range :math:`-2^{32}` to :math:`2^{31}-1`. Its C declaration is given below. @@ -439,16 +452,18 @@ declaration is given below. typedef SANE_Word SANE_Int; -Note that ``SANE_Int`` is simply an alias of ``SANE_Word``. It is +Note that :type:`SANE_Int` is simply an alias of :type:`SANE_Word`. It is therefore always legal to use the latter type in place of the former. -However, for clarity, it is recommended to use ``SANE_Int`` whenever a +However, for clarity, it is recommended to use :type:`SANE_Int` whenever a given variable or formal argument has a fixed interpretation as an integer object. +.. index:: SANE_Fixed, SANE_FIXED_SCALE_SHIFT + Fixed-point Type ~~~~~~~~~~~~~~~~ -:raw-latex:`\code{\defn{SANE_Fixed}}` is used for variables that can +:type:`SANE_Fixed` is used for variables that can take fixed point values in the range :math:`-32768` to :math:`32767.9999` with a resolution of :math:`1/65535`. The C declarations relating to this type are given below. @@ -458,31 +473,33 @@ declarations relating to this type are given below. #define SANE_FIXED_SCALE_SHIFT 16 typedef SANE_Word SANE_Fixed; -The macro :raw-latex:`\code{\defn{SANE_FIXED_SCALE_SHIFT}}` gives the +The macro :macro:`SANE_FIXED_SCALE_SHIFT` gives the location of the fixed binary point. This standard defines that value to be 16, which yields a resolution of :math:`1/65536`. -Note that ``SANE_Fixed`` is simply an alias of ``SANE_Word``. It is +Note that :type:`SANE_Fixed` is simply an alias of :type:`SANE_Word`. It is therefore always legal to use the latter type in place of the former. -However, for clarity, it is recommended to use ``SANE_Fixed`` whenever a +However, for clarity, it is recommended to use :type:`SANE_Fixed` whenever a given variable or formal argument has a fixed interpretation as a fixed-point object. For convenience, SANE also defines two macros that convert fixed-point values to and from C double floating point values. - :raw-latex:`\code{\defn{SANE_FIX}(\var{d})}`: + .. function:: SANE_FIX(d) + Returns the largest SANE fixed-point value that is smaller than - the double value :raw-latex:`\var{d}`. No range checking is - performed. If the value of :raw-latex:`\var{d}` is out of range, + the double value :data:`d`. No range checking is + performed. If the value of :data:`d` is out of range, the result is undefined. - :raw-latex:`\code{\defn{SANE_UNFIX}(\var{w})}`: + .. function:: SANE_UNFIX(w) + Returns the nearest double machine number that corresponds to - fixed-point value :raw-latex:`\var{w}`. + fixed-point value :data:`w`. SANE does *not* require that the following two expressions hold true -(even if the values of :raw-latex:`\var{w}` and :raw-latex:`\var{d}` are +(even if the values of :data:`w` and :data:`d` are in range): :: @@ -497,35 +514,39 @@ two representations. Text ~~~~ +.. index:: SANE_Char + Character Type ^^^^^^^^^^^^^^ -Type :raw-latex:`\code{\defn{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 -underlying C ``char`` type (typically one byte). The encoding for such +underlying C :type:`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 should be taken to avoid the assumption that -``sizeof(SANE_Char)==sizeof(char)``. +:math:`\verb|sizeof|(\verb|SANE_Char|) == \verb|sizeof|(\verb|char|)`. :: typedef char SANE_Char; +.. index:: SANE_String, SANE_String_Const, NUL + String Type ^^^^^^^^^^^ -Type :raw-latex:`\code{\defn{SANE_String}}` represents a text string as -a sequence of C ``char`` values. The end of the sequence is indicated by -a ``'\0'`` (:raw-latex:`\defn{NUL}`) character. +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. :: typedef SANE_Char *SANE_String; typedef const SANE_Char *SANE_String_Const; -The type :raw-latex:`\code{\defn{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 that in ANSI C, the declaration @@ -536,11 +557,13 @@ that in ANSI C, the declaration declares a string pointer that is constant (not a string pointer that points to a constant value). +.. index:: SANE_Handle + Scanner Handle Type ~~~~~~~~~~~~~~~~~~~ Access to a scanner is provided through an opaque type called -:raw-latex:`\code{\defn{SANE_Handle}}`. The C declaration of this type +:type:`SANE_Handle`. The C declaration of this type is given below. :: @@ -548,21 +571,23 @@ is given below. typedef void *SANE_Handle; While this type is declared to be a void pointer, an application must -not attempt to interpret the value of a ``SANE_Handle``. In particular, +not attempt to interpret the value of a :type:`SANE_Handle`. In particular, SANE does not require that a value of this type is a legal pointer value. +.. index:: SANE_Status + Status Type ~~~~~~~~~~~ Most SANE operations return a value of type -:raw-latex:`\code{\defn{SANE_Status}}` to indicate whether the +:type:`SANE_Status` to indicate whether the completion status of the operation. If an operation completes -successfully, ``SANE_STATUS_GOOD`` is returned. In case of an error, a +successfully, :macro:`SANE_STATUS_GOOD` is returned. In case of an error, a value is returned that indicates the nature of the problem. The complete list of available status codes is listed in Table :raw-latex:`\ref{tab:status}`. It is recommended to use function -:raw-latex:`\code{sane_strstatus()}` to convert status codes into a +:func:`sane_strstatus()` to convert status codes into a legible string. +------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------+ @@ -595,11 +620,13 @@ legible string. Table: Status Codes +.. index:: SANE_Device + Device Descriptor Type ~~~~~~~~~~~~~~~~~~~~~~ Each SANE device is represented by a structure of type -:raw-latex:`\code{\defn{SANE_Device}}`. The C declaration of this type +:type:`SANE_Device`. The C declaration of this type is given below. :: @@ -613,9 +640,11 @@ is given below. } SANE_Device; -:raw-latex:`\index{device-name}` The structure provides the unique name -of the scanner in member :raw-latex:`\code{name}`. It is this unique -name that should be passed in a call to :raw-latex:`\code{sane_open()}`. +.. index:: device-name + +The structure provides the unique name +of the scanner in member :member:`name`. It is this unique +name that should be passed in a call to :func:`sane_open()`. The format of this name is completely up to the backend. The only constraints are that the name is unique among all devices supported by the backend and that the name is a legal SANE text string. To simplify @@ -626,8 +655,8 @@ length unique names. The remaining members in the device structure provide additional information on the device corresponding to the unique name. -Specifically, members :raw-latex:`\code{vendor}`, -:raw-latex:`\code{model}`, and :raw-latex:`\code{type}` are single-line +Specifically, members :member:`vendor`, +:member:`model`, and :member:`type` are single-line strings that give information on the vendor (manufacturer), model, and the type of the device. For consistency’s sake, the following strings should be used when appropriate (the lists will be expanded as need @@ -683,11 +712,13 @@ Table: Predefined Device Information Strings \hspace{\fill} -Note that vendor string :raw-latex:`\code{Noname}` can be used for +Note that vendor string ``Noname`` can be used for virtual devices that have no physical vendor associated. Also, there are no predefined model name strings since those are vendor specific and therefore completely under control of the respective backends. +.. index:: SANE_Option_Descriptor + Option Descriptor Type ~~~~~~~~~~~~~~~~~~~~~~ @@ -699,7 +730,7 @@ their respective option descriptor. Thus, a frontend can control a scanner abstractly, without requiring knowledge as to what the purpose of any given option is. Conversely, a scanner can describe its controls without requiring knowledge of how the frontend operates. The C -declaration of the :raw-latex:`\code{\defn{SANE_Option_Descriptor}}` +declaration of the :type:`SANE_Option_Descriptor` type is given below. :: @@ -727,19 +758,19 @@ type is given below. Option Name ^^^^^^^^^^^ -Member :raw-latex:`\code{name}` is a string that uniquely identifies the +Member :member:`name` is a string that uniquely identifies the option. The name must be unique for a given device (i.e., the option names across different backends or devices need not be unique). The option name must consist of lower-case ASCII letters -(:raw-latex:`\code{a}`–:raw-latex:`\code{z}`), digits -(:raw-latex:`\code{0}`–:raw-latex:`\code{9}`), or the dash character -(:raw-latex:`\code{-}`) only. The first character must be a lower-case +(``a``–``z``), digits +(``0``–``9``), or the dash character +(``-``) only. The first character must be a lower-case ASCII character (i.e., not a digit or a dash). Option Title ^^^^^^^^^^^^ -Member :raw-latex:`\code{title}` is a single-line string that can be +Member :member:`title` is a single-line string that can be used by the frontend as a title string. This should typically be a short (one or two-word) string that is chosen based on the function of the option. @@ -747,17 +778,19 @@ option. Option Description ^^^^^^^^^^^^^^^^^^ -Member :raw-latex:`\code{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 responsibility of the frontend to break the string into managable-length lines. Newline characters in this string should be interpreted as paragraph breaks. +.. index:: SANE_Value_Type + Option Value Type ^^^^^^^^^^^^^^^^^ -Member :raw-latex:`\code{type}` specifies the type of the option value. -The possible values for type :raw-latex:`\code{\defn{SANE_Value_Type}}` +Member :member:`type` specifies the type of the option value. +The possible values for type :type:`SANE_Value_Type` are described in Table :raw-latex:`\ref{tab:valuetype}`. :raw-latex:`\leavevmode` @@ -799,12 +832,14 @@ are described in Table :raw-latex:`\ref{tab:valuetype}`. \hline \end{tabular} +.. index:: SANE_Unit + Option Value Unit ^^^^^^^^^^^^^^^^^ -Member :raw-latex:`\code{unit}` specifies what the physical unit of the +Member :member:`unit` specifies what the physical unit of the option value is. The possible values for type -:raw-latex:`\code{\defn{SANE_Unit}}` are described in Table +:type:`SANE_Unit` are described in Table :raw-latex:`\ref{tab:units}`. Note that the specified unit is what the SANE backend expects. It is entirely up to a frontend as to how these units a presented to the user. For example, SANE expresses all lengths @@ -838,48 +873,47 @@ unit (e.g., inches or centimeters). Option Value Size ^^^^^^^^^^^^^^^^^ -Member :raw-latex:`\code{size}` specifies the size of the option value +Member :member:`size` specifies the size of the option value (in bytes). This member has a slightly different interpretation depending on the type of the option value: - :raw-latex:`\code{SANE_TYPE_STRING}`: - The size is the maximum size of the string. For the purpose of - string size calcuations, the terminating :raw-latex:`\code{NUL}` - character is considered to be part of the string. Note that the - terminating :raw-latex:`\code{NUL}` character must always be - present in string option values. + :macro:`SANE_TYPE_STRING`: + The size is the maximum size of the string. For the purpose of + string size calcuations, the terminating :data:`NUL` + character is considered to be part of the string. Note that the + terminating :data:`NUL` character must always be + present in string option values. - :raw-latex:`\code{SANE_TYPE_INT}`, - :raw-latex:`\code{SANE_TYPE_FIXED}`: - The size must be a positive integer multiple of the size of a - ``SANE_Word``. The option value is a vector of length + :macro:`SANE_TYPE_INT`, :macro:`SANE_TYPE_FIXED`: + The size must be a positive integer multiple of the size of a + :type:`SANE_Word`. The option value is a vector of length + :math:`\verb|size| / \verb|sizeof|(\verb|SANE_Word|)`. - .. math:: \code{size}/\code{sizeof(SANE_Word)}. + :macro:`SANE_TYPE_BOOL`: + The size must be set to :math:`\verb|sizeof|(\verb|SANE_Word|)`. - :raw-latex:`\code{SANE_TYPE_BOOL}`: - The size must be set to :raw-latex:`\code{sizeof(SANE_Word)}`. - - :raw-latex:`\code{SANE_TYPE_BUTTON}`, - :raw-latex:`\code{SANE_TYPE_GROUP}`: - The option size is ignored. + :macro:`SANE_TYPE_BUTTON`, :macro:`SANE_TYPE_GROUP`: + The option size is ignored. Option Capabilities ^^^^^^^^^^^^^^^^^^^ -Member :raw-latex:`\code{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 the capabilities described in Table :raw-latex:`\ref{tab:capabilities}`. The SANE API provides the following to macros to test certain features of a given capability bitset: - :raw-latex:`\code{\defn{SANE_OPTION_IS_ACTIVE}(\var{cap})}`: - This macro returns :raw-latex:`\code{SANE_TRUE}` if and only if - the option with the capability set :raw-latex:`\var{cap}` is + .. function:: SANE_OPTION_IS_ACTIVE(cap) + + This macro returns :macro:`SANE_TRUE` if and only if + the option with the capability set :data:`cap` is currently active. - :raw-latex:`\code{\defn{SANE_OPTION_IS_SETTABLE}(\var{cap})}`: - This macro returns :raw-latex:`\code{SANE_TRUE}` if and only if - the option with the capability set :raw-latex:`\var{cap}` is + .. function:: SANE_OPTION_IS_SETTABLE(cap) + + This macro returns :macro:`SANE_TRUE` if and only if + the option with the capability set :data:`cap` is software settable. :raw-latex:`\leavevmode` @@ -940,17 +974,19 @@ of a given capability bitset: \hline \end{tabular} +.. index:: SANE_Constraint_Type + Option Value Constraints ^^^^^^^^^^^^^^^^^^^^^^^^ It is often useful to constrain the values that an option can take. For example, constraints can be used by a frontend to determine how to -represent a given option. Member :raw-latex:`\code{constraint_type}` +represent a given option. Member :member:`constraint_type` indicates what constraint is in effect for the option. The constrained values that are allowed for the option are described by one of the union -members of member :raw-latex:`\code{constraint}`. The possible values of -type :raw-latex:`\code{\defn{SANE_Constraint_Type}}` and the -interpretation of the :raw-latex:`\code{constraint}` union is described +members of member :member:`constraint`. The possible values of +type :type:`SANE_Constraint_Type` and the +interpretation of the :member:`constraint` union is described in Table :raw-latex:`\ref{tab:constraints}`. :raw-latex:`\leavevmode` @@ -1017,21 +1053,21 @@ in Table :raw-latex:`\ref{tab:constraints}`. Operations ---------- -:raw-latex:`\code{sane_init}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: sane_init + +:func:`sane_init` +~~~~~~~~~~~~~~~~~ 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. The version code of the backend is returned in the -value pointed to by :raw-latex:`\code{version_code}`. If that pointer is -:raw-latex:`\code{NULL}`, no version code is returned. Argument -:raw-latex:`\code{authorize}` is either a pointer to a function that is +value pointed to by :data:`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 invoked when the backend requires authentication for a specific resource -or :raw-latex:`\code{NULL}` if the frontend does not support +or :macro:`NULL` if the frontend does not support authentication. - :raw-latex:`\index{sane_init}` - :: SANE_Status sane_init (SANE_Int * version_code, @@ -1040,9 +1076,9 @@ authentication. The authorization function may be called by a backend in response to any of the following calls: - :raw-latex:`\code{sane_open}`, - :raw-latex:`\code{sane_control_option}`, - :raw-latex:`\code{sane_start}` + - :func:`sane_open()`, + - :func:`sane_control_option()`, + - :func:`sane_start()` If a backend was initialized without authorization function, then authorization requests that cannot be handled by the backend itself will @@ -1053,10 +1089,9 @@ multi-user system that authenticates users through a login process a backend could automatically lookup the apporpriate password based on resource- and user-name. -The authentication function type has the following declaration: +.. index:: SANE_Authorization_Callback, domain, username, password - :raw-latex:`\index{SANE_Authorization_Callback}` - :raw-latex:`\index{domain}`:raw-latex:`\index{username}`:raw-latex:`\index{password}` +The authentication function type has the following declaration: :: @@ -1069,168 +1104,170 @@ The authentication function type has the following declaration: SANE_Char password[SANE_MAX_PASSWORD_LEN]); Three arguments are passed to the authorization function: -:raw-latex:`\code{resource}` is a string specifying the name of the +:data:`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 -:raw-latex:`\code{username}` and :raw-latex:`\code{password}` arguments -are (pointers to) an array of :raw-latex:`\code{SANE_MAX_USERNAME_LEN}` -and :raw-latex:`\code{SANE_MAX_PASSWORD_LEN}` characters, respectively. +:data:`username` and :data:`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 these arrays. The returned strings *must* be ASCII-NUL terminated. -:raw-latex:`\code{sane_exit}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: sane_exit + +:func:`sane_exit` +~~~~~~~~~~~~~~~~~ This function must be called to terminate use of a backend. The function will first close all device handles that still might be open (it is recommended to close device handles explicitly through a call to -:raw-latex:`\code{sane_close()}`, but backends are required to release +:func:`sane_close()`, but backends are required to release all resources upon a call to this function). After this function -returns, no function other than :raw-latex:`\code{sane_init()}` may be +returns, no function other than :func:`sane_init()` may be called (regardless of the status value returned by -:raw-latex:`\code{sane_exit()}`. Neglecting to call this function may +:func:`sane_exit()`. Neglecting to call this function may result in some resources not being released properly. - :raw-latex:`\index{sane_exit}` - :: void sane_exit (void); -:raw-latex:`\code{sane_get_devices}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: sane_get_devices + +:func:`sane_get_devices` +~~~~~~~~~~~~~~~~~~~~~~~~ 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 :raw-latex:`\code{NULL}` terminated array of pointers to -``SANE_Device`` structures in :raw-latex:`\code{*device_list}`. The +a :macro:`NULL` terminated array of pointers to +:type:`SANE_Device` structures in :data:`*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 -:raw-latex:`\code{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 -argument :raw-latex:`\code{local_only}` is true, only local devices are +argument :data:`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. - :raw-latex:`\index{sane_get_devices}` - :: SANE_Status sane_get_devices (const SANE_Device *** device_list, SANE_Bool local_only); -This function may fail with :raw-latex:`\code{SANE_STATUS_NO_MEM}` if an +This function may fail with :macro:`SANE_STATUS_NO_MEM` if an insufficient amount of memory is available. **Backend Implementation Note** SANE does not require that this function is called before a - :raw-latex:`\code{sane_open()}` call is performed. A device name may + :func:`sane_open()` call is performed. A device name may be specified explicitly by a user which would make it unnecessary and undesirable to call this function first. -:raw-latex:`\code{sane_open}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: sane_open + +:func:`sane_open` +~~~~~~~~~~~~~~~~~ This function is used to establish a connection to a particular device. The name of the device to be opened is passed in argument -:raw-latex:`\code{name}`. If the call completes successfully, a handle -for the device is returned in :raw-latex:`\code{*h}`. As a special case, +:data:`name`. If the call completes successfully, a handle +for the device is returned in :data:`*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). - :raw-latex:`\index{sane_open}` - :: SANE_Status sane_open (SANE_String_Const name, SANE_Handle * h); This function may fail with one of the following status codes. - :raw-latex:`\code{SANE_STATUS_DEVICE_BUSY}`: - The device is currently busy (in use by somebody else). + :macro:`SANE_STATUS_DEVICE_BUSY`: + The device is currently busy (in use by somebody else). - :raw-latex:`\code{SANE_STATUS_INVAL}`: - The device name is not valid. + :macro:`SANE_STATUS_INVAL`: + The device name is not valid. - :raw-latex:`\code{SANE_STATUS_IO_ERROR}`: - An error occured while communicating with the device. + :macro:`SANE_STATUS_IO_ERROR`: + An error occured while communicating with the device. - :raw-latex:`\code{SANE_STATUS_NO_MEM}`: - An insufficent amount of memory is available. + :macro:`SANE_STATUS_NO_MEM`: + An insufficent amount of memory is available. - :raw-latex:`\code{SANE_STATUS_ACCESS_DENIED}`: - Access to the device has been denied due to insufficient or - invalid authentication. + :macro:`SANE_STATUS_ACCESS_DENIED`: + Access to the device has been denied due to insufficient or + invalid authentication. -:raw-latex:`\code{sane_close}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: sane_close + +:func:`sane_close` +~~~~~~~~~~~~~~~~~~ This function terminates the association between the device handle -passed in argument :raw-latex:`\code{h}` and the device it represents. +passed in argument :data:`h` and the device it represents. If the device is presently active, a call to -:raw-latex:`\code{sane_cancel()}` is performed first. After this -function returns, handle :raw-latex:`\code{h}` must not be used anymore. - - :raw-latex:`\index{sane_close}` +:func:`sane_cancel()` is performed first. After this +function returns, handle :data:`h` must not be used anymore. :: void sane_close (SANE_Handle h); -:raw-latex:`\code{sane_get_option_descriptor}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: sane_get_option_descriptor + +:func:`sane_get_option_descriptor` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This function is used to access option descriptors. The function returns -the option descriptor for option number :raw-latex:`\code{n}` of the -device represented by handle :raw-latex:`\code{h}`. Option number 0 is +the option descriptor for option number :data:`n` of the +device represented by handle :data:`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 -:raw-latex:`\code{h}` (the count includes option 0). If :math:`n` is not -a valid option index, the function returns :raw-latex:`\code{NULL}`. The +:data:`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. - :raw-latex:`\index{sane_get_option_descriptor}` - :: const SANE_Option_Descriptor * sane_get_option_descriptor (SANE_Handle h, SANE_Int n); -:raw-latex:`\code{sane_control_option}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: sane_control_option + +:func:`sane_control_option` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ This function is used to set or inquire the current value of option -number :raw-latex:`\code{n}` of the device represented by handle -:raw-latex:`\code{h}`. The manner in which the option is controlled is -specified by parameter :raw-latex:`\code{a}`. The possible values of +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 this parameter are described in more detail below. The value of the -option is passed through argument :raw-latex:`\code{v}`. It is a pointer +option is passed through argument :data:`v`. It is a pointer to the memory that holds the option value. The memory area pointed to by -:raw-latex:`\code{v}` must be big enough to hold the entire option value -(determined by member :raw-latex:`\code{size}` in the corresponding +:data:`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 -:raw-latex:`\code{v}` may be shorter since the backend will stop reading -the option value upon encountering the first :raw-latex:`\code{NUL}` -terminator in the string. If argument :raw-latex:`\code{i}` is not -:raw-latex:`\code{NULL}`, the value of :raw-latex:`\code{*i}` will be +: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 set to provide details on how well the request has been met. The meaning of this argument is described in more detail below. - :raw-latex:`\index{sane_control_option}` - :: SANE_Status sane_control_option (SANE_Handle h, SANE_Int n, SANE_Action a, void *v, SANE_Int * i); +.. index:: SANE_Action + The way the option is affected by a call to this function is controlled -by parameter :raw-latex:`\code{a}` which is a value of type -:raw-latex:`\code{\defn{SANE_Action}}`. The possible values and their +by parameter :data:`a` which is a value of type +:type:`SANE_Action`. The possible values and their meaning is described in Table :raw-latex:`\ref{tab:actions}`. :raw-latex:`\leavevmode` @@ -1260,10 +1297,10 @@ meaning is described in Table :raw-latex:`\ref{tab:actions}`. \hline \end{tabular} -After setting a value via an action value of ``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 -in :raw-latex:`\code{*i}` (if :raw-latex:`\code{i}` is -non-:raw-latex:`\code{NULL}`). The returned value is a bitset that may +in :data:`*i` (if :data:`i` is +non-:macro:`NULL`). The returned value is a bitset that may contain any combination of the values described in Table :raw-latex:`\ref{tab:info}`. @@ -1310,48 +1347,50 @@ Table :raw-latex:`\ref{tab:info}`. This function may fail with one of the following status codes. - :raw-latex:`\code{SANE_STATUS_UNSUPPORTED}`: - The operation is not supported for the specified handle and - option number. + :macro:`SANE_STATUS_UNSUPPORTED`: + The operation is not supported for the specified handle and + option number. - :raw-latex:`\code{SANE_STATUS_INVAL}`: - The option value is not valid. + :macro:`SANE_STATUS_INVAL`: + The option value is not valid. - :raw-latex:`\code{SANE_STATUS_IO_ERROR}`: - An error occured while communicating with the device. + :macro:`SANE_STATUS_IO_ERROR`: + An error occured while communicating with the device. - :raw-latex:`\code{SANE_STATUS_NO_MEM}`: - An insufficent amount of memory is available. + :macro:`SANE_STATUS_NO_MEM`: + An insufficent amount of memory is available. - :raw-latex:`\code{SANE_STATUS_ACCESS_DENIED}`: - Access to the option has been denied due to insufficient or - invalid authentication. + :macro:`SANE_STATUS_ACCESS_DENIED`: + Access to the option has been denied due to insufficient or + invalid authentication. -:raw-latex:`\code{sane_get_parameters}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: sane_get_parameters + +:func:`sane_get_parameters` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ This function is used to obtain the current scan parameters. The returned parameters are guaranteed to be accurate between the time a -scan has been started (:raw-latex:`\code{sane_start()}` has been called) +scan has been started (:func:`sane_start()` has been called) and the completion of that request. Outside of that window, the returned values are best-effort estimates of what the parameters will be when -:raw-latex:`\code{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 estimate of how big the scanned image will be. The parameters passed to -this function are the handle :raw-latex:`\code{h}` of the device for +this function are the handle :data:`h` of the device for which the parameters should be obtained and a pointer -:raw-latex:`\code{p}` to a parameter structure. The parameter structure +:data:`p` to a parameter structure. The parameter structure is described in more detail below. - :raw-latex:`\index{sane_get_parameters}` - :: SANE_Status sane_get_parameters (SANE_Handle h, SANE_Parameters * p); +.. index:: SANE_Parameters + The scan parameters are returned in a structure of type -:raw-latex:`\code{\defn{SANE_Parameters}}`. The C declaration of this +:type:`SANE_Parameters`. The C declaration of this structure is given below. :: @@ -1367,9 +1406,11 @@ structure is given below. } SANE_Parameters; -Member :raw-latex:`\code{format}` specifies the format of the next frame +.. index:: SANE_Frame + +Member :member:`format` specifies the format of the next frame to be returned. The possible values for type -:raw-latex:`\code{\defn{SANE_Frame}}` are described in +:type:`SANE_Frame` are described in Table :raw-latex:`\ref{tab:frameformat}`. The meaning of these values is described in more detail in Section :raw-latex:`\ref{sec:imageformat}`. @@ -1394,32 +1435,32 @@ described in more detail in Section :raw-latex:`\ref{sec:imageformat}`. \hline \end{tabular} -Member :raw-latex:`\code{last_frame}` is set to -:raw-latex:`\code{SANE_TRUE}` if and only if the frame that is currently +Member :member:`last_frame` is set to +:macro:`SANE_TRUE` if and only if the frame that is currently being acquired (or the frame that will be acquired next if there is no current frame) is the last frame of a multi frame image (e.g., the current frame is the blue component of a red, green, blue image). -Member :raw-latex:`\code{lines}` specifies how many scan lines the frame +Member :member:`lines` specifies how many scan lines the frame is comprised of. If this value is -1, the number of lines is not known a -priori and the frontend should call :raw-latex:`\code{sane_read()}` -until it returns a status of :raw-latex:`\code{SANE_STATUS_EOF}`. +priori and the frontend should call :func:`sane_read()` +until it returns a status of :macro:`SANE_STATUS_EOF`. -Member :raw-latex:`\code{bytes_per_line}` specifies the number of bytes +Member :member:`bytes_per_line` specifies the number of bytes that comprise one scan line. -Member :raw-latex:`\code{depth}` specifies the number of bits per +Member :member:`depth` specifies the number of bits per sample. -Member :raw-latex:`\code{pixels_per_line}` specifies the number of +Member :member:`pixels_per_line` specifies the number of pixels that comprise one scan line. Assume :math:`B` is the number of channels in the frame, then the bit -depth :math:`d` (as given by member :raw-latex:`\code{depth}`) and the +depth :math:`d` (as given by member :member:`depth`) and the number of pixels per line :math:`n` (as given by this member -:raw-latex:`\code{pixels_per_line}`) are related to :math:`c`, the +:member:`pixels_per_line`) are related to :math:`c`, the number of bytes per line (as given by member -:raw-latex:`\code{bytes_per_line}`) as follows: +:member:`bytes_per_line`) as follows: .. math:: @@ -1434,13 +1475,13 @@ Note that the number of bytes per line can be larger than the minimum value imposed by the right side of this equation. A frontend must be able to properly cope with such “padded” image formats. -:raw-latex:`\code{sane_start}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: sane_start + +:func:`sane_start` +~~~~~~~~~~~~~~~~~~ This function initiates aquisition of an image from the device -represented by handle :raw-latex:`\code{h}`. - - :raw-latex:`\index{sane_start}` +represented by handle :data:`h`. :: @@ -1448,42 +1489,42 @@ represented by handle :raw-latex:`\code{h}`. This function may fail with one of the following status codes. - :raw-latex:`\code{SANE_STATUS_CANCELLED}`: - The operation was cancelled through a call to - :raw-latex:`\code{sane_cancel}`. + :macro:`SANE_STATUS_CANCELLED`: + The operation was cancelled through a call to + :func:`sane_cancel()`. - :raw-latex:`\code{SANE_STATUS_DEVICE_BUSY}`: - The device is busy. The operation should be retried later. + :macro:`SANE_STATUS_DEVICE_BUSY`: + The device is busy. The operation should be retried later. - :raw-latex:`\code{SANE_STATUS_JAMMED}`: - The document feeder is jammed. + :macro:`SANE_STATUS_JAMMED`: + The document feeder is jammed. - :raw-latex:`\code{SANE_STATUS_NO_DOCS}`: - The document feeder is out of documents. + :macro:`SANE_STATUS_NO_DOCS`: + The document feeder is out of documents. - :raw-latex:`\code{SANE_STATUS_COVER_OPEN}`: - The scanner cover is open. + :macro:`SANE_STATUS_COVER_OPEN`: + The scanner cover is open. - :raw-latex:`\code{SANE_STATUS_IO_ERROR}`: - An error occurred while communicating with the device. + :macro:`SANE_STATUS_IO_ERROR`: + An error occurred while communicating with the device. - :raw-latex:`\code{SANE_STATUS_NO_MEM}`: - An insufficent amount of memory is available. + :macro:`SANE_STATUS_NO_MEM`: + An insufficent amount of memory is available. -:raw-latex:`\code{sane_read}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: sane_read + +:func:`sane_read` +~~~~~~~~~~~~~~~~~ This function is used to read image data from the device represented by -handle :raw-latex:`\code{h}`. Argument :raw-latex:`\code{buf}` is a -pointer to a memory area that is at least :raw-latex:`\code{maxlen}` +handle :data:`h`. Argument :data:`buf` is a +pointer to a memory area that is at least :data:`maxlen` bytes long. The number of bytes returned is stored in -:raw-latex:`\code{*len}`. A backend must set this to zero when the call +:data:`*len`. A backend must set this to zero when the call fails (i.e., when a status other than -:raw-latex:`\code{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 -0 to :raw-latex:`\code{maxlen}` bytes. - - :raw-latex:`\index{sane_read}` +0 to :data:`maxlen` bytes. :: @@ -1492,188 +1533,188 @@ 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 -:raw-latex:`\code{h}`. +:data:`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 occurs). #. If the device is in non-blocking I/O mode, the call returns - immediately with status :raw-latex:`\code{SANE_STATUS_GOOD}` and with - :raw-latex:`\code{*len}` set to zero. + immediately with status :macro:`SANE_STATUS_GOOD` and + with :data:`*len` set to zero. -The I/O mode of handle :raw-latex:`\code{h}` can be set via a call to -:raw-latex:`\code{sane_set_io_mode()}`. +The I/O mode of handle :data:`h` can be set via a call to +:func:`sane_set_io_mode()`. This function may fail with one of the following status codes. - :raw-latex:`\code{SANE_STATUS_CANCELLED}`: - The operation was cancelled through a call to - :raw-latex:`\code{sane_cancel}`. + :macro:`SANE_STATUS_CANCELLED`: + The operation was cancelled through a call to + :func:`sane_cancel()`. - :raw-latex:`\code{SANE_STATUS_EOF}`: - No more data is available for the current frame. + :macro:`SANE_STATUS_EOF`: + No more data is available for the current frame. - :raw-latex:`\code{SANE_STATUS_JAMMED}`: - The document feeder is jammed. + :macro:`SANE_STATUS_JAMMED`: + The document feeder is jammed. - :raw-latex:`\code{SANE_STATUS_NO_DOCS}`: - The document feeder is out of documents. + :macro:`SANE_STATUS_NO_DOCS`: + The document feeder is out of documents. - :raw-latex:`\code{SANE_STATUS_COVER_OPEN}`: - The scanner cover is open. + :macro:`SANE_STATUS_COVER_OPEN`: + The scanner cover is open. - :raw-latex:`\code{SANE_STATUS_IO_ERROR}`: - An error occurred while communicating with the device. + :macro:`SANE_STATUS_IO_ERROR`: + An error occurred while communicating with the device. - :raw-latex:`\code{SANE_STATUS_NO_MEM}`: - An insufficent amount of memory is available. + :macro:`SANE_STATUS_NO_MEM`: + An insufficent amount of memory is available. - :raw-latex:`\code{SANE_STATUS_ACCESS_DENIED}`: - Access to the device has been denied due to insufficient or - invalid authentication. + :macro:`SANE_STATUS_ACCESS_DENIED`: + Access to the device has been denied due to insufficient or + invalid authentication. -:raw-latex:`\code{sane_cancel}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: sane_cancel + +:func:`sane_cancel` +~~~~~~~~~~~~~~~~~~~ This function is used to immediately or as quickly as possible cancel the currently pending operation of the device represented by handle -:raw-latex:`\code{h}`. - - :raw-latex:`\index{sane_cancel}` +:data:`h`. :: void sane_cancel (SANE_Handle h); This function can be called at any time (as long as handle -:raw-latex:`\code{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 to call this function asynchronously (e.g., from within a signal handler). It is important to note that completion of this operaton does *not* imply that the currently pending operation has been cancelled. It only guarantees that cancellation has been *initiated*. Cancellation completes only when the cancelled call returns (typically with a status -value of :raw-latex:`\code{SANE_STATUS_CANCELLED}`). Since the SANE API +value of :macro:`SANE_STATUS_CANCELLED`). Since the SANE API does not require any other operations to be re-entrant, this implies that a frontend must *not* call any other operation until the cancelled operation has returned. -:raw-latex:`\code{sane_set_io_mode}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: sane_set_io_mode + +:func:`sane_set_io_mode` +~~~~~~~~~~~~~~~~~~~~~~~~ This function is used to set the I/O mode of handle -:raw-latex:`\code{h}`. The I/O mode can be either blocking or -non-blocking. If argument :raw-latex:`\code{m}` is -:raw-latex:`\code{SANE_TRUE}`, the mode is set to non-blocking mode, +:data:`h`. The I/O mode can be either blocking or +non-blocking. If argument :data:`m` is +:macro:`SANE_TRUE`, the mode is set to non-blocking mode, otherwise it’s set to blocking mode. - :raw-latex:`\index{sane_set_io_mode}` - :: SANE_Status sane_set_io_mode (SANE_Handle h, SANE_Bool m); 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 :raw-latex:`\code{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 -argument :raw-latex:`\code{m}` set to :raw-latex:`\code{SANE_FALSE}` is +argument :data:`m` set to :macro:`SANE_FALSE` is guaranteed to complete successfully. This function may fail with one of the following status codes: - :raw-latex:`\code{SANE_STATUS_INVAL}`: - No image acquisition is pending. + :macro:`SANE_STATUS_INVAL`: + No image acquisition is pending. - :raw-latex:`\code{SANE_STATUS_UNSUPPORTED}`: - The backend does not support this operation. + :macro:`SANE_STATUS_UNSUPPORTED`: + The backend does not support this operation. -:raw-latex:`\code{sane_get_select_fd}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: sane_get_select_fd + +:func:`sane_get_select_fd` +~~~~~~~~~~~~~~~~~~~~~~~~~~ This function is used to obtain a (platform-specific) file-descriptor -for handle :raw-latex:`\code{h}` that is readable if and only if image -data is available (i.e., when a call to :raw-latex:`\code{sane_read()}` +for handle :data:`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 -:raw-latex:`\code{*fd}`. - - :raw-latex:`\index{sane_get_select_fd}` +:data:`*fd`. :: SANE_Status sane_get_select_fd (SANE_Handle h, SANE_Int *fd); This function can be called only after a call to -:raw-latex:`\code{sane_start()}` has been performed and the returned +:func:`sane_start()` has been performed and the returned file-descriptor is guaranteed to remain valid for the duration of the -current image acquisition (i.e., until :raw-latex:`\code{sane_cancel()}` -or :raw-latex:`\code{sane_start()}` get called again or until -:raw-latex:`\code{sane_read()}` returns with status -:raw-latex:`\code{SANE_STATUS_EOF}`). Indeed, a backend must guarantee +current image acquisition (i.e., until :func:`sane_cancel()` +or :func:`sane_start()` get called again or until +:func:`sane_read()` returns with status +:macro:`SANE_STATUS_EOF`). Indeed, a backend must guarantee to close the returned select file descriptor at the point when the next -:raw-latex:`\code{sane_read()}` call would return -:raw-latex:`\code{SANE_STATUS_EOF}`. This is necessary to ensure the +:func:`sane_read()` call would return +:macro:`SANE_STATUS_EOF`. This is necessary to ensure the application can detect when this condition occurs without actually -having to call :raw-latex:`\code{sane_read()}`. +having to call :func:`sane_read()`. A backend may elect not to support this operation. In such a case, the function returns with status code -:raw-latex:`\code{SANE_STATUS_UNSUPPORTED}`. +:macro:`SANE_STATUS_UNSUPPORTED`. Note that the only operation supported by the returned file-descriptor is a host operating-system dependent test whether the file-descriptor is readable (e.g., this test can be implemented using -:raw-latex:`\code{select()}` or :raw-latex:`\code{poll()}` under UNIX). +:func:`select()` or :func:`poll()` under UNIX). If any other operation is performed on the file descriptor, the behavior of the backend becomes unpredictable. Once the file-descriptor signals “readable” status, it will remain in that state until a call to -:raw-latex:`\code{sane_read()}` is performed. Since many input devices +:func:`sane_read()` is performed. Since many input devices are very slow, support for this operation is strongly encouraged as it permits an application to do other work while image acquisition is in progress. This function may fail with one of the following status codes: - :raw-latex:`\code{SANE_STATUS_INVAL}`: - No image acquisition is pending. + :macro:`SANE_STATUS_INVAL`: + No image acquisition is pending. - :raw-latex:`\code{SANE_STATUS_UNSUPPORTED}`: - The backend does not support this operation. + :macro:`SANE_STATUS_UNSUPPORTED`: + The backend does not support this operation. -:raw-latex:`\code{sane_strstatus}` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. index:: sane_strstatus + +:func:`sane_strstatus` +~~~~~~~~~~~~~~~~~~~~~~ This function can be used to translate a SANE status code into a printable string. The returned string is a single line of text that forms a complete sentence, but without the trailing period (full-stop). -The function is guaranteed to never return :raw-latex:`\code{NULL}`. The +The function is guaranteed to never return :macro:`NULL`. The returned pointer is valid at least until the next call to this function is performed. - :raw-latex:`\index{sane_strstatus}` - :: const SANE_String_Const sane_strstatus (SANE_Status status); +.. index:: code flow + Code Flow --------- -:raw-latex:`\index{code flow}` - The code flow for the SANE API is illustrated in Figure :raw-latex:`\ref{fig:flow}`. Functions -:raw-latex:`\code{sane_init()}` and :raw-latex:`\code{sane_exit()}` +:func:`sane_init()` and :func:`sane_exit()` initialize and exit the backend, respectively. All other calls must be performed after initialization and before exiting the backend. :raw-latex:`\leavevmode` :raw-latex:`\psfig{file=figs/flow.eps,height=0.5\textheight}` -Function :raw-latex:`\code{sane_get_devices()}` can be called any time -after :raw-latex:`\code{sane_init()}` has been called. It returns the +Function :func:`sane_get_devices()` can be called any time +after :func:`sane_init()` has been called. It returns the list of the devices that are known at the time of the call. This list may change over time since some devices may be turned on or off or a remote host may boot or shutdown between different calls. It should be @@ -1684,13 +1725,13 @@ to directly select a desired device without requiring a call to this function. Once a device has been chosen, it is opened using a call to -:raw-latex:`\code{sane_open()}`. Multiple devices can be open at any +:func:`sane_open()`. Multiple devices can be open at any given time. A SANE backend must not impose artificial constraints on how many devices can be open at any given time. An opened device can be setup through the corresponding device handle -using functions :raw-latex:`\code{sane_get_option_descriptor()}` and -:raw-latex:`\code{sane_control_option()}`. While setting up a device, +using functions :func:`sane_get_option_descriptor()` and +:func:`sane_control_option()`. While setting up a device, obtaining option descriptors and setting and reading of option values can be mixed freely. It is typical for a frontend to read out all available options at the beginning and then build a dialog (either @@ -1700,51 +1741,51 @@ fixed for a given handle. However, as options are set, other options may become active or inactive. Thus, after setting an option, it maybe necessary to re-read some or all option descriptors. While setting up the device, it is also admissible to call -:raw-latex:`\code{sane_get_parameters()}` to get an estimate of what the +:func:`sane_get_parameters()` to get an estimate of what the image parameters will look like once image acquisition begins. The device handle can be put in blocking or non-blocking mode by a call -to :raw-latex:`\code{sane_set_io_mode()}`. Devices are required to +to :func:`sane_set_io_mode()`. Devices are required to support blocking mode (which is the default mode), but support for non-blocking I/O is strongly encouraged for operating systems such as UNIX. After the device is setup properly, image acquisition can be started by -a call to :raw-latex:`\code{sane_start()}`. The backend calculates the +a call to :func:`sane_start()`. The backend calculates the exact image parameters at this point. So future calls to -:raw-latex:`\code{sane_get_parameters()}` will return the exact values, +:func:`sane_get_parameters()` will return the exact values, rather than estimates. Whether the physical image acquisition starts at -this point or during the first call to :raw-latex:`\code{sane_read()}` +this point or during the first call to :func:`sane_read()` is unspecified by the SANE API. If non-blocking I/O and/or a select-style interface is desired, the frontend may attempt to call -:raw-latex:`\code{sane_set_io_mode()}` and/or -:raw-latex:`\code{sane_get_select_fd()}` at this point. Either of these +:func:`sane_set_io_mode()` and/or +:func:`sane_get_select_fd()` at this point. Either of these functions may fail if the backend does not support the requested operation. Image data is collected by repeatedly calling -:raw-latex:`\code{sane_read()}`. Eventually, this function will return -an end-of-file status (:raw-latex:`\code{SANE_STATUS_EOF}`). This +:func:`sane_read()`. Eventually, this function will return +an end-of-file status (:macro:`SANE_STATUS_EOF`). This indicates the end of the current frame. If the frontend expects additional frames (e.g., the individual channels in of a red/green/blue -image or multiple images), it can call :raw-latex:`\code{sane_start()}` +image or multiple images), it can call :func:`sane_start()` again. Once all desired frames have been acquired, function -:raw-latex:`\code{sane_cancel()}` must be called. This operation can +:func:`sane_cancel()` must be called. This operation can also be called at any other time to cancel a pending operation. Note -that :raw-latex:`\code{sane_cancel()}` must be called even if the last -read operation returned :raw-latex:`\code{SANE_STATUS_EOF}`. +that :func:`sane_cancel()` must be called even if the last +read operation returned :macro:`SANE_STATUS_EOF`. When done using the device, the handle should be closed by a call to -:raw-latex:`\code{sane_close()}`. Finally, before exiting the -application, function :raw-latex:`\code{sane_exit()}` must be called. It +:func:`sane_close()`. Finally, before exiting the +application, function :func:`sane_exit()` must be called. It is important not to forget to call this function since otherwise some resources (e.g., temporary files or locks) may remain unclaimed. +.. index:: well known options + Well-Known Options ------------------ -:raw-latex:`\index{well-known options}` - While most backend options are completely self-describing, there are a cases where a user interface might want to special-case the handling of certain options. For example, the scan area is typically defined by four @@ -1756,62 +1797,62 @@ surface and let the user pick the scan area by dragging a rectangle into the desired position. For this reason, the SANE API specifies a small number of option names that have well-defined meanings. +.. index:: option count + Option Number Count ~~~~~~~~~~~~~~~~~~~ -:raw-latex:`\index{option count}` - Option number 0 has an empty string as its name. The value of this -option is of type :raw-latex:`\code{SANE_TYPE_INT}` and it specifies the +option is of type :macro:`SANE_TYPE_INT` and it specifies the total number of options available for a given device (the count includes option number 0). This means that there are two ways of counting the number of options available: a frontend can either cycle through all option numbers starting at one until -:raw-latex:`\code{sane_get_option_descriptor()}` returns -:raw-latex:`\code{NULL}`, or a frontend can directly read out the value +:func:`sane_get_option_descriptor()` returns +:macro:`NULL`, or a frontend can directly read out the value of option number 0. +.. index:: scan resolution, resolution option + Scan Resolution Option ~~~~~~~~~~~~~~~~~~~~~~ -:raw-latex:`\index{scan resolution}`:raw-latex:`\index{resolution option}` - -Option :raw-latex:`\code{resolution}` is used to select the resolution +Option ``resolution`` is used to select the resolution at which an image should be acquired. The type of this option is either -:raw-latex:`\code{SANE_TYPE_INT}` or -:raw-latex:`\code{SANE_TYPE_FIXED}`. The unit is -:raw-latex:`\code{SANE_UNIT_DPI}` (dots/inch). +:macro:`SANE_TYPE_INT` or +:macro:`SANE_TYPE_FIXED`. The unit is +:macro:`SANE_UNIT_DPI` (dots/inch). This option is not mandatory, but if a backend does support it, it must implement it in a manner consistent with the above definition. +.. index:: preview mode + Preview Mode Option ~~~~~~~~~~~~~~~~~~~ -:raw-latex:`\index{preview mode}` - -The boolean option :raw-latex:`\code{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, rather than quality (“preview mode”). When set to -:raw-latex:`\code{SANE_TRUE}`, preview mode is in effect, when set to -:raw-latex:`\code{SANE_FALSE}` image acquisition should proceed in +:macro:`SANE_TRUE`, preview mode is in effect, when set to +:macro:`SANE_FALSE` image acquisition should proceed in normal quality mode. The setting of this option *must not* affect any other option. That is, as far as the other options are concerned, the preview mode is completely side effect free. A backend can assume that the frontend will take care of appropriately setting the scan resolution -for preview mode (through option :raw-latex:`\code{resolution}`). A -backend is free to override the :raw-latex:`\code{resolution}` value +for preview mode (through option ``resolution``). A +backend is free to override the ``resolution`` value with its own choice for preview mode, but it is advised to leave this choice to the frontend wherever possible. This option is not mandatory, but if a backend does support it, it must implement it in a manner consistent with the above definition. +.. index:: scan area options + Scan Area Options ~~~~~~~~~~~~~~~~~ -:raw-latex:`\index{scan area options}` - The four most important well-known options are the ones that define the scan area. The scan area is defined by two points (x/y coordinate pairs) that specify the top-left and the bottom-right corners. This is @@ -1847,8 +1888,8 @@ There are several rules that should be followed by front and backends regarding these options: - Backends must attach a unit of either pixels - (:raw-latex:`\code{SANE_UNIT_PIXEL}`) or millimeters - (:raw-latex:`\code{SANE_UNIT_MM}`) to these options. The unit of all + (:macro:`SANE_UNIT_PIXEL`) or millimeters + (:macro:`SANE_UNIT_MM`) to these options. The unit of all four options must be identical. - Whenever meaningful, a backend should attach a range or a word-list @@ -1865,6 +1906,8 @@ regarding these options: .. include:: net.rst +.. index:: mailing list + Contact Information =================== @@ -1872,15 +1915,13 @@ The SANE standard is discussed and evolved via a mailing list. Anybody with email access to the Internet can automatically join and leave the discussion group by sending mail to the following address. - :raw-latex:`\index{mailing list}` - mailto:majordomo@mostang.com To subscribe, send a mail with the body “``subscribe sane-devel``” to the above address. A complete list of commands supported can be obtained by sending a mail -with a subject of “:raw-latex:`\code{help}`” to the above address. The +with a subject of “``help``” to the above address. The mailing list is archived and available through the SANE home page at URL: