/*

 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 System.Collections.Generic;
using System.Net;
using System;

namespace org.myurc.uch.Interfaces.UIPM
{
	/// <summary>
	/// Interface to be implemented by all the UI Protocol Modules to allow to the UI
	/// Protocol Manager to communicate with them.
	/// </summary>
	public interface IUIPM {


		/// <summary>
		/// Tell the UIPM to clean up its own memory. 
        /// The UIPM does not need to clean up for the sessions or user interface 
        /// items it has created within the UCH – the UCH will take care about this itself.
        /// The UCH should call finalize() before it uninstalls or unloads the UIPM.  
        /// However, finalize() shall not be called after init() has thrown a UIPMFatalException.
		/// </summary>
		void finalize();


		/// <summary>
        /// When the UIPM is installed and loaded, the UCH calls init() prior to any other UIPM function.  
        /// This allows the UIPM to initialize itself.
        /// 
        /// •	UIPMFatalException: In case the UIPM cannot initialize itself, it throws a UIPMFatalException.  
        /// In this case the UCH should call no function of the UIPM anymore, and may unload the UIPM (without calling finalize).  
        /// The exception shall include a text string describing the problem that occurred.  
		/// </summary>
        /// <param name="uipmListener">Object in the UCH implementing the IUIPMListener interface. 
        /// The UIPM will call the uipmListener’s functions to communicate with the UCH.</param>
        /// <param name="uipmProps">: Property map for the UIPM configuration, with properties as specified in [RES-PROP-VOCAB].  
        /// Additional (implementation-specific) properties may occur. </param>
        /// <param name="uchProps">Property map for the UCH. </param>
        void init(IUIPMListener uipmListener, Map uipmProps, Map uchProps);

	
        /// <summary>
        /// This function allows the UCH to check whether any of
        /// 
        /// •	Return value: true=function implemented, false=function not available.the optional functions are implemented by the UIPM.
        /// </summary>
        /// <param name="functionName">Any of the name of the optional functions, without parentheses</param>
        bool isImplemented(string functionName);


        /// <summary>
        /// The target has terminated a session (which may be in active or suspended mode).  
        /// 
        /// •	UIPMFatalException: The UIPM has encountered a problem that cannot be fixed, and needs to shut down.  From now on, the UCH should call no function of the UIPM anymore, and may unload the UIPM (without calling finalize).  
        /// The exception shall include a text string describing the problem that occurred.
		/// </summary>
        /// <param name="sessionId">UCH internal session Id</param>
        void sessionAborted(string sessionId);

		/// <summary>
        /// The target requests the UIPM to open a session with a different socket.  
        /// There are two types of forward requests: A “destructive forward request” asks the client to close the current session. 
        /// A “spawn forward request” does not affect the current session.
        /// 
        /// •	UIPMFatalException: The UIPM has encountered a problem that cannot be fixed, and needs to shut down.  From now on, the UCH should call no function of the UIPM anymore, and may unload the UIPM (without calling finalize). 
        /// The exception shall include a text string describing the problem that occurred.
		/// </summary>
        /// <param name="sessionId">UCH internal session Id</param>
		/// <param name="forwardInfo"> Map (property-value pairs) with the following properties:
        ///      o	forwardType: “D”=destructive, “S”=spawn.  
        /// 	    Note: After a destructive forward request, the UIPM should close the current session by calling closeSession().  
        ///      o	targetId (shall be present if target instance  identifier available)
        ///      o	targetName (shall be present if target instance identifier not available
        ///      o	socketName (shall be present).
        ///      o	authorizationCode (may be present)</param>
        void sessionForwardRequest(string sessionId, Map forwardInfo);

		/// <summary>
        /// This function is called when a target has been discarded after initialization of the UIPM.
        /// •	UIPMFatalException: The UIPM has encountered a problem that cannot be fixed, and needs to shut down.  From now on, the UCH should call no function of the UIPM anymore, and may unload the UIPM (without calling finalize).  
        /// The exception shall include a text string describing the problem that occurred.
		/// </summary>
        /// <param name="targetId">Globally unique target instance identifier</param>
		void targetDiscarded(string targetId);

		/// <summary>
        /// This function is called when a new target has been discovered after initialization of the UIPM.
		/// 
        /// •	UIPMFatalException: The UIPM has encountered a problem that cannot be fixed, and needs to shut down.  From now on, the UCH should call no function of the UIPM anymore, and may unload the UIPM (without calling finalize). 
        /// The exception shall include a text string describing the problem that occurred.
		/// </summary>
        /// <param name="targetId">Globally unique target instance identifier</param>
		void targetDiscovered(string targetId);
        
        /// <summary>
        /// The target’s status has changed, affecting one or more sessions.  
        /// Note: The arrays paths, operations, values and hasDynRes shall be of the same size.
        /// Note: A UCH that watches dependencies may trigger an update for a variable that has a ‘calculate’ dependency defined if one if the parameters in its ‘calculate’ dependency has changed.  The UCH may either add the update to the arrays as part of an “accumulated update”, or as a separate call to updateValues().
        ///
        /// •	UIPMFatalException: The UIPM has encountered a problem that cannot be fixed, and needs to shut down.  From now on, the UCH should call no function of the UIPM anymore, and may unload the UIPM (without calling finalize). 
        /// The exception shall include a text string describing the problem that occurred.
        /// </summary>
        /// <param name="sessionIds">Array with UCH-internal session identifiers.  
        /// The status change applies to all sessions that are included in the array.</param>
        /// <param name="paths">array of paths to socket elements</param>
        /// <param name="operations">array of operations</param>
        /// <param name="values">array of values</param>
        /// <param name="hasDynRes">array of bools that represent if the element has dynamic resources or not</param>
        void updateValues(string[] sessionIds, string[] paths, string[] operations, string[] values, bool[] hasDynRes);

        /// <summary>
        /// Get a map with UIPM-specific property-value pairs.
        /// 
        /// •	Return value: Map (property-value pairs) of UIPM properties at runtime.  
        /// The UIPM may return the uipmProps map it got when init() was called,
        /// or any other map (with properties beyond the ones specified in uipmProps)
        /// </summary>
        Map getUIPMProps();

        /// <summary>
        /// A UIPM may implement the controllerRequest() function.  If it does not implement it, it shall not call the UCH’s startUriService() function.  
        /// The UCH calls this function if it has received a request from a controller to a URI that the UIPM has claimed for itself 
        /// by a previous call to startUriService().  The UCH is responsible for creating the request and (partially empty) 
        /// response objects prior to calling controllerRequest().
        /// 
        /// •	UIPMFatalException: The UIPM has encountered a problem that cannot be fixed, and needs to shut down.  From now on, the UCH should call no function of the UIPM anymore, and may unload the UIPM (without calling finalize).  
        /// The exception shall include a text string describing the problem that occurred.
        /// </summary>
        /// <param name="request">Request object (specific to programming language and URI scheme used), containing all information regarding the request that the controller sent</param>
        /// <param name="response">Response object (specific to programming language and URI scheme used), containing information regarding the response to the controller</param>
        void controllerRequest(object request, object response);

	}

}