Revert "Patch from mcortez: Update groups, add ALPHA Siman grid connector for groups"

Causes an exception within HttpServer, headers have already been sent.

This reverts commit 8187fccd25.
avinationmerge
Melanie 2010-05-06 16:38:23 +01:00
parent 11971fb302
commit 69d0201d4c
5 changed files with 437 additions and 207 deletions

View File

@ -28,41 +28,30 @@
using System; using System;
using System.Collections.Generic; using System.Collections.Generic;
using System.Reflection; using System.Reflection;
using log4net; using log4net;
using Mono.Addins; using Mono.Addins;
using Nini.Config; using Nini.Config;
using OpenMetaverse; using OpenMetaverse;
using OpenMetaverse.StructuredData; using OpenMetaverse.StructuredData;
using OpenSim.Framework; using OpenSim.Framework;
using OpenSim.Region.CoreModules.Framework.EventQueue; using OpenSim.Region.CoreModules.Framework.EventQueue;
using OpenSim.Region.Framework.Interfaces; using OpenSim.Region.Framework.Interfaces;
using OpenSim.Region.Framework.Scenes; using OpenSim.Region.Framework.Scenes;
using Caps = OpenSim.Framework.Capabilities.Caps; using Caps = OpenSim.Framework.Capabilities.Caps;
namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
{ {
[Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule")] [Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule")]
public class GroupsMessagingModule : ISharedRegionModule public class GroupsMessagingModule : ISharedRegionModule, IGroupsMessagingModule
{ {
private static readonly ILog m_log = LogManager.GetLogger(MethodBase.GetCurrentMethod().DeclaringType); private static readonly ILog m_log = LogManager.GetLogger(MethodBase.GetCurrentMethod().DeclaringType);
private List<Scene> m_sceneList = new List<Scene>(); private List<Scene> m_sceneList = new List<Scene>();
private IMessageTransferModule m_msgTransferModule = null; private IMessageTransferModule m_msgTransferModule = null;
private IGroupsModule m_groupsModule = null; private IGroupsServicesConnector m_groupData = null;
// TODO: Move this off to the Groups Server
public Dictionary<Guid, List<Guid>> m_agentsInGroupSession = new Dictionary<Guid, List<Guid>>();
public Dictionary<Guid, List<Guid>> m_agentsDroppedSession = new Dictionary<Guid, List<Guid>>();
// Config Options // Config Options
private bool m_groupMessagingEnabled = false; private bool m_groupMessagingEnabled = false;
@ -108,8 +97,12 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
public void AddRegion(Scene scene) public void AddRegion(Scene scene)
{ {
// NoOp if (!m_groupMessagingEnabled)
return;
scene.RegisterModuleInterface<IGroupsMessagingModule>(this);
} }
public void RegionLoaded(Scene scene) public void RegionLoaded(Scene scene)
{ {
if (!m_groupMessagingEnabled) if (!m_groupMessagingEnabled)
@ -117,12 +110,12 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: {0} called", System.Reflection.MethodBase.GetCurrentMethod().Name); if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: {0} called", System.Reflection.MethodBase.GetCurrentMethod().Name);
m_groupsModule = scene.RequestModuleInterface<IGroupsModule>(); m_groupData = scene.RequestModuleInterface<IGroupsServicesConnector>();
// No groups module, no groups messaging // No groups module, no groups messaging
if (m_groupsModule == null) if (m_groupData == null)
{ {
m_log.Error("[GROUPS-MESSAGING]: Could not get IGroupsModule, GroupsMessagingModule is now disabled."); m_log.Error("[GROUPS-MESSAGING]: Could not get IGroupsServicesConnector, GroupsMessagingModule is now disabled.");
Close(); Close();
m_groupMessagingEnabled = false; m_groupMessagingEnabled = false;
return; return;
@ -144,7 +137,7 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
scene.EventManager.OnNewClient += OnNewClient; scene.EventManager.OnNewClient += OnNewClient;
scene.EventManager.OnIncomingInstantMessage += OnGridInstantMessage; scene.EventManager.OnIncomingInstantMessage += OnGridInstantMessage;
scene.EventManager.OnClientLogin += OnClientLogin;
} }
public void RemoveRegion(Scene scene) public void RemoveRegion(Scene scene)
@ -172,7 +165,7 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
m_sceneList.Clear(); m_sceneList.Clear();
m_groupsModule = null; m_groupData = null;
m_msgTransferModule = null; m_msgTransferModule = null;
} }
@ -197,8 +190,84 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
#endregion #endregion
/// <summary>
/// Not really needed, but does confirm that the group exists.
/// </summary>
public bool StartGroupChatSession(UUID agentID, UUID groupID)
{
if (m_debugEnabled)
m_log.DebugFormat("[GROUPS-MESSAGING]: {0} called", System.Reflection.MethodBase.GetCurrentMethod().Name);
GroupRecord groupInfo = m_groupData.GetGroupRecord(agentID, groupID, null);
if (groupInfo != null)
{
return true;
}
else
{
return false;
}
}
public void SendMessageToGroup(GridInstantMessage im, UUID groupID)
{
if (m_debugEnabled)
m_log.DebugFormat("[GROUPS-MESSAGING]: {0} called", System.Reflection.MethodBase.GetCurrentMethod().Name);
foreach (GroupMembersData member in m_groupData.GetGroupMembers(UUID.Zero, groupID))
{
if (m_groupData.hasAgentDroppedGroupChatSession(member.AgentID, groupID))
{
// Don't deliver messages to people who have dropped this session
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: {0} has dropped session, not delivering to them", member.AgentID);
continue;
}
// Copy Message
GridInstantMessage msg = new GridInstantMessage();
msg.imSessionID = groupID.Guid;
msg.fromAgentName = im.fromAgentName;
msg.message = im.message;
msg.dialog = im.dialog;
msg.offline = im.offline;
msg.ParentEstateID = im.ParentEstateID;
msg.Position = im.Position;
msg.RegionID = im.RegionID;
msg.binaryBucket = im.binaryBucket;
msg.timestamp = (uint)Util.UnixTimeSinceEpoch();
msg.fromAgentID = im.fromAgentID;
msg.fromGroup = true;
msg.toAgentID = member.AgentID.Guid;
IClientAPI client = GetActiveClient(member.AgentID);
if (client == null)
{
// If they're not local, forward across the grid
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: Delivering to {0} via Grid", member.AgentID);
m_msgTransferModule.SendInstantMessage(msg, delegate(bool success) { });
}
else
{
// Deliver locally, directly
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: Passing to ProcessMessageFromGroupSession to deliver to {0} locally", client.Name);
ProcessMessageFromGroupSession(msg);
}
}
}
#region SimGridEventHandlers #region SimGridEventHandlers
void OnClientLogin(IClientAPI client)
{
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: OnInstantMessage registered for {0}", client.Name);
}
private void OnNewClient(IClientAPI client) private void OnNewClient(IClientAPI client)
{ {
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: OnInstantMessage registered for {0}", client.Name); if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: OnInstantMessage registered for {0}", client.Name);
@ -236,42 +305,46 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
{ {
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: Session message from {0} going to agent {1}", msg.fromAgentName, msg.toAgentID); if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: Session message from {0} going to agent {1}", msg.fromAgentName, msg.toAgentID);
UUID AgentID = new UUID(msg.fromAgentID);
UUID GroupID = new UUID(msg.imSessionID);
switch (msg.dialog) switch (msg.dialog)
{ {
case (byte)InstantMessageDialog.SessionAdd: case (byte)InstantMessageDialog.SessionAdd:
AddAgentToGroupSession(msg.fromAgentID, msg.imSessionID); m_groupData.AgentInvitedToGroupChatSession(AgentID, GroupID);
break; break;
case (byte)InstantMessageDialog.SessionDrop: case (byte)InstantMessageDialog.SessionDrop:
RemoveAgentFromGroupSession(msg.fromAgentID, msg.imSessionID); m_groupData.AgentDroppedFromGroupChatSession(AgentID, GroupID);
break; break;
case (byte)InstantMessageDialog.SessionSend: case (byte)InstantMessageDialog.SessionSend:
if (!m_agentsInGroupSession.ContainsKey(msg.toAgentID) if (!m_groupData.hasAgentDroppedGroupChatSession(AgentID, GroupID)
&& !m_agentsDroppedSession.ContainsKey(msg.toAgentID)) && !m_groupData.hasAgentBeenInvitedToGroupChatSession(AgentID, GroupID)
)
{ {
// Agent not in session and hasn't dropped from session // Agent not in session and hasn't dropped from session
// Add them to the session for now, and Invite them // Add them to the session for now, and Invite them
AddAgentToGroupSession(msg.toAgentID, msg.imSessionID); m_groupData.AgentInvitedToGroupChatSession(AgentID, GroupID);
UUID toAgentID = new UUID(msg.toAgentID); UUID toAgentID = new UUID(msg.toAgentID);
IClientAPI activeClient = GetActiveClient(toAgentID); IClientAPI activeClient = GetActiveClient(toAgentID);
if (activeClient != null) if (activeClient != null)
{ {
UUID groupID = new UUID(msg.fromAgentID); GroupRecord groupInfo = m_groupData.GetGroupRecord(UUID.Zero, GroupID, null);
GroupRecord groupInfo = m_groupsModule.GetGroupRecord(groupID);
if (groupInfo != null) if (groupInfo != null)
{ {
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: Sending chatterbox invite instant message"); if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: Sending chatterbox invite instant message");
// Force? open the group session dialog??? // Force? open the group session dialog???
// and simultanously deliver the message, so we don't need to do a seperate client.SendInstantMessage(msg);
IEventQueue eq = activeClient.Scene.RequestModuleInterface<IEventQueue>(); IEventQueue eq = activeClient.Scene.RequestModuleInterface<IEventQueue>();
eq.ChatterboxInvitation( eq.ChatterboxInvitation(
groupID GroupID
, groupInfo.GroupName , groupInfo.GroupName
, new UUID(msg.fromAgentID) , new UUID(msg.fromAgentID)
, msg.message, new UUID(msg.toAgentID) , msg.message
, new UUID(msg.toAgentID)
, msg.fromAgentName , msg.fromAgentName
, msg.dialog , msg.dialog
, msg.timestamp , msg.timestamp
@ -285,7 +358,7 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
); );
eq.ChatterBoxSessionAgentListUpdates( eq.ChatterBoxSessionAgentListUpdates(
new UUID(groupID) new UUID(GroupID)
, new UUID(msg.fromAgentID) , new UUID(msg.fromAgentID)
, new UUID(msg.toAgentID) , new UUID(msg.toAgentID)
, false //canVoiceChat , false //canVoiceChat
@ -295,7 +368,7 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
} }
} }
} }
else if (!m_agentsDroppedSession.ContainsKey(msg.toAgentID)) else if (!m_groupData.hasAgentDroppedGroupChatSession(AgentID, GroupID))
{ {
// User hasn't dropped, so they're in the session, // User hasn't dropped, so they're in the session,
// maybe we should deliver it. // maybe we should deliver it.
@ -321,56 +394,8 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
#endregion #endregion
#region ClientEvents #region ClientEvents
private void RemoveAgentFromGroupSession(Guid agentID, Guid sessionID)
{
if (m_agentsInGroupSession.ContainsKey(sessionID))
{
// If in session remove
if (m_agentsInGroupSession[sessionID].Contains(agentID))
{
m_agentsInGroupSession[sessionID].Remove(agentID);
}
// If not in dropped list, add
if (!m_agentsDroppedSession[sessionID].Contains(agentID))
{
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: Dropped {1} from session {0}", sessionID, agentID);
m_agentsDroppedSession[sessionID].Add(agentID);
}
}
}
private void AddAgentToGroupSession(Guid agentID, Guid sessionID)
{
// Add Session Status if it doesn't exist for this session
CreateGroupSessionTracking(sessionID);
// If nessesary, remove from dropped list
if (m_agentsDroppedSession[sessionID].Contains(agentID))
{
m_agentsDroppedSession[sessionID].Remove(agentID);
}
// If nessesary, add to in session list
if (!m_agentsInGroupSession[sessionID].Contains(agentID))
{
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: Added {1} to session {0}", sessionID, agentID);
m_agentsInGroupSession[sessionID].Add(agentID);
}
}
private void CreateGroupSessionTracking(Guid sessionID)
{
if (!m_agentsInGroupSession.ContainsKey(sessionID))
{
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: Creating session tracking for : {0}", sessionID);
m_agentsInGroupSession.Add(sessionID, new List<Guid>());
m_agentsDroppedSession.Add(sessionID, new List<Guid>());
}
}
private void OnInstantMessage(IClientAPI remoteClient, GridInstantMessage im) private void OnInstantMessage(IClientAPI remoteClient, GridInstantMessage im)
{ {
if (m_debugEnabled) if (m_debugEnabled)
@ -383,21 +408,23 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
// Start group IM session // Start group IM session
if ((im.dialog == (byte)InstantMessageDialog.SessionGroupStart)) if ((im.dialog == (byte)InstantMessageDialog.SessionGroupStart))
{ {
UUID groupID = new UUID(im.toAgentID); if (m_debugEnabled) m_log.InfoFormat("[GROUPS-MESSAGING]: imSessionID({0}) toAgentID({1})", im.imSessionID, im.toAgentID);
GroupRecord groupInfo = m_groupsModule.GetGroupRecord(groupID); UUID GroupID = new UUID(im.imSessionID);
UUID AgentID = new UUID(im.fromAgentID);
GroupRecord groupInfo = m_groupData.GetGroupRecord(UUID.Zero, GroupID, null);
if (groupInfo != null) if (groupInfo != null)
{ {
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: Start Group Session for {0}", groupInfo.GroupName); m_groupData.AgentInvitedToGroupChatSession(AgentID, GroupID);
AddAgentToGroupSession(im.fromAgentID, im.imSessionID); ChatterBoxSessionStartReplyViaCaps(remoteClient, groupInfo.GroupName, GroupID);
ChatterBoxSessionStartReplyViaCaps(remoteClient, groupInfo.GroupName, groupID);
IEventQueue queue = remoteClient.Scene.RequestModuleInterface<IEventQueue>(); IEventQueue queue = remoteClient.Scene.RequestModuleInterface<IEventQueue>();
queue.ChatterBoxSessionAgentListUpdates( queue.ChatterBoxSessionAgentListUpdates(
new UUID(groupID) GroupID
, new UUID(im.fromAgentID) , AgentID
, new UUID(im.toAgentID) , new UUID(im.toAgentID)
, false //canVoiceChat , false //canVoiceChat
, false //isModerator , false //isModerator
@ -409,64 +436,21 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
// Send a message from locally connected client to a group // Send a message from locally connected client to a group
if ((im.dialog == (byte)InstantMessageDialog.SessionSend)) if ((im.dialog == (byte)InstantMessageDialog.SessionSend))
{ {
UUID groupID = new UUID(im.toAgentID); UUID GroupID = new UUID(im.imSessionID);
UUID AgentID = new UUID(im.fromAgentID);
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: Send message to session for group {0} with session ID {1}", groupID, im.imSessionID.ToString()); if (m_debugEnabled)
m_log.DebugFormat("[GROUPS-MESSAGING]: Send message to session for group {0} with session ID {1}", GroupID, im.imSessionID.ToString());
SendMessageToGroup(im, groupID); //If this agent is sending a message, then they want to be in the session
m_groupData.AgentInvitedToGroupChatSession(AgentID, GroupID);
SendMessageToGroup(im, GroupID);
} }
} }
#endregion #endregion
private void SendMessageToGroup(GridInstantMessage im, UUID groupID)
{
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: {0} called", System.Reflection.MethodBase.GetCurrentMethod().Name);
foreach (GroupMembersData member in m_groupsModule.GroupMembersRequest(null, groupID))
{
if (!m_agentsDroppedSession.ContainsKey(im.imSessionID) || m_agentsDroppedSession[im.imSessionID].Contains(member.AgentID.Guid))
{
// Don't deliver messages to people who have dropped this session
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: {0} has dropped session, not delivering to them", member.AgentID);
continue;
}
// Copy Message
GridInstantMessage msg = new GridInstantMessage();
msg.imSessionID = im.imSessionID;
msg.fromAgentName = im.fromAgentName;
msg.message = im.message;
msg.dialog = im.dialog;
msg.offline = im.offline;
msg.ParentEstateID = im.ParentEstateID;
msg.Position = im.Position;
msg.RegionID = im.RegionID;
msg.binaryBucket = im.binaryBucket;
msg.timestamp = (uint)Util.UnixTimeSinceEpoch();
// Updat Pertinate fields to make it a "group message"
msg.fromAgentID = groupID.Guid;
msg.fromGroup = true;
msg.toAgentID = member.AgentID.Guid;
IClientAPI client = GetActiveClient(member.AgentID);
if (client == null)
{
// If they're not local, forward across the grid
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: Delivering to {0} via Grid", member.AgentID);
m_msgTransferModule.SendInstantMessage(msg, delegate(bool success) { });
}
else
{
// Deliver locally, directly
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: Passing to ProcessMessageFromGroupSession to deliver to {0} locally", client.Name);
ProcessMessageFromGroupSession(msg);
}
}
}
void ChatterBoxSessionStartReplyViaCaps(IClientAPI remoteClient, string groupName, UUID groupID) void ChatterBoxSessionStartReplyViaCaps(IClientAPI remoteClient, string groupName, UUID groupID)
{ {
if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: {0} called", System.Reflection.MethodBase.GetCurrentMethod().Name); if (m_debugEnabled) m_log.DebugFormat("[GROUPS-MESSAGING]: {0} called", System.Reflection.MethodBase.GetCurrentMethod().Name);
@ -518,6 +502,8 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
/// </summary> /// </summary>
private IClientAPI GetActiveClient(UUID agentID) private IClientAPI GetActiveClient(UUID agentID)
{ {
if (m_debugEnabled) m_log.WarnFormat("[GROUPS-MESSAGING]: Looking for local client {0}", agentID);
IClientAPI child = null; IClientAPI child = null;
// Try root avatar first // Try root avatar first
@ -529,16 +515,26 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
ScenePresence user = (ScenePresence)scene.Entities[agentID]; ScenePresence user = (ScenePresence)scene.Entities[agentID];
if (!user.IsChildAgent) if (!user.IsChildAgent)
{ {
if (m_debugEnabled) m_log.WarnFormat("[GROUPS-MESSAGING]: Found root agent for client : {0}", user.ControllingClient.Name);
return user.ControllingClient; return user.ControllingClient;
} }
else else
{ {
if (m_debugEnabled) m_log.WarnFormat("[GROUPS-MESSAGING]: Found child agent for client : {0}", user.ControllingClient.Name);
child = user.ControllingClient; child = user.ControllingClient;
} }
} }
} }
// If we didn't find a root, then just return whichever child we found, or null if none // If we didn't find a root, then just return whichever child we found, or null if none
if (child == null)
{
if (m_debugEnabled) m_log.WarnFormat("[GROUPS-MESSAGING]: Could not find local client for agent : {0}", agentID);
}
else
{
if (m_debugEnabled) m_log.WarnFormat("[GROUPS-MESSAGING]: Returning child agent for client : {0}", child.Name);
}
return child; return child;
} }

View File

@ -176,7 +176,6 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
scene.EventManager.OnNewClient += OnNewClient; scene.EventManager.OnNewClient += OnNewClient;
scene.EventManager.OnIncomingInstantMessage += OnGridInstantMessage; scene.EventManager.OnIncomingInstantMessage += OnGridInstantMessage;
// The InstantMessageModule itself doesn't do this, // The InstantMessageModule itself doesn't do this,
// so lets see if things explode if we don't do it // so lets see if things explode if we don't do it
// scene.EventManager.OnClientClosed += OnClientClosed; // scene.EventManager.OnClientClosed += OnClientClosed;
@ -510,7 +509,7 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
IClientAPI ejectee = GetActiveClient(ejecteeID); IClientAPI ejectee = GetActiveClient(ejecteeID);
if (ejectee != null) if (ejectee != null)
{ {
UUID groupID = new UUID(im.fromAgentID); UUID groupID = new UUID(im.imSessionID);
ejectee.SendAgentDropGroup(groupID); ejectee.SendAgentDropGroup(groupID);
} }
} }

View File

@ -71,6 +71,12 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
void AddGroupNotice(UUID RequestingAgentID, UUID groupID, UUID noticeID, string fromName, string subject, string message, byte[] binaryBucket); void AddGroupNotice(UUID RequestingAgentID, UUID groupID, UUID noticeID, string fromName, string subject, string message, byte[] binaryBucket);
GroupNoticeInfo GetGroupNotice(UUID RequestingAgentID, UUID noticeID); GroupNoticeInfo GetGroupNotice(UUID RequestingAgentID, UUID noticeID);
List<GroupNoticeData> GetGroupNotices(UUID RequestingAgentID, UUID GroupID); List<GroupNoticeData> GetGroupNotices(UUID RequestingAgentID, UUID GroupID);
void ResetAgentGroupChatSessions(UUID agentID);
bool hasAgentBeenInvitedToGroupChatSession(UUID agentID, UUID groupID);
bool hasAgentDroppedGroupChatSession(UUID agentID, UUID groupID);
void AgentDroppedFromGroupChatSession(UUID agentID, UUID groupID);
void AgentInvitedToGroupChatSession(UUID agentID, UUID groupID);
} }
public class GroupInviteInfo public class GroupInviteInfo

View File

@ -55,6 +55,9 @@ using OpenSim.Services.Interfaces;
* UserID -> Group -> ActiveGroup * UserID -> Group -> ActiveGroup
* + GroupID * + GroupID
* *
* UserID -> GroupSessionDropped -> GroupID
* UserID -> GroupSessionInvited -> GroupID
*
* UserID -> GroupMember -> GroupID * UserID -> GroupMember -> GroupID
* + SelectedRoleID [UUID] * + SelectedRoleID [UUID]
* + AcceptNotices [bool] * + AcceptNotices [bool]
@ -63,6 +66,7 @@ using OpenSim.Services.Interfaces;
* *
* UserID -> GroupRole[GroupID] -> RoleID * UserID -> GroupRole[GroupID] -> RoleID
* *
*
* GroupID -> Group -> GroupName * GroupID -> Group -> GroupName
* + Charter * + Charter
* + ShowInList * + ShowInList
@ -159,10 +163,13 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
private bool m_connectorEnabled = false; private bool m_connectorEnabled = false;
private string m_serviceURL = string.Empty; private string m_groupsServerURI = string.Empty;
private bool m_debugEnabled = false; private bool m_debugEnabled = false;
private ExpiringCache<string, OSDMap> m_memoryCache;
private int m_cacheTimeout = 30;
// private IUserAccountService m_accountService = null; // private IUserAccountService m_accountService = null;
@ -199,17 +206,33 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
return; return;
} }
m_log.InfoFormat("[GROUPS-CONNECTOR]: Initializing {0}", this.Name); m_log.InfoFormat("[SIMIAN-GROUPS-CONNECTOR]: Initializing {0}", this.Name);
m_serviceURL = groupsConfig.GetString("XmlRpcServiceURL", string.Empty); m_groupsServerURI = groupsConfig.GetString("GroupsServerURI", string.Empty);
if ((m_serviceURL == null) || if ((m_groupsServerURI == null) ||
(m_serviceURL == string.Empty)) (m_groupsServerURI == string.Empty))
{ {
m_log.ErrorFormat("Please specify a valid Simian Server URL for XmlRpcServiceURL in OpenSim.ini, [Groups]"); m_log.ErrorFormat("Please specify a valid Simian Server for GroupsServerURI in OpenSim.ini, [Groups]");
m_connectorEnabled = false; m_connectorEnabled = false;
return; return;
} }
m_cacheTimeout = groupsConfig.GetInt("GroupsCacheTimeout", 30);
if (m_cacheTimeout == 0)
{
m_log.WarnFormat("[SIMIAN-GROUPS-CONNECTOR] Groups Cache Disabled.");
}
else
{
m_log.InfoFormat("[SIMIAN-GROUPS-CONNECTOR] Groups Cache Timeout set to {0}.", m_cacheTimeout);
}
m_memoryCache = new ExpiringCache<string,OSDMap>();
// If we got all the config options we need, lets start'er'up // If we got all the config options we need, lets start'er'up
m_connectorEnabled = true; m_connectorEnabled = true;
@ -220,7 +243,7 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
public void Close() public void Close()
{ {
m_log.InfoFormat("[GROUPS-CONNECTOR]: Closing {0}", this.Name); m_log.InfoFormat("[SIMIAN-GROUPS-CONNECTOR]: Closing {0}", this.Name);
} }
public void AddRegion(OpenSim.Region.Framework.Scenes.Scene scene) public void AddRegion(OpenSim.Region.Framework.Scenes.Scene scene)
@ -653,7 +676,7 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
}; };
OSDMap response = WebUtil.PostToService(m_serviceURL, requestArgs); OSDMap response = CachedPostRequest(requestArgs);
if (response["Success"].AsBoolean() && response["Entries"] is OSDArray) if (response["Success"].AsBoolean() && response["Entries"] is OSDArray)
{ {
OSDArray entryArray = (OSDArray)response["Entries"]; OSDArray entryArray = (OSDArray)response["Entries"];
@ -998,6 +1021,52 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
} }
#endregion #endregion
#region GroupSessionTracking
public void ResetAgentGroupChatSessions(UUID agentID)
{
Dictionary<string, OSDMap> agentSessions;
if (SimianGetGenericEntries(agentID, "GroupSessionDropped", out agentSessions))
{
foreach (string GroupID in agentSessions.Keys)
{
SimianRemoveGenericEntry(agentID, "GroupSessionDropped", GroupID);
}
}
if (SimianGetGenericEntries(agentID, "GroupSessionInvited", out agentSessions))
{
foreach (string GroupID in agentSessions.Keys)
{
SimianRemoveGenericEntry(agentID, "GroupSessionInvited", GroupID);
}
}
}
public bool hasAgentDroppedGroupChatSession(UUID agentID, UUID groupID)
{
OSDMap session;
return SimianGetGenericEntry(agentID, "GroupSessionDropped", groupID.ToString(), out session);
}
public void AgentDroppedFromGroupChatSession(UUID agentID, UUID groupID)
{
SimianAddGeneric(agentID, "GroupSessionDropped", groupID.ToString(), new OSDMap());
}
public void AgentInvitedToGroupChatSession(UUID agentID, UUID groupID)
{
SimianAddGeneric(agentID, "GroupSessionInvited", groupID.ToString(), new OSDMap());
}
public bool hasAgentBeenInvitedToGroupChatSession(UUID agentID, UUID groupID)
{
OSDMap session;
return SimianGetGenericEntry(agentID, "GroupSessionDropped", groupID.ToString(), out session);
}
#endregion
private void EnsureRoleNotSelectedByMember(UUID groupID, UUID roleID, UUID userID) private void EnsureRoleNotSelectedByMember(UUID groupID, UUID roleID, UUID userID)
{ {
@ -1036,7 +1105,7 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
}; };
OSDMap Response = WebUtil.PostToService(m_serviceURL, RequestArgs); OSDMap Response = CachedPostRequest(RequestArgs);
if (Response["Success"].AsBoolean()) if (Response["Success"].AsBoolean())
{ {
return true; return true;
@ -1063,7 +1132,7 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
}; };
OSDMap Response = WebUtil.PostToService(m_serviceURL, RequestArgs); OSDMap Response = CachedPostRequest(RequestArgs);
if (Response["Success"].AsBoolean() && Response["Entries"] is OSDArray) if (Response["Success"].AsBoolean() && Response["Entries"] is OSDArray)
{ {
OSDArray entryArray = (OSDArray)Response["Entries"]; OSDArray entryArray = (OSDArray)Response["Entries"];
@ -1103,7 +1172,7 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
}; };
OSDMap Response = WebUtil.PostToService(m_serviceURL, RequestArgs); OSDMap Response = CachedPostRequest(RequestArgs);
if (Response["Success"].AsBoolean() && Response["Entries"] is OSDArray) if (Response["Success"].AsBoolean() && Response["Entries"] is OSDArray)
{ {
OSDArray entryArray = (OSDArray)Response["Entries"]; OSDArray entryArray = (OSDArray)Response["Entries"];
@ -1144,7 +1213,7 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
}; };
OSDMap Response = WebUtil.PostToService(m_serviceURL, RequestArgs); OSDMap Response = CachedPostRequest(RequestArgs);
if (Response["Success"].AsBoolean() && Response["Entries"] is OSDArray) if (Response["Success"].AsBoolean() && Response["Entries"] is OSDArray)
{ {
OSDArray entryArray = (OSDArray)Response["Entries"]; OSDArray entryArray = (OSDArray)Response["Entries"];
@ -1184,7 +1253,7 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
OSDMap response = WebUtil.PostToService(m_serviceURL, requestArgs); OSDMap response = CachedPostRequest(requestArgs);
if (response["Success"].AsBoolean() && response["Entries"] is OSDArray) if (response["Success"].AsBoolean() && response["Entries"] is OSDArray)
{ {
maps = new Dictionary<string, OSDMap>(); maps = new Dictionary<string, OSDMap>();
@ -1222,7 +1291,7 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
OSDMap response = WebUtil.PostToService(m_serviceURL, requestArgs); OSDMap response = CachedPostRequest(requestArgs);
if (response["Success"].AsBoolean() && response["Entries"] is OSDArray) if (response["Success"].AsBoolean() && response["Entries"] is OSDArray)
{ {
maps = new Dictionary<UUID, OSDMap>(); maps = new Dictionary<UUID, OSDMap>();
@ -1260,7 +1329,7 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
}; };
OSDMap response = WebUtil.PostToService(m_serviceURL, requestArgs); OSDMap response = CachedPostRequest(requestArgs);
if (response["Success"].AsBoolean()) if (response["Success"].AsBoolean())
{ {
return true; return true;
@ -1272,6 +1341,49 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
} }
} }
#endregion #endregion
#region CheesyCache
OSDMap CachedPostRequest(NameValueCollection requestArgs)
{
// Immediately forward the request if the cache is disabled.
if (m_cacheTimeout == 0)
{
return WebUtil.PostToService(m_groupsServerURI, requestArgs);
}
// Check if this is an update or a request
if ( requestArgs["RequestMethod"] == "RemoveGeneric"
|| requestArgs["RequestMethod"] == "AddGeneric"
)
{
// Any and all updates cause the cache to clear
m_memoryCache.Clear();
// Send update to server, return the response without caching it
return WebUtil.PostToService(m_groupsServerURI, requestArgs);
}
// If we're not doing an update, we must be requesting data
// Create the cache key for the request and see if we have it cached
string CacheKey = WebUtil.BuildQueryString(requestArgs);
OSDMap response = null;
if (!m_memoryCache.TryGetValue(CacheKey, out response))
{
// if it wasn't in the cache, pass the request to the Simian Grid Services
response = WebUtil.PostToService(m_groupsServerURI, requestArgs);
// and cache the response
m_memoryCache.AddOrUpdate(CacheKey, response, TimeSpan.FromSeconds(m_cacheTimeout));
}
// return cached response
return response;
}
#endregion
} }
} }

View File

@ -29,6 +29,7 @@ using System;
using System.Collections; using System.Collections;
using System.Collections.Generic; using System.Collections.Generic;
using System.Reflection; using System.Reflection;
using System.Text;
using Nwc.XmlRpc; using Nwc.XmlRpc;
@ -61,7 +62,7 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
private bool m_connectorEnabled = false; private bool m_connectorEnabled = false;
private string m_serviceURL = string.Empty; private string m_groupsServerURI = string.Empty;
private bool m_disableKeepAlive = false; private bool m_disableKeepAlive = false;
@ -69,7 +70,17 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
private string m_groupWriteKey = string.Empty; private string m_groupWriteKey = string.Empty;
private IUserAccountService m_accountService = null; private IUserAccountService m_accountService = null;
private ExpiringCache<string, XmlRpcResponse> m_memoryCache;
private int m_cacheTimeout = 30;
// Used to track which agents are have dropped from a group chat session
// Should be reset per agent, on logon
// TODO: move this to Flotsam XmlRpc Service
// SessionID, List<AgentID>
private Dictionary<UUID, List<UUID>> m_groupsAgentsDroppedFromChatSession = new Dictionary<UUID, List<UUID>>();
private Dictionary<UUID, List<UUID>> m_groupsAgentsInvitedToChatSession = new Dictionary<UUID, List<UUID>>();
#region IRegionModuleBase Members #region IRegionModuleBase Members
@ -104,13 +115,13 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
return; return;
} }
m_log.InfoFormat("[GROUPS-CONNECTOR]: Initializing {0}", this.Name); m_log.InfoFormat("[XMLRPC-GROUPS-CONNECTOR]: Initializing {0}", this.Name);
m_serviceURL = groupsConfig.GetString("XmlRpcServiceURL", string.Empty); m_groupsServerURI = groupsConfig.GetString("GroupsServerURI", string.Empty);
if ((m_serviceURL == null) || if ((m_groupsServerURI == null) ||
(m_serviceURL == string.Empty)) (m_groupsServerURI == string.Empty))
{ {
m_log.ErrorFormat("Please specify a valid URL for XmlRpcServiceURL in OpenSim.ini, [Groups]"); m_log.ErrorFormat("Please specify a valid URL for GroupsServerURI in OpenSim.ini, [Groups]");
m_connectorEnabled = false; m_connectorEnabled = false;
return; return;
} }
@ -120,17 +131,26 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
m_groupReadKey = groupsConfig.GetString("XmlRpcServiceReadKey", string.Empty); m_groupReadKey = groupsConfig.GetString("XmlRpcServiceReadKey", string.Empty);
m_groupWriteKey = groupsConfig.GetString("XmlRpcServiceWriteKey", string.Empty); m_groupWriteKey = groupsConfig.GetString("XmlRpcServiceWriteKey", string.Empty);
m_cacheTimeout = groupsConfig.GetInt("GroupsCacheTimeout", 30);
if (m_cacheTimeout == 0)
{
m_log.WarnFormat("[XMLRPC-GROUPS-CONNECTOR]: Groups Cache Disabled.");
}
else
{
m_log.InfoFormat("[XMLRPC-GROUPS-CONNECTOR]: Groups Cache Timeout set to {0}.", m_cacheTimeout);
}
// If we got all the config options we need, lets start'er'up // If we got all the config options we need, lets start'er'up
m_memoryCache = new ExpiringCache<string, XmlRpcResponse>();
m_connectorEnabled = true; m_connectorEnabled = true;
} }
} }
public void Close() public void Close()
{ {
m_log.InfoFormat("[GROUPS-CONNECTOR]: Closing {0}", this.Name); m_log.InfoFormat("[XMLRPC-GROUPS-CONNECTOR]: Closing {0}", this.Name);
} }
public void AddRegion(OpenSim.Region.Framework.Scenes.Scene scene) public void AddRegion(OpenSim.Region.Framework.Scenes.Scene scene)
@ -756,6 +776,69 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
XmlRpcCall(requestingAgentID, "groups.addGroupNotice", param); XmlRpcCall(requestingAgentID, "groups.addGroupNotice", param);
} }
#endregion
#region GroupSessionTracking
public void ResetAgentGroupChatSessions(UUID agentID)
{
foreach (List<UUID> agentList in m_groupsAgentsDroppedFromChatSession.Values)
{
agentList.Remove(agentID);
}
}
public bool hasAgentBeenInvitedToGroupChatSession(UUID agentID, UUID groupID)
{
// If we're tracking this group, and we can find them in the tracking, then they've been invited
return m_groupsAgentsInvitedToChatSession.ContainsKey(groupID)
&& m_groupsAgentsInvitedToChatSession[groupID].Contains(agentID);
}
public bool hasAgentDroppedGroupChatSession(UUID agentID, UUID groupID)
{
// If we're tracking drops for this group,
// and we find them, well... then they've dropped
return m_groupsAgentsDroppedFromChatSession.ContainsKey(groupID)
&& m_groupsAgentsDroppedFromChatSession[groupID].Contains(agentID);
}
public void AgentDroppedFromGroupChatSession(UUID agentID, UUID groupID)
{
if (m_groupsAgentsDroppedFromChatSession.ContainsKey(groupID))
{
// If not in dropped list, add
if (!m_groupsAgentsDroppedFromChatSession[groupID].Contains(agentID))
{
m_groupsAgentsDroppedFromChatSession[groupID].Add(agentID);
}
}
}
public void AgentInvitedToGroupChatSession(UUID agentID, UUID groupID)
{
// Add Session Status if it doesn't exist for this session
CreateGroupChatSessionTracking(groupID);
// If nessesary, remove from dropped list
if (m_groupsAgentsDroppedFromChatSession[groupID].Contains(agentID))
{
m_groupsAgentsDroppedFromChatSession[groupID].Remove(agentID);
}
}
private void CreateGroupChatSessionTracking(UUID groupID)
{
if (!m_groupsAgentsDroppedFromChatSession.ContainsKey(groupID))
{
m_groupsAgentsDroppedFromChatSession.Add(groupID, new List<UUID>());
m_groupsAgentsInvitedToChatSession.Add(groupID, new List<UUID>());
}
}
#endregion #endregion
#region XmlRpcHashtableMarshalling #region XmlRpcHashtableMarshalling
@ -849,50 +932,84 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
/// </summary> /// </summary>
private Hashtable XmlRpcCall(UUID requestingAgentID, string function, Hashtable param) private Hashtable XmlRpcCall(UUID requestingAgentID, string function, Hashtable param)
{ {
string UserService;
UUID SessionID;
GetClientGroupRequestID(requestingAgentID, out UserService, out SessionID);
param.Add("requestingAgentID", requestingAgentID.ToString());
param.Add("RequestingAgentUserService", UserService);
param.Add("RequestingSessionID", SessionID.ToString());
param.Add("ReadKey", m_groupReadKey);
param.Add("WriteKey", m_groupWriteKey);
IList parameters = new ArrayList();
parameters.Add(param);
ConfigurableKeepAliveXmlRpcRequest req;
req = new ConfigurableKeepAliveXmlRpcRequest(function, parameters, m_disableKeepAlive);
XmlRpcResponse resp = null; XmlRpcResponse resp = null;
string CacheKey = null;
try // Only bother with the cache if it isn't disabled.
if (m_cacheTimeout > 0)
{ {
resp = req.Send(m_serviceURL, 10000); if (!function.StartsWith("groups.get"))
{
// Any and all updates cause the cache to clear
m_memoryCache.Clear();
}
else
{
StringBuilder sb = new StringBuilder(requestingAgentID + function);
foreach (object key in param.Keys)
{
if (param[key] != null)
{
sb.AppendFormat(",{0}:{1}", key.ToString(), param[key].ToString());
}
}
CacheKey = sb.ToString();
m_memoryCache.TryGetValue(CacheKey, out resp);
}
} }
catch (Exception e)
if( resp == null )
{ {
string UserService;
UUID SessionID;
GetClientGroupRequestID(requestingAgentID, out UserService, out SessionID);
param.Add("requestingAgentID", requestingAgentID.ToString());
param.Add("RequestingAgentUserService", UserService);
param.Add("RequestingSessionID", SessionID.ToString());
m_log.ErrorFormat("[XMLRPCGROUPDATA]: An error has occured while attempting to access the XmlRpcGroups server method: {0}", function);
m_log.ErrorFormat("[XMLRPCGROUPDATA]: {0} ", e.ToString());
foreach (string ResponseLine in req.RequestResponse.Split(new string[] { Environment.NewLine },StringSplitOptions.None)) param.Add("ReadKey", m_groupReadKey);
param.Add("WriteKey", m_groupWriteKey);
IList parameters = new ArrayList();
parameters.Add(param);
ConfigurableKeepAliveXmlRpcRequest req;
req = new ConfigurableKeepAliveXmlRpcRequest(function, parameters, m_disableKeepAlive);
try
{ {
m_log.ErrorFormat("[XMLRPCGROUPDATA]: {0} ", ResponseLine); resp = req.Send(m_groupsServerURI, 10000);
}
foreach (string key in param.Keys) if ((m_cacheTimeout > 0) && (CacheKey != null))
{
m_memoryCache.AddOrUpdate(CacheKey, resp, TimeSpan.FromSeconds(m_cacheTimeout));
}
}
catch (Exception e)
{ {
m_log.WarnFormat("[XMLRPCGROUPDATA]: {0} :: {1}", key, param[key].ToString()); m_log.ErrorFormat("[XMLRPC-GROUPS-CONNECTOR]: An error has occured while attempting to access the XmlRpcGroups server method: {0}", function);
} m_log.ErrorFormat("[XMLRPC-GROUPS-CONNECTOR]: {0} ", e.ToString());
Hashtable respData = new Hashtable(); foreach (string ResponseLine in req.RequestResponse.Split(new string[] { Environment.NewLine }, StringSplitOptions.None))
respData.Add("error", e.ToString()); {
return respData; m_log.ErrorFormat("[XMLRPC-GROUPS-CONNECTOR]: {0} ", ResponseLine);
}
foreach (string key in param.Keys)
{
m_log.WarnFormat("[XMLRPC-GROUPS-CONNECTOR]: {0} :: {1}", key, param[key].ToString());
}
Hashtable respData = new Hashtable();
respData.Add("error", e.ToString());
return respData;
}
} }
if (resp.Value is Hashtable) if (resp.Value is Hashtable)
@ -906,21 +1023,21 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
return respData; return respData;
} }
m_log.ErrorFormat("[XMLRPCGROUPDATA]: The XmlRpc server returned a {1} instead of a hashtable for {0}", function, resp.Value.GetType().ToString()); m_log.ErrorFormat("[XMLRPC-GROUPS-CONNECTOR]: The XmlRpc server returned a {1} instead of a hashtable for {0}", function, resp.Value.GetType().ToString());
if (resp.Value is ArrayList) if (resp.Value is ArrayList)
{ {
ArrayList al = (ArrayList)resp.Value; ArrayList al = (ArrayList)resp.Value;
m_log.ErrorFormat("[XMLRPCGROUPDATA]: Contains {0} elements", al.Count); m_log.ErrorFormat("[XMLRPC-GROUPS-CONNECTOR]: Contains {0} elements", al.Count);
foreach (object o in al) foreach (object o in al)
{ {
m_log.ErrorFormat("[XMLRPCGROUPDATA]: {0} :: {1}", o.GetType().ToString(), o.ToString()); m_log.ErrorFormat("[XMLRPC-GROUPS-CONNECTOR]: {0} :: {1}", o.GetType().ToString(), o.ToString());
} }
} }
else else
{ {
m_log.ErrorFormat("[XMLRPCGROUPDATA]: Function returned: {0}", resp.Value.ToString()); m_log.ErrorFormat("[XMLRPC-GROUPS-CONNECTOR]: Function returned: {0}", resp.Value.ToString());
} }
Hashtable error = new Hashtable(); Hashtable error = new Hashtable();
@ -930,16 +1047,16 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
private void LogRespDataToConsoleError(Hashtable respData) private void LogRespDataToConsoleError(Hashtable respData)
{ {
m_log.Error("[XMLRPCGROUPDATA]: Error:"); m_log.Error("[XMLRPC-GROUPS-CONNECTOR]: Error:");
foreach (string key in respData.Keys) foreach (string key in respData.Keys)
{ {
m_log.ErrorFormat("[XMLRPCGROUPDATA]: Key: {0}", key); m_log.ErrorFormat("[XMLRPC-GROUPS-CONNECTOR]: Key: {0}", key);
string[] lines = respData[key].ToString().Split(new char[] { '\n' }); string[] lines = respData[key].ToString().Split(new char[] { '\n' });
foreach (string line in lines) foreach (string line in lines)
{ {
m_log.ErrorFormat("[XMLRPCGROUPDATA]: {0}", line); m_log.ErrorFormat("[XMLRPC-GROUPS-CONNECTOR]: {0}", line);
} }
} }
@ -948,8 +1065,8 @@ namespace OpenSim.Region.OptionalModules.Avatar.XmlRpcGroups
/// <summary> /// <summary>
/// Group Request Tokens are an attempt to allow the groups service to authenticate /// Group Request Tokens are an attempt to allow the groups service to authenticate
/// requests. Currently uses UserService, AgentID, and SessionID /// requests.
/// TODO: Find a better way to do this. /// TODO: This broke after the big grid refactor, either find a better way, or discard this
/// </summary> /// </summary>
/// <param name="client"></param> /// <param name="client"></param>
/// <returns></returns> /// <returns></returns>