/*********************************************************************/
/*                                                                   */
/*                     AgentService Framework                        */
/*                       www.agentservice.it                         */
/*                                                                   */
/* Copyright (C) 2007 l.i.d.o. - DIST, University of Genoa, Italy    */
/* GNU Lesser General Public License                                 */
/*                                                                   */
/* This library is free software; you can redistribute it and/or     */
/* modify it under the terms of the GNU Lesser General Public        */
/* License as published by the Free Software Foundation,             */
/* version 2.1 of the License.                                       */
/*                                                                   */
/* This library is distributed in the hope that it will be useful,   */
/* but WITHOUT ANY WARRANTY; without even the implied warranty of    */
/* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU */
/* Lesser General Public License for more details.                   */
/*                                                                   */
/* You should have received a copy of the GNU Lesser General Public  */
/* License along with this library; if not, write to the             */
/* Free Software Foundation, Inc., 59 Temple Place - Suite 330,      */
/* Boston, MA  02111-1307, USA.                                      */
/*                                                                   */
/*********************************************************************/
using System;

using AgentService.Platform.AMS;
using AgentService.Platform.MTS;
using AgentService.Agent.Runtime;

namespace AgentService.Platform.Modules
{

	/// <summary>
	/// Delegate MessageEventHandler. Call-back signature for
	/// methods used to handle messages sent to core agents.
	/// </summary>
	public delegate void MessageEventHandler(AgentMessage message);

	/// <summary>
	/// Interface IMessagingModule. Defines the 
	/// basic functionalities that each concrete
	/// messaging subsystem must implement in order
	/// to be plugged into the AgentService platform
	/// </summary>
	public interface IMessagingModule : IPlatformModule
	{
		/// <summary>
		/// Creates a message queue owned by the given agent.
		/// </summary>
		/// <param name="aid">agent identifier of the agent that owns the queue</param>
		/// <returns>true if the queue has been successfully created</returns>
		bool CreateAgentQueue(AID aid);
		
		/// <summary>
		/// Removes a message queue owned by the given agent.
		/// </summary>
		/// <param name="aid">agent identifier of the agent that owns the queue</param>
		/// <returns>true if the queue has been successfully removed</returns>
		bool RemoveAgentQueue(AID aid);

		/// <summary>
		/// Checks whether a queue has messages.
		/// </summary>
		/// <param name="aid">agent identifier of the owner of the queue</param>
		/// <returns>true if the queue has messages</returns>
		bool HasMessages(AID aid);


		/// <summary>
		/// Sends a message to an agent.
		/// </summary>
		/// <param name="message">message</param>
		/// <returns>true if the message has been successfully sent</returns>
		bool SendMessage(AgentMessage message);


		/// <summary>
		/// Receives a message pops it from the queue.
		/// </summary>
		/// <param name="aid">agent identifier of the agent that owns the queue</param>
		/// <returns>the first message available in the queue</returns>
		AgentMessage ReceiveMessage(AID aid);
		
		/// <summary>
		/// Retrieves all the messages and leaves them in the queue.
		/// </summary>
		/// <param name="aid">agent identifier of the agent that owns the queue</param>
        /// <param name="filter">message filter, set this parameter to null if you do not want to apply any filter</param>
        /// <param name="max">maximum number of element to retrieve place, set this value to 0 or less 
        /// to retrieve all the messages in the queue which satisfy the filter</param>
        /// <param name="bRemove">if true remove the message from the queue</param>
		/// <returns>the collection of messages retrieved from the queue</returns>
		AgentMessageCollection GetMessages(AID aid, MessageFilter filter, int max, bool bRemove);

        /// <summary>
        /// Same as GetMessages but returns just the first message satisfying the filter.
        /// This method provide a fast implementation for retrieving one single implementation
        /// and also provide the implementation of the Peek verb.
        /// </summary>
        /// <param name="aid">agent identifier of the agent that owns the queue</param>
        /// <param name="filter">message filter, null if no filters are required</param>
        /// <param name="bRemove">if true removes the message from the queue</param>
        /// <returns>the first message in the queue or null</returns>
        AgentMessage GetMessage(AID aid, MessageFilter filter, bool bRemove);

		/// <summary>
		/// Creates a client of the messaging module for the given agent.
		/// </summary>
		/// <param name="aid">agent identifier.</param>
		/// <returns>a messaging client for the given agent, null if the module does not provide a custom client.</returns>
		IMsgClient CreateClient(AID aid);

		/// <summary>
		/// Returns true if the messaging module provides a custom client.
		/// </summary>
		bool HasClient 
		{
			get;
		}
		
		/// <summary>
		/// Removes the given message from the queue.
		/// </summary>
		/// <param name="aid">agent identifier of the agent that owns the queue</param>
		/// <param name="message">message to be destroyed</param>
		/// <returns>true if message is successfully removed</returns>
		bool RemoveMessage(AID aid, AgentMessage message);

		/// <summary>
		/// Removes all the messages in each agent queue
		/// </summary>
		/// <returns>True if succeds</returns>
		void ClearAllMessages();

		/// <summary>
		/// Removes all the messages from the queue of the given agent
		/// </summary>
		/// <param name="aid">AID of the agent</param>
		/// <returns>True if succeds</returns>
		bool ClearAllMessages(AID aid);

        /// <summary>
        /// Gets a string containing information about the address of the platform, e.g.: AgentService@10.0.0.1:4989
        /// </summary>
        string TransportProfile
        {
            get;
        }

		/// <summary>
		/// Raises every time a message is sent to the
		/// AMS queue.
		/// </summary>
		event MessageEventHandler NotifyAMS;
		/// <summary>
		/// Raises every time a message is sent to the
		/// MTS queue.
		/// </summary>
		event MessageEventHandler NotifyMTS;
		/// <summary>
		/// Raises every time a message is sent to the
		/// DF queue.
		/// </summary>
		event MessageEventHandler NotifyDF;

	}

}