[sane-devel] SANE V2

[Henning Meier-Geinitz]

Hi,

On Wed, Dec 04, 2002 at 11:08:31AM +0100, Enno Fennema wrote:
> I would like to make some comments on the SANE 2.06 draft standard.

Thanks for your comments. I hope I can put some more time into SANE2
during the next days.

> They represent my personal preferences and proposals and are offerered
> for discussion but rather than prefixing each statement with 'I
> think...' 'I propose...' etc. 

Same here.

> 1)
> One preliminary question: Who does turn the switch when and decide to go
> to version 2.0 ?

Well, "we" do :-) But I don't think there will be a hard switch. My
idea is to finish the standard at least to a degree, where all the
wishlist items are included and all major bugs are fixed. Then coding
for the core elements can begin. This will be a completely different
source tree, no code is just copied from sane1 to avoid keeping old
cruft. The first thing to do is probably to alow some testing with
scanimage and a test backend. Then, if there are maintainers, the
backends are ported.

There is no hard switch because it's planned to write a "bridge"
meta backend that allows SANE2-frontends to communicate with SANE1
backends. So SANE1 will be around some time and may be updated, e.g.
if severe errors are found.

> 2) SANE_Handle
> A SANE_Handle points to a very important structure, viz.

As Oliver, I don't like this approach. It completely changes the way
SANE works and I'm not sure if the reduction in parameters really buys
us anything.

> This also obviates the fiddling of backend related names and looking
> them up after dynamically loading a backend. 
> Now only lookup the backend name, which returns the address of the
> handle through which all backend functions can be accessed.

That's an advantage, but well, the existing code works.

> Each backend has exactly one struct SANE_HANDLE with the backend name as
> name. This allows the frontend or meta backend to know how to get the
> address of the handle of a backend with dlsym().

As far as I know, the standard aloows to open more than one device
simultaneously (or am I wrong?) This isn't used currently by any
frontend however.

> 2) SANE_Device
> 
> typedef struct SANE_Device {
>     struct SANE_Device *next;
>     SANE_String_Const name;	/* unique device name */
>     SANE_String_Const vendor;	/* device vendor string */
>     SANE_String_Const model;	/* device model name */
>     SANE_String_Const type;	/* device type (e.g., "flatbed scanner") */
>     SANE_String       devname;	/* from sane.conf eg. /dev/usbscanner0 */ 
> }	SANE_Device;
> 
> 
> <<
> next pointer: If sane_get_devices() returns a list of devices rather
> than an array it is easier for a meta-backend to string all those lists
> together.
>
> When enquiring into models managed by a particular backend
> sane_get_devices need only return the pointer to the first device
> managed by it, assuming that in the backend they are also linked into a
> list.

Sounds reasonable. Are there any compatibility issues with SANE1?

> devname: How to open the device with an operating system dependent way.
> See also comments on config file.

Why should the frontend know about the real device name? The frontend
mustn't touch the device anyway.

> I have no serious problems with all the other fields proposed already
> but am worried that you may be going overboard with detail  like which
> floor the printer is on and e-mail addresses.

It's ok to have the email address and webpage because that's an easy
way to contact the maintainer if anything goes wrong.

I would name it "email_backend_maintainer" because that's the one who
wants to get email. The orginal author may have been lost since years...

I also would only recommend the addition of a webpage/ftp location
("should", not "must") jsut because not every simple backend has one.

As the device location and comment strings are optional, I don't think
they cause any harm.

We should define that all strings that are not uses are set to "".

> Most people use only very few scanners and they know which one is which.
> >>

True, but then they just won't use the feature. No need to remove it.

> 4) sanei
> Probably stands for SANE Internal ???.

Yes.

> The available functions, even though their use appears to be optional,
> deserve some documentation.

http://sanei.meier-geinitz.de/

The SANE standard defines the interface between frontends and
backends. While it explains implementation details sometimes, it
should not comment on such helper functions. In my opinion the
standard already provides too much backend/frontend implementation
stuff that isn't strictly necessary and doesn't touch the interface at
all. I'll comment on the details later this week.

> In my view sane_strstatus() is a sanei_ rather than a sane_ function.

It's an interface between the frontend and the backend. The frontend
asks the backend about the textual meaning of an error.
The function is also used in the backends but the idea is to use it in
frontends.

> 5) Option descriptor
> Include a one-character shortname for common options to be used by eg.
> get_opt_long().

That's an implementation detail. Most frontends don't even know what
short options are. And further more, the backend can't know which
short options already in use by the frontend. The same is true with
long options, but the risk of clashes is lower.

> Is there any point in including a SANE_Value (union word, fixed, char*)
> in an option descriptor
> containing the current value? Not quite sure myself/not very important.

I don't think so. That's why we have sane_control_option().

> 6) Configuration files
> Agree a format for a standard /etc/sane.conf file. 

Only over my dead body :-)

One of the problems with such files is that updating only one or
adding backends is complicated. And one mistake in the format can
break all other backends.

Also I don't like editing long config files. We have about 50 backends
that all would need sections in this file.

Keep in mind that ideally configuration files shouldn't not be used.
That means, that the backend should autodetect any device. Well, the
world is not perfect, but that's the goal.

> Could by commandline option use other path, etc.

SANE_CONFIG_DIR=/opt/etc/sane.d/ already works.

> Backends need at least a method to derive the name of the device as used
> by the operating system but could benefit from some configuration
> information, calibration settings etc.

You mean frontends? Backends should know hat they are doing. There
shouldn't be a hidden path to communicate between backends and/or
frontends. This will cause trouble...

> My preferred format is somewhat like Windows ini files.

Uh! :-)

> Each line consists of a number of words. 
> Words are essentially characters separated by white space.
> White space is a space, a tab, a newline or carriage return.
> Characters, including whitespace, enclosed in double quotes are treated
> as one word.

These rules are already used in current config files.

> The first word on each line is the type of configuration data. Standard
> lines could be:
> 
>     scanner <name> <backend> <opsysname>
> 
> eg. scanner "Canon N656U" canonusb /dev/usbscanner0

/dev/usbscanner0 and other hardwired device files should be avoided
anyway. They are only used when autodetection doesn't work.

You are right concerning config file rules, however. It's an
implementation detail, so it won'z go in the standard but e.g. to
backend-writing.txt. Maybe also sane_config can have more code. E.g.
ignoring everything that starts with a "#" so we don't need to do this
check in every backend.

Some things that could be standardized:

[usb]
--> all following devices are usb (same for SCSI etc)

usb vendor device
scsi VENDOR MODEL TYPE BUS CHANNEL ID LUN
--> already define in man pages. Should be used everywhere.

device-vendor string
device-model string
device-location string
device-comment string
(or similar)
--> to overwrite the backend's default values, e.g. for rebadged scanners

device /some/device/name
--> to define a hardwired device name if autodetection doesn't work

port 0x432
--> to set a port number for parport scanners if autodetection doesn't
    work

Bye,
  Henning