Merge branch 'master' into presence-refactor

This was a large, heavily conflicted merge and things MAY have got broken.
Please check!

OpenSim/Region/Framework/Interfaces/IEntityInventory.cs

@@ -71,13 +71,18 @@ namespace OpenSim.Region.Framework.Interfaces
         /// <summary>
         /// Start all the scripts contained in this entity's inventory
         /// </summary>
-       void CreateScriptInstances(int startParam, bool postOnRez, string engine, int stateSource);
+        void CreateScriptInstances(int startParam, bool postOnRez, string engine, int stateSource);
+        
         ArrayList GetScriptErrors(UUID itemID);
 
         /// <summary>
         /// Stop all the scripts in this entity.
         /// </summary>
-        void RemoveScriptInstances();
+        /// <param name="sceneObjectBeingDeleted">
+        /// Should be true if these scripts are being removed because the scene
+        /// object is being deleted.  This will prevent spurious updates to the client.
+        /// </param>
+        void RemoveScriptInstances(bool sceneObjectBeingDeleted);
 
         /// <summary>
         /// Start a script which is in this entity's inventory.
@@ -103,7 +108,11 @@ namespace OpenSim.Region.Framework.Interfaces
         /// Stop a script which is in this prim's inventory.
         /// </summary>
         /// <param name="itemId"></param>
-        void RemoveScriptInstance(UUID itemId);
+        /// <param name="sceneObjectBeingDeleted">
+        /// Should be true if these scripts are being removed because the scene
+        /// object is being deleted.  This will prevent spurious updates to the client.
+        /// </param>
+        void RemoveScriptInstance(UUID itemId, bool sceneObjectBeingDeleted);
 
         /// <summary>
         /// Add an item to this entity's inventory.  If an item with the same name already exists, then an alternative
@@ -134,6 +143,16 @@ namespace OpenSim.Region.Framework.Interfaces
         /// <returns>null if the item does not exist</returns>
         TaskInventoryItem GetInventoryItem(UUID itemId);
 
+        /// <summary>
+        /// Get inventory items by name.
+        /// </summary>
+        /// <param name="name"></param>
+        /// <returns>
+        /// A list of inventory items with that name.
+        /// If no inventory item has that name then an empty list is returned.
+        /// </returns>        
+        IList<TaskInventoryItem> GetInventoryItems(string name);
+
         /// <summary>
         /// Update an existing inventory item.
         /// </summary>

OpenSim/Region/Framework/Interfaces/IWorldComm.cs

@@ -49,10 +49,49 @@ namespace OpenSim.Region.Framework.Interfaces
 
     public interface IWorldComm
     {
+        /// <summary>
+        /// Create a listen event callback with the specified filters.
+        /// The parameters localID,itemID are needed to uniquely identify
+        /// the script during 'peek' time. Parameter hostID is needed to
+        /// determine the position of the script.
+        /// </summary>
+        /// <param name="localID">localID of the script engine</param>
+        /// <param name="itemID">UUID of the script engine</param>
+        /// <param name="hostID">UUID of the SceneObjectPart</param>
+        /// <param name="channel">channel to listen on</param>
+        /// <param name="name">name to filter on</param>
+        /// <param name="id">key to filter on (user given, could be totally faked)</param>
+        /// <param name="msg">msg to filter on</param>
+        /// <returns>number of the scripts handle</returns>        
         int Listen(uint LocalID, UUID itemID, UUID hostID, int channel, string name, UUID id, string msg);
+
+        /// <summary>
+        /// This method scans over the objects which registered an interest in listen callbacks.
+        /// For everyone it finds, it checks if it fits the given filter. If it does,  then
+        /// enqueue the message for delivery to the objects listen event handler.
+        /// The enqueued ListenerInfo no longer has filter values, but the actually trigged values.
+        /// Objects that do an llSay have their messages delivered here and for nearby avatars,
+        /// the OnChatFromClient event is used.
+        /// </summary>
+        /// <param name="type">type of delvery (whisper,say,shout or regionwide)</param>
+        /// <param name="channel">channel to sent on</param>
+        /// <param name="name">name of sender (object or avatar)</param>
+        /// <param name="id">key of sender (object or avatar)</param>
+        /// <param name="msg">msg to sent</param>        
         void DeliverMessage(ChatTypeEnum type, int channel, string name, UUID id, string msg);
+
+        /// <summary>
+        /// Are there any listen events ready to be dispatched?
+        /// </summary>
+        /// <returns>boolean indication</returns>        
         bool HasMessages();
+
+        /// <summary>
+        /// Pop the first availlable listen event from the queue
+        /// </summary>
+        /// <returns>ListenerInfo with filter filled in</returns>        
         IWorldCommListenerInfo GetNextMessage();
+        
         void ListenControl(UUID itemID, int handle, int active);
         void ListenRemove(UUID itemID, int handle);
         void DeleteListener(UUID itemID);