[sane-devel] A possible way to extend SANE API

[stef]

	Hello,

	here is the way I think the SANE API could be extended to address my two
main concerns, which are warming up notification and handling calibration of
sheet fed scanners

1 - warming up : 

	To handle warming up, we could add a sane_prepare_to_scan() function 
which would be called after sane_open() and before sane_start(). If the 
scanner is ready, it will return SANE_STATUS_GOOD. If not it will return a
SANE_PREPARATION_IN_PROGRESS status. The frontend will have then to wait until
SANE_STATUS_GOOD is returned. In order to help the frontend to generate 
a progress bar or a nice message, the function will also return the maximum
time to wait left (in seconds):
	SANE_Status sane_prepare_to_scan(SANE_Int *max_remaining_time);

	Backends that don't implement special warming up handling will only have
to return SANE_STATUS_GOOD in this function.


2 - uncalibrated scan notification :

	By extending the SANE_Parameters by adding a SANE_Bool uncalibrated_scan 
field at the end of the structure, a backend will be able to signal that a 
scan is uncalibrated. By default the field will be SANE_FALSE, and only 
backends using it will set up to SANE_TRUE. 
	By calling sane_get_parameters(), a frontend will then know if the scan is 
uncalibrated.


3 - calibration using an external target sheet:

	First there must be a mean for the frontend to know that a special
calibration process must be used. For that we could add a function like
	SANE_Status sane_get_device_features(SANE_Handle h, SANE_Features *features);
where 'h' is the handle of the opened device and 'features' a structure 
describing  optional features of the opened device. One of these fields would 
be a SANE_Bool external_calibration_target .This flag is SANE_TRUE when the 
backend needs a special calibration target to be fed in.
	The SANE_Features struct would have to be designed so that defaults 
settings can be assign for backends which don't use this.

	When the frontend detects that scans are uncalibrated and there is an
external calibration target feature. It will require the user to insert the 
special calibration sheet  and then call 
SANE_Status sane_external_target_calibration(SANE_Handle h);
	Backends that don't implement this (all backends but some sheet fed ones) 
will have a default function that only return SANE_STATUS_UNSUPPORTED .

	By keeping the changes small like proposed here, we can promote all
the backends in the source to the new revision. We could modifiy them all to
include a sane-compat.h file that brings default functions matching 
the extensions to the API.

	The binary only or external backends case can be addressed by a meta
backend based on the code of dll.c . I posted a demo patch that does this some 
weeks ago.

Regards,
	Stef