Editing OpenSimulator Internals/Connector Architecture/Grid Connector (section)

= OpenSimulator Internals/Connector Architecture/Grid Connector =

== Overview ==

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 ===

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 ===

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 ===

{| class="wikitable"
! 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 ===

* 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.

----

== See Also ==

* [[OpenSimulator Internals/Connector Architecture]]
* [[OpenSimulator Internals/Code Map/ROBUST/GridService RegisterRegion]]
* [[OpenSimulator Internals/Code Map/Shared]]