Revision as of 17:20, 17 December 2013

Introduction

This is a page which gives some details about the protocols used to transfer inventory between a viewer (client) and an OpenSimulator installation. Like many pages, it is a work-in-progress, so if there are more things you would like to know, please ask on the opensim-dev Mailing Lists.

Protocols

There are two OpenSimulator <-> viewer inventory protocols. The first works purely with UDP messages. The second uses HTTP instead via capabilities to replace the fetch parts of the UDP protocol.

The UDP protocol is older and the fetch parts have been replaced in the Linden Lab grid completely by the HTTP capability protocol. However, some viewers can still fall back on the UDP for fetching and it remains supported in OpenSimulator.

Other inventory operations (e.g. folder creation) are still done via UDP.

The HTTP protocol should perform considerably better than the UDP protocol for users with large inventories. However, many viewers provide the option to fallback to UDP inventory if there are issues with the HTTP protocol. It is also possible to disable the HTTP protocol in the OpenSimulator installation by disabling the capabilties.

UDP Protocol

These are some of the UDP messages involved in protocol manipuation. Warning: list is probably incomplete, need to fill out.

 BulkUpdateInventory
   server -> client
   sent when an inventory item is given to the agent
   contains only the update item(s)

 CreateInventoryItem
   client -> server
   received when a client directly creates a new item in inventory
   not when a client takes an object or a copy of an object from the environment

 FetchInventory
   client -> server
   fetch the details of a particular item

 FetchInventoryDescendents
   client -> server
   received when an inventory folder is opened
   InventoryDescendents is the reply

 FetchInventoryReplyPacket
   server -> client
   contains inventory item details
   for some reason this is the same as item data sent in InventoryDescendents

 InventoryDescendents
   reply packet for FetchInventoryDescendents containing inventory details
   contains folder and item data

 LinkInventoryItem
   client -> server
   link an inventory item to an existing item

 RemoveInventoryItem
   invoked by the client when Purge Item is selected on an item in the trash

 UpdateCreateInventoryItem
   server -> client
   sent when 
     an item is derezzed into an avatar's inventory
     an item is dragged into an avatar's inventory

 UpdateInventoryItem
   client <-> server
   sent server -> client
     apparently when a derez suceeds
   sent client -> server
     when different eyes are worn in viewer 2
       possibly this is to change worn status

 UpdateInventoryFolder
   called when a folder is renamed

HTTP protocol

The HTTP protocol works via various Capabilities. The capabilities required for HTTP transfer at the present time are

• FetchInventory2
• FetchInventoryDescendents2
• FetchLib2
• FetchLibDescendents2

For more details about how they operate, please see the Linden Lab Inventory capabilities document.

Historically, the following capabilities were used. However, these have been obsolete for a long time and can be disregarded.

• FetchInventory
• FetchLib
• FetchLibDescendents

If the inventory capabilities are disabled, then some viewers (very probably all current viewers) will fall back on the UDP mechanism to fetch inventory data. Various viewers may provide a menu option to not use HTTP inventory. Older viewers will solely use the UDP mechanism. However, some viewers have historically been buggy where the fallback fails to be setup properly.