Re: [QStat-devx] draft for new query protocol and API

[Ludwig N. <l-...@us...>]

Steve Jankowski wrote:
> Thanks, Ludwig.  I've made some comments on the package format.
> 
> But first, I'm not convinced the world needs another game query
> protocol.  If you implement something for BZFlag that's compatible
> with an existing game (HL or Quake), then other game browsers can
> support it straight away.  That's good for BZFlag, right?

Those protocols are flawed in one way or another. AFAIK HL does not
deal with fragmented packets and Quake(3) only has a fixed set of
player properties. The gamespy format is some kind of standard, but
we know it's not easy to deal with either.

> See my comments below on the query protocol.
> 
> I could comment on the API, but without knowing the architecture of
> the application (BZFlag) I can't say if the API meets the needs of
> the app.  From scanning the API, I imagine that the API might be
> perfect, or it might be intrusive.  Depends on the BZFlag data
> structures and main control flow.

I don't think the API doesn't assume any special preconditions. You
just tell it when some state of your server changed (rule changes,
player joins, frags, dies etc). On every incoming packet (that maybe
does not contain your own magic header) you have to call
qs_respond_to_query() to form a query response if needed.

> If you go ahead with the API, let me know and I'll give you some feedback
> on the API.  Just for giggles if nothing else.

I'd really like to hear your opinion.

> > [...]
> > Query response:
> > ~~~~~~~~~~~~~~~
> > 
> > QUERYRESPONSE ::= HEADER MANDDATA '\n' (RULE)* '\n' (TEAM)* '\n' (PLAYER)*
> '\n'
> 
> I'm concerned about using \n since it might appear in a string (rule value).
> I suggest using \0 since that's not a legal character.

Strings are always null terminated. \n is used to let the parser
know when the e.g. the rules section ends and the team section
starts. Like:

... 'r' 'u' 'l' 'e' '\0' 'v' 'a' 'l' 'u' 'e' \0' '\n' ...

> > [...]
> > integers are in network byte order
> > strings are null terminated C-strings in UTF-8 or iso8859-1 encoding
> 
> How do you distinguish between encodings?

You try to read a string in UTF-8. If that fails because it violates
the rules, it's assumed to be iso8859-1. I do this in XQF already
when using GTK2 for the UI. See
http://developer.gnome.org/doc/API/2.0/glib/glib-Unicode-Manipulation.html#g-utf8-validate

> > PKGID has to be copied from the query packet to the query response packet by
> > the server, it is used by the client to distinguish retry packets
> > 
> > DATALEN is only present if FRAGMENTNO == 0
> 
> Optional bits of data are annoying.  It's only a few extra bytes.
> 
> On the topic of DATALEN, I'd rather know the total number of packets
> to expect.  Once I have all the packets, then I'll know how much data
> there is; I don't have to be told.  The trouble is knowing if I got all
> the packets.  If each packets tells me the total # packets, then it's
> easier.

That's the part I'm unsure about. I specified it this way because
the API does not know how big each fragment can be. So it just
generates as much as needed on demand. The receiver knows how much
data to expect. As long as the sum of all received packets is
smaller than that it has to wait a little longer for more packet to
arrive.

> Change the header to:
> 
> HEADER ::= 'q' 's' PROTOVERS PKGID TOTALFRAGMENTS FRAGMENTNO
> 
> The API should build the whole packet, then divide by 1394 (1400 minus
> the 6 byte header).  Then it will know how many fragments there will
> be and can put this in each frag header.
> 
> I chose 1400 to avoid exceeding the MTU (usually 1500 on ethernet, but
> occasionally smaller).

If you want to make sure the packet can be tansmitted over the
internet you would need to restrict the packet size to 576 bytes.
That's the minimum size each device needs to be able to handle.

> > the first key of each player or team must be "name"
> > 
> > PROTOVERS is 0x01 in this revision of the protocol
> > 
> > QUERYDATA is "sendreport"
> 
> Maybe allow fetching of different data sets:
> 
> "send:"          send just the MANDDATA
> "send:all"       send everything
> "send:rules"     send rules
> "send:players"   send players
> "send:teams"     send teams
> "send:teams,players"    send just teams and players
> 
> Of course, MANDDATA is always included.
> 
> For now, you can support just "send:" and "send:all", but you've left
> yourself room for expansion to support other queries.

Maybe single bytes after the colon are better, no additional string
compares would be needed. E.g. send:a for all or send:tp for teams
and players.

cu
Ludwig

-- 
(o_     Ludwig Nussel
//\   ICQ:     52166811
V_/_  PGP Key: FF8135CE