/*********************************************************************/
/*                                                                   */
/*                     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.ServiceModel;
using AgentService.Platform.DF;
using AgentService.Platform.AMS;
using AgentService.Platform.Modules;

namespace AgentService.Agent.Runtime
{
	/// <summary>
	/// Interface IYellowPagesServer. Interface to the Directory Facilitator Agent of the 
	/// Platform.
	/// </summary>
	public interface IYellowPagesServer
	{	
		/// <summary>
		/// Looks for agents that offer the requested service.
		/// </summary>
		/// <param name="sd">Description of the requested service</param>
		/// <returns>An array of DFAgentDescription objects</returns>
		DFAgentDescription[] SearchAgent(ServiceDescription sd);

		/// <summary>
		/// Looks for agents that offer the requested service.
		/// </summary>
		/// <param name="sd">Description of the requested service</param>
		/// <param name="flags">Flags that specify which fields are used to compare the services</param>
		/// <returns>An array of DFAgentDescription objects</returns>
		DFAgentDescription[] SearchAgent(ServiceDescription sd, ServiceComparison flags);

		/// <summary>
		/// Looks for agents that offer the requested service and applies the given constraint to the search.
		/// </summary>
		/// <param name="sd">Description of the requested service</param>
		/// <param name="constraint">Constraint applied to the search process</param>
		/// <returns>An array of DFAgentDescription objects</returns>
		DFAgentDescription[] SearchAgent(ServiceDescription sd, SearchConstraints constraint);

		/// <summary>
		/// Looks for agents that offer the requested service and applies the given constraint to the search.
		/// </summary>
		/// <param name="sd">Description of the requested service</param>
		/// <param name="constraint">Constraint applied to the search process</param>
		/// <param name="flags">Flags that specify which fields are used to compare the services</param>
		/// <returns>An array of DFAgentDescription objects</returns>
		DFAgentDescription[] SearchAgent(ServiceDescription sd, ServiceComparison flags, SearchConstraints constraint);


		/// <summary>
		/// Registers an agent with the directory facilitator service.
		/// </summary>
		/// <param name="description">description of the services promoted by the agent</param>
		void Register(DFAgentDescription description);

		/// <summary>
		/// Modifies the agent description previously registered with the directory facilitator service.
		/// </summary>
		/// <param name="description">description of the services promoted by the agent</param>
		void Edit(DFAgentDescription description);

		/// <summary>
		/// Registers an agent with the directory facilitator service.
		/// </summary>
		/// <param name="aid">identifier of the agents whoes description has to be removed</param>
		void Deregister(AID aid);
	}

	/// <summary>
	/// Interface IYellowPagesClient. Interface to the Directory Facilitator Agent of the 
	/// Platform.
	/// </summary>
    [ServiceContract]
    [ServiceKnownType(typeof(AgentTemplateDescriptor))]
    [ServiceKnownType(typeof(KnowledgeDescriptor))]
    [ServiceKnownType(typeof(BehaviourDescriptor))]
	public interface IYellowPagesClient : IRuntimeBindable
	{	
		/// <summary>
		/// Looks for agents that offer the requested service.
		/// </summary>
		/// <param name="sd">Description of the requested service</param>
		/// <returns>An array of DFAgentDescription objects</returns>
        [OperationContract(Name = "SearchAgent_Description")]
        DFAgentDescription[] SearchAgent(ServiceDescription sd);

		/// <summary>
		/// Looks for agents that offer the requested service.
		/// </summary>
		/// <param name="sd">Description of the requested service</param>
		/// <param name="flags">Flags that specify which fields are used to compare the services</param>
		/// <returns>An array of DFAgentDescription objects</returns>
        [OperationContract(Name = "SearchAgent_Description_Comparison")]
        DFAgentDescription[] SearchAgent(ServiceDescription sd, ServiceComparison flags);

		/// <summary>
		/// Looks for agents that offer the requested service and applies the given constraint to the search.
		/// </summary>
		/// <param name="sd">Description of the requested service</param>
		/// <param name="constraint">Constraint applied to the search process</param>
		/// <returns>An array of DFAgentDescription objects</returns>
        [OperationContract(Name = "SearchAgent_Description_Constraint")]
        DFAgentDescription[] SearchAgent(ServiceDescription sd, SearchConstraints constraint);

		/// <summary>
		/// Looks for agents that offer the requested service and applies the given constraint to the search.
		/// </summary>
		/// <param name="sd">Description of the requested service</param>
		/// <param name="constraint">Constraint applied to the search process</param>
		/// <param name="flags">Flags that specify which fields are used to compare the services</param>
		/// <returns>An array of DFAgentDescription objects</returns>
        [OperationContract(Name = "SearchAgent_Description_Comparison_Constraint")]
        DFAgentDescription[] SearchAgent(ServiceDescription sd, ServiceComparison flags, SearchConstraints constraint);

		/// <summary>
		/// Registers an agent with the directory facilitator service.
		/// </summary>
		/// <param name="description">description of the services promoted by the agent</param>
        [OperationContract]
        void Register(DFAgentDescription description);

		/// <summary>
		/// Modifies the agent description previously registered with the directory facilitator service.
		/// </summary>
		/// <param name="description">description of the services promoted by the agent</param>
        [OperationContract]
        void Edit(DFAgentDescription description);

		/// <summary>
		/// Deregisters an agent with the directory facilitator service.
		/// </summary>
        void Deregister();

        /// <summary>
        /// Deregisters an agent with the directory facilitator service.
        /// </summary>
        /// <param name="aid">identifier of the agents whoes description has to be removed</param>
        [OperationContract]
        void Deregister(AID aid);
	}
}