<?xml alibi="this is to let vim highlight all XML tags within this file ;)"?>

This document describes the format of GGZComm protocols.

Each protocol starts with the standard XML header, including version and
(maybe) the encoding.

	<?xml version="1.0"?>

What follows is the protocol top-level tag ('ggzcomm'), which contains the
game name ('engine') and its version ('version').

	<ggzcomm engine="GGZCards" version="2">
		...
	</ggzcomm>

Within these tags, we have 4 types of tags now: Those which describes which
events are sent by the server ('server'), which ones are sent by the client and
received by the server ('client'), those who guarantee a certain order
('protocol'), and constants definitions ('definitions').

The following applies to the client and server tags:
Each side can have any number of events ('event'), each of them may carry
information in it or be empty.
Information ('data') tags always contain an identifier ('name') and an
associated data type ('type').
Optionally, the attribute 'global' can be supplied (as in global="protocol"), to
make this variable visible globally within the protocol address space. If
global is set to "all", even the application will be able to access it. Special
care should then be taken for the naming, as renaming of variables can happen
if any conflicts are discovered.

	<event name="msg_language">
		<data name="language" type="string"/>
	</event>

If many elements of one type are to be read or written, a 'sequence' may be
used within an event.
A NULL-terminated list (array) of this type is then returned.
If a variable is used as count option, the maxcount parameter must be specified
as a constant number, otherwise it can be omitted.

	<sequence count="number" maxcount="5">
		<data name="option" type="int"/>
	</sequence>

A constant can be defined in order to allow evaluations.
The type is assumed to be integer ('int'), unless the type parameter is given,
which can also be 'string' or 'byte', where string refers to an easysock-style
string, that is, one which is prefixed with an integer containing its length.

	<definitions>
		<def name="game_message_text" value="5"/>
	</definitions>

There are five standard definitions always available, namely 'ggz:seat_open',
'ggz:seat_bot', 'ggz:seat_player', 'ggz:seat_reserved', and
'ggz:seat_abandoned'.

Conditional execution is contained in evaluation blocks, which consist of
data as well as a condition, which can be of type 'equal', 'unequal',
'smaller' or 'larger', where 'equal' is the default.

	<eval>
		<condition name="type" result="ggz:seat_open" type="unequal">
		<data name="seat_assignment" type="byte"/>
	</eval>

This can then be used for simple types of algorithms:

	<event name="message_game">
		<data name="msgtype" type="int"/>
		<eval>
			<condition name="msgtype" result="game_message_text">
			<data name="marker" type="string"/>
			<data name="message" type="string"/>
		</eval>
	</event>

Finally, the links exist to ensure a certain order of data.

	<protocol>
		<link server="req_move" client="rsp_move"/>
	</protocol>

Josef Spillner
30.04.2002
updated 27.12.2005

