/*

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

namespace org.myurc.uch.Interfaces.TA
{
	/// <summary>
	/// Allow Target Manager receive events from the Target Adapters.
	/// </summary>
	public interface ITAListener {

		/// <summary>
        /// The TA has terminated a session (which may be in active or suspended mode).  
        /// From now on, the TA may have no knowledge about that session any more.
		/// </summary>
        /// <param name="sessionId">: UCH-internal session identifier </param>
        void abortSession(string sessionId);

		/// <summary>
        /// The TA requests the client 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.
        /// 
		/// </summary>
        /// <param name="sessionId">UCH-internal session identifier.</param>
		/// <param name="forwardInfo">: Map (property-value pairs) with at least the following properties:
        /// o	forwardType: “D”=destructive, “S”=spawn.  
        /// 
        /// 	Note: After a destructive forward request, the TA may abort the current session by calling sessionAborted().
        /// 	targetId or targetName (either targetId or targetName shall be present if result=”F”):
        /// 
        /// 	-> targetId: UCH-internal target identifier specifying the target instance to which the client is forwarded to (may be the same as for the open session request).  
        ///               If target instance is not available (e.g. because a target of this kind has not been discovered), targetName shall be specified instead.
        ///               •	Note: A TA may know about other targets (that are being managed by other TAs) through the local UCH store (see 5.11).
        ///     -> targetName: Name (URI) of the target that the session is forwarded to.  
        /// targetName is only specified if the TA does not know the target instance or if no target instance of such kind is available.
        /// 
        /// o socketName (shall be present if result=”F”): Socket name (URI) to which the client is forwarded to.
        /// o authorizationCode (may be present if result=”F”): Any authorization code for opening a session with the forward target and socket.</param>
        void sessionForwardRequest(string sessionId, Map forwardInfo);

	

        /// <summary>
        /// The TA signals a change in the target’s status, affecting one or more sessions.  
        /// Note: The arrays paths, operations, values and hasDynRes shall be of the same size.
        /// </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, each item of any of the forms specified in 5.8.  This array is cross-indexed with the arrays values, operations and hasDynRes, 
        /// i.e. they have the same size, and items with the same index are corresponding. </param>
        /// <param name="operations">Array of operation codes.  The following codes are allowed:
        /// o	“S”=set value (this applies to variable values, command states and notification states)
        /// o	“A”=add indices (only for path with given indices)
        /// o	“R”=remove indices (only for path without indices, or path with given indices)</param>
        /// <param name="values">Array of associated values, as strings.  Corresponding items for operations “R” (remove indices) shall be NULL.</param>
        /// <param name="hasDynRes">Array signaling whether the corresponding path is associated with a dynamic resource.  
        /// o	Note: The UCH may call getDynRes() to retrieve dynamic resources from the TA.  In this case it has to extract the element identifier from the path, since resources are common to all element components (index combinations).</param>
        void updateValues(string[] sessionIds, string[] paths, string[] operations, string[] values, bool[] hasDynRes);


        /// <summary>
        /// The TA signals that the set of atomic resources pertaining to a specific socket element has changed.  
        /// Note that this function does not provide the new set of resources, but rather waits until the UCH request a specific dynamic resource via a subsequent call to getDynRes().
        /// NOTE: •NOTE – This is an “out-of-session” function which may be called even if no session is open with the TA
        /// </summary>
        /// <param name="sessionIds">sessions ids to which the resources apply to</param>
        /// <param name="eltIds">Array with element identifiers for which the set of dynamic resources has changed.</param>
        void updateDynRes(string[] sessionIds, string[] eltIds);

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

        /// <summary>
        /// The TA tells the UCH to do validation for the TA or not.  
        /// Validation means that the UCH will filter out requests for setting variable values, inserting or removing indices, 
        /// invoking commands, and acknowledging notifications, based on type and dependency information from the socket description.
        /// 
        ///     Note: A UCH implementation may or may not support validation.  If it doesn’t support validation, it shall always return false.
        ///     Note: By default, the UCH should not do validation.
        /// 
        /// •	Return value: true=UCH set to validate for the calling TA, false=UCH will not validate.
        /// </summary>
        /// <param name="ta">ta in which we want to do this operation</param>
        /// <param name="activate">activate: true=request for validation, false=request for no validation.</param>
        bool setValidation(ITA ta, bool activate);

        /// <summary>
        /// Get the IP address of the UCH.
        /// A TA 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 TA 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 TA 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="ta">TA 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(ITA ta, string scheme, int port, bool portIsFlexible, string basePath, bool basePathIsFlexible);

        /// <summary>
        /// The TA 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>
        /// Same as function IUIPMListener.getResources(), see 6.2.1.13.
        /// 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 properties may occur.  See also 5.6.</returns>
        Map getUCHProps();

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

        /// <summary>
        /// The TA requests the UCH to be finalized and unloaded.  TAs 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 TA before it unloads the TA.
        /// </summary>
        /// <param name="ta">TA object (caller) that wants to be removed</param>
        void removeTA(ITA ta);

	}

}