Revision as of 18:25, 14 November 2012

Introduction

The OpenSimulator user account service stores data such as name, UUID (PrincipalID), UserLevel, etc.data (object items, notecard items, folders, etc.).

This documentation is not complete yet - some more information can be found at UserManipulation.

TODO: Document getaccount operation.

API

Not properly documented yet, but some calling information can be found at UserManipulation.

Formats

UserAccount

This has the format

 <account type="List">
   <FirstName>Jon</FirstName>
   <LastName>Snow</LastName>
   <Email/>
   <PrincipalID>12f0e87c-50b1-46c2-892e-facf1ce4a274</PrincipalID>
   <ScopeID>00000000-0000-0000-0000-000000000000</ScopeID>
   <Created>1350088195</Created>
   <UserLevel>0</UserLevel>
   <UserFlags>0</UserFlags>
   <UserTitle/>
   <LocalToGrid>True</LocalToGrid>
   <ServiceURLs>HomeURI*;GatekeeperURI*;InventoryServerURI*;AssetServerURI*;</ServiceURLs>
 </account0>

where

• FirstName is the user's first name.
• LastName is the user's last name.
• Email is the user's e-mail. In this case, no e-mail was set.
• PrincipalID is the user's UUID.
• ScopeID is the scope to which this user belongs. Unless you are using the undocumented feature of hosting multiple grids in a single database, this will always be 00000000-0000-0000-0000-000000000000 (UUID.Zero).
• Created is the Unix timestamp of when the user was created.
• UserLevel is the level of the user. Different levels are given different permissions in OpenSimulator. Currently, the only levels that are used natively by OpenSimulator are 200, which indicates the user can become a god, 0 which indicates a normal user and a negative number, which normally stops the user from logging in (though the minimum login level can itself be adjusted via the "login level" ROBUST console command or by adjusting MinLoginLevel in the [LoginService] section of Robust.ini
• UserFlags may be currently unused.
• UserTitle currently unused.
• LocalToGrid should be true for all users. May not currently be in use.
• ServiceURLs service URLs for use by another grid if Hypergrid is turned on and the user goes to another grid.

In cases where multiple accounts can be returned the account element will have an index value appended (e.g. account3 instead of account).

Calls

getaccount

This gets a user account that matches a given name or UUID.

When requesting a user account by name, the POST field is a urlencoded string like so

FirstName=tom&LastName=thumb&METHOD=getaccount

If requesting a user account by UUID, then the POST field is encoded like so

UserID=15a040d8-a089-4b53-b82a-df0899564314&METHOD=getaccount

If successful, a server response like

<?xml version="1.0"?>
<ServerResponse>
  <account0 type="List">
    <FirstName>tom</FirstName>
    <LastName>thumb</LastName>
    <Email/>
    <PrincipalID>15a040d8-a089-4b53-b82a-df0899564314</PrincipalID>
    <ScopeID>00000000-0000-0000-0000-000000000000</ScopeID>
    <Created>1349819064</Created>
    <UserLevel>0</UserLevel>
    <UserFlags>0</UserFlags>
    <UserTitle/>
    <LocalToGrid>True</LocalToGrid>
    <ServiceURLs>HomeURI*http://127.0.0.1:9000/;GatekeeperURI*;InventoryServerURI*http://127.0.0.1:9000/;AssetServerURI*http://127.0.0.1:9000/;ProfileServerURI*http://127.0.0.1:9000/;FriendsServerURI*http://127.0.0.1:9000/;IMServerURI*http://127.0.0.1:9000/;</ServiceURLs>
  </account0>
  <account1 type="List">
  ...
</ServerResponse>

will be returned.

If no matching user is found, then

<?xml version="1.0"?>
<ServerResponse>
  <result>null</result>
</ServerResponse>

will be returned.

getaccounts

This gets 0 or more user accounts that match a given name query. This is an extremely old query and so has a few strange features. POST field is a urlencoded string like so

query=tom%20thumb&METHOD=getaccounts

where

• query is a space separated list of a firstname fragment and a lastname fragment. These can match anywhere in the first and last names. So "re lins" will match "Fred Flintstone". A plain % can be used to match any string, so all user accounts can be retrieved with "% %".

If successful, a server response like

<?xml version="1.0"?>
<ServerResponse>
  <account0 type="List">
    <FirstName>Fred</FirstName>
    <LastName>Flintstone</LastName>
    <Email/>
    <PrincipalID>15a040d8-a089-4b53-b82a-df0899564313</PrincipalID>
    <ScopeID>00000000-0000-0000-0000-000000000000</ScopeID>
    <Created>1349819064</Created>
    <UserLevel>0</UserLevel>
    <UserFlags>0</UserFlags>
    <UserTitle/>
    <LocalToGrid>True</LocalToGrid>
    <ServiceURLs>HomeURI*http://127.0.0.1:9000/;GatekeeperURI*;InventoryServerURI*http://127.0.0.1:9000/;AssetServerURI*http://127.0.0.1:9000/;ProfileServerURI*http://127.0.0.1:9000/;FriendsServerURI*http://127.0.0.1:9000/;IMServerURI*http://127.0.0.1:9000/;</ServiceURLs>
  </account0>
  <account1 type="List">
  ...
</ServerResponse>

will be returned.

If no matching users are found, then

<?xml version="1.0"?>
<ServerResponse>
  <result>null</result>
</ServerResponse>

will be returned.

Sample scripts

<?php
 
    $ch = curl_init("http://localhost:8003/xinventory");
 
    curl_setopt($ch, CURLOPT_POST, TRUE);
    curl_setopt($ch, CURLOPT_POSTFIELDS, "query=tom+thumb&METHOD=getaccounts");
    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";
 
?>
 
=== setaccount ===
 
This is only available if you have explicitly set 
 
 [UserAccountService]
 AllowSetAccount = true
 
in Robust.ini.  This can currently only safely be done on closed grids (i.e. where you control all simulators).
 
Here's an example python program to call this.  It assumes that your ROBUST services are running on localhost.
 
<source lang="python">
#!/usr/bin/python
 
import httplib
import urllib
 
params = urllib.urlencode({'METHOD':'setaccount', 'FirstName':'Tyrion', 'PrincipalID':'3a1c8128-908f-4455-8157-66c96a46f75e'})
conn = httplib.HTTPConnection("localhost", 8003);
conn.request("POST", "/accounts", params)
response = conn.getresponse()
print response.read();

PrincipalID is the unique ID of the user. Here, it is used to identify the user that we set up earlier.

If everything goes well, you should get back

<?xml version="1.0"?>
<ServerResponse>
  <result type="List">
    <FirstName>Tyrion</FirstName>
    <LastName>Snow</LastName>
    <Email/>
    <PrincipalID>3a1c8128-908f-4455-8157-66c96a46f75e</PrincipalID>
    <ScopeID>00000000-0000-0000-0000-000000000000</ScopeID>
    <Created>1318974501</Created>
    <UserLevel>0</UserLevel>
    <UserFlags>0</UserFlags>
    <ServiceURLs>HomeURI*;GatekeeperURI*;InventoryServerURI*;AssetServerURI*;</ServiceURLs>
  </result>
</ServerResponse>

Note that the first name has now changed from Jon to Tyrion.

If the call fails you will get the response

<?xml version="1.0"?>
<ServerResponse>
  <result>Failure</result>
</ServerResponse>