GridService

From OpenSimulator

(Difference between revisions)
Jump to: navigation, search
(→‎API)
(→‎Calls)
Line 70: Line 70:
  
 
== Calls ==
 
== Calls ==
 +
 +
=== get_region_by_uuid ===
 +
This gets information on the region with the given UUID.
 +
 +
The POST field is a urlencoded string like so
 +
 +
SCOPEID=00000000-0000-0000-0000-000000000000&REGIONID=dd5b77f8-bf88-45ac-aace-35bd76426c81&METHOD=get_region_by_uuid
 +
 +
where
 +
 +
* '''SCOPEID''' must always be present and always 00000000-0000-0000-0000-000000000000 (UUID.Zero) at the present time.
 +
* '''REGIONID''' is the UUID of region to query for flags.
 +
 +
If there are any regions in the range, a response like
 +
 +
<source lang='xml'>
 +
<?xml version="1.0"?>
 +
<ServerResponse>
 +
  <result type="List">
 +
    <uuid>dd5b77f8-bf88-45ac-aace-35bd76426c81</uuid>
 +
    <locX>256000</locX>
 +
    <locY>256000</locY>
 +
    <sizeX>256</sizeX>
 +
    <sizeY>256</sizeY>
 +
    <regionName>test</regionName>
 +
    <serverIP>192.168.1.2</serverIP>
 +
    <serverHttpPort>9000</serverHttpPort>
 +
    <serverURI>http://192.168.1.2:9000/</serverURI>
 +
    <serverPort>9000</serverPort>
 +
    <regionMapTexture>fc8fda13-c2e9-4e83-8543-b7fe98231399</regionMapTexture>
 +
    <parcelMapTexture>00000000-0000-0000-0000-000000000000</parcelMapTexture>
 +
    <access>13</access>
 +
    <regionSecret>0ab0a97d-ffcc-4b29-a715-74372b763b88</regionSecret>
 +
    <owner_uuid>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</owner_uuid>
 +
    <Token/>
 +
  </result>
 +
</ServerResponse>
 +
</source>
 +
 +
If no matching regions are found then
 +
 +
<source lang='xml'>
 +
<?xml version="1.0"?>
 +
<ServerResponse>
 +
  <result>null</result>
 +
</ServerResponse>
 +
</source>
 +
 +
will be returned.
  
 
=== get_region_flags ===
 
=== get_region_flags ===

Revision as of 16:07, 29 July 2014

Contents

Introduction

The grid service manages information about regions on the grid.

API

Functions available on the grid service are

  • register - registers a region with the grid.
  • deregister - deregisters a region from the grid.
  • get_neighbours - gets the region neighbours of a given location.
  • get_region_by_uuid - returns region details given a region UUID.
  • get_region_by_position - returns region details given a position.
  • get_region_by_name - returns region details given a name. This will only return the first name if there are multiple regions with the same name.
  • get_regions_by_name - returns details of all regions that match a given name
  • get_region_range - returns details of all regions in a given area
  • get_default_regions - returns default regions for a grid. These are regions that are tried in order if the requested login region does not exist.
  • get_default_hypergrid_regions - returns default Hypergrid regions for a grid. These are regions that are tried in order if Hypergrid destination request by an inbound foreign user does not exist.
  • get_fallback_regions - returns fallback regions for a grid. These are regions that are tried in order if no default regions are online.
  • get_hyperlinks - get linked Hypergrid regions.
  • get_region_flags - get flags for a region.

Formats

Region

This has the format 

 <region0 type="List">
   <uuid>dd5b77f8-bf88-45ac-aace-35bd76426c81</uuid>
   <locX>256000</locX>
   <locY>256000</locY>
   <sizeX>256</sizeX>
   <sizeY>256</sizeY>
   <regionName>test</regionName>
   <serverIP>192.168.1.2</serverIP>
   <serverHttpPort>9000</serverHttpPort>
   <serverURI>http://192.168.1.2:9000/</serverURI>
   <serverPort>9000</serverPort>
   <regionMapTexture>fc8fda13-c2e9-4e83-8543-b7fe98231399</regionMapTexture>
   <parcelMapTexture>00000000-0000-0000-0000-000000000000</parcelMapTexture>
   <access>13</access>
   <regionSecret>0ab0a97d-ffcc-4b29-a715-74372b763b88</regionSecret>
   <owner_uuid>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</owner_uuid>
   <Token/>
 </region0>

where

  • uuid uuid of the region
  • locX X location of the south-west corner of the region. Please note that this is in meters, not map tiles (each 256m). So a location of 256000 corresponds to a map tile at 1000.
  • locY Y location of the south-west corner of the region. Please note that this is in meters, not map tiles (each 256m).
  • sizeX X dimension size of the region in meters.
  • sizeY Y dimension size of the region in meters.
  • regionName name of the region
  • serverIP IP address of the region passed to clients.
  • serverHttpPort HTTP port of the region as passed to clients.
  • serverURI URI of the region.
  • serverPort UDP port of the region as passed to clients.
  • regionMapTexture map texture of the region as stored in the asset service.
  • parcelMapTexture parcel map of the region as stored in the asset database.
  • access mainly signals avatar maturity level required for access. Possible values (not all of which are used by core OpenSimulator) are
    • Unknown = 0, Unknown or invalid access level
    • Trial = 7, Trial accounts allowed
    • PG = 13, PG rating. This is the default value to allow access by all avatars.
    • Mature = 21, Mature rating.
    • Adult = 42, Adult rating.
    • Down = 254, Simulator is offline.
    • NonExistent = 255, Simulator does not exist.
  • regionSecret, currently unused.
  • owner_uuid, UUID of estate user that owns the region.

Calls

get_region_by_uuid

This gets information on the region with the given UUID.

The POST field is a urlencoded string like so 

SCOPEID=00000000-0000-0000-0000-000000000000&REGIONID=dd5b77f8-bf88-45ac-aace-35bd76426c81&METHOD=get_region_by_uuid

where

  • SCOPEID must always be present and always 00000000-0000-0000-0000-000000000000 (UUID.Zero) at the present time.
  • REGIONID is the UUID of region to query for flags.

If there are any regions in the range, a response like 

<?xml version="1.0"?>
<ServerResponse>
  <result type="List">
    <uuid>dd5b77f8-bf88-45ac-aace-35bd76426c81</uuid>
    <locX>256000</locX>
    <locY>256000</locY>
    <sizeX>256</sizeX>
    <sizeY>256</sizeY>
    <regionName>test</regionName>
    <serverIP>192.168.1.2</serverIP>
    <serverHttpPort>9000</serverHttpPort>
    <serverURI>http://192.168.1.2:9000/</serverURI>
    <serverPort>9000</serverPort>
    <regionMapTexture>fc8fda13-c2e9-4e83-8543-b7fe98231399</regionMapTexture>
    <parcelMapTexture>00000000-0000-0000-0000-000000000000</parcelMapTexture>
    <access>13</access>
    <regionSecret>0ab0a97d-ffcc-4b29-a715-74372b763b88</regionSecret>
    <owner_uuid>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</owner_uuid>
    <Token/>
  </result>
</ServerResponse>

If no matching regions are found then 

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

will be returned.

get_region_flags

This get information on the flags of a region (yes, this should really just be included in get_region_range).

The POST field is a urlencoded string like so 

SCOPEID=00000000-0000-0000-0000-000000000000&REGIONID=dd5b77f8-bf88-45ac-aace-35bd76426c81&METHOD=get_region_flags

where

  • SCOPEID must always be present and always 00000000-0000-0000-0000-000000000000 (UUID.Zero) at the present time.
  • REGIONID is the UUID of region to query for flags.

If the region exists, a response like 

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

will be received. The result corresponds to bit flags

  • DefaultRegion = 1, // Used for new Rez. Random if multiple defined
  • FallbackRegion = 2, // Regions we redirect to when the destination is down
  • RegionOnline = 4, // Set when a region comes online, unset when it unregisters and DeleteOnUnregister is false
  • NoDirectLogin = 8, // Region unavailable for direct logins (by name)
  • Persistent = 16, // Don't remove on unregister
  • LockedOut = 32, // Don't allow registration
  • NoMove = 64, // Don't allow moving this region
  • Reservation = 128, // This is an inactive reservation
  • Authenticate = 256, // Require authentication
  • Hyperlink = 512, // Record represents a HG link
  • DefaultHGRegion = 1024 // Record represents a default region for hypergrid teleports only.

If no region with the given ID is found, then the response is 

<?xml version="1.0"?>
<ServerResponse>
  <result>-1</result>
</ServerResponse>

get_region_range

This gets information on all the regions in a given co-ordinate range.

The POST field is a urlencoded string like so 

SCOPEID=00000000-0000-0000-0000-000000000000&XMIN=0&YMIN=0&XMAX=2147483647&YMAX=2147483647&METHOD=get_region_range

where

  • SCOPEID must always be present and always 00000000-0000-0000-0000-000000000000 (UUID.Zero) at the present time.
  • XMIN The minimum x-coordinate in the region range. Please note that this is in meters, not 256m map tiles. This must be in the range 0 - 2147483647. So to start this at map tile co-ordinate 1000, one must specify 256000 (1000 * 256).
  • YMIN The minimum u-coordinate in the region range. Please note that this is in meters, not 256m map tiles. This must be in the range 0 - 2147483647.
  • XMAX The maximum x-coordinate in the region range. Please note that this is in meters, not 256m map tiles. This must be in the range 0 - 2147483647.
  • XMIN The maximum y-coordinate in the region range. Please note that this is in meters, not 256m map tiles. This must be in the range 0 - 2147483647.

If there are any regions in the range, a response like 

<?xml version="1.0"?>
<ServerResponse>
  <region0 type="List">
    <uuid>dd5b77f8-bf88-45ac-aace-35bd76426c81</uuid>
    <locX>256000</locX>
    <locY>256000</locY>
    <sizeX>256</sizeX>
    <sizeY>256</sizeY>
    <regionName>test</regionName>
    <serverIP>192.168.1.2</serverIP>
    <serverHttpPort>9000</serverHttpPort>
    <serverURI>http://192.168.1.2:9000/</serverURI>
    <serverPort>9000</serverPort>
    <regionMapTexture>fc8fda13-c2e9-4e83-8543-b7fe98231399</regionMapTexture>
    <parcelMapTexture>00000000-0000-0000-0000-000000000000</parcelMapTexture>
    <access>13</access>
    <regionSecret>0ab0a97d-ffcc-4b29-a715-74372b763b88</regionSecret>
    <owner_uuid>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</owner_uuid>
    <Token/>
  </region0>
  <region1 type="List">
    <uuid>dd5b77f8-bf88-45ac-aace-35bd76426c82</uuid>
    <locX>256000</locX>
    <locY>256256</locY>
    <sizeX>256</sizeX>
    <sizeY>256</sizeY>
    <regionName>test2</regionName>
    <serverIP>192.168.1.2</serverIP>
    <serverHttpPort>9000</serverHttpPort>
    <serverURI>http://192.168.1.2:9000/</serverURI>
    <serverPort>9001</serverPort>
    <regionMapTexture>e8c14947-c7d2-48e8-bab2-5a62ec4da4d8</regionMapTexture>
    <parcelMapTexture>00000000-0000-0000-0000-000000000000</parcelMapTexture>
    <access>13</access>
    <regionSecret>273b84ff-bfe1-480b-901b-c6e4bcd3e091</regionSecret>
    <owner_uuid>f2f493c0-27d3-4cf2-be97-b44dfdad13b6</owner_uuid>
    <Token/>
  </region1>
</ServerResponse>

If no matching regions are found then 

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

will be returned.

Notes

You can get information on all the regions in a grid by specifying 0,0 min values and 2147483647,2147483647 max values.

Retrieved from "http://opensimulator.org/index.php?title=GridService&oldid=39385"
Personal tools
General
About This Wiki