LibInsane: Normalized C scan API (aka the solutions)

| LibInsane 1.0.10 Cross-platform Cross-API Cross-driver Cross-image-scanner Image Scan Library

Loading...
Searching...
No Matches
Normalized C scan API (aka the solutions)

# 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:

- Wrapper for libsane API
- Wrapper for WIA2 low-level API
- Wrapper for TWAIN API
- Various wrappers that allow working transparently around bugs
- Various wrappers that normalize the behaviors of scanners and drivers from an application standpoint

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;
}
capi.h
error.h
lis_error
lis_error
Definition error.h:13
normalizers.h
lis_api_normalizer_source_nodes
enum lis_error lis_api_normalizer_source_nodes(struct lis_api *to_wrap, struct lis_api **out_impl)
Ensure that sources are represented as node.
lis_api_normalizer_min_one_source
enum lis_error lis_api_normalizer_min_one_source(struct lis_api *to_wrap, struct lis_api **out_impl)
Ensure there is at least one source.
lis_api_normalizer_all_opts_on_all_sources
enum lis_error lis_api_normalizer_all_opts_on_all_sources(struct lis_api *to_wrap, struct lis_api **out_impl)
Ensure all options are available on sources.
sane.h
lis_api_sane
enum lis_error lis_api_sane(struct lis_api **api)
Wraps the Sane API into the LibInsane API.
lis_api
LibInsane C API.
Definition capi.h:422
workarounds.h
lis_api_workaround_opt_values
enum lis_error lis_api_workaround_opt_values(struct lis_api *to_wrap, struct lis_api **out_impl)
Replace unusual option values by usual ones.
lis_api_workaround_opt_names
enum lis_error lis_api_workaround_opt_names(struct lis_api *to_wrap, struct lis_api **out_impl)
Fix options names.