/*

 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;
using org.myurc.uch.Interfaces.UCHStore;

namespace org.myurc.uch.Interfaces.TDM
{
	/// <summary>
	/// This interface must be implemented by the classes that wants to compliant with it
	/// </summary>
	public interface ITDMListener {

		/// <summary>
        /// A TDM calls this function when a target has disappeared from the network.  
        /// Depending on the target and its networking platform, this can mean that the target was powered off, or just disconnected from the network.
        /// 
        /// Note: In case the same target will be discovered again later, it may get the same or a new targetId assigned by the UCH 
        /// (implementation-specific).  In any case, the TDM does not have to remember the targetId of a disappeared target.
		/// </summary>
		/// <param name="targetId">Unique device id.</param>    
		void targetDiscarded(string targetId);


		/// <summary>
        /// This function is called by a TDM when it has discovered a new target.  
        /// In response, the UCH will install and load an appropriate Target Adapter (TA) for the new target.
        /// If the corresponding TA is already installed, the new target shall be registered with the already installed TA.
		/// </summary>
        /// <param name="targetProps">: Map (property-value pairs) of target properties at runtime.
        /// o	A property may occur multiple times with different values.  A value shall be of type string.
        /// o	The set of properties that the map contains is implementation-specific.  
        /// o	Required properties:
        ///    	    friendlyName (a short human-readable name, typically user-specified at installation time)
        ///
        /// o	Suggested properties: 
        ///        	    targetPlatform (e.g. “UPnP”, “CHAIN”)
        ///         	deviceClass
        ///         	manufacturer
        ///         	modelName
        /// 
        ///o	Note: targetProps should contain adequate information
        ///	for identifying a matching Target Adapter for the target discovered, potentially involving a resource server for match-making; and
        ///	for registering the target with the Target Adapter so that it can uniquely identify and connect to it in a network.</param>
        /// <param name="taProps">Property map for target adapter (TA) that should help the UCH to find an appropriate TA at runtime.  Any property as specified for TAs in [RES-PROP-VOCAB] may be present, but none is required (since these properties are used for querying a TA).  Other (implementation-specific) properties may occur.
        /// o	Special case: If the property http://myurc.org/ns/res#name is present, the UCH shall retrieve and use the TA with the given identifier (no need for querying).
        /// </param>
        /// <returns>The UCH shall return the targetId (string) that it has assigned the newly discovered target.  NULL if the UCH does not instantiate a Target Adapter for this target, and does not want to be notified when the target will be discarded.
        ///  Note: The TDM is responsible for storing the targetId for the discovered target.  It will be needed for signaling the disappearance of the target via the function targetDiscarded().</returns>
        string targetDiscovered(Map targetProps, Map taProps);

        /// <summary>
        /// Get the local UCH store
        /// 
        /// •	Return value: Local UCH Store.
        /// </summary>
        IUCHStore getLocalUCHStore();

        /// <summary>
        /// Get any kind of resource from the UCH.
        /// </summary>
        /// <param name="sessionId"></param>
        /// <param name="resProps"></param>
        /// <returns></returns>
        Map[] getResources(string sessionId, Map[] resProps);

        /// <summary>
        /// Same as function IUIPMListener.getDocument(), see 6.2.1.5
        /// </summary>
        /// <param name="uri"></param>
        /// <param name="postData"></param>
        /// <returns></returns>
        string getDocument(string uri, string postData);

        /// <summary>
        /// Get property map of the UCH. 
        /// </summary>
        /// <returns>Property map for the UCH at runtime, with properties as specified in [RES-PROP-VOCAB].  
        /// Additional (implementation-specific) properties may occur.</returns>
        Map getUCHProps();

        /// <summary>
        /// Get the IP address of the UCH.
        /// A TDM may need this information to set up its own listener for a port that is not serviced by the UCH.
        /// </summary>
        /// <returns>ip address of UCH as string</returns>
        string getIpAddress();

        /// <summary>
        /// The TDM requests the UCH to start servicing a URI which is made up of a given scheme, port, and base path.  
        /// If successful, the UCH will forward all messages that have this URI as its base, to targetRequest().   
        /// If the TDM indicates that the base path is flexible, the UCH can modify the base path in case it is not available any more.
        /// </summary>
        /// <param name="tdm">TDM object (caller) that is requesting service for a URI with the UCH.  The targetRequest() function of this object will be called upon a request to the specified URI.</param>
        /// <param name="scheme">URI scheme, such as “http”, “ftp”, “urn”, “vnc”, etc.</param>
        /// <param name="port">number of port for listening to requests.</param>
        /// <param name="portIsFlexible">true if the UCH may modify the port number, otherwise false.  Must be true if parameter port is 0</param>
        /// <param name="basePath">base path for the URI.</param>
        /// <param name="basePathIsFlexible">true indicates that the UCH may modify the base path in case the specified path is already taken.  false indicates that the UCH may not modify the base path – if the path is already taken the function returns NULL.</param>
        /// <returns>URI for which the UCH has started service for the TA (e.g. “http://192.168.0.10/Target/”).  If the URI is based on a hierarchical folder system, the URI shall end with a folder delimiter (‘/’ in case of http and ftp).  Note that, if the path is flexible, the path may have been modified by the UCH (e.g. modify “Target” to “Target01”, etc.).  Returns NULL if the UCH cannot service the specified URI.</returns>
        string startUriService(ITDM tdm, string scheme, int port, bool portIsFlexible, string basePath, bool basePathIsFlexible);

        /// <summary>
        /// The TDM requests the UCH to stop servicing a URI that was requested to be serviced in a previous call to startUriService().
        /// org.myurc.uch.Exceptions.UCH.UCHException: Invalid request.
        /// </summary>
        /// <param name="uri">URI that the UCH is requested to stop servicing.  URI has been returned by the UCH in a previous call to startUriService().</param>
        void stopUriService(string uri);

        /// <summary>
        /// This function allows the TDM to check whether any of the optional functions are implemented by the TDMListener.
        /// </summary>
        /// <param name="functionName">Any of the name of the optional functions below, without parentheses.  Example: “removeTDM”.</param>
        /// <returns>true=function implemented, false=function not available</returns>
        bool isImplemented(string functionName);

        /// <summary>
        /// The TDM requests the UCH to be finalized and unloaded.  TDMs should call this function if they cannot operate anymore because of external events or other reasons.
        /// The UCH may follow this request.  In any case, the UCH shall call finalize() on the TDM before it unloads the TDM.
        /// </summary>
        /// <param name="tdm">TDM object (caller) that wants to be removed</param>
        void removeTDM(ITDM tdm);

	}

}