Hi,
On Fri, Dec 06, 2002 at 10:00:12AM +1100, Matthew Duggan wrote:
> Henning Meier-Geinitz <henn...@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 wasn't there when the original standard was written so I can only
guess the intention by the words written there and by the
implementation. Look at ChangeLog-1.0.0 for some info. E.g.
sane_strstatus was explicitely moved from sanei to backend.
As far as I understand, this function should really return just the
textual meaning of the SANE error codes as defined in 4.2.7. sane.h
does not contain texts for the error values so this is a simple method
for frontends to ask what they should print on the screen without
maintaining a list themselves. And it is used by the frontends this
way.
It's also used by the backends themselves for DBG messages, but that's
ok.
The interesting thing is that the most of the mssages in
sane_strstatus.c are not complete sentences so all backends are not
sane-compliant :-)
And the declation in the standard is wrong!
const SANE_String_Const sane_strstatus (SANE_Status status);
The const is too much! Looks like nobody noticed in 6 years.
> 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.
You were right, it doesn't exist. But it will exist in SANE2.
> 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,
Huh? What should they do when they don't implement it? They must
define the symbol but can't return NULL. So maybe retunr ""?
> and a default
> implementation is avaialble for use in both backends and frontends.
Don't mix the SANE standard/interface with implementation details in
the current SANE distribution.
Ok, while we are at this topic: The idea was to provide a second error
function that gives more details of the latest error.
So the frontend would call e.g. sane_start and gets back
SANE_STATUS_INVAL. It could call sane_strstatus(SANE_STATUS_INVAL) and
for further detils calls sane_verbose_error(handle). So it could print:
Invalid argument: The top-x coordinate was bigger then the bottom-x
coordinate.
The first one will be the general error type while the second one is
the more detailed one.
Proposal:
4.3.16 sane_verbose_error
This function returns a verbose description of the latest error. The
returned string consists of one or more complete sentences. It is the
responsibility of the frontend to break the string into
managable-length lines. Newline characters in this string should be
interpreted as paragraph breaks. The function is guaranteed to never
return NULL. The returned pointer is valid at least until the next
call to this function is performed.
SANE_String_Const sane_verbose_error(Sane_Handle h)
Bye,
Henning
