Pyogp/Documentation/Specification/pyogp.lib.base

ToDo: fill out this page Enus Linden 10:10, 24 July 2008 (PDT)

see Pyogp/Client_Lib

UDP Template Messaging

There are a few main components to sending a UDP message, the message template, the parser, the builder, and the reader.

Message Template

Can be found [message_template.msg]
The message template is the file that outlines all the different types of UDP messages that can be sent. It breaks each message down by the message header information, its blocks, and the block data.
In order to communicate between the client and sim (or anything else) we need to be able to parse the message template, determine which messages can be sent, build messages based on the format they are specified to be in, and then read incoming messages.

Message Template Parser

In order to build or read (and therefore send or receive) any UDP messages, we have to first parse the message template. The parser parses the message template, searching for each message listed in it, and then iterates through the message's blocks and the block data.
The parser goes through the message template and constructs a data object of type MessageTemplate, MessageTemplateBlock, and MessageTemplateVariable. These types are used to store general information about the message that is read from the message template. In other words, these objects created by the parser hold no incoming or outgoing data. They are simply used as templates to build data out of. They allow us to know the header information for the message, the blocks it is supposed to have, and the data that the blocks are supposed to have.
The parser reads things such as the message frequency, the message number (which is a unique value that is matched with frequency), its trust, encoding, and deprecation.

• The template also stores something called the hex num, which is the combination of the frequency and the message number stored as a hex number. It is stored here because the hex value never changes for the templates, and rather than building the hex value every time a message is going to be sent, it is just stored in the template for quicker access.

It also reads the block information such as its type (one of single, multiple, or variable)

• If the block is of type multiple, then something called the block number is also stored. This number represents how many of the given block MUST be written for a message.
• If the block is of type variable, then any number of the given block can be written for a message.

Finally, it reads the block data for things such as the data type (one of many types) and its size.

• The string type read from the template is converted to a class variable (like an enum)
• The size of the variable is gotten from our sizeof function in message_types.py
  • Although, if the variable is of type variable or fixed, the maximum number of bytes that the variable can be is stored (it is also listed in the message template as a third parameter, such as { Data Variable 2 }, which says the variable called "Data" is of type "Variable" where the variable can store up to 2 bytes worth of data.

The output of the parser is a list of message template objects, where each object has its list of blocks, and where each block has its list of variables.

Message Template Dict

The parser outputs a list of message templates. In order to make accessing this list easier and more efficient, a dict has been created. This takes the list and makes dicts out of it, one that maps the template name to the template, and one that maps the frequency/num combination to the template. This way, we can get any template by its name or frequency/num combination.