I'd like to set up XML formatting for the BNETDocs packet documentation. I feel this would establish a standard of formatting the documentation, and also open up mash-up possibilities for webmasters and bot developers alike. The editors of BNETDocs had already developed a XML structure for each packet on the forums of BNETDocs, but due to the server crash, that thread had been lost.

While I could ask the editors to re-develop the structure, I felt that it'd be better to involve the Battle.net Development community in this to ensure greater consensus.

Does anyone have ideas on what a good packet XML structure would look like?

Some general talk lead to this:
[quote]
// example query
index.php?op=packet&type=bncs&pid=0x00&direction=2
<0x00 name="SID_NULL" direction="2" clients="delimited list of clients that use this packet" related"delimited list of other packets that relate">
      <Format>Blank</Format>
      <Remarks/> // if any
</0x00>
[/quote]

How about this?

[code]<0x15 name="SID_CHECKAD" direction="2" clients="star,sexp,etc" relatedurls="type=bncs&id=0x15&direction=1">
//relatedurls would be delimited by commas
<format>
<DWORD descr="Platform ID">
<DWORD descr="Product ID">
<DWORD descr="ID of last displayed banner">
<DWORD descr="Current Time">
//Following are just fake, meant as an example
<STRING descr="Null Terminated String">
<VOID descr="Non-Null Terminated String">
<DWORD amt="4" descr="4 level DWORD array">
</format>
<remarks> // if any, can include html for formatting, using [] instead of <>
Requests ad banner information from battle.net.
</remarks>
</0x15>[/code]

Or in the case of repeated data, for example, SID_GETADVLISTEX:

[code]<0x09 name="SID_GETADVLISTEX" direction="1" clients="star,sexp,etc" relatedurls="type=bncs&id=0x19&direction=2">
//relatedurls would be delimited by commas
<format>
<DWORD descr="Number of Games">
<DWORD case="if DWORD1 = 0" descr="Status">
<REPEAT case="DWORD1 > 0" amt="DWORD1">
<WORD descr="Game Type">
<WORD descr="Parameter">
<DWORD descr="Language ID">
<WORD descr="Address Family" default="AF_INET">
<WORD descr="Port">
<DWORD descr="Host's IP Address">
<DWORD amt="2" descr="Sin Zero (0)">
<DWORD descr="Game Status">
<DWORD descr="Elapsed time (in seconds)">
<STRING descr="Game Name">
<STRING descr="Game Password">
<STRING descr="Game Statstring">
</REPEAT>
</format>
<remarks>
[p]Returns a list of available games and their information. Varies depending on product.[/p]
[p]Note that fields from Address Family to sin_zero form a sockaddr_in structure.[/p]
[u]Valid status codes:[/u]
    [dl][dd]0x00: OK
0x01: Game doesn't exist
0x02: Incorrect password
0x03: Game full
0x04: Game already started
0x06: Too many server requests[/dd][/dl]
</remarks>
</0x09>[/code]

That'd allow for repeative payloads, allow conditionals, defining amounts to establish arrays, and also allow defining amount in array based on dword data. Thoughts?

Try this: This way, all the packets are in a <packet> element. The fields are all <field>s, and they have a type, name, and descr element, allowing robust tooltips to be displayed for difficult to understand packet elements. The star, sexp, diablo2, etc arguments of the <packet> elements only need to be marked true if necessary, and are otherwise assumed false, in order to allow for smaller code size for packets that are only used on a few clients.

[code]<packet ordinal="0x15" name="SID_CHECKAD" direction="2" star="true" sexp="true" diablo2="true" relatedurls="type=bncs&id=0x15&direction=1">
<field type="DWORD" name="Platform ID" descr="Four byte platform ID">
<field type="DWORD" name="Product ID">
<field type="DWORD" name="ID of last displayed banner">
<field type="DWORD" name="Current Time">
//Following are just fake, meant as an example
<field type="STRING" name="Null Terminated String">
<field type="VOID" name="Non-Null Terminated String">
<field type="ADWORD" len="4" name="4 level DWORD array">
<remarks> <!--// if any, can include html for formatting, using [] instead of <> !>
Requests ad banner information from battle.net.
</remarks>
</packet>[/code]