Next Up Previous Contents Index

4.3 Operations

Operations

4.3.1 sane_init

<tt>sane_init</tt>

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 version_code. If that pointer is NULL, no version code is returned.

SANE_Status sane_init (SANE_Int * version_code);

4.3.2 sane_exit

<tt>sane_exit</tt>

This function must be called to terminate use of a backend. It must not be called before all device handles have been called. After this function returns, no function other than sane_init() may be called (regardless of the status value returned by sane_exit(). Neglecting to call this function may result in some resources not being released properly.

SANE_Status sane_exit (void);

4.3.3 sane_get_devices

<tt>sane_get_devices</tt>

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 NULL terminated array of pointers to SANE_Device structures 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 repeatedly to detect when new devices become available.

SANE_Status sane_get_devices (const SANE_Device *** device_list);

This function may fail with 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 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.

4.3.4 sane_open

<tt>sane_open</tt>

This function is used to establish a connection to a particular device. The name of the device to be opened is passed in argument name. If the call completes successfully, a handle for the device is returned in *handle. As a special case, an empty device name requests opening the first available device (if there is such a device).

SANE_Status sane_open (SANE_String_Const name, SANE_Handle * h);

This function may fail with one of the following status codes.

SANE_STATUS_DEVICE_BUSY:
The device is currently busy (in use by somebody else).
SANE_STATUS_INVAL:
The device name is not valid.
SANE_STATUS_IO_ERROR:
An error occured while communicating with the device.
SANE_STATUS_NO_MEM:
An insufficent amount of memory is available.

4.3.5 sane_close

<tt>sane_close</tt>

This function terminates the association between the device handle passed in argument h and the device it represents. If the device is presently active, a call to sane_cancel() is performed first. After this function returns, handle h must not be used anymore.

SANE_Status sane_close (SANE_Handle h);

4.3.6 sane_get_option_descriptor

<tt>sane_get_option_descriptor</tt>

This function is used to access option descriptors. The function returns the option descriptor for option number n of the device represented by handle 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 h (the count includes option 0). If n is not a valid option index, the function returns NULL.

const SANE_Option_Descriptor *
    sane_get_option_descriptor (SANE_Handle h, SANE_Int n);

4.3.7 sane_control_option

<tt>sane_control_option</tt>

This function is used to set or inquire the current value of option number n of the device represented by handle h. The manner in which the option is controlled is specified by parameter a. The possible values of this parameter are described in more detail below. The value of the option is passed through argument v. It is a pointer to the memory that holds the option value. The memory area pointed to by v must be big enough to hold the entire option value (determined by 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 v may be shorter since the backend will stop reading the option value upon encountering the first NUL terminator in the string. If argument i is not NULL, the value of *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.

SANE_Status sane_control_option (SANE_Handle h, SANE_Int n,
                                 SANE_Action a, void *v,
                                 SANE_Int * i);

The way the option is affected by a call to this function is controlled by parameter a which is a value of type SANE_Action. The possible values and their meaning is described in Table 7.

Symbol Code Description

SANE_ACTION_GET_VALUE

0 Get current option value.

SANE_ACTION_SET_VALUE

1 Set option value. Note that the passed value may be changed by the backend if the value cannot be set exactly.

SANE_ACTION_SET_AUTO

2 Turn on automatic mode. Backend or device will automatically select an appropriate value. This mode remains in effect until overridden by an explicit set value request.

Table 7:Action Values (SANE_Action)

After setting a value via an action value of SANE_ACTION_SET_VALUE, additional information on how well the request has been met is returned in *i (if i is non-NULL). The returned value is a bitset that may contain any combination of the values described in Table 8.

Symbol Code Description

SANE_INFO_INEXACT

1 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 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 *i 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.

SANE_INFO_RELOAD_OPTIONS

2 The setting an option may affect the value or availability of other options. When this happens, the SANE backend sets this member in *i to indicate that the application should reload all options. Note that this member may be set even if no other option changed. However, it is guaranteed that other options never change without this member being set.

SANE_INFO_RELOAD_PARAMS

4 The setting of an option may affect the parameter values (see sane_get_parameters()). If setting an option affects the parameter values, this member will be set in *i. 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.

Table 8:Additional Information Returned When Setting an Option

This function may fail with one of the following status codes.

SANE_STATUS_UNSUPPORTED:
The operation is not supported for the specified handle and option number.
SANE_STATUS_INVAL:
The device name is not valid.
SANE_STATUS_IO_ERROR:
An error occured while communicating with the device.
SANE_STATUS_NO_MEM:
An insufficent amount of memory is available.

4.3.8 sane_get_parameters

<tt>sane_get_parameters</tt>

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 (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 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 h of the device for which the parameters should be obtained and a pointer p to a parameter structure. The parameter structure is described in more detail below.

SANE_Status sane_get_parameters (SANE_Handle h,
                                 SANE_Parameters * p);

The scan parameters are returned in a structure of type SANE_Parameters. The C declaration of this structure is given below.

typedef struct
  {
    SANE_Frame format;
    SANE_Bool first_frame;
    SANE_Int bytes_per_line;
    SANE_Int pixels_per_line;
    SANE_Int lines;
    SANE_Int depth;
  }
SANE_Parameters;

Member format specifies the format of the next frame to be returned. The possible values for type SANE_Frame are described in Table 9.

Symbol Code Description

SANE_FRAME_GRAY

0 Band covering human visual range.
SANE_FRAME_RGB 1 Pixel-interleaved red/green/blue bands.
SANE_FRAME_RED 2 Red band of a red/green/blue image.
SANE_FRAME_GREEN 3 Green band of a red/green/blue image.
SANE_FRAME_BLUE 4 Blue band of a red/green/blue image.

Table 9:Frame Format (SANE_Frame)

Member first_frame is set to SANE_TRUE if and only if the next frame to be transmitted is the first frame of a multi frame image (e.g., the next frame is the red component of a red, green, blue image).

Member bytes_per_line specifies the number of bytes that comprise one scan line.

Member pixels_per_line specifies the number of pixels that comprise one scan line. This value multiplied by the number of bands in this frame and the number of bits per sample must be less than or equal to the value of bytes_per_line.

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 sane_read() until it returns a status of SANE_STATUS_EOF.

Member depth specifies the number of bits per sample. This value multiplied by the number of bands in the frame gives the number of bits in each pixel.

Please refer to Section 3.2 for a detailed description of the SANE image model.

4.3.9 sane_start

<tt>sane_start</tt>

This function initiates aquisition of an image from the device represented by handle h.

SANE_Status sane_start (SANE_Handle h);
This function may fail with one of the following status codes.
SANE_STATUS_CANCELLED:
The operation code cancelled through a call to sane_cancel.
SANE_STATUS_DEVICE_BUSY:
The device is busy. The operation should be retried later.
SANE_STATUS_JAMMED:
The document feeder is jammed.
SANE_STATUS_NO_DOCS:
The document feeder is out of documents.
SANE_STATUS_COVER_OPEN:
The scanner cover is open.
SANE_STATUS_IO_ERROR:
An error occurred while communicating with the device.
SANE_STATUS_NO_MEM:
An insufficent amount of memory is available.

4.3.10 sane_read

<tt>sane_read</tt>

This function is used to read image from the device represented by handle h. Argument buf is a pointer to a memory area that is at least maxlen bytes long. The number of bytes returned is stored in *len. The number of bytes returned can be anywhere in the range from 0 to maxlen bytes.

SANE_Status sane_read (SANE_Handle h, SANE_Byte * buf,
                       SANE_Int maxlen, SANE_Int * len);
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 h.
  1. 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).

  2. If the device is in non-blocking I/O mode, the call returns immediately with status SANE_STATUS_GOOD and with *len set to zero.
The I/O mode of handle h can be set via a call to sane_set_io_mode().

This function may fail with one of the following status codes.

SANE_STATUS_CANCELLED:
The operation code cancelled through a call to sane_cancel.
SANE_STATUS_EOF:
No more data is available for the current frame.
SANE_STATUS_JAMMED:
The document feeder is jammed.
SANE_STATUS_NO_DOCS:
The document feeder is out of documents.
SANE_STATUS_COVER_OPEN:
The scanner cover is open.
SANE_STATUS_IO_ERROR:
An error occurred while communicating with the device.
SANE_STATUS_NO_MEM:
An insufficent amount of memory is available.

4.3.11 sane_cancel

<tt>sane_cancel</tt>

This function is used to immediately or as quickly as possible cancel the currently pending operation of the device represented by handle h.

SANE_Status sane_cancel (SANE_Handle h);
This function can be called at any time (as long as handle 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 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.

4.3.12 sane_set_io_mode

<tt>sane_set_io_mode</tt>

This function is used to set the I/O mode of handle h. The I/O mode can be either blocking or non-blocking. If argument m is SANE_TRUE, the mode is set to non-blocking mode, otherwise it's set to blocking 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 SANE_STATUS_UNSUPPORTED is returned. Blocking I/O must be supported by all backends, so calling this function with argument m set to SANE_FALSE is guaranteed to complete successfully.

This function can be called only after a call to sane_start has been performed and the I/O mode is guaranteed to remain unchanged for the duration of the current image acquisition (i.e., until sane_cancel or sane_start get called again or until sane_read returns with status SANE_STATUS_EOF).

This function may fail with one of the following status codes:

SANE_STATUS_INVAL:
No image acquisition is pending.
SANE_STATUS_UNSUPPORTED:
The backend does not support this operation.

4.3.13 sane_get_select_fd

<tt>sane_get_select_fd</tt>

This function is used to obtain a (platform-specific) file-descriptor for handle h that becomes readable when image data becomes available (i.e., when a call to sane_read() will return at least one byte of data). If the call completes successfully, the select file-descriptor is returned in *fd.

SANE_Status sane_get_select_fd (SANE_Handle h, SANE_Int *fd);
This function can be called only after a call to sane_start has been performed and the returned file-descriptor is guaranteed to remain valid only for the duration of the current image acquisition (i.e., until sane_cancel or sane_start get called again or until sane_read returns with status SANE_STATUS_EOF).

A backend may elect not to support this operation. In such a case, the function returns with status code 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 select() 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 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:

SANE_STATUS_INVAL:
No image acquisition is pending.
SANE_STATUS_UNSUPPORTED:
The backend does not support this operation.

4.3.14 sane_strstatus

<tt>sane_strstatus</tt>

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 NULL.

const SANE_String_Const sane_strstatus (SANE_Status status);


Next Up Previous Contents Index