Next Up Previous Contents

4.3 Operations

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);


Next Up Previous Contents