1 files changed, 53 insertions, 13 deletions

diff --git a/OpenSim/Services/Interfaces/IHypergridServices.cs b/OpenSim/Services/Interfaces/IHypergridServices.cs
index 3dc877a..5e012fb 100644
--- a/OpenSim/Services/Interfaces/IHypergridServices.cs
+++ b/OpenSim/Services/Interfaces/IHypergridServices.cs
@@ -1,4 +1,4 @@
-/*
+/*
  * Copyright (c) Contributors, http://opensimulator.org/
  * See CONTRIBUTORS.TXT for a full list of copyright holders.
  *
@@ -37,31 +37,71 @@ namespace OpenSim.Services.Interfaces
     public interface IGatekeeperService
     {
         bool LinkRegion(string regionDescriptor, out UUID regionID, out ulong regionHandle, out string externalName, out string imageURL, out string reason);
-        GridRegion GetHyperlinkRegion(UUID regionID);
+        
+        /// <summary>
+        /// Returns the region a Hypergrid visitor should enter.
+        /// </summary>
+        /// <remarks>
+        /// Usually the returned region will be the requested region. But the grid can choose to
+        /// redirect the user to another region: e.g., a default gateway region.
+        /// </remarks>
+        /// <param name="regionID">The region the visitor *wants* to enter</param>
+        /// <param name="agentID">The visitor's User ID. Will be missing (UUID.Zero) in older OpenSims.</param>
+        /// <param name="agentHomeURI">The visitor's Home URI. Will be missing (null) in older OpenSims.</param>
+        /// <param name="message">[out] A message to show to the user (optional, may be null)</param>
+        /// <returns>The region the visitor should enter, or null if no region can be found / is allowed</returns>
+        GridRegion GetHyperlinkRegion(UUID regionID, UUID agentID, string agentHomeURI, out string message);
 
-        bool LoginAgent(AgentCircuitData aCircuit, GridRegion destination, out string reason);
+        bool LoginAgent(GridRegion source, AgentCircuitData aCircuit, GridRegion destination, out string reason);
 
     }
 
-    /// <summary>
-    /// HG1.5 only
-    /// </summary>
     public interface IUserAgentService
     {
-        // called by login service only
-        bool LoginAgentToGrid(AgentCircuitData agent, GridRegion gatekeeper, GridRegion finalDestination, IPEndPoint clientIP, out string reason);
-        // called by simulators
-        bool LoginAgentToGrid(AgentCircuitData agent, GridRegion gatekeeper, GridRegion finalDestination, out string reason);
+        bool LoginAgentToGrid(GridRegion source, AgentCircuitData agent, GridRegion gatekeeper, GridRegion finalDestination, bool fromLogin, out string reason);
+        
         void LogoutAgent(UUID userID, UUID sessionID);
+
+        /// <summary>
+        /// Returns the home region of a remote user.
+        /// </summary>
+        /// <returns>On success: the user's home region. If the user doesn't exist: null.</returns>
+        /// <remarks>Throws an exception if an error occurs (e.g., can't contact the server).</remarks>
         GridRegion GetHomeRegion(UUID userID, out Vector3 position, out Vector3 lookAt);
+
+        /// <summary>
+        /// Returns the Server URLs of a remote user.
+        /// </summary>
+        /// <returns>On success: the user's Server URLs. If the user doesn't exist: an empty dictionary.</returns>
+        /// <remarks>Throws an exception if an error occurs (e.g., can't contact the server).</remarks>
         Dictionary<string, object> GetServerURLs(UUID userID);
-        Dictionary<string,object> GetUserInfo(UUID userID);
 
+        /// <summary>
+        /// Returns the UserInfo of a remote user.
+        /// </summary>
+        /// <returns>On success: the user's UserInfo. If the user doesn't exist: an empty dictionary.</returns>
+        /// <remarks>Throws an exception if an error occurs (e.g., can't contact the server).</remarks>
+        Dictionary<string, object> GetUserInfo(UUID userID);
+
+        /// <summary>
+        /// Returns the current location of a remote user.
+        /// </summary>
+        /// <returns>On success: the user's Server URLs. If the user doesn't exist: "".</returns>
+        /// <remarks>Throws an exception if an error occurs (e.g., can't contact the server).</remarks>
         string LocateUser(UUID userID);
-        // Tries to get the universal user identifier for the targetUserId
-        // on behalf of the userID
+        
+        /// <summary>
+        /// Returns the Universal User Identifier for 'targetUserID' on behalf of 'userID'.
+        /// </summary>
+        /// <returns>On success: the user's UUI. If the user doesn't exist: "".</returns>
+        /// <remarks>Throws an exception if an error occurs (e.g., can't contact the server).</remarks>
         string GetUUI(UUID userID, UUID targetUserID);
 
+        /// <summary>
+        /// Returns the remote user that has the given name.
+        /// </summary>
+        /// <returns>On success: the user's UUID. If the user doesn't exist: UUID.Zero.</returns>
+        /// <remarks>Throws an exception if an error occurs (e.g., can't contact the server).</remarks>
         UUID GetUUID(String first, String last);
 
         // Returns the local friends online