Operations
/* Must be called before any other 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 VERSION_CODE. If VERSION_CODE is a NULL
pointer, no version code is returned. */
extern SANE_Status sane_init (SANE_Int * version_code);
/* Must be called to terminate use of a backend. After this function
returns no function other than sane_init() may be called.
Neglecting to call this function may result in some resources not
being released properly (e.g., shared memory or temporary files may
not be cleaned up properly in such a case. */
extern SANE_Status sane_exit (void);
/* Store a pointer to a NULL terminated array of available input
devices in *DEVICE_LIST. The returned list is guaranteed to remain
unchanged and valid until (a) another call to this function is
performed or (b) a call to sane_exit() is performed. This function
can be called repeated to detect when new devices have become
available. */
extern SANE_Status sane_get_devices (const SANE_Device *** device_list);
/* Open a device an return a handle for it. If the devicename is an
empty string, the first available device is opened (if any). */
extern SANE_Status sane_open (SANE_String_Const devicename,
SANE_Handle * handle);
/* Terminate the association between HANDLE and the device it
represents. If the device is presently active, a call to
sane_cancel() is performed. HANDLE must not be used anymore after
this call. */
extern SANE_Status sane_close (SANE_Handle handle);
/* Request the descriptor of the option with index OPTION. The number
of options supported by the device represented by HANDLE can be
determined from the value of SANE_OPT_NUM_OPTIONS, which is
guaranteed to be always a valid option. */
extern const SANE_Option_Descriptor *
sane_get_option_descriptor (SANE_Handle handle, SANE_Int option);
/* Set or inquire the current value of the option with index OPTION of
the device represented by HANDLE. ACTION specifies how the option
should be affected. VALUE is a pointer to an array of words or an
array of strings of appropriate length (see SIZE member in option
descriptor). INFO is used to return additional information on the
completion of the operation (see SANE_INFO_* declarations). If
INFO is NULL, nothing is returned.
XXX *value may change as a result of a SET_VALUE (e.g., due to
INEXACT). */
extern SANE_Status sane_control_option (SANE_Handle handle, SANE_Int option,
SANE_Action action, void *value,
SANE_Word * info);
/* Return an estimate for the scan parameters given the currently
effective options. The returned parameters are guaranteed to be
accurate only after a scan has started (sane_start()) and before
the scan has completed. Outside of that time-frame, the returned
values are best-effort estimates of what the parameters will be
when sane_start() gets invoked (this is useful, e.g., to get an
estimate of how big the scanned image will be). */
extern SANE_Status sane_get_parameters (SANE_Handle handle,
SANE_Parameters * params);
/* Start the input device operation. The parameters of the resulting
scan are returned in PARMS. */
extern SANE_Status sane_start (SANE_Handle handle);
/* Read data from the device represented by HANDLE. DATA is a pointer
to a storage area that can hold up to MAX_LENGTH bytes. The number
of bytes returned is stored in *LENGTH. The number of bytes
returned can be anywhere in the range from 0..MAX_LENGTH.
If no data is available, one of two things may happen:
(1) If the device is in blocking I/O mode (the default mode),
the call blocks until at least 1 data byte is available (or
until some error occurs).
(2) If the device is in non-blocking I/O mode, the call returns
immediately with SANE_STATUS_GOOD and with *LENGTH set to 0
(i.e., no data is returned).
See sane_set_io_mode() on how to control the I/O mode of a
handle. */
extern SANE_Status sane_read (SANE_Handle handle, SANE_Byte * data,
SANE_Int max_length, SANE_Int * length);
/* Immediately (or as quickly as possible) cancel the currently
pending operation of the device represented by HANDLE. This
function can be called at any time (as long as HANDLE is a valid
handle) but usually has an effect only when an image is being
acquired (i.e., after a call to sane_start() has been called. It
is safe to call this function asynchronously (e.g., from within a
signal handler). XXX return from this function does NOT mean
cancelled operation has stopped already. */
extern SANE_Status sane_cancel (SANE_Handle handle);
/* Set the I/O mode of HANDLE. If NON_BLOCKING is non-zero, the
handle is put into non-blocking I/O mode. A backend may elect not
to support non-blocking I/O mode. In such a case the status value
SANE_STATUS_UNSUPPORTED is returned. Note that blocking I/O must
be supported by all backends, so calling this function with
NON_BLOCKING set to zero is guaranteed to return with
SANE_STATUS_GOOD. */
extern SANE_Status sane_set_io_mode (SANE_Handle handle,
SANE_Bool non_blocking);
/* Return a filedescriptor that becomes readable when data becomes
available. If the backend does not support this operation, it
returns a status value of SANE_STATUS_UNSUPPORTED. The only
operation supported by the returned filedescriptor is a host
operating-system dependent test whether the filedescriptor is
readable (e.g., this test can be implemented using select under
Unix). If any other operation is performed on the file descriptor,
the behavior of the backend becomes unpredictable. Once the
filedescriptor signals "readable" status, it will remain in that
state until a call to 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 a
scan is in progress. */
extern SANE_Status sane_get_select_fd (SANE_Handle handle,
SANE_Int * fd);
/* Translate a SANE status value into a printable string. */
extern const SANE_String_Const sane_strstatus (SANE_Status status);