[sane-devel] [RFC] how to enable 1.1 features

[Olaf Meeuwissen]

Alessandro Zummo <azummo-lists at towertech.it> writes:

>   please see the attached patch regarding my proposal
>  for a safe enabling of 1.1 features in the backends.
>
> [snip]
> --- sane-backends.orig/include/sane/sane.h	2008-02-26 00:07:40.000000000 +0100
> +++ sane-backends/include/sane/sane.h	2008-02-26 00:19:29.000000000 +0100
> @@ -31,6 +31,8 @@ extern "C" {
>     | (((SANE_Word) (minor) &   0xff) << 16)	\
>     | (((SANE_Word) (build) & 0xffff) <<  0))
>  
> +#define SANE_VERSION(major,minor) (SANE_VERSION_CODE(major, minor, 0))
> +
>  #define SANE_VERSION_MAJOR(code)	((((SANE_Word)(code)) >> 24) &   0xff)
>  #define SANE_VERSION_MINOR(code)	((((SANE_Word)(code)) >> 16) &   0xff)
>  #define SANE_VERSION_BUILD(code)	((((SANE_Word)(code)) >>  0) & 0xffff)

Hmm, the SANE Standard Version 1.03 says about SANE_VERSION_CODE():

  Note that the major version number alone determines whether a
  frontend/backend pair is compatible.  The minor version and the
  build revision are used for informational and bug-fixing purposes
  only.

This means that a backend implementer is free to pass back something
like

  SANE_VERSION_CODE(1,2,3)

for a SANE 1.0 backend.  Isn't that a bit confusing?  I think that
just changing the name of the macro to something like SANE_API_LEVEL
would improve code readability and reduce confusion.

> [snip]
> --- /dev/null	1970-01-01 00:00:00.000000000 +0000
> +++ sane-backends/doc/sane-11-frontends-howto.txt	2008-02-27 22:03:31.000000000 +0100
> @@ -0,0 +1,27 @@
> +A quick SANE 1.1 guide for frontend authors
> +===========================================
> +
> +If, and only if, a frontend wants to enable 1.1 features
> +in a backed, the following procedure SHOULD be used:
> +
> +
> +	SANE_Int sane_version;
> +	sane_init(&sane_version, NULL);
> +
> +	if (sane_version >= SANE_VERSION(1,1)) {
> +		SANE_Int version = SANE_VERSION(1,1);
> +		result = sane_control_option(handle, 0, SANE_ACTION_COMPAT_LEVEL,
> +			&version);
> +	}
> +
> +
> +If the backed returns SANE_STATUS_GOOD to that sane_control_option
> +call, the frontend knows that the backend correctly handles any
> +SANE 1.1 feature.

The same SANE Standard Version 1.03 does not explicitly state what a
backend is supposed to return when passed and unknown action.  I'd
assume that any sane developer would return SANE_STATUS_UNSUPPORTED
but I wouldn't quite bet on it.

Another issue I have with the SANE_ACTION_COMPAT_LEVEL symbol is that
I don't think of that as an action.  A symbol more action-like, like
SANE_ACTION_CHECK_API_LEVEL for example, is clearer IMHO.


Apart from the above (and the fact that it is an ugly hack as SANE 1.0
surely didn't intend to provide for API major/minor versions ;-), the
above would work fine in practice.

Hope this helps,
-- 
Olaf Meeuwissen             FLOSS Engineer -- EPSON AVASYS Corporation
FSF Associate Member #1962           sign up at http://member.fsf.org/