/*********************************************************************/
/*                                                                   */
/*                     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 AgentService.Platform.MTS;
using AgentService.Interop;
using AgentService.Ontology;
using System.ServiceModel;
using AgentService.Platform.Modules;
using AgentService.Platform.AMS;
using System;
using System.Collections.Generic;

namespace AgentService.Agent.Runtime
{
    [ServiceContract]
    [ServiceKnownType(typeof(MessageBodyItemCollection))]
    [ServiceKnownType(typeof(MessageBodyItem))]
    [ServiceKnownType(typeof(ConversationBody))]
    [ServiceKnownType(typeof(OntologyTypeDescriptor))]
    [ServiceKnownType(typeof(TypeDescriptor))]
    public interface IRemoteMsgClient: IRuntimeBindable
    {

        /// <summary>
        /// Raises when a proposal for a new conversation is received.
        /// </summary>
        event ConversationDelegate OnIncomingConversation;

        /// <summary>
        /// Open a bidirectional conversation with an agents.
        /// </summary>
        /// <param name="to">agent identifier of the agent to talk to</param>
        /// <returns>identifier of the new conversation</returns>
        [OperationContract(Name = "OpenConversation_AID")]
        [ServiceKnownType(typeof(RemoteConversation))]
        IConversation OpenConversation(AID from, AID to);

        /// <summary>
        /// Open a bidirectional conversation, using the ontology service to represent message content and to validate it.
        /// </summary>
        /// <param name="to">agent identifier of the agent to talk to</param>
        /// <param name="onto">the ontology used to represent the message content</param>
        /// <returns>identifier of the new conversation</returns>
        [OperationContract(Name = "OpenConversation_AID_Ontology")]
        [ServiceKnownType(typeof(RemoteOntologicalConversation))]
        IOntologicalConversation OpenConversation(AID from, AID to, AgentService.Ontology.Ontology onto);

        /// <summary>
        /// Checks whether the agent's queue has messages.
        /// </summary>
        /// <returns>true if the queue has messages</returns>
        [OperationContract]
        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>
        [OperationContract]
        [ServiceKnownType(typeof(ConversationBody))]
        bool SendMessage(AgentMessage message);

        /// <summary>
        /// Receives a message and pops it from the queue.
        /// </summary>
        /// <returns>the first message available in the queue</returns>
        [OperationContract(Name = "ReceiveMessage")]
        AgentMessage ReceiveMessage(AID aid);

        /// <summary>
        /// Receives all the messages that satisfy the condition of the given filter.  
        /// </summary>
        /// <param name="filter">Specifies the selection criteria</param>
        /// <param name="blocking">If true the call is blocking</param>
        /// <returns>A collection of filtered messages retrieved from the agent's queue</returns>
        [OperationContract(Name = "ReceiveMessage_Filter_Blocking")]
        AgentMessageCollection ReceiveMessage(AID aid, MessageFilter filter, bool blocking);

        /// <summary>
        /// Looks in the agent's queue for a message.
        /// </summary>
        /// <returns>the first message available in the queue</returns>
        [OperationContract]
        AgentMessage PeekMessage(AID aid);

        /// <summary>
        /// Retrieves all the messages and removes them from the queue.
        /// </summary>
        /// <param name="bRemove">if true messages are removed from the queue</param>
        /// <returns>the collection of messages retrieved from the queue</returns>
        [OperationContract]
        AgentMessageCollection GetAllMessages(AID aid, bool bRemove);

        /// <summary>
        /// Retrieves all the messages and removes them from the queue.
        /// </summary>
        /// <param name="identifier">
        /// identifies the kind of messages to be retreived.
        ///	identifier greater than 0 returns all the messages belonging to the specified conversation
        ///	identifier equal to 0 returns all the service messages in the queue
        ///	identifier less than than 0 returns specific type of service messages				
        ///	</param>
        /// <param name="bRemove">if true messages are removed from the queue</param>
        /// <returns>the collection of messages retrieved from the queue</returns>
        [OperationContract(Name = "GetAllMessages_id_brem")]
        AgentMessageCollection GetAllMessages(AID aid, string identifier, bool bRemove);

        /// <summary>
        /// Waits until a new message arrives in the agent's queue and pops it.
        /// </summary>
        /// <returns>The new message arrived</returns>
        /// NOT ACTUALLY USED
        [OperationContract]
        AgentMessage WaitForMessage(AID aid);

        /// <summary>
        /// Removes the given message from the queue.
        /// </summary>
        /// <param name="message">message to be destroyed</param>
        /// <returns>true if message is successfully removed</returns>
        [OperationContract]
        bool RemoveMessage(AID aid, AgentMessage message);

        /// <summary>
        /// Receives a message belonging to a given conversation and pops it from the queue.
        /// </summary>
        /// <param name="convId">conversation identifier</param>
        /// <param name="bRemove">if true removes the message from the queue</param>
        /// <returns>the first message available in the queue</returns>
        [OperationContract]
        AgentMessage GetMessage(AID aid, string convId, bool bRemove);

        /// <summary>
        /// Close an active conversation
        /// </summary>
        /// <param name="aid">The AID of the owner of the conversation</param>
        /// <param name="convId">The ID of the conversation</param>
        [OperationContract]
        void CloseConversation(AID aid, string convId);

        /// <summary>
        /// Removes a conversation from the active conversation list
        /// </summary>
        /// <param name="aid">The owner of the conversation</param>
        /// <param name="convId">The ID of the conversation</param>
        [OperationContract]
        void RemoveConversation(AID aid, string convId);

        [OperationContract]
        [ServiceKnownType(typeof(RemoteConversationDescriptor))]
        List<RemoteConversationDescriptor> GetConversationsList(AID aid);

        /// <summary>
        /// Accept an incoming conversation
        /// </summary>
        /// <param name="aid">The conversation owner</param>
        /// <param name="convId">The ID of the incoming conversation</param>
        [OperationContract]
        void AcceptConversation(AID aid, string convId);

        /// <summary>
        /// Reject an incoming conversation
        /// </summary>
        /// <param name="aid">The conversation owner</param>
        /// <param name="convId">The ID of the incoming conversation</param>
        [OperationContract]
        void RejectConversation(AID aid, string convId);
    }
}