OpenSimulator Internals/Connector Architecture/Grid Connector
OpenSimulator Internals/Connector Architecture/Grid Connector
[edit]Overview
[edit]GridServicesConnector is the simulator-side remote connector for IGridService. It translates IGridService calls into HTTP POST requests to the ROBUST Grid handler at /grid.
Source file:
OpenSim/Services/Connectors/Grid/GridServicesConnector.cs
Initialisation
[edit]Config section: [GridService]
Required key:
- GridServerURI -- URL of the ROBUST grid endpoint; throws if missing
Two URIs are constructed:
- m_ServerURI -- base URI (trailing slash trimmed)
- m_ServerGridURI -- m_ServerURI + "/grid" -- used for all requests
Base class BaseServiceConnector.Initialise() called for auth setup.
Three constructors:
- Default (no args) -- URIs must be set externally
- String URI -- sets both m_ServerURI and m_ServerGridURI directly
- IConfigSource -- calls Initialise(), normal grid mode
Transport
[edit]All methods POST to m_ServerGridURI using SynchronousRestFormsRequester.MakePostRequest(). All requests include a METHOD field. Most also include SCOPEID.
List-returning methods iterate all values in the reply dictionary and construct GridRegion from each dictionary entry. Empty list returned on empty reply or exception.
Single-region methods check for a "result" key containing a dictionary and construct GridRegion from it. Null returned if not found.
Methods
[edit]| Method | METHOD field | Returns | Notes |
|---|---|---|---|
| RegisterRegion(scopeID, regionInfo) | "register" | string | Empty string on success; error message on failure. Sends full GridRegion via ToKeyValuePairs(). Checks Result field for "success"/"failure". |
| DeregisterRegion(regionID) | "deregister" | bool | Checks Result == "success" |
| GetNeighbours(scopeID, regionID) | "get_neighbours" | List<GridRegion> | Returns empty list on failure |
| GetRegionByUUID(scopeID, regionID) | "get_region_by_uuid" | GridRegion | Null on not found |
| GetRegionByHandle(scopeID, handle) | (none) | GridRegion | Converts handle to x,y coords; delegates to GetRegionByPosition() |
| GetRegionByPosition(scopeID, x, y) | "get_region_by_position" | GridRegion | Null on not found |
| GetRegionByName(scopeID, name) | "get_region_by_name" | GridRegion | Null on not found |
| GetLocalRegionByName(scopeID, name) | "get_localregion_by_name" | GridRegion | Null on not found; used by GatekeeperService |
| GetRegionByURI(scopeID, uri) | (none) | GridRegion | Always returns null -- not implemented |
| GetLocalRegionByURI(scopeID, uri) | (none) | GridRegion | Always returns null -- not implemented |
| GetRegionsByName(scopeID, name, max) | "get_regions_by_name" | List<GridRegion> | Name prefix search; max limits results |
| GetRegionsByURI(scopeID, uri, max) | (none) | List<GridRegion> | Always returns null -- not implemented |
| GetRegionRange(scopeID, xmin, xmax, ymin, ymax) | "get_region_range" | List<GridRegion> | Bounding box query |
| GetDefaultRegions(scopeID) | "get_default_regions" | List<GridRegion> | Returns empty list on failure |
| GetDefaultHypergridRegions(scopeID) | "get_default_hypergrid_regions" | List<GridRegion> | Returns empty list on failure |
| GetFallbackRegions(scopeID, x, y) | "get_fallback_regions" | List<GridRegion> | Returns empty list on failure |
| GetOnlineRegions(scopeID, x, y, max) | "get_online_regions" | List<GridRegion> | Sends MC for max count; returns empty list on failure |
| GetHyperlinks(scopeID) | "get_hyperlinks" | List<GridRegion> | Returns empty list on failure |
| GetRegionFlags(scopeID, regionID) | "get_region_flags" | int | Returns -1 on failure; parses result as int |
| GetExtraFeatures() | "get_grid_extra_features" | Dictionary<string,object> | Returns all key-value pairs from reply; empty dict on failure |
RegisterRegion() result handling:
- "success" (case-insensitive) -- returns empty string
- "failure" (case-insensitive) -- logs Message field and returns it
- Anything else -- logs "unexpected result" and returns it
- All errors return a non-empty string; callers check for empty string to detect success
Notes
[edit]- GetRegionByURI(), GetLocalRegionByURI(), and GetRegionsByURI() always return null -- RegionURI queries are not implemented in this connector.
- GetRegionByHandle() is a local conversion wrapper -- it does not make a separate HTTP call with the handle value.
- List methods return empty list (not null) on all failure paths.
- Single-region methods return null on failure.
- GetRegionFlags() returns -1 on failure, not 0 -- callers should check for negative values.