[sane-devel] SANE V2

[Matthew Duggan]

Hi,

Henning Meier-Geinitz <henning at meier-geinitz.de> wrote:
> > 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.
>

Although this may have been the original intent, it's not how the
function has been used in *any* of the backends - probably due to the
vague wording of the original.  I think the information deserves
clarification.  As a backend author I had been looking for a function to
allow me to return more detailed error messages (rather than just "I/O
Error"), but it didn't seem to exist.  Perhaps to make the intended use
more clear, it needs to say something like:

--------------------
  sane_strstatus

This function can be used to translate a SANE status code into a
printable string. The returned string is a single line of text that
forms a complete sentence, but without the trailing period (full-stop).
The function is guaranteed to never return NULL. The returned pointer is
valid at least until the next call to this function is performed.   This
function is optional for backends to implement, and a default
implementation is avaialble for use in both backends and frontends.  If
a backend implements this function, it should provide more detailed
information about the current status of the device than the default
implementation.  This information may be device-dependent, and should
assist users in diagnosing the real problem, e.g. "lp0 is on fire".

const SANE_String_Const sane_strstatus (SANE_Status status);

-------------------

Ok, so that example doesn't neccessarily assist users in diagnosing the
problem, but you get the idea.

- Matthew