[sane-devel] Proposal: SANE standard additions/fixes

[Henning Meier-Geinitz]

Hi,

While I'm working on this topic some more small issues that got lost
somehow after older discussions. These are proposals for SANE 1. From
TODO:

1) What happens when sane_init returns a status other than
   SANE_STATUS_GOOD?

That's not defined but we should state that explicitely.

The standard reads:

| 4.3.1 sane_init
| This function must be called before any other SANE function can be
| called. The behavior of a SANE backend is undefined if this function
| is not called first. The version code of the backend is returned in
| the value pointed to by version_code. If that pointer is NULL, no
| version code is returned. Argument authorize is either a pointer to a
| function that is invoked when the backend requires authentication for
| a specific resource or NULL if the frontend does not support
| authentication.

I propose to add "or if the returned status code is different from
SANE_STATUS_GOOD" after the second sentence resulting in:

"This function must be called before any other SANE function can be
called. The behavior of a SANE backend is undefined if this function
is not called first or if the returned status code is different from
SANE_STATUS_GOOD. The version code of the backend is returned in the
value pointed to by version_code. If that pointer is NULL, no version
code is returned. Argument authorize is either a pointer to a function
that is invoked when the backend requires authentication for a
specific resource or NULL if the frontend does not support
authentication."


2) Concerning sane_get_select_fd: It's not that easy to implement the
   select fd correctly in frontends and backends. For frontends the
   problem is, that not only the readable status has to be cheked but
   also if the fd was closed. E.g. using a gdk_input will not work
   because it won't detect the closing of the file descriptor by the
   backend and waits forever.
   
   So if you use select you have to check the return value of select
   if the fd was closed (that means EOF in the next call to SANE_READ)
   and so you can call sane_cancel. If no error occured, check if the
   fd is readable. If yes, run sane_read, otherwise wait.
   
   Maybe we can add a "frontend implementation note" for that one.
   I don't know how to write this exactly, maybe Oliver?
   
3) Defining the meaning of SANE_CAP_ADVANCED for option groups.
   The current usage of SANE_CAP_ADVANCED for option groups is that
   all the options are advanced even if it's not mentioned in the
   standard. At least xsane has this behaviour.

   Should we state this explicitely? What happens if some options in a
   group are adavanced an some are not? Shall the backend display two
   groups?
   
   Or should only groups be allowed to use SANE_CAP_ADVANCED? Or only
   normal options?
   
   Or all the options in a group and the group itsself must be either
   advanced or not but not mixed?

4) Return status of sane_start:

The standard reads:

| 4.3.9 sane_start
| This function initiates aquisition of an image from the device
| represented by handle h.
| 
| SANE_Status sane_start (SANE_Handle h);
| 
| This function may fail with one of the following status codes.
|
| SANE_STATUS_CANCELLED:
| The operation was cancelled through a call to sane_cancel.
| 
| SANE_STATUS_DEVICE_BUSY:
| The device is busy. The operation should be retried later.
| 
| SANE_STATUS_JAMMED:
| The document feeder is jammed.
|
| SANE_STATUS_NO_DOCS:
| The document feeder is out of documents.
| 
| SANE_STATUS_COVER_OPEN:
| The scanner cover is open.
| 
| SANE_STATUS_IO_ERROR:
| An error occurred while communicating with the device.
| 
| SANE_STATUS_NO_MEM:
| An insufficent amount of memory is available.

I propose to add:

" SANE_STATUS_INVAL
The scan can't be started with the current set of options."

The reason is, that this is the only way to handle case whe TL_X >
BR_X without breaking graphical frontends. Other reasons may be that
the TA was turned off in the meantime or similar.


5) sane_set_io_mode

The description is unclear concerning the meaning of
SANE_STATUS_UNSUPPORTED and the time when it's allowed to call it.

The standard reads:

| 4.3.12 sane_set_io_mode
| 
| This function is used to set the I/O mode of handle h. The I/O mode
| can be either blocking or non-blocking. If argument m is SANE_TRUE,
| the mode is set to non-blocking mode, otherwise it's set to blocking
| mode.

[...]

| This function may fail with one of the following status codes:
|
| SANE_STATUS_INVAL:
| No image acquisition is pending.
|
| SANE_STATUS_UNSUPPORTED:
| The backend does not support this operation.

I propose the following changes:

"This function is used to set the I/O mode of handle h. The I/O mode
can be either blocking or non-blocking. If argument m is SANE_TRUE,
the mode is set to non-blocking mode, otherwise it's set to blocking
mode. This function can be called only after a call to sane_start()
has been performed."

[...]

"This function may fail with one of the following status codes:

SANE_STATUS_INVAL:
No image acquisition is pending.

SANE_STATUS_UNSUPPORTED:
The backend does not support the requested I/O mode."


Ok, that's it. The button issue was discuessed in another thread
already.


Please comment (also on spelling/grammar).

Bye,
  Henning