/*

 Copyright: Meticube, Portugal, 2008. 

 This software is licensed under the CC-GNU GPL.  See http://creativecommons.org/licenses/GPL/2.0/ for

 human-readable Commons Deed, lawyer-readable legal code, and machine-readable digital code.

 Note: This file is based on the UCH 1.0 specification of the URC Consortium, http://myurc.org/TR/uch1.0/.

*/

using org.myurc.uch.Utils;

namespace org.myurc.uch.Interfaces.TDM
{
	/// <summary>
	/// Interface to be implemented for creating a Target Discovery Module for a
	/// specific networking platform.
	/// </summary>
	public interface ITDM {

        /// <summary>
        /// When the TDM is installed and loaded, the UCH calls init() prior to any other TDM function. 
        /// This allows the TDM to initialize itself.  
        /// Note that discovery of targets shall only start upon calling startDiscovery().
        /// 
        /// •	TDMFatalException: In case the TDM cannot initialize itself, it throws a TDMFatalException.  In this case the UCH should call no function of the TDM anymore, and may unload the TDM (without calling finalize).  
        /// The exception shall include a text string describing the problem that occurred.  
        /// </summary>
        /// <param name="tdmListener">Object in the UCH implementing the ITDMListener interface (see 7.2).  The TDM will call the tdmListener’s functions to communicate with the UCH</param>
        /// <param name="tdmProps">: Property map for the TDM 
        /// o	http://purl.org/dc/elements/1.1/type (value shall be “http://www.myurc.org/TR/uch/#tdm”)</param>
        /// <param name="uchProps">Property map for the UCH</param>
        void init(ITDMListener tdmListener, Map tdmProps, Map uchProps);

		/// <summary>
        /// The UCH should call finalize() before it uninstalls or unloads the TDM
        /// 
        /// •	Note: The UCH should call stopDiscovery() prior to finalize().  
        /// In any case, the TDM shall stop discovery upon finalize() is called.
		/// </summary>
		void finalize();

		/// <summary>
        /// This function signals the TDM to start discovery of targets, until stopDiscovery() is called.  Shall be ignored if the TDM is already in target discovery mode
        /// 
        /// •	Note: The TDM will now look for new and disappearing targets, until either stopDiscovery() or finalize() is called.
        /// 
        /// •	TDMFatalException: In case the TDM encounters an error condition that prevents discovery and cannot be fixed, it throws a TDMFatalException.  In this case the UCH should call no function of the TDM anymore, and may unload the TDM (without calling finalize).  
        /// The exception includes a text string describing the problem that occurred.  
		/// </summary>
		void startDiscovery();

		/// <summary>
        /// This function signals the TDM to stop discovery of targets, until startDiscovery() is called.  Shall be ignored if the TDM is not in target discovery mode.
        /// 
        /// •	TDMFatalException: The TDM has encountered an error condition that cannot be fixed.  In this case the UCH should call no function of the TDM anymore, and may unload the TDM (without calling finalize).  
        /// The exception includes a text string describing the problem that occurred.  
		/// </summary>
		void stopDiscovery();

        /// <summary>
        /// Note: The targetRequest() function is currently specific to HTTP requests and responses.  Future versions of this document may accommodate additional URI schemes.
        /// A TDM may implement the targetRequest() function.  If it does not implement it, it shall not call the UCH’s startUriService() function.  
        /// The UCH calls targetRequest() if it has received a request from a target to a URI that the TDM has claimed for itself by a previous call to serviceUri().  The UCH is responsible for creating the request and response objects prior to calling targetRequest().
        /// •	The request and response parameters of targetRequest() have exactly the same meaning as the request and response parameters of controllerRequest(), respectively
        /// </summary>
        /// <param name="request"></param>
        /// <param name="response"></param>
        void targetRequest(object request, object response);

        /// <summary>
        /// Get property map of the TDM
        /// </summary>
        /// <returns>: Property map for the TDM at runtime, with properties as specified in [RES-PROP-VOCAB].  
        /// This shall be the tdmProps map it got when init() was called (see 7.1.1.1), optionally with additional properties added.  
        /// See also 5.6</returns>
        Map getTDMProps();

	}

}