Description

LibInsane has one C API. It is designed so it can wrap the Sane API, the WIA API, or the TWAIN API without losing too many features.

This API is implemented by a variety of components:

The function lis_safebet() stacks all the recommended implementations. It is your recommended entry point to LibInsane. Since all the components implement the same API, you can simply use the one provided by lis_safebet() without ever worrying about which components are actually used.

Expected use of LibInsane

Expected order of calling when most of the normalizers are enabled:

impl = lis_safebet()
impl->list_devices()
dev = impl->get_device()
- sources = dev->get_children()
  - options = sources[a]->get_options()
    - options[x]->fn.get_value().
    - options[x]->fn.set_value().
      Option that should always be set by the application:
      - scan resolution (option "resolution")
    - options[y]->fn.get_value().
    - options[y]->fn.set_value().
    - options[z]->fn.get_value().
    - options[z]->fn.set_value().
  - scan_session = sources[a]->scan_start()
    From this point and until lis_scan_session::end_of_feed return true, scan_session->cancel() can be called at any moment.
  - scan_session->get_scan_parameters()
  - while not scan_session->end_of_feed():
    - while not scan_session->end_of_page():
      - scan_session->scan_read().
- dev->close()
cleanup()

See capi.h.

Usage examples

Scanning

See quickstart.

Stacking API implementations

If you don't want to use lis_safebet, you can stack the API implementations yourself.

Please note that you should use lis_safebet in most applications. There shouldn't be any reason not to use it. Don't hesitate to report a bug if lis_safebet doesn't work for you.

Once you have wrapped an implementation with another, you don't have to worry about the first implementation. The wrapping one will take care of the wrapped one.

Quick and lazy example:

#include <libinsane/capi.h>
#include <libinsane/error.h>
#include <libinsane/normalizers.h>
#include <libinsane/sane.h>
#include <libinsane/workarounds.h>
 
struct lis_api *lets_stack(void)
{
    struct lis_api *impl;
    enum lis_error err;
 
    CHECK_ERR(lis_api_sane(&impl));
    CHECK_ERR(lis_api_workaround_opt_scan_resolution(impl, &impl));
    CHECK_ERR(lis_api_workaround_opt_names(impl, &impl));
    CHECK_ERR(lis_api_workaround_opt_values(impl, &impl));
    CHECK_ERR(lis_api_normalizer_source_nodes(impl, &impl));
    CHECK_ERR(lis_api_normalizer_min_one_source(impl, &impl));
    CHECK_ERR(lis_api_normalizer_all_opts_on_all_sources(impl, &impl));
 
    // impl is ready to roll
    return impl;
}