////////////////////////////////////////////////////////////////////////////
// ---------------------------------------------------------------------- //
// Copyright (C) 2006 - 2008 FRESCOR consortium partners:		  //
// 									  //
//   Universidad de Cantabria,              SPAIN			  //
//   University of York,                    UK				  //
//   Scuola Superiore Sant'Anna,            ITALY			  //
//   Kaiserslautern University,             GERMANY			  //
//   Univ. Politécnica  Valencia,           SPAIN			  //
//   Czech Technical University in Prague,  CZECH REPUBLIC		  //
//   ENEA                                   SWEDEN			  //
//   Thales Communication S.A.              FRANCE			  //
//   Visual Tools S.A.                      SPAIN			  //
//   Rapita Systems Ltd                     UK				  //
//   Evidence                               ITALY			  //
// 									  //
//   See http://www.frescor.org for a link to partners' websites	  //
// 									  //
//          FRESCOR project (FP6/2005/IST/5-034026) is funded		  //
//       in part by the European Union Sixth Framework Programme	  //
//       The European Union is not liable of any use that may be	  //
//       made of this code.						  //
// 									  //
// 									  //
// based on previous work (FSF) done in the FIRST project		  //
// 									  //
//  Copyright (C) 2005  Mälardalen University, SWEDEN			  //
//                      Scuola Superiore S.Anna, ITALY			  //
//                      Universidad de Cantabria, SPAIN			  //
//                      University of York, UK				  //
// 									  //
//  FSF API web pages: http:marte.unican.es/fsf/docs			  //
//                     http:shark.sssup.it/contrib/first/docs/		  //
// 									  //
//  This file is part of FORB (Frescor Object Request Broker)		  //
// 									  //
// FORB is free software; you can redistribute it and/or modify it	  //
// under terms of the GNU General Public License as published by the	  //
// Free Software Foundation; either version 2, or (at your option) any	  //
// later version.  FORB 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	  //
// General Public License for more details. You should have received a	  //
// copy of the GNU General Public License along with FORB; see file	  //
// COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,  //
// Cambridge, MA 02139, USA.						  //
// 									  //
// As a special exception, including FORB header files in a file,	  //
// instantiating FORB generics or templates, or linking other files	  //
// with FORB objects to produce an executable application, does not	  //
// by itself cause the resulting executable application to be covered	  //
// by the GNU General Public License. This exception does not		  //
// however invalidate any other reasons why the executable file might be  //
// covered by the GNU Public License.					  //
////////////////////////////////////////////////////////////////////////////

#ifndef _CM_IDL
#define _CM_IDL

#include "../contract/fres_contract_idl.idl"
#include "../contract/fres_transaction_idl.idl"
#include "../contract/fres_blocks.idl"
#include "../resmng/frm.idl"
#include "../resalloc/fra.idl"

module fres {

	/** Description of a resource */
	struct resource_desc {
		/** Manager */
		resource_manager     manager;
		string		     name; /**< Human understandable name of the resource (used by frm_gui) */
	};

	struct resource {
		frsh_resource_type_t restype;
		frsh_resource_id_t   resid;
		resource_desc	     desc;
	};
	
	typedef sequence<resource> resource_seq;

	interface contract_broker {
		const string reg_name = "fcb";
		/** 
		 * Registers a resource with the contract broker
		 * 
		 * @param restype 
		 * @param resid 
		 * @param res_desc Description of the resource
		 * 
		 * @return Zero on success, non-zero error code on error.
		 */
		long register_resource(in frsh_resource_type_t restype,
				       in frsh_resource_id_t   resid,
				       in resource_desc        res_desc);

		/** 
		 * Registers a resource allocator with the contract broker
		 * 
		 * @param restype 
		 * @param resid 
		 * @param rs_obj 
		 * 
		 * @return Zero on success, non-zero error code on error.
		 */
		long register_allocator(in frsh_resource_type_t restype,
					in frsh_resource_id_t   resid,
					in resource_allocator 	rs_obj);
		
		long deregister_allocator(in resource_allocator rs_obj);

		/** 
		 * This function performs a set of negotiation
		 * operations with one resource. The oprations can
		 * include: adding new contracts (neg), modifying
		 * existing vres (reneg) or cancelling existing vres
		 * (cancel). It is guarantied that either all
		 * operation will be completed or none of them.
		 * 
		 * @param[in] contracts Contract(s) to negotiate,
		 * renegotiate or cancel. The operation on the
		 * contract is determined as follows:
		 * - neg: contracts without ID
		 * - cancel: contracts with an ID and without any block
		 * - reneg: contracts with ID and some blocks (the old
                 *   contract will we replaced by the new one).
		 * 
		 * @param[out] ids IDs of the newly negotiated
		 * contracts, if negotiation was successful. Ordering
		 * of IDs is the same as in @a contracts.
		 * 
		 * @return Zero if all operations were successfully
		 * carried out, non-zero code on error or when
		 * negotiation failed.
		 */
		long negotiate_contracts(in contract::ptr_seq contracts, out contract::id_seq ids);

		/** 
		 * Redistributes spare capacity for a given resource.
		 * This is meant as a support for resources with
		 * variable capacity (WiFi) as a mean for applications
		 * to adapt to the changed capacity.
		 * 
		 * @param restype For which resource to perform
		 * redistribution.
		 */
		void redistribute_spare_capacity(in frsh_resource_type_t restype,
						 in frsh_resource_id_t   resid);

		/** 
		 * Returns sequence of registered resources.
		 * 
		 * @param[out] resources
		 */
		void get_resources(out resource_seq resources);

		long negotiate_transaction(in transaction_t transaction);
		long wait_transaction(in string name,
				      out transaction_t transaction);
		long allocate_transaction_vres(in string name, in long index,
					       out contract::id_t cid);
	};
};

#endif