[sane-standard] preliminary protocol doc

[Johannes Berg]

[To the list, apparently I only replied to HMG, sorry]

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.

> On Fri, Oct 15, 2004 at 03:47:21PM +0200, Johannes Berg wrote:
> > In the sane network protocol, an array is represented by the length of the array
> > following the items.
> 
> "... followed by ...". The length is a SANE_Word.

Yup. Uhh, that's what you get when re-arranging words.

> > A string is transferred as an array of its bytes,
> 
> SANE_Chars actually (doesn't matter as of now but you never know...)

Oh. right.

> > unless the protocol is in ASCII mode.
> 
> As far as I understand the standard there is no ascii protocol. I know
> codec_ascii but it's not in the standard and practically only used for
> saving frontend options.

Hm. Ok, I only observed that it was there and in theory could be hooked
up to a wire.

> > The transferred data does not include the trailing 0.
> 
> It does! ("The trailing NUL byte is considered part of the array").

Already fixed, sorry.

> > === SANE_NET_AUTHORIZE ===
> > This message is used to send authorization tokens for a given resource.
> > ==== request ====
> >  * resource (string)
> >  * username (string)
> >  * password (string)
> > 
> > ==== reply ====
> >  * a single 0 word if no protocol errors occurred
> 
> There is one word of reply but it's value doesn't matter.

See rationale above -- I was documenting what the code was doing.

> > === 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.

> > ==== 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[]

?

> The SANE device name can contain a colon (e.g. test:001).

Ups. I was reading the code that zeroed out the colon, but now I realize
that is only in resource, not name.

> Your points are about an empty string, not a NULL string:

Yeah, at that point I was still confused if the network layer was able
to distinguish.

> >  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...

> As far as I can see resource name is the backend name of the first
> device. "saned" is only used as the name of the file that contains
> passwords (saned.users).

Yup. Confused the arguments.

> > ==== 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...

> Practically speaking, you are right. The excemption for
> SANE_ACTION_SET_AUTO is not in the standard, however (as far as I can
> see).

Yeah, like I said, I was trying to document the current behaviour.

> 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?

> (everything else is undefined, see above)
> 
> > After the status returned is SANE_STATUS_GOOD, the server starts listening
> > on the port given in the port field. The client must then connect to that port
> > (the server blocks until that has happened). The client must not send any data
> > to the data connection, that connection is only for receiving data (like FTP).
> 
> With FTP you can send data :-)

Yeah, '(like FTP)' should be earlier.

Thanks for your comments, I'll update my wiki page accordingly and add a
note that I was documenting the current state of the code, not the
standard.

johannes