Protocol (network)

From libopenmetaverse - libomv - Developer Wiki

Jump to: navigation, search

XML-RPC Login

See Login for infomation about the XML-RPC login process.

General Packet Format

Second Life uses a UDP-based message system for communication between the client ("viewer") and server ("simulator"). The protocol definition is stored in a file called "message_template.msg". This file lists each packet, along with the names and types of each field inside that packet; it also contains some comments as to the meaning of the fields, but often not enough to completely understand them.

Every time a new client (forced upgrade) is released, you must update your copy of the message template file for libsecondlife to function correctly. The latest version of this file is available at http://lib.openmetaverse.org/template

Every packet begins with the following six bytes:

XX XX XX XX XX XX

The first byte contains the packed flags; the four most significant bits are a bitfield with the following bits: 

#define MSG_APPENDED_ACKS		0x10 
#define MSG_RESENT			0x20 
#define MSG_RELIABLE			0x40 
#define MSG_ZEROCODED			0x80

MSG_APPENDED_ACKS is set to indicate that ACKs are appended to the packet. MSG_RELIABLE means an ACK is requested, and if one isn't sent in a certain timeframe the packet will be resent with the MSG_RESENT flag set. MSG_ZEROCODED indicates that a packet, including its packet ID, is Zero Encoded; you must undo this encoding before identifying the packet ID.

The four least significant bits of the first byte are unused and normally sent as zeros.

The second to fifth bytes are a 32-bit sequence number, in big-endian order. Sequence numbers are unique to each connection and each direction. The sixth byte is always zero in all packets seen so far, but apparently indicates the size of some as-yet unused extra header.

From here to the start of the appended acks, the data is optionally zerocoded. The next bytes indicate the category (roughly corresponding to frequency; "Low", "Medium","High", and "Fixed") and type of packet. The category is indicated by the number of 0xFF bytes; the packet ID follows the last 0xFF.

Fixed:  XX XX XX XX FF FF FF XX
Low:    XX XX XX XX FF FF XX XX
Medium: XX XX XX XX FF XX
High:   XX XX XX XX XX

  • Red: Flags
  • Green: Unused
  • Blue: Sequence number (big endian)
  • Black: Literal hex values
  • Cyan: Packet ID number (big endian for the multi-byte IDs)

The frequency and the packet ID number are used to look up the correct packet in the message template; the contents of that template are then used to decode the rest of the packet, which is specified in terms of blocks and fields.

The message template details how many blocks are in the packet, which can be a fixed number or a variable number specified in the packet. Fixed is straightforward: there are 1, 2, 4, or more of those blocks in order with no separators. Variable blocks are prepended with either one or two bytes saying how many there are. If a block is Variable 2 in the protocol map it uses two bytes in big endian format, so a count of 7 would be specified with 0x00 0x07. The same approach is used for the fields.

Packets

See Category:Packets for pages on individual packets.

Retrieved from "http://lib.openmetaverse.org/wiki/Protocol_%28network%29"