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

== Overview ==

UserAgentServiceConnector is the remote connector for IUserAgentService. It is used by foreign grids to talk to a home grid's UserAgentService -- verifying agents, getting home region info, and checking online friends. It extends SimulationServiceConnector, inheriting the agent transfer path and overriding the agent URL path.

Source file:

 OpenSim/Services/Connectors/Hypergrid/UserAgentServiceConnector.cs

----

=== Inheritance ===

Extends SimulationServiceConnector. Overrides:
* AgentPath() -- returns "homeagent/" instead of "agent/"
* PackData() -- adds gatekeeper_serveruri, gatekeeper_host, gatekeeper_port, destination_serveruri to the OSD payload

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

----

=== Initialisation ===

Two constructors:
* String URL -- validates URI, normalizes to lowercase with trailing slash
* IConfigSource -- reads HomeURL from GridInfo; throws if missing or invalid

No config section key -- the URL is taken from GridInfo.HomeURL, which reads from [Const], [Startup], or [Hypergrid] sections.

----

=== Transport -- Two Protocols ===

This connector uses two different transports depending on the method:

Agent transfer (inherited from SimulationServiceConnector):
* LoginAgentToGrid() calls CreateAgent() -- uses WebUtil OSD/LLSD over HTTP POST/PUT to "homeagent/" path

All other methods:
* Use XML-RPC via Nwc.XmlRpc over HTTP POST to m_ServerURL
* CallServer() is the shared helper for XML-RPC calls that return a Hashtable
* GetBoolResponse() is the shared helper for XML-RPC calls that return a bool via a "result" key

----

=== LoginAgentToGrid() ===

Two overloads:

 public bool LoginAgentToGrid(GridRegion source, AgentCircuitData aCircuit, GridRegion gatekeeper,
     GridRegion destination, bool fromLogin, out string reason)

Constructs a synthetic home GridRegion using m_ServerURL as ServerURI, then calls the parent CreateAgent(). Teleport flag is ViaLogin if fromLogin, ViaHome otherwise. Stores gatekeeper in m_Gatekeeper for use by PackData().

 public bool LoginAgentToGrid(GridRegion source, AgentCircuitData aCircuit, GridRegion gatekeeper,
     GridRegion destination, out string reason)

Always passes fromLogin = false. Used by simulators.

----

=== XML-RPC Methods ===

{| class="wikitable"
! Method !! XmlRpc method !! Returns !! Notes
|-
| GetHomeRegion(userID, out position, out lookAt) || "get_home_region" || GridRegion || Parses full GridRegion from Hashtable; returns null on failure
|-
| IsAgentComingHome(sessionID, thisGridExternalName) || "agent_is_coming_home" || bool || Via GetBoolResponse()
|-
| VerifyAgent(sessionID, token) || "verify_agent" || bool || Via GetBoolResponse()
|-
| VerifyClient(sessionID, token) || "verify_client" || bool || Via GetBoolResponse()
|-
| LogoutAgent(userID, sessionID) || "logout_agent" || void || Calls GetBoolResponse() but discards result
|-
| GetUserInfo(userID) || "get_user_info" || Dictionary<string,object> || All non-null Hashtable entries returned
|-
| GetServerURLs(userID) || "get_server_urls" || Dictionary<string,object> || Only SRV_-prefixed keys returned; "SRV_" prefix stripped
|-
| LocateUser(userID) || "locate_user" || string || Returns hash["URL"] or empty string
|-
| GetUUI(userID, targetUserID) || "get_uui" || string || Returns hash["UUI"] or empty string
|-
| GetUUID(first, last) || "get_uuid" || UUID || Throws on missing or unparseable UUID response
|-
| StatusNotification(friends, userID, online) || "status_notification" || List<UUID> || [Obsolete]; friends sent as friend_0, friend_1...; returns online UUIDs
|-
| GetOnlineFriends(userID, friends) || "get_online_friends" || List<UUID> || [Obsolete]; same encoding as StatusNotification
|}

GetHomeRegion() field parsing: uuid, x, y, size_x, size_y, region_name, hostname, http_port, server_uri, internal_port, position, lookAt. All fields checked for null before parsing. Missing fields silently use zero/default values.

GetServerURLs() strips the "SRV_" prefix from keys, returning just the service type name.

GetUUID() throws on failure -- the only method in this connector that throws instead of returning a sentinel value.

----

=== SetClientToken() ===

No-op. Accepted but does nothing.

----

=== Notes ===

* This connector uses XML-RPC for most operations and OSD/REST for agent transfer -- two different protocols in the same class.
* StatusNotification() and GetOnlineFriends() are both marked [Obsolete]. Exception catch blocks in both methods silently swallow all exceptions with no logging.
* LogoutAgent() discards the bool result from GetBoolResponse() -- callers cannot detect failure.
* GetUUID() is the only method that throws on error rather than returning null/empty/false.
* The error message in GetBoolResponse() for "THIS IS BAAAAD" is verbatim from the source.

----