/*********************************************************************/
/*                                                                   */
/*                     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 System.Collections.Generic;
using System.Text;
using AgentService.Platform.Modules;

namespace AgentService.Platform
{
    public interface IEventManager
    {
        #region Standard Platform Events

        /// <summary>
        /// Fires every time an agent is created.
        /// </summary>
        event PlatformEventHandler OnAgentCreated;
        /// <summary>
        /// Fires every time an agent is resumed.
        /// </summary>
        event PlatformEventHandler OnAgentResumed;
        /// <summary>
        /// Fires every time an agent is stopped.
        /// </summary>
        event PlatformEventHandler OnAgentStopped;
        /// <summary>
        /// Fires every time an agent is woken up.
        /// </summary>
        event PlatformEventHandler OnAgentWokenUp;
        /// <summary>
        /// Fires every time a message is sent.
        /// </summary>
        event PlatformEventHandler OnMessageSent;
        /// <summary>
        /// Fires every time a message is sent.
        /// </summary>
        event PlatformEventHandler OnMessageReceived;
        /// <summary>
        /// Fires every time a bulk of messages is received.
        /// </summary>
        event PlatformEventHandler OnMessageBatch;
        /// <summary>
        /// Fires every time a conversation is requested.
        /// </summary>
        event PlatformEventHandler OnConversationRequested;
        /// <summary>
        /// Fires every time a conversation is accepted and then opened.
        /// </summary>
        event PlatformEventHandler OnConversationAccepted;
        /// <summary>
        /// Fires every time a comversation is refused.
        /// </summary>
        event PlatformEventHandler OnConversationRefused;
        /// <summary>
        /// Fires every time a conversation is closed.
        /// </summary>
        event PlatformEventHandler OnConversationClosed;
        /// <summary>
        /// Fires every time an agent is persisted.
        /// </summary>
        event PlatformEventHandler OnAgentPersisted;
        /// <summary>
        /// Fires every time an assembly is uploaded into the platform storage.
        /// </summary>
        event PlatformEventHandler OnAssemblyUploaded;
        /// <summary>
        /// Fires every time an assembly is removed from the platform storage.
        /// </summary>
        event PlatformEventHandler OnAssemblyRemoved;

        #endregion

        #region Standard Event Management
        /// <summary>
        /// Fires a specified PlatformEvent, with the given args,
        /// used by the platform in order to notify the modules that
        /// have been registered for that event
        /// </summary>
        /// <param name="eventType">type of the event</param>
        /// <param name="args">corresponding srguments</param>
        /// <param name="token">owning token</param>
        void RaiseStandardEvent(PlatformEvent eventType, PlatformEventArgs args, int token);

        /// <summary>
        /// Retrieves a valid token for the given core module.
        /// The token is used to allow core modules to raise
        /// the standard events that belongs to them.
        /// </summary>
        /// <param name="module">the instance of the module
        /// which is requesting the token</param>
        /// <returns>owning token</returns>
        int GetToken(IPlatformModule module);
        #endregion

        #region Custom Events Management

        /// <summary>
        /// Adds an event to the custom event registry
        /// </summary>
        /// <param name="evtName">name of the event</param>
        /// <returns>a token that is used by the owner to track the event, 0 if the event is already present</returns>
        int AddEvent(string evtName);


        /// <summary>
        /// Removes the event associated to the given token
        /// </summary>
        /// <param name="token">token that identifies the event</param>
        bool RemoveEvent(int token);

        /// <summary>
        /// Raises the event associated to the given token
        /// </summary>
        /// <param name="token">token that identifies the event</param>
        /// <param name="args">event argument</param>
        /// <returns>true if the event is found</returns>
        bool RaiseEvent(int token, PlatformEventArgs args);

        /// <summary>
        /// Registers an handler to the given event
        /// </summary>
        /// <param name="evtName">name that identifies the event</param>
        /// <param name="handler">delegate the will be registered</param>
        /// <returns>true if the registration process is successful, false if the event is not present</returns>
        bool Register(string evtName, PlatformEventHandler handler);

        /// <summary>
        /// Deregisters an handler to the given event
        /// </summary>
        /// <param name="evtName">name that identifies the event</param>
        /// <param name="handler">delegate to deregister</param>
        /// <returns>true if the deregistration process succeeds, falise if the event is not present</returns>
        bool Deregister(string evtName, PlatformEventHandler handler);
        #endregion


    }
}