kopia lustrzana https://gitlab.com/sane-project/website
667 wiersze
27 KiB
HTML
667 wiersze
27 KiB
HTML
<html><body>
|
|
<a href="doc013.html"><img src=../icons/next.gif alt="Next"></a>
|
|
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
|
<a href="doc011.html"><img src=../icons/previous.gif alt="Previous"></a>
|
|
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
|
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
|
<hr>
|
|
|
|
<title>Operations</title>
|
|
<h2><a name="s4.3">4.3 Operations</a></h2>
|
|
|
|
<p><h3><a name="s4.3.1">4.3.1 <tt>sane_init</tt></a></h3>
|
|
|
|
<p>This function must be called before any other SANE function can be called.
|
|
The behavior of a SANE backend is undefined if this function is not called
|
|
first or if the status code returned by <tt>sane_init</tt> is different from
|
|
<tt>SANE_STATUS_GOOD<a name="i72"></tt>. The version code of the backend is returned
|
|
in the value pointed to by <tt>version_code</tt>. If that pointer is
|
|
<tt>NULL</tt>, no version code is returned. Argument <tt>authorize</tt> is either
|
|
a pointer to a function that is invoked when the backend requires
|
|
authentication for a specific resource or <tt>NULL</tt> if the frontend does not
|
|
support authentication.
|
|
<blockquote><a name="i73">
|
|
<pre>
|
|
SANE_Status sane_init (SANE_Int * version_code,
|
|
SANE_Authorization_Callback authorize);
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The authorization function may be called by a backend in response to
|
|
any of the following calls:
|
|
<blockquote>
|
|
<tt>sane_open</tt>, <tt>sane_control_option</tt>, <tt>sane_start</tt>
|
|
</blockquote>
|
|
If a backend was initialized without authorization function, then
|
|
authorization requests that cannot be handled by the backend itself
|
|
will fail automatically and the user may be prevented from accessing
|
|
protected resources. Backends are encouraged to implement means of
|
|
authentication that do not require user assistance. E.g., on a
|
|
multi-user system that authenticates users through a login process a
|
|
backend could automatically lookup the apporpriate password based on
|
|
resource- and user-name.
|
|
|
|
<p>The authentication function type has the following declaration:
|
|
<blockquote><a name="i74">
|
|
<a name="i75"><a name="i76"><a name="i77">
|
|
<pre>
|
|
#define SANE_MAX_USERNAME_LEN 128
|
|
#define SANE_MAX_PASSWORD_LEN 128
|
|
|
|
typedef void (*SANE_Authorization_Callback)
|
|
(SANE_String_Const resource,
|
|
SANE_Char username[SANE_MAX_USERNAME_LEN],
|
|
SANE_Char password[SANE_MAX_PASSWORD_LEN]);
|
|
</pre>
|
|
</blockquote>
|
|
Three arguments are passed to the authorization function:
|
|
<tt>resource</tt> 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 <tt>username</tt>
|
|
and <tt>password</tt> arguments are (pointers to) an array of
|
|
<tt>SANE_MAX_USERNAME_LEN</tt> and <tt>SANE_MAX_PASSWORD_LEN</tt>
|
|
characters, respectively. The authorization call should place the
|
|
entered username and password in these arrays. The returned strings
|
|
<em>must</em> be ASCII-NUL terminated.
|
|
|
|
<p><h3><a name="s4.3.2">4.3.2 <tt>sane_exit</tt></a></h3>
|
|
|
|
<p>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 <tt>sane_close()</tt>, but backends are required to release all
|
|
resources upon a call to this function). After this function returns,
|
|
no function other than <tt>sane_init()</tt> may be called (regardless
|
|
of the status value returned by <tt>sane_exit()</tt>. Neglecting to
|
|
call this function may result in some resources not being released
|
|
properly.
|
|
<blockquote><a name="i78">
|
|
<pre>
|
|
void sane_exit (void);
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p><h3><a name="s4.3.3">4.3.3 <tt>sane_get_devices</tt></a></h3>
|
|
|
|
<p>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 <tt>NULL</tt> terminated array of pointers to <tt>SANE_Device</tt>
|
|
structures in <tt>*device_list</tt>. The returned list is guaranteed
|
|
to remain unchanged and valid until (a) another call to this function
|
|
is performed or (b) a call to <tt>sane_exit()</tt> is performed. This
|
|
function can be called repeatedly to detect when new devices become
|
|
available. If argument <tt>local_only</tt> 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.
|
|
<blockquote><a name="i79">
|
|
<pre>
|
|
SANE_Status sane_get_devices (const SANE_Device *** device_list,
|
|
SANE_Bool local_only);
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>This function may fail with <tt>SANE_STATUS_NO_MEM</tt> if an
|
|
insufficient amount of memory is available.
|
|
|
|
<p><blockquote>
|
|
<center>
|
|
<b>Backend Implementation Note</b>
|
|
</center>
|
|
SANE does not require that this function is called before a
|
|
<tt>sane_open()</tt> 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.
|
|
</blockquote>
|
|
|
|
<p><h3><a name="s4.3.4">4.3.4 <tt>sane_open</tt></a></h3>
|
|
|
|
<p>This function is used to establish a connection to a particular
|
|
device. The name of the device to be opened is passed in argument
|
|
<tt>name</tt>. If the call completes successfully, a handle for the
|
|
device is returned in <tt>*h</tt>. As a special case, specifying a
|
|
zero-length string as the device requests opening the first available
|
|
device (if there is such a device).
|
|
<blockquote><a name="i80">
|
|
<pre>
|
|
SANE_Status sane_open (SANE_String_Const name, SANE_Handle * h);
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>This function may fail with one of the following status codes.
|
|
<blockquote>
|
|
<dl>
|
|
<dt><tt>SANE_STATUS_DEVICE_BUSY</tt>:<dd> The device is currently
|
|
busy (in use by somebody else).
|
|
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> The device name is not valid.
|
|
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occured while
|
|
communicating with the device.
|
|
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
|
is available.
|
|
<dt><tt>SANE_STATUS_ACCESS_DENIED</tt>:<dd> Access to the device has
|
|
been denied due to insufficient or invalid authentication.
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<p><h3><a name="s4.3.5">4.3.5 <tt>sane_close</tt></a></h3>
|
|
|
|
<p>This function terminates the association between the device handle
|
|
passed in argument <tt>h</tt> and the device it represents. If the
|
|
device is presently active, a call to <tt>sane_cancel()</tt> is
|
|
performed first. After this function returns, handle <tt>h</tt> must
|
|
not be used anymore.
|
|
|
|
<p><blockquote><a name="i81">
|
|
<pre>
|
|
void sane_close (SANE_Handle h);
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p><h3><a name="s4.3.6">4.3.6 <tt>sane_get_option_descriptor</tt></a></h3>
|
|
|
|
<p>This function is used to access option descriptors. The function
|
|
returns the option descriptor for option number <tt>n</tt> of the device
|
|
represented by handle <tt>h</tt>. 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 <tt>h</tt> (the count
|
|
includes option 0). If n is not a valid option index, the function
|
|
returns <tt>NULL</tt>. The returned option descriptor is guaranteed to
|
|
remain valid (and at the returned address) until the device is closed.
|
|
|
|
<p><blockquote><a name="i82">
|
|
<pre>
|
|
const SANE_Option_Descriptor *
|
|
sane_get_option_descriptor (SANE_Handle h, SANE_Int n);
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p><h3><a name="s4.3.7">4.3.7 <tt>sane_control_option</tt></a></h3>
|
|
|
|
<p>This function is used to set or inquire the current value of option
|
|
number <tt>n</tt> of the device represented by handle <tt>h</tt>. The
|
|
manner in which the option is controlled is specified by parameter
|
|
<tt>a</tt>. The possible values of this parameter are described in more
|
|
detail below. The value of the option is passed through argument
|
|
<tt>v</tt>. It is a pointer to the memory that holds the option value.
|
|
The memory area pointed to by <tt>v</tt> must be big enough to hold the
|
|
entire option value (determined by member <tt>size</tt> 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 <tt>v</tt> may be shorter since the backend will stop
|
|
reading the option value upon encountering the first <tt>NUL</tt>
|
|
terminator in the string. If argument <tt>i</tt> is not <tt>NULL</tt>,
|
|
the value of <tt>*i</tt> 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.
|
|
<blockquote><a name="i83">
|
|
<pre>
|
|
SANE_Status sane_control_option (SANE_Handle h, SANE_Int n,
|
|
SANE_Action a, void *v,
|
|
SANE_Int * i);
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The way the option is affected by a call to this function is
|
|
controlled by parameter <tt>a</tt> which is a value of type
|
|
<tt>SANE_Action<a name="i84"></tt>. The possible values and their meaning is
|
|
described in Table <a href="doc012.html#t7">7</a>.
|
|
|
|
<p><p><a name="t7"></a>
|
|
<center>
|
|
|
|
<table cellpadding=0 cellspacing=0 border=1>
|
|
<tr valign=top>
|
|
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
|
<td colspan=1 align=center nowrap><b>Code</b></td>
|
|
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
|
|
<p>
|
|
|
|
<p><tt>SANE_ACTION_GET_VALUE<a name="i85"></tt> </td>
|
|
<td colspan=1 align=right nowrap> 0 </td>
|
|
<td colspan=1 align=left> Get current option value. </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
|
|
<p><tt>SANE_ACTION_SET_VALUE<a name="i86"></tt> </td>
|
|
<td colspan=1 align=right nowrap> 1 </td>
|
|
<td colspan=1 align=left> Set option value. The
|
|
option value passed through argument <tt>v</tt> may be modified by the
|
|
backend if the value cannot be set exactly. </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
|
|
<p><tt>SANE_ACTION_SET_AUTO<a name="i87"></tt> </td>
|
|
<td colspan=1 align=right nowrap> 2 </td>
|
|
<td colspan=1 align=left> Turn on automatic mode. Backend
|
|
or device will automatically select an appropriate value. This mode
|
|
remains effective until overridden by an explicit set value request.
|
|
The value of parameter <tt>v</tt> is completely ignored in this case and
|
|
may be <tt>NULL</tt>. </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
|
|
<p>
|
|
</td></tr>
|
|
</table>
|
|
<p><center>Table 7: Action Values (<tt>SANE_Action</tt>)</center>
|
|
|
|
</center>
|
|
<p>
|
|
|
|
<p>After setting a value via an action value of
|
|
<tt>SANE_ACTION_SET_VALUE</tt>, additional information on how well the
|
|
request has been met is returned in <tt>*i</tt> (if <tt>i</tt> is
|
|
non-<tt>NULL</tt>). The returned value is a bitset that may contain any
|
|
combination of the values described in Table <a href="doc012.html#t8">8</a>.
|
|
<p><a name="t8"></a>
|
|
<center>
|
|
|
|
<table cellpadding=0 cellspacing=0 border=1>
|
|
<tr valign=top>
|
|
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
|
<td colspan=1 align=center nowrap><b>Code</b></td>
|
|
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
|
|
<p>
|
|
|
|
<p><tt>SANE_INFO_INEXACT<a name="i88"></tt> </td>
|
|
<td colspan=1 align=right nowrap> 1 </td>
|
|
<td colspan=1 align=left> This value is returned when
|
|
setting an option value resulted in a value being selected that does
|
|
not exactly match the requested value. For example, if a scanner
|
|
can adjust the resolution in increments of 30dpi only, setting the
|
|
resolution to 307dpi may result in an actual setting of 300dpi.
|
|
When this happens, the bitset returned in <tt>*i</tt> has this member
|
|
set. In addition, the option value is modified to reflect the
|
|
actual (rounded) value that was used by the backend. Note that
|
|
inexact values are admissible for strings as well. A backend may
|
|
choose to ``round'' a string to the closest matching legal string
|
|
for a constrained string value. </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
|
|
<p> <tt>SANE_INFO_RELOAD_OPTIONS<a name="i89"></tt> </td>
|
|
<td colspan=1 align=right nowrap> 2 </td>
|
|
<td colspan=1 align=left> The setting of an
|
|
option may affect the value or availability of one or more <em>
|
|
other</em> options. When this happens, the SANE backend sets this
|
|
member in <tt>*i</tt> to indicate that the application should reload
|
|
all options. This member may be set if and only if at least one
|
|
option changed. </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
|
|
<p><tt>SANE_INFO_RELOAD_PARAMS<a name="i90"></tt> </td>
|
|
<td colspan=1 align=right nowrap> 4 </td>
|
|
<td colspan=1 align=left> The setting of an option may
|
|
affect the parameter values (see <tt>sane_get_parameters()</tt>).
|
|
If setting an option affects the parameter values, this member will
|
|
be set in <tt>*i</tt>. Note that this member may be set even if the
|
|
parameters did not actually change. However, it is guaranteed that
|
|
the parameters never change without this member being set. </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
|
|
<p>
|
|
</td></tr>
|
|
</table>
|
|
<p><center>Table 8: Additional Information Returned When Setting an Option</center>
|
|
|
|
</center>
|
|
<p>
|
|
|
|
<p>This function may fail with one of the following status codes.
|
|
<blockquote>
|
|
<dl>
|
|
<dt><tt>SANE_STATUS_UNSUPPORTED</tt>:<dd> The operation is not
|
|
supported for the specified handle and option number.
|
|
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> The option value is not valid.
|
|
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occured while
|
|
communicating with the device.
|
|
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
|
is available.
|
|
<dt><tt>SANE_STATUS_ACCESS_DENIED</tt>:<dd> Access to the option has
|
|
been denied due to insufficient or invalid authentication.
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<p><h3><a name="s4.3.8">4.3.8 <tt>sane_get_parameters</tt></a></h3>
|
|
|
|
<p>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 (<tt>sane_start()</tt> 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
|
|
<tt>sane_start()</tt> 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 <tt>h</tt> of the device for which the
|
|
parameters should be obtained and a pointer <tt>p</tt> to a parameter
|
|
structure. The parameter structure is described in more detail below.
|
|
|
|
<p><blockquote><a name="i91">
|
|
<pre>
|
|
SANE_Status sane_get_parameters (SANE_Handle h,
|
|
SANE_Parameters * p);
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The scan parameters are returned in a structure of type
|
|
<tt>SANE_Parameters<a name="i92"></tt>. The C declaration of this structure
|
|
is given below.
|
|
<blockquote>
|
|
<pre>
|
|
typedef struct
|
|
{
|
|
SANE_Frame format;
|
|
SANE_Bool last_frame;
|
|
SANE_Int bytes_per_line;
|
|
SANE_Int pixels_per_line;
|
|
SANE_Int lines;
|
|
SANE_Int depth;
|
|
}
|
|
SANE_Parameters;
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>Member <tt>format</tt> specifies the format of the next frame to be
|
|
returned. The possible values for type <tt>SANE_Frame<a name="i93"></tt> are
|
|
described in Table <a href="doc012.html#t9">9</a>. The meaning of these
|
|
values is described in more detail in Section <a href="doc008.html#s3.2">3.2</a>.
|
|
<p><a name="t9"></a>
|
|
<center>
|
|
|
|
<table cellpadding=0 cellspacing=0 border=1>
|
|
<tr valign=top>
|
|
<td colspan=1 align=center nowrap><b>Symbol</b></td>
|
|
<td colspan=1 align=center nowrap><b>Code</b></td>
|
|
<td colspan=1 align=center nowrap><b>Description</b></td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
|
|
<p>
|
|
|
|
<p><tt>SANE_FRAME_GRAY<a name="i94"></tt> </td>
|
|
<td colspan=1 align=right nowrap> 0 </td>
|
|
<td colspan=1 align=left nowrap> Band covering human visual range. </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
<tt>SANE_FRAME_RGB<a name="i95"></tt> </td>
|
|
<td colspan=1 align=right nowrap> 1 </td>
|
|
<td colspan=1 align=left nowrap> Pixel-interleaved red/green/blue bands. </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
<tt>SANE_FRAME_RED<a name="i96"></tt> </td>
|
|
<td colspan=1 align=right nowrap> 2 </td>
|
|
<td colspan=1 align=left nowrap> Red band of a red/green/blue image. </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
<tt>SANE_FRAME_GREEN<a name="i97"></tt> </td>
|
|
<td colspan=1 align=right nowrap> 3 </td>
|
|
<td colspan=1 align=left nowrap> Green band of a red/green/blue image. </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
<tt>SANE_FRAME_BLUE<a name="i98"></tt> </td>
|
|
<td colspan=1 align=right nowrap> 4 </td>
|
|
<td colspan=1 align=left nowrap> Blue band of a red/green/blue image. </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
|
|
<p>
|
|
</td></tr>
|
|
</table>
|
|
<p><center>Table 9: Frame Format (<tt>SANE_Frame</tt>)</center>
|
|
|
|
</center>
|
|
<p>
|
|
|
|
<p>Member <tt>last_frame</tt> is set to <tt>SANE_TRUE</tt> 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).
|
|
|
|
<p>Member <tt>lines</tt> 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 <tt>sane_read()</tt> until it
|
|
returns a status of <tt>SANE_STATUS_EOF</tt>.
|
|
|
|
<p>Member <tt>bytes_per_line</tt> specifies the number of bytes that
|
|
comprise one scan line.
|
|
|
|
<p>Member <tt>depth</tt> specifies the number of bits per sample.
|
|
|
|
<p>Member <tt>pixels_per_line</tt> specifies the number of pixels that
|
|
comprise one scan line.
|
|
|
|
<p>Assume B is the number of channels in the frame, then the bit depth
|
|
d (as given by member <tt>depth</tt>) and the number of pixels per
|
|
line n (as given by this member <tt>pixels_per_line</tt>) are
|
|
related to c, the number of bytes per line (as given by member
|
|
<tt>bytes_per_line</tt>) as follows:
|
|
|
|
<p>
|
|
<center>
|
|
|
|
c >= \left{
|
|
ll
|
|
B*\lfloor (n + 7) / 8\rfloor if d=1
|
|
</td><td align=right>(1)</td></tr><tr><td align=center>
|
|
|
|
B*n *d / 8 if d>1
|
|
|
|
\right.
|
|
</center>
|
|
<p>
|
|
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.
|
|
|
|
<p><h3><a name="s4.3.9">4.3.9 <tt>sane_start</tt></a></h3>
|
|
|
|
<p>This function initiates aquisition of an image from the device
|
|
represented by handle <tt>h</tt>.
|
|
<blockquote><a name="i99">
|
|
<pre>
|
|
SANE_Status sane_start (SANE_Handle h);
|
|
</pre>
|
|
</blockquote>
|
|
This function may fail with one of the following status codes.
|
|
<blockquote>
|
|
<dl>
|
|
<dt><tt>SANE_STATUS_CANCELLED</tt>:<dd> The operation was cancelled through
|
|
a call to <tt>sane_cancel</tt>.
|
|
<dt><tt>SANE_STATUS_DEVICE_BUSY</tt>:<dd> The device is busy. The
|
|
operation should be retried later.
|
|
<dt><tt>SANE_STATUS_JAMMED</tt>:<dd> The document feeder is jammed.
|
|
<dt><tt>SANE_STATUS_NO_DOCS</tt>:<dd> The document feeder is out of
|
|
documents.
|
|
<dt><tt>SANE_STATUS_COVER_OPEN</tt>:<dd> The scanner cover is open.
|
|
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occurred while communicating
|
|
with the device.
|
|
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
|
is available.
|
|
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> The scan cannot be started with the current
|
|
set of options. The frontend should reload the option descriptors, as if
|
|
<tt>SANE_INFO_RELOAD_OPTIONS<a name="i100"></tt> had been returned from a call to
|
|
<tt>sane_control_option()</tt>, since the device's capabilities may have
|
|
changed.
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<p><h3><a name="s4.3.10">4.3.10 <tt>sane_read</tt></a></h3>
|
|
|
|
<p>This function is used to read image data from the device represented
|
|
by handle <tt>h</tt>. Argument <tt>buf</tt> is a pointer to a memory area
|
|
that is at least <tt>maxlen</tt> bytes long. The number of bytes
|
|
returned is stored in <tt>*len</tt>. A backend must set this to zero
|
|
when a status other than <tt>SANE_STATUS_GOOD</tt> is returned.
|
|
When the call succeeds, the number of bytes returned can be anywhere in
|
|
the range from 0 to <tt>maxlen</tt> bytes.
|
|
<blockquote><a name="i101">
|
|
<pre>
|
|
SANE_Status sane_read (SANE_Handle h, SANE_Byte * buf,
|
|
SANE_Int maxlen, SANE_Int * len);
|
|
</pre>
|
|
</blockquote>
|
|
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 <tt>h</tt>.
|
|
<ol>
|
|
<li>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).
|
|
|
|
<p><li>If the device is in non-blocking I/O mode, the call returns
|
|
immediately with status <tt>SANE_STATUS_GOOD</tt> and with
|
|
<tt>*len</tt> set to zero.
|
|
</ol>
|
|
The I/O mode of handle <tt>h</tt> can be set via a call to
|
|
<tt>sane_set_io_mode()</tt>.
|
|
|
|
<p>This function may fail with one of the following status codes.
|
|
<blockquote>
|
|
<dl>
|
|
<dt><tt>SANE_STATUS_CANCELLED</tt>:<dd> The operation was cancelled through
|
|
a call to <tt>sane_cancel</tt>.
|
|
<dt><tt>SANE_STATUS_EOF</tt>:<dd> No more data is available for the
|
|
current frame.
|
|
<dt><tt>SANE_STATUS_JAMMED</tt>:<dd> The document feeder is jammed.
|
|
<dt><tt>SANE_STATUS_NO_DOCS</tt>:<dd> The document feeder is out of
|
|
documents.
|
|
<dt><tt>SANE_STATUS_COVER_OPEN</tt>:<dd> The scanner cover is open.
|
|
<dt><tt>SANE_STATUS_IO_ERROR</tt>:<dd> An error occurred while communicating
|
|
with the device.
|
|
<dt><tt>SANE_STATUS_NO_MEM</tt>:<dd> An insufficent amount of memory
|
|
is available.
|
|
<dt><tt>SANE_STATUS_ACCESS_DENIED</tt>:<dd> Access to the device has
|
|
been denied due to insufficient or invalid authentication.
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<p><h3><a name="s4.3.11">4.3.11 <tt>sane_cancel</tt></a></h3>
|
|
|
|
<p>This function is used to immediately or as quickly as possible cancel
|
|
the currently pending operation of the device represented by handle
|
|
<tt>h</tt>.
|
|
<blockquote><a name="i102">
|
|
<pre>
|
|
void sane_cancel (SANE_Handle h);
|
|
</pre>
|
|
</blockquote>
|
|
This function can be called at any time (as long as handle <tt>h</tt> 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 <em>not</em> imply that
|
|
the currently pending operation has been cancelled. It only
|
|
guarantees that cancellation has been <em>initiated</em>. Cancellation
|
|
completes only when the cancelled call returns (typically with a
|
|
status value of <tt>SANE_STATUS_CANCELLED</tt>). Since the SANE API
|
|
does not require any other operations to be re-entrant, this implies
|
|
that a frontend must <em>not</em> call any other operation until the
|
|
cancelled operation has returned.
|
|
|
|
<p><h3><a name="s4.3.12">4.3.12 <tt>sane_set_io_mode</tt></a></h3>
|
|
|
|
<p>This function is used to set the I/O mode of handle <tt>h</tt>. The I/O mode
|
|
can be either blocking or non-blocking. If argument <tt>m</tt> is
|
|
<tt>SANE_TRUE</tt>, the mode is set to non-blocking mode, otherwise it's set to
|
|
blocking mode. This function can be called only after a call to
|
|
<tt>sane_start()</tt> has been performed.
|
|
<blockquote><a name="i103">
|
|
<pre>
|
|
SANE_Status sane_set_io_mode (SANE_Handle h, SANE_Bool m);
|
|
</pre>
|
|
</blockquote>
|
|
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 <tt>SANE_STATUS_UNSUPPORTED</tt> is returned. Blocking
|
|
I/O must be supported by all backends, so calling this function with
|
|
argument <tt>m</tt> set to <tt>SANE_FALSE</tt> is guaranteed to complete
|
|
successfully.
|
|
|
|
<p>This function may fail with one of the following status codes:
|
|
<blockquote>
|
|
<dl>
|
|
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> No image acquisition is pending.
|
|
<dt><tt>SANE_STATUS_UNSUPPORTED</tt>:<dd> The backend does not support
|
|
the requested I/O mode.
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<p><h3><a name="s4.3.13">4.3.13 <tt>sane_get_select_fd</tt></a></h3>
|
|
|
|
<p>This function is used to obtain a (platform-specific) file-descriptor
|
|
for handle <tt>h</tt> that is readable if and only if image data is
|
|
available (i.e., when a call to <tt>sane_read()</tt> will return at
|
|
least one byte of data). If the call completes successfully, the
|
|
select file-descriptor is returned in <tt>*fd</tt>.
|
|
<blockquote><a name="i104">
|
|
<pre>
|
|
SANE_Status sane_get_select_fd (SANE_Handle h, SANE_Int *fd);
|
|
</pre>
|
|
</blockquote>
|
|
This function can be called only after a call to <tt>sane_start()</tt>
|
|
has been performed and the returned file-descriptor is guaranteed to
|
|
remain valid for the duration of the current image acquisition (i.e.,
|
|
until <tt>sane_cancel()</tt> or <tt>sane_start()</tt> get called again
|
|
or until <tt>sane_read()</tt> returns with status
|
|
<tt>SANE_STATUS_EOF</tt>). Indeed, a backend must guarantee to
|
|
close the returned select file descriptor at the point when the next
|
|
<tt>sane_read()</tt> call would return <tt>SANE_STATUS_EOF</tt>.
|
|
This is necessary to ensure the application can detect when this
|
|
condition occurs without actually having to call <tt>sane_read()</tt>.
|
|
|
|
<p>A backend may elect not to support this operation. In such a case,
|
|
the function returns with status code
|
|
<tt>SANE_STATUS_UNSUPPORTED</tt>.
|
|
|
|
<p>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 <tt>select()</tt>
|
|
or <tt>poll()</tt> 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 <tt>sane_read()</tt> 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.
|
|
|
|
<p>This function may fail with one of the following status codes:
|
|
<blockquote>
|
|
<dl>
|
|
<dt><tt>SANE_STATUS_INVAL</tt>:<dd> No image acquisition is pending.
|
|
<dt><tt>SANE_STATUS_UNSUPPORTED</tt>:<dd> The backend does not support
|
|
this operation.
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<p><h3><a name="s4.3.14">4.3.14 <tt>sane_strstatus</tt></a></h3>
|
|
|
|
<p>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 <tt>NULL</tt>.
|
|
The returned pointer is valid at least until the next call to this
|
|
function is performed.
|
|
<blockquote><a name="i105">
|
|
<pre>
|
|
const SANE_String_Const sane_strstatus (SANE_Status status);
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p><p><hr>
|
|
<a href="doc013.html"><img src=../icons/next.gif alt="Next"></a>
|
|
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
|
<a href="doc011.html"><img src=../icons/previous.gif alt="Previous"></a>
|
|
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
|
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
|
<hr>
|
|
</body></html>
|