1 files changed, 21 insertions, 15 deletions

diff --git a/OpenSim/Region/CoreModules/Framework/EntityTransfer/EntityTransferModule.cs b/OpenSim/Region/CoreModules/Framework/EntityTransfer/EntityTransferModule.cs
index 9b1b69a..58a6654 100644
--- a/OpenSim/Region/CoreModules/Framework/EntityTransfer/EntityTransferModule.cs
+++ b/OpenSim/Region/CoreModules/Framework/EntityTransfer/EntityTransferModule.cs
@@ -517,12 +517,6 @@ namespace OpenSim.Region.CoreModules.Framework.EntityTransfer
                     "[ENTITY TRANSFER MODULE]: Failed validation of all attachments for teleport of {0} from {1} to {2}.  Continuing.",
                     sp.Name, sp.Scene.RegionInfo.RegionName, finalDestination.RegionName);
 
-//                if (!sp.ValidateAttachments())
-//                {
-//                    sp.ControllingClient.SendTeleportFailed("Inconsistent attachment state");
-//                    return;
-//                }
-
             string reason;
             string version;
             if (!Scene.SimulationService.QueryAccess(
@@ -583,6 +577,7 @@ namespace OpenSim.Region.CoreModules.Framework.EntityTransfer
             }
 
             // Let's create an agent there if one doesn't exist yet. 
+            // NOTE: logout will always be false for a non-HG teleport.
             bool logout = false;
             if (!CreateAgent(sp, reg, finalDestination, agentCircuit, teleportFlags, out reason, out logout))
             {
@@ -625,11 +620,13 @@ namespace OpenSim.Region.CoreModules.Framework.EntityTransfer
 
                 if (m_eqModule != null)
                 {
+                    // The EnableSimulator message makes the client establish a connection with the destination
+                    // simulator by sending the initial UseCircuitCode UDP packet to the destination containing the
+                    // correct circuit code.
                     m_eqModule.EnableSimulator(destinationHandle, endPoint, sp.UUID);
 
-                    // ES makes the client send a UseCircuitCode message to the destination, 
-                    // which triggers a bunch of things there.
-                    // So let's wait
+                    // XXX: Is this wait necessary?  We will always end up waiting on UpdateAgent for the destination
+                    // simulator to confirm that it has established communication with the viewer.
                     Thread.Sleep(200);
 
                     // At least on LL 3.3.4 for teleports between different regions on the same simulator this appears
@@ -640,6 +637,9 @@ namespace OpenSim.Region.CoreModules.Framework.EntityTransfer
                 }
                 else
                 {
+                    // XXX: This is a little misleading since we're information the client of its avatar destination,
+                    // which may or may not be a neighbour region of the source region.  This path is probably little
+                    // used anyway (with EQ being the one used).  But it is currently being used for test code.
                     sp.ControllingClient.InformClientOfNeighbour(destinationHandle, endPoint);
                 }
             }
@@ -657,14 +657,17 @@ namespace OpenSim.Region.CoreModules.Framework.EntityTransfer
 
             //sp.ControllingClient.SendTeleportProgress(teleportFlags, "Updating agent...");
 
+            // A common teleport failure occurs when we can send CreateAgent to the 
+            // destination region but the viewer cannot establish the connection (e.g. due to network issues between
+            // the viewer and the destination).  In this case, UpdateAgent timesout after 10 seconds, although then
+            // there's a further 10 second wait whilst we attempt to tell the destination to delete the agent in Fail().
             if (!UpdateAgent(reg, finalDestination, agent, sp))
             {
-                // Region doesn't take it
                 m_log.WarnFormat(
-                    "[ENTITY TRANSFER MODULE]: UpdateAgent failed on teleport of {0} to {1} from {2}.  Returning avatar to source region.",
+                    "[ENTITY TRANSFER MODULE]: UpdateAgent failed on teleport of {0} to {1} from {2}.  Keeping avatar in source region.",
                     sp.Name, finalDestination.RegionName, sp.Scene.RegionInfo.RegionName);
                 
-                Fail(sp, finalDestination, logout);
+                Fail(sp, finalDestination, logout, "Connection between viewer and destination region could not be established.");
                 return;
             }
 
@@ -705,7 +708,7 @@ namespace OpenSim.Region.CoreModules.Framework.EntityTransfer
                     "[ENTITY TRANSFER MODULE]: Teleport of {0} to {1} from {2} failed due to no callback from destination region.  Returning avatar to source region.",
                     sp.Name, finalDestination.RegionName, sp.Scene.RegionInfo.RegionName);
                 
-                Fail(sp, finalDestination, logout);
+                Fail(sp, finalDestination, logout, "Destination region did not signal teleport completion.");
                 return;
             }
 
@@ -788,12 +791,15 @@ namespace OpenSim.Region.CoreModules.Framework.EntityTransfer
         /// <param name='sp'></param>
         /// <param name='finalDestination'></param>
         /// <param name='logout'></param>
-        protected virtual void Fail(ScenePresence sp, GridRegion finalDestination, bool logout)
+        /// <param name='reason'>Human readable reason for teleport failure.  Will be sent to client.</param>
+        protected virtual void Fail(ScenePresence sp, GridRegion finalDestination, bool logout, string reason)
         {
             CleanupAbortedInterRegionTeleport(sp, finalDestination);
 
             sp.ControllingClient.SendTeleportFailed(
-                string.Format("Problems connecting to destination {0}", finalDestination.RegionName));
+                string.Format(
+                    "Problems connecting to destination {0}, reason: {1}", finalDestination.RegionName, reason));
+
             sp.Scene.EventManager.TriggerTeleportFail(sp.ControllingClient, logout);
         }