[sane-devel] [RFC] how to enable 1.1 features
Olaf Meeuwissen
olaf.meeuwissen at avasys.jp
Wed Feb 27 23:43:26 UTC 2008
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/
More information about the sane-devel
mailing list