[sane-standard] preliminary protocol doc

[Henning Meier-Geinitz]

Hi,

Could you resend your response to sane-standard? I think I got it only
by persoanl mail, not over the list.

On Mon, Oct 18, 2004 at 10:33:35PM +0200, Johannes Berg wrote:
> On Mon, 2004-10-18 at 20:21 +0200, Henning Meier-Geinitz wrote:
> > Some comments. Mostly by reading the standard and the code. I haven't
> > tested anything so I may be wrong.
> 
> Whew. Thanks :)
> 
> I've done all this by reading the saned code, so if I say that something
> the standard says "dummy" to is 0, then that's because 0 is sent. I'm
> not trying to claim that I was documenting the standard, I was only
> observing. Maybe I should clarify.

I have understood that but I wanted to avoid that someone depends on
the values of the dummies.

> > > === SANE_NET_GET_DEVICES ===
> > > This message causes the network daemon to enumerate all devices it can
> > > access.
> > 
> > enumerate?
> 
> Am I misunderstanding this? It is handing out a list of devices.

I'm not a native English speaker so I may misunderstand the meaning of
"enumerate". I thought the meaning of "enumerate" is to give something
numbers. And I think that's not the case here, it's just a list.
Anyway, it doesn't really matter.

> > > ==== request ====
> > >  nothing but the procedure code
> > > 
> > > ==== reply ====
> > >  TODO 
> > 
> > *((* SANE_Device)[])
> > 
> > I hope I got the brackets right :-)
> 
> So it is a "pointer to an array of SANE_Device pointers". Any reason why
> the data transferred over the wire couldn't just be
> 
>   SANE_Device[]
> 
> ?

I haven't checked the details but I guess that's the same structure as
used in the normal backend code (sane_get_devices). So you don't need
to convert it again after you got it from the server.

> > >  1. handle is 0 and the resource is NULL, then status contains an error code from sane_get_devices
> > 
> > Not really. If status is not 0, handle and resource are undefined. The
> > net backend doesn't check the status before looking at resource but it
> > should IMHO.
> > 
> > >  2. no devices exist, and the status is SANE_STATUS_INVAL
> > 
> > 3. authorization is needed for the first device (or more exactly, the
> >    backend of that device) and so status 0 and resource = backend name
> >    is returned
> > 
> > 4. No authorization is needed and the handle of the first device is
> >    returned (SANE_NET_OPEN succeeded).
> > 
> 
> Seems pretty complex...

Now you know why I hate callbacks :-)

> > > ==== reply ====
> > >  * the status code (word)
> > 
> > A struct consisting of
> >   SANE_Word num_options;
> > and  
> > 
> > >  * an array of pointers to a SANE_Option_Descriptor struct which contains (in the given order):
> > 
> > [...]
> 
> Seriously? That would mean the number of options is transferred twice.
> <checking code/>
> As far as I can see it calls only sanei_w_option_descriptor_array, which
> sends the array. And no status code. Dunno where I got that from...

Check it again. In saned, it sends opt which is a struct that contains
opt.num_options and opt.desc. The latter is an array of pointers to
the option descriptors.

> > They can be any value (undefined).
> > 
> > > Otherwise, the reply contains the result of sane_control_option.
> > 
> > If the status isn't 0, all other values are undefined. That's a
> > contradiction to the authorization stuff IMHO. Do I have to check
> > status or resource first?
> 
> But I do need to know when to authorize. Is that done when resource !=
> NULL?

Yes. But in principle there are two ways to check:

a)
1) call SANE_NET_WHATEVER
2) check status, if status != 0, return error and exit
3) otherwise check resource, if resource != 0 authorize

b)
1) call SANE_NET_WHATEVER
2) check resource, if resource != 0 authorize otherwise go on
3) check status, if status != 0, return error and exit

It doesn't seem clear to me what way is intended by the standard. b)
seems to be implemented.

Bye,
  Henning