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

== Overview ==

GatekeeperServiceConnector is the client-side connector used to talk to a foreign grid's GatekeeperService. It handles HG region linking, map tile retrieval, and region lookup. It extends SimulationServiceConnector, inheriting the agent and object transfer paths with overridden URL prefixes.

Source file:

 OpenSim/Services/Connectors/Hypergrid/GatekeeperServiceConnector.cs

----

=== Inheritance ===

Extends SimulationServiceConnector. Overrides:
* AgentPath() -- returns "foreignagent/" instead of "agent/"
* ObjectPath() -- returns "foreignobject/" instead of "object/"

This means CreateAgent() from the parent sends to destination.ServerURI + "foreignagent/" + agentID + "/" when called through this connector.

----

=== Initialisation ===

Two constructors:
* Default (no args) -- no asset service; GetMapImage() will return the default HG map tile UUID
* IAssetService argument -- asset service used by GetMapImage() to store downloaded map tiles

No config file reading. The destination URI comes from GridRegion.ServerURI per call.

----

=== Transport ===

All non-inherited methods use XML-RPC via Nwc.XmlRpc over HTTP POST to the gatekeeper's ServerURI. 10-second timeout on all XML-RPC calls.

Agent and object transfer methods are inherited from SimulationServiceConnector and use WebUtil OSD/REST.

----

=== LinkRegion() ===

 public bool LinkRegion(GridRegion info, out UUID regionID, out ulong realHandle,
     out string externalName, out string imageURL, out string reason, out int sizeX, out int sizeY)

XML-RPC method: "link_region"

Sends: region_name

On success parses: uuid, handle (as ulong), region_image, external_name, size_x, size_y. All fields checked for null before parsing. Default sizeX/sizeY is Constants.RegionSize if not provided.

Returns false on connection error, XML-RPC fault, or parse exception.

----

=== GetMapImage() ===

 public UUID GetMapImage(UUID regionID, string imageURL, string storagePath)

Downloads and stores a foreign region's map tile as an asset.

Sequence:
# If no AssetService: returns m_HGMapImage (00000000-0000-1111-9999-000000000013) immediately
# Builds filename: storagePath + regionID + ".jpg"
# If file not on disk: downloads from imageURL via WebClient.DownloadFile()
# Opens as Bitmap, encodes to JPEG2000 via OpenJPEG.EncodeFromImage()
# Stores as AssetType.Texture with random UUID, name "region {regionID}", creator = regionID
# Returns the stored asset UUID

Exception handling: entire sequence wrapped in bare catch -- logs "probably already in the cache" and returns m_HGMapImage. This catches OpenJPEG p/invoke failures specifically (comment says "LEGIT").

m_HGMapImage (00000000-0000-1111-9999-000000000013) is the fallback UUID returned on any failure.

----

=== GetHyperlinkRegion() ===

 public GridRegion GetHyperlinkRegion(GridRegion gatekeeper, UUID regionID, UUID agentID,
     string agentHomeURI, out string message)

XML-RPC method: "get_region"

Sends: region_uuid; optionally agent_id and agent_home_uri if agentID is non-zero.

On success parses full GridRegion: uuid, x, y, size_x, size_y, region_name, hostname, http_port, internal_port, server_uri. All fields null-checked before parsing.

message handling:
* If hash["message"] present: use it
* If success and no message: set message = null
* If failure and no message: set message = "The teleport destination could not be found." (comment notes this is for old grids that don't send message)

Returns null on connection error, XML-RPC fault, parse exception, or result == false.

----

=== Notes ===

* GetMapImage() uses the deprecated WebClient class for download. The comment "LEGIT" on the bare catch is the only documentation for why all exceptions are swallowed there.
* The fallback map tile UUID (00000000-0000-1111-9999-000000000013) is a static field -- the same UUID is returned for all failed map tile fetches regardless of region.
* Agent transfer uses "foreignagent/" path rather than "agent/" -- this is what distinguishes inbound HG agent traffic from local teleport traffic on the receiving simulator.

----