Latest revision as of 11:32, 31 July 2014

[edit] 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.

[edit] API

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

[edit] Formats

[edit] 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).

[edit] Calls

[edit] 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.

[edit] 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.

[edit] 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";
 
?>

[edit] 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.

#!/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>

[edit] createuser

This is only available if you have explicitly set

[UserAccountService]
AllowCreateUser = true

in Robust.ini. This can currently only safely be done on closed grids (i.e. where you control all simulators).

You may also want to make sure that you have

[UserAccountService] 
CreateDefaultAvatarEntries = true 

set so that a new user will have the initial minimal body-part/clothing set (skin, shape, eyes, hair, pants, shirt) required for them to appear as anything other than a gas-cloud on Viewer 3 and related third party viewers (viewer version 1 and related third party viewers will show a default "Ruth" avatar instead).

Here's an example python program to call this. It assumes that your ROBUST services are running on localhost.

#!/usr/bin/python
 
import httplib
import urllib
 
params = urllib.urlencode({'METHOD':'setaccount', 'FirstName':'Tyrion', 'LastName':'Snow', '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>