The code flow for the SANE API is illustrated in Figure 4. Functions sane_init() and sane_exit() initialize and exit the backend, respectively. All other calls must be performed after initialization and before exiting the backend.
Function sane_get_devices() can be called any time after sane_init() has been called. It returns the list of the devices that are known at the time of the call. This list may change over time since some devices may be turned on or off or a remote host may boot or shutdown between different calls. It should be noted that this operation may be relatively slow since it requires contacting all configured devices (some of which may be on remote hosts). A frontend may therefore want to provide the ability for a user to directly select a desired device without requiring a call to this function.
Once a device has been chosen, it is opened using a call to sane_open(). Multiple devices can be open at any given time. A SANE backend must not impose artificial constraints on how many devices can be open at any given time.
An opened device can be setup through the corresponding device handle using functions sane_get_option_descriptor() and sane_control_option(). While setting up a device, obtaining option descriptors and setting and reading of option values can be mixed freely. It is typical for a frontend to read out all available options at the beginning and then build a dialog (either graphical or a command-line oriented option list) that allows to control the available options. It should be noted that the number of options is fixed for a given handle. However, as options are set, other options may become active or inactive. Thus, after setting an option, it maybe necessary to re-read some or all option descriptors. While setting up the device, it is also admissible to call sane_get_parameters() to get an estimate of what the image parameters will look like once image acquisition begins.
The device handle can be put in blocking or non-blocking mode by a call to sane_set_io_mode(). Devices are required to support blocking mode (which is the default mode), but support for non-blocking I/O is strongly encouraged for operating systems such as UNIX.
After the device is setup properly, image acquisition can be started by a call to sane_start(). The backend calculates the exact image parameters at this point. So future calls to sane_get_parameters() will return the exact values, rather than estimates. Whether the physical image acquisition starts at this point or during the first call to sane_read() is unspecified by the SANE API. If non-blocking I/O and/or a select-style interface is desired, the frontend may attempt to call sane_set_io_mode() and/or sane_get_select_fd() at this point. Either of these functions may fail if the backend does not support the requested operation.
Image data is collected by repeatedly calling sane_read(). Eventually, this function will return an end-of-file status (SANE_STATUS_EOF). This indicates the end of the current frame. If the frontend expects additional frames (e.g., the individual channels in of a red/green/blue image or multiple images), it can call sane_start() again. Once all desired frames have been acquired, function sane_cancel() must be called. This operation can also be called at any other time to cancel a pending operation. Note that sane_cancel() must be called even if the last read operation returned SANE_STATUS_EOF.
When done using the device, the handle should be closed by a call to sane_close(). Finally, before exiting the application, function sane_exit() must be called. It is important not to forget to call this function since otherwise some resources (e.g., temporary files or locks) may remain unclaimed.