InventoryService
From OpenSimulator
Contents |
Introduction
The OpenSimulator inventory service stores user inventory data (object items, notecard items, folders, etc.) and provides this on request. Note that every inventory item points towards an immutable asset entry that actually contains the data.
The current default ROBUST OpenSimulator inventory service is known as the XInventoryService.
API
General notes
Unlike the asset service, the xinventory service is an RPC interface. Therefore it exposes only one URI which is xinventory (e.g. http://localhost:8003/xinventory). The invocation of different operations (e.g. add item, get item) is controlled via a METHOD parameter.
Formats
The API calls below return folder and item data in the same format. These formats are detailed below.
Folder
This has the form
<folder type="List"> <ParentID>00000000-0000-0000-0000-000000000000</ParentID> <Type>9</Type> <Version>1</Version> <Name>My Inventory</Name> <Owner>efc1b932-20e3-4298-8824-0f891fe3dc59</Owner> <ID>035f457b-a0f6-4580-a10c-e4f908e176ac</ID> </folder>
where
- ParentID is the parent folder ID. For the root ("My Inventory") folder this is always UUID.Zero (00000000-0000-0000-0000-000000000000).
- Type is the type of the folder. See the InventoryType enum in libopenmetaverse for more details. In this case, the type is 9 (RootCategory) since this is a root folder.
- Version is the version of the folder. This is used for viewer inventory caching purposes.
- Name is the name of the folder.
- Owner is the UUID of the avatar that owns the folder.
- ID is the unique id of the folder itself.
Though in some cases while multiple folders can be returned the folder element will have an underscore and index value appended (e.g. folder_0 instead of folder). This is for historical reasons.
Calls
GETROOTFOLDER
This returns data about a user's root folder (i.e. their "My Inventory" folder"). POST field is a urlencoded string like so
PRINCIPAL=efc1b932-20e3-4298-8824-0f891fe3dc59&METHOD=GETROOTFOLDER
where
- METHOD is GETROOTFOLDER
- PRINCIPAL is the UUID of the user
If successful, example return is
<?xml version="1.0"?> <ServerResponse> <folder type="List"> <ParentID>00000000-0000-0000-0000-000000000000</ParentID> <Type>9</Type> <Version>1</Version> <Name>My Inventory</Name> <Owner>efc1b932-20e3-4298-8824-0f891fe3dc59</Owner> <ID>035f457b-a0f6-4580-a10c-e4f908e176ac</ID> </folder> </ServerResponse>
If the request fails (e.g. because the PRINCIPAL does not exist) you will receive an empty response
<?xml version="1.0"?><ServerResponse />
See #Folder for more details about the folder format.
Sample scripts
<?php $ch = curl_init("http://localhost:8003/xinventory"); curl_setopt($ch, CURLOPT_POST, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, "PRINCIPAL=efc1b931-20e3-4298-8824-0f891fe3dc59&METHOD=GETROOTFOLDER"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); $result = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo "Return code:" . $info['http_code'] . "\n"; echo "$result\n"; ?>
GETFOLDER
This returns data about a particular inventory folder. POST field is a urlencoded string like so
ID=efc1b932-20e3-4298-8824-0f891fe3dc59&METHOD=GETFOLDER
where
- METHOD is GETFOLDER
- ID is the folder UUID
If successful, example return is
<?xml version="1.0"?> <ServerResponse> <folder type="List"> <ParentID>035f457b-a0f6-4580-a10c-e4f908e176ac</ParentID> <Type>8</Type> <Version>1</Version> <Name>Some folder</Name> <Owner>efc1b932-20e3-4298-8824-0f891fe3dc59</Owner> <ID>e3c2a5e8-20c4-4e70-a994-61dae3265b58</ID> </folder> </ServerResponse>
If the request fails (e.g. because the PRINCIPAL does not exist) you will receive an empty response
<?xml version="1.0"?><ServerResponse />
See #Folder for more details about the folder format.
Sample scripts
<?php $ch = curl_init("http://localhost:8003/xinventory"); curl_setopt($ch, CURLOPT_POST, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, "ID=e3c2a5e8-20c4-4e70-a994-61dae3265b58&METHOD=GETFOLDER"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); $result = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo "Return code:" . $info['http_code'] . "\n"; echo "$result\n"; ?>
GETFOLDERCONTENT
This returns the children folders and items of a given inventory folder. POST field is a urlencoded string like so
PRINCIPAL=efc1b931-20e3-4298-8824-0f891fe3dc59&FOLDER=efc1b932-20e3-4298-8824-0f891fe3dc59&METHOD=GETFOLDERCONTENT
where
- METHOD is GETFOLDERCONTENT
- PRINCIPAL is the user that owns the folder. This is currently mandatory but is really only present for historical reasons.
- FOLDER is the folder UUID
If successful, example return is
<?xml version="1.0"?> <ServerResponse> <FOLDERS type="List"> <folder_0 type="List"> <ParentID>859723cf-6338-497b-ab70-64ca04b64f70</ParentID> <Type>-1</Type> <Version>1</Version> <Name>f1</Name> <Owner>efc1b932-20e3-4298-8824-0f891fe3dc59</Owner> <ID>4174f4cd-9ff5-8d23-0721-2a758f36f7d0</ID> </folder_0> </FOLDERS> <ITEMS type="List"> <item_0 type="List"> <AssetID>31f51766-4a99-4b59-9e53-61f436614c71</AssetID> <AssetType>6</AssetType> <BasePermissions>581639</BasePermissions> <CreationDate>1347487471</CreationDate> <CreatorId>efc1b932-20e3-4298-8824-0f891fe3dc59</CreatorId> <CreatorData/> <CurrentPermissions>581639</CurrentPermissions> <Description/> <EveryOnePermissions>0</EveryOnePermissions> <Flags>0</Flags> <Folder>859723cf-6338-497b-ab70-64ca04b64f70</Folder> <GroupID>00000000-0000-0000-0000-000000000000</GroupID> <GroupOwned>False</GroupOwned> <GroupPermissions>0</GroupPermissions> <ID>25e16367-accd-4b92-8f46-b55d3f63ad0d</ID> <InvType>6</InvType> <Name>Primitive</Name> <NextPermissions>581632</NextPermissions> <Owner>efc1b932-20e3-4298-8824-0f891fe3dc59</Owner> <SalePrice>0</SalePrice> <SaleType>0</SaleType> </item_0> <item_1 type="List"> <AssetID>37f0cbe1-c61f-492b-835b-f9f44b636e37</AssetID> <AssetType>6</AssetType> <BasePermissions>581633</BasePermissions> <CreationDate>1347400903</CreationDate> <CreatorId>efc1b932-20e3-4298-8824-0f891fe3dc59</CreatorId> <CreatorData/> <CurrentPermissions>581633</CurrentPermissions> <Description/> <EveryOnePermissions>0</EveryOnePermissions> <Flags>0</Flags> <Folder>859723cf-6338-497b-ab70-64ca04b64f70</Folder> <GroupID>00000000-0000-0000-0000-000000000000</GroupID> <GroupOwned>False</GroupOwned> <GroupPermissions>0</GroupPermissions> <ID>dde22b2c-1ae3-40df-8480-7b793544aceb</ID> <InvType>6</InvType> <Name>Primitive2</Name> <NextPermissions>581632</NextPermissions> <Owner>efc1b932-20e3-4298-8824-0f891fe3dc59</Owner> <SalePrice>0</SalePrice> <SaleType>0</SaleType> </item_1> </ITEMS> </ServerResponse>
If the request fails (e.g. because the PRINCIPAL does not exist) you will receive an empty response
<?xml version="1.0"?><ServerResponse />
See #Folder for more details about the folder format. Note that the folder elements here have an index parameter appended (<folder_0> rather than <folder>). This piece of insanity is for historical reasons.
Sample scripts
<?php $ch = curl_init("http://localhost:8003/xinventory"); curl_setopt($ch, CURLOPT_POST, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, "PRINCIPAL=efc1b931-20e3-4298-8824-0f891fe3dc59&FOLDER=e3c2a5e8-20c4-4e70-a994-61dae3265b58&METHOD=GETFOLDERCONTENT"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); $result = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo "Return code:" . $info['http_code'] . "\n"; echo "$result\n"; ?>