GridService

From OpenSimulator

(Difference between revisions)
Jump to: navigation, search
(→‎Methods)
(→‎API)
 
(7 intermediate revisions by one user not shown)
Line 1: Line 1:
 
= Introduction =
 
= Introduction =
  
−
The grid service manages information about regions on the grid.
+
The grid service manages information about regions on the grid.  Some of the API is a little odd - this is a legacy of its original undocumented private-only use.
 +
 
 +
This service should only be accessible from the LAN.
  
 
= API =
 
= API =
Line 19: Line 21:
 
* get_hyperlinks - get linked Hypergrid regions.
 
* get_hyperlinks - get linked Hypergrid regions.
 
* get_region_flags - get flags for a region.
 
* get_region_flags - get flags for a region.
 +
* get_grid_extra_features - get default extra features see: [[SimulatorFeatures Extras]]
  
−
== get_region_range ==
+
== 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_name ===
 +
This gets information on the region with the given name.
 +
 
 +
The POST field is a urlencoded string like so
 +
 
 +
SCOPEID=00000000-0000-0000-0000-000000000000&NAME=test&METHOD=get_region_by_name
 +
 
 +
where
 +
 
 +
* '''SCOPEID''' must always be present and always 00000000-0000-0000-0000-000000000000 (UUID.Zero) at the present time.
 +
* '''NAME''' is the name of the region to get.
 +
 
 +
If there is a region with the corresponding name, a response is sent 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 there is more than one region with the same name (not allowed in OpenSimulator by default), then the first matching region only is returned.
 +
 
 +
If no matching region is found then the response is
 +
 
 +
<source lang='xml'>
 +
<?xml version="1.0"?>
 +
<ServerResponse>
 +
  <result>null</result>
 +
</ServerResponse>
 +
</source>
 +
 
 +
=== 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 get.
 +
 
 +
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 ===
 +
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
 +
 
 +
<source lang='xml'>
 +
<?xml version="1.0"?>
 +
<ServerResponse>
 +
  <result>7</result>
 +
</ServerResponse>
 +
</source>
 +
 
 +
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
 +
 
 +
<source lang='xml'>
 +
<?xml version="1.0"?>
 +
<ServerResponse>
 +
  <result>-1</result>
 +
</ServerResponse>
 +
</source>
 +
 
 +
=== get_region_range ===
 
This gets information on all the regions in a given co-ordinate range.
 
This gets information on all the regions in a given co-ordinate range.
  
Line 30: Line 226:
  
 
* '''SCOPEID''' must always be present and always 00000000-0000-0000-0000-000000000000 (UUID.Zero) at the present time.
 
* '''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.  So to start this at map tile co-ordinate 1000, one must specify 256000 (1000 * 256).
+
* '''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.
+
* '''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.
+
* '''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.
+
* '''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
 
If there are any regions in the range, a response like
Line 89: Line 285:
  
 
will be returned.
 
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.

Latest revision as of 11:03, 6 August 2014

Contents

[edit] Introduction

The grid service manages information about regions on the grid. Some of the API is a little odd - this is a legacy of its original undocumented private-only use.

This service should only be accessible from the LAN.

[edit] 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.
  • get_grid_extra_features - get default extra features see: SimulatorFeatures Extras

[edit] Formats

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

[edit] Calls

[edit] get_region_by_name

This gets information on the region with the given name.

The POST field is a urlencoded string like so 

SCOPEID=00000000-0000-0000-0000-000000000000&NAME=test&METHOD=get_region_by_name

where

  • SCOPEID must always be present and always 00000000-0000-0000-0000-000000000000 (UUID.Zero) at the present time.
  • NAME is the name of the region to get.

If there is a region with the corresponding name, a response is sent 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 there is more than one region with the same name (not allowed in OpenSimulator by default), then the first matching region only is returned.

If no matching region is found then the response is 

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

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

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.

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

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

[edit] 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=39441"
Personal tools
General
About This Wiki