4.3 Operations

4.3.1 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 or if the status code returned by sane_init is different from SANE_STATUS_GOOD. 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. Argument authorize is either a pointer to a function that is invoked when the backend requires authentication for a specific resource or NULL if the frontend does not support authentication.

SANE_Status sane_init (SANE_Int * version_code,
                       SANE_Authorization_Callback authorize);

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

4.3.2 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 sane_close(), but backends are required to release all resources upon a call to this function). 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.

void sane_exit (void);

4.3.3 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 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. If argument 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.

SANE_Status sane_get_devices (const SANE_Device *** device_list,
                              SANE_Bool local_only);

4.3.4 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 name. If the call completes successfully, a handle for the device is returned in *h. The description of the device is returned in **device_description. This is the same description that is returned in the list by sane_get_devices. The returned data *h and *device_description is guaranteed to remain unchanged and valid until a call to sane_close() is performed. As a special case, specifying a zero-length string as the device requests opening the first available device (if there is such a device).

SANE_Status sane_open (SANE_String_Const name, SANE_Handle * h,
const SANE_Device ** device_description);

4.3.5 sane_close

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.

void sane_close (SANE_Handle h);

4.3.6 sane_get_option_descriptor

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. The returned option descriptor is guaranteed to remain valid (and at the returned address) until the device is closed.

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

4.3.7 sane_control_option

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.

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.

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 option value 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.

SANE_STATUS_ACCESS_DENIED:

Access to the option has been denied due to insufficient or invalid authentication.

4.3.8 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 (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_Int flags;
    SANE_Int lines;
    SANE_Int depth;
    SANE_Int pixels_per_line;
    SANE_Int bytes_per_line;
    SANE_Int channels_per_image;
    SANE_String format_desc;
    SANE_String proposed_filename;
    SANE_String proposed_comment;
    SANE_Int dpi_x;
    SANE_Int dpi_y;
    char reserved[32]; /* 32 bytes for future use */
  }
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. The meaning of these values is described in more detail in section 3.2. The frame types used by version 1 of this standard (SANE_FRAME_GRAY, SANE_FRAME_RGB, SANE_FRAME_RED, SANE_FRAME_GREEN, and SANE_FRAME_BLUE) are obsolete and superseded by the frame type SANE_FRAME_RAW.

Note, that flags is compatible to member last_frame of SANE_Parameters of SANE standard version 1 (same size and only bit 0 (bitvalue 1) was used with same function).

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. Note, that even when transferring formats that have this information inband, it is recommended to set that member, if available. If unavailable or not applicable, set to -1 as mentioned above.

Member bytes_per_line specifies the number of bytes that comprise one scan line. If this value is not applicable for image data of type SANE_FRAME_MIME, it must be set to -1. In this case the frontend should just call sane_read until SANE_STATUS_EOF is returned.

Member depth specifies the number of bits per sample. Note, that only -1 (for not applicable), 1, and multiples of 8 are allowed values. Data with other depths has to be scaled up accordingly. Depth 1 is only allowed if the image consists of a single channel (lineart or halftone modes).

Member pixels_per_line specifies the number of pixels that comprise one scan line. If unavailable or not applicable, set to -1.

Assume B is the number of channels in the frame, then the bit depth d (as given by member depth) and the number of pixels per line n (as given by this member pixels_per_line) are related to c, the number of bytes per line (as given by member bytes_per_line) as follows:

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.

Member channels_per_image specifies the number of channels the image consists of. When the image is transmitted in more than one frame channels_per_image has to be the same for all frames for this image.

Member format_desc is used to describe the details of the frame formats. Its meaning differs between the two formats:

• SANE_FRAME_RAW: The format_desc contains a description of the channel data and an optional depth information separated by a colon(:).

  A plane is descibed by one channel, e.g. ``gray'' or ``gray:12''.

  Channel interleaved data is described by a comma separated list of channel descriptions, for example ``red,green,blue'' or ``red:8,green:8,blue:8'', the channel data is sent in the given order.

  The depth information does not define the size of the transmitted channel data, it is only an information for the frontend. The channel data has to be sent in the size defined by member depth.

  Well known channels are red, green, blue and gray. It also is allowed to use other channel descriptions, e.g. if you use an infrared camera or scanner it could be infrared or a wavelength description like 1100nm, but be aware that a frontend may not be able to display such channels with useful colors.

  Note that an image can be sent in single planes, in one interleaved frame that contains all channels or in several frames that contain one or more (interleaved) channels. When an RGB image is sent it is prefered to send the image data in one interleaved frame that consist of red, green and blue data in this order. The number of channels is defined in member channels_per_image.

• SANE_FRAME_MIME:

  format_desc contains the MIME Content-Type: header field as described in RFC 1521 (section 4) without the prefixing "Content-Type:". MIME Types and subtypes should be either chosen from the RFC or from the list of IANA-approved values. The data stream must be compliant with the corresponding specification.

  When data is transmitted with the frame type SANE_FRAME_MIME all data has to be transmitted within one frame, multiple frames are not allowed (so the flag last_frame has to be set when using this frame type).

  A SANE backend must be able to at least optionally transmit SANE_FRAME_RAW (possibly with the help of a meta backend), if the hardware supports delivering image data at all. For data that doesn't comprise images, it's admisable to only provide MIME frames. As a general principle, if there are several choices in MIME types, the format that is most widely implemented should be used.

The member reserved is an array of 32 bytes (char) to keep the size of the struct unchanged when future extensions are done. The backend has to set the reserved bytes to 0.

4.3.9 sane_start

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

SANE_Status sane_start (SANE_Handle h);

SANE_STATUS_CANCELLED:

The operation was 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.

SANE_STATUS_INVAL:

The scan cannot be started with the current set of options. The frontend should reload the option descriptors, as if SANE_INFO_RELOAD_OPTIONS had been returned from a call to sane_control_option(), since the device's capabilities may have changed.

4.3.10 sane_read

This function is used to read image data 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. A backend must set this to zero when a status other than SANE_STATUS_GOOD is returned). When the call succeeds, 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);

4.3.11 sane_cancel

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

void sane_cancel (SANE_Handle h);

4.3.12 sane_set_io_mode

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. This function can be called only after a call to sane_start() has been performed.

SANE_Status sane_set_io_mode (SANE_Handle h, SANE_Bool m);

4.3.13 sane_get_select_fd

This function is used to obtain a (platform-specific) file-descriptor for handle h that is readable if and only if image data is 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);

4.3.14 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 NULL. The returned pointer is valid at least until the next call to this function is performed.

SANE_String_Const sane_strstatus (SANE_Status status);