![interreality.org [VOS]](/wwwvos/banner5.jpg)
| Creating Interreality: The Virtual Object System: Version 0.23.0 | ||
|---|---|---|
| Prev | Chapter 6. VOP, a Virtual Object Protocol | Next |
6.5. Message Encoding
VOP Messages are encoded individually in XML style. A communication session consists of a sequence of such messages and/or message blocks, which are a grouping mechanism. In contrast to regular XML documents, there is no leading XML header nor encompassing root element. Encoding is 7 bit ASCII [ASCII], except for parameter values, see below.
A Message consists of a header element, specifying the message type as element tag. The header element may have zero or more child elements, specifying parameters of the message. Parameters never have any child elements themselves, but they may contain a value. In contrast to regular XML, a parameter value may be a sequence of arbitrary bytes (8 bit). In this case however, the parameter must employ the quoting mechanism, see below.
6.5.1. Messages
Possible message element types are <message> and <update>. Any other type is illegal and must be treated as fatal protocol error. <message> indicates a regular message, used for remote invocation or similar purposes. <update> indicates a cache update message, sent by a peer in response to a <message>, or independently after a change to a local Vobject.
The header element may contain various attributes, enumerated below. The attributes, if given, should be appear in the same order as presented here. For security reasons, the length attribute should always be specified as first attribute, in order to prevent buffer overflows due to "message bombs".
- length="n"
This mandatory attribute specifies the total size of the message in bytes. Counting starts with the opening bracket (<) of the start tag, and ends with the closing bracket (>) of the end tag, or the closing bracket of the start tag if no parameters are given. Note that it encompasses even whitespace between elements and attributes. Violation of the length constraint, either during or after parsing the message, must be treated as a fatal protocol error. Negative or suspiciously big values should be treated as fatal protocol errors as well. [Note that the old "S3" release may omit this attribute on certain messages; a sensible default length (256) should be assumed in this case.]
- from="url"
This optional attribute specifies the Vobject that sent this message. The value of the attribute must be its canonical URL. If this attribute is omitted, it defaults to the URL of the sending site. On <update> messages, this indicates the local Vobject that changed its state, which should be reflected by all its remote Vobjects.
- to="url"
This optional attribute specifies the Vobject that is supposed to receive this message. The value of the attribute must be its canonical URL. If this attribute is omitted, it defaults to the URL of the receiving site. On <message> messages, this indicates the local Vobject that is supposed to perform some action.
- method="string"
This mandatory attribute specifies the action that the receiver should take on reception of the message. The given method also determines type and number of message parameters.
- nonce="n"
This optional attribute can be used to correlate messages. The value can be any alpha-numeric string. However, it should be reasonably unique during the lifetime of a VOP session, to prevent collisions. A sequence counter or a 32 bit random value is usually sufficient. For details on nonce usage, see below.
- timestamp="n"
This optional attribute is not used by the VOS, but may be useful for applications, so is documented here for informational purposes.
The attributes above comprise the core set of the VOP protocol. Additional attributes may also be specified. The receiver may ignore any unknown attributes.
6.5.2. Parameters
Depending on the method attribute, a message may have zero or more child elements, the message parameters or fields. The order of the parameters is significant in most cases. A parameter has a name, specified by its tag, and an optional value. A non-empty value may also be quoted. Normally this is optional, but it is mandatory for values that contain angle brackets, or consist of binary data (i.e. contains non-7 bit ASCII values). Quoting is indicated by the presence of the optional length attribute. Its value specifies the total size of the parameter value in bytes. Counting starts with the first byte after the opening tag, and ends with the last byte before the closing tag. Violation of the length constraint should be treated as a fatal protocol error.
6.5.3. Message Blocks
Finally, VOP offers a grouping mechanism for messages, the message block. A message block can appear as toplevel element is the VOP session, just like a regular message. It consists of a <messageblock> element with one or more enclosed regular messages. In contrast to regular messages, messages inside a message block are not delivered immediately. Instead, delivery is deferred until all messages of the block have been parsed. A message block may have the following attributes:
- length="n"
This mandatory attribute specifies the total size of the message block in bytes. This corresponds to the length attribute of a message; in particular, violation of this constraint should be treated as a fatal protocol error.
- name="string"
This optional attribute determines the semantics of the message block, see below. The value of the attribute uniquely identifies the block. It is a non-empty string of characters in the usual VOP encoding (7 bit ASCII).
When an unnamed message block is received, the contained messages must be delivered in strict sequential order. This means that message processing must not overlap. Processing of the next message must be deferred until processing of the current message is completed.
When a named message block is received, its contained messages form a template. Instead of being delivered, they are just stored for future reference. If another block with the same name is received, it replaces the older template of that name. Future messages may then trigger the delivery of a template.