Introduction

The GridUser service that holds information about user's home region, last logged in region (as used during login), last login time, etc.

See GridUser for database table details.

API

Functions available on this service are:

• loggedin - called to register an avatar as logged in. For internal use only.
• loggedout - called to register an avatar as logged out. For internal use only. This is for record keeping purposes and will not by itself log out an avatar if they are present in the installation.
• sethome - set the home location for an avatar.
• setposition - set current approximate region and position of an avatar. This is both for record keeping purposes and is the position used if the avatar chooses to login to its last location on beginning a new session.
• getgriduserinfo - Get the grid user information for a user, such as home details, last region details and login/logout/online details, though these are less accurate than those that can be seen in the UserAccount service.
• getgriduserinfos - Get griduserinfo for several users in the same call.

Calls

getgriduserinfo

Get the grid user information for a user.

The POST field is a urlencoded string like so

UserID=f2f493c0-27d3-4cf2-be97-b44dfdad13b6&METHOD=getgriduserinfo

where

• UserID is the user ID for whom info is required.

If successful, this will return a response such as

<ServerResponse>
  <result type="List">
    <UserID>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</UserID>
    <HomeRegionID>00000000-0000-0000-0000-000000000000</HomeRegionID>
    <HomePosition>&lt;0, 0, 0&gt;</HomePosition>
    <HomeLookAt>&lt;0, 0, 0&gt;</HomeLookAt>
    <LastRegionID>6f0bb095-2f17-474e-8243-21226b3f934f</LastRegionID>
    <LastPosition>&lt;131.1209, 132.1123, 25.91188&gt;</LastPosition>
    <LastLookAt>&lt;0.3348421, -0.9422743, 0&gt;</LastLookAt>
    <Online>False</Online>
    <Login>9/4/2014 7:55:33 PM</Login>
    <Logout>9/4/2014 7:58:25 PM</Logout>
  </result>
</ServerResponse>

where

• UserID is the user ID.
• HomeRegionID is the ID of the user's home region.
• HomePosition is the position of the user in the home region when they go home. This is an encoding of the Vector3.ToString() where the 1st component is the x co-ordinate, the second is the y co-ordinate and the third is the z co-ordinate. For instance, if the user's home position is (100, 100, 20) then the HomePosition string here will be "<100, 100, 20>".
• HomeLookAt the point the avatar is facing when they go home. This is an encoding of the Vector3.ToString() where the 1st component is the x co-ordinate and the second it the y co-ordinate. The z co-ordinate in this case is always ignored and should be 0. This is a unit vector so (0, 1, 0) is facing straight north, (1, 0, 0) is east, (0,-1, 0) is south and (-1, 0, 0) is west.
• LastRegionID is the ID of the region where the user was last reported present. For a local avatar this will always be the region they are in unless they have logged out. For a Hypergrid foreign user this reflects the last region they occupied when present in the installation served by this grid user service.
• LastPosition is the last position of the user reported by the simulators in this grid. This is generally only refreshed on teleport to a different region or logout and will not accurately reflect the current location of the region. The format is the same as for HomePosition above.
• LastLookAt the point the avatar was facing when there position was last reported by the simulators in this OpenSimulator installation. This is generally only refreshed on teleport to a different region or logout and will not accurately reflect the current location of the region. The format is the same as for HomeLookAt above.
• Online true if the user is considered to be online in this grid, false otherwise.
• 'Login the recorded login time of this user.
• Logout the recorded logout time of this user. This will not be accurate if the simulator they were occupying crashed or was not cleanly shut down.

If a user with the given ID does not have a grid user entry then the following is returned.

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

sethome

Set the home region, position and look direction for a grid user.

The arguments and responses are identical to the setposition call.

The POST field is a urlencoded string like so

UserID=f2f493c0-27d3-4cf2-be97-b44dfdad13b6&RegionID=dd5b77f8-bf88-45ac-aace-35bd76426c81&Position=%3C50%2C100%2C200%3E&LookAt=%3C1%2C0%2C0%3E&METHOD=sethome

where

• UserID (f2f493c0-27d3-4cf2-be97-b44dfdad13b6) is the user ID whose home is to be set.
• RegionID (dd5b77f8-bf88-45ac-aace-35bd76426c81) is the ID of the home region to be set.
• Position (%3C50%2C100%2C200%3E) is the x,y,z co-ordinate of the home position to set. In this case, this is an encode of the string "<50,100,200>".
• LookAt (%3C1%2C0%2C0%3E) is the x,y,z unit vector for the avatar rotation (and hence look direction) to set. In this case, this is an encode of the string "<1, 0, 0>". The z co-ordinate is currently always ignored by OpenSimulator and so can always be set to 0. For this unit vector, (0, 1, 0) is facing straight north, (1, 0, 0) is east, (0,-1, 0) is south and (-1, 0, 0) is west.

If setting home details is considered successful, the service will return

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

If setting home details fails then the service will return

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

However,

• Failure will only be given if the UserID or regionID were not UUIDs.
• Success will be returned even if the user does not exist on this grid, since this table also potentially holds information for foreign users travelling when Hypergrid is enabled.
• Success will be returned even if the region does not exist. In this case, a user travelling home will be sent to the default region as given in the OpenSimulator configuration.
• Success will be returned even if the Position or LookAt parameters are invalid, either because they are badly formed or because one of the values is invalid (e.g. negative value in position). In this case, the relevant parameter will be set to 0,0,0.

setposition

Set internally by the grid when a user moves between regions on that grid and when they logout.

This is the used for the user's initial position when they set the "last" position option on login, so can be called externally to change this position. If called when a user is logged in the change has no effect and will be overwritten when that user teleports or logs out.

The arguments and responses are identical to the sethome call.

The POST field is a urlencoded string like so

UserID=f2f493c0-27d3-4cf2-be97-b44dfdad13b6&RegionID=dd5b77f8-bf88-45ac-aace-35bd76426c81&Position=%3C50%2C100%2C200%3E&LookAt=%3C1%2C0%2C0%3E&METHOD=setposition

where

• UserID (f2f493c0-27d3-4cf2-be97-b44dfdad13b6) is the user ID whose home is to be set.
• RegionID (dd5b77f8-bf88-45ac-aace-35bd76426c81) is the ID of the home region to be set.
• Position (%3C50%2C100%2C200%3E) is the x,y,z co-ordinate of the home position to set. In this case, this is an encode of the string "<50,100,200>".
• LookAt (%3C1%2C0%2C0%3E) is the x,y,z unit vector for the avatar rotation (and hence look direction) to set. In this case, this is an encode of the string "<1, 0, 0>". The z co-ordinate is currently always ignored by OpenSimulator and so can always be set to 0. For this unit vector, (0, 1, 0) is facing straight north, (1, 0, 0) is east, (0,-1, 0) is south and (-1, 0, 0) is west.

If setting home details is considered successful, the service will return

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

If setting home details fails then the service will return

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

However,

• Failure will only be given if the UserID or regionID were not UUIDs.
• Success will be returned even if the user does not exist on this grid, since this table also potentially holds information for foreign users travelling when Hypergrid is enabled.
• Success will be returned even if the region does not exist. In this case, a user logging in to their last position will be sent to the default region as given in the OpenSimulator configuration.
• Success will be returned even if the Position or LookAt parameters are invalid, either because they are badly formed or because one of the values is invalid (e.g. negative value in position). In this case, the relevant parameter will be set to 0,0,0.