/*

 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.Collections;

namespace org.myurc.uch.Interfaces.TA
{
	/// <summary>
	/// Interface to be implemented for creating a Target Adapter for a socket of a
	/// specific networking platform.
	/// This interface just specify methods to Target Manager interact with Target
	/// Adapter. That is, just specify the behaviour between TA and Target Manager not
	/// between TA and Target.
	/// 
	/// The main objective of a TA is the mapping between the UCH API and other Target
	/// specific standards. Any one that implements a TA sould implement his own
	/// mapping.
	/// </summary>
	public interface ITA {

		/// <summary>
        /// The UCH should call finalize() before it uninstalls or unloads the TA.  
        /// However, finalize() shall not be called after init() has thrown a TAFatalException
		/// </summary>
		void finalize();

        /// <summary>
        /// When the TA is installed and loaded, the UCH calls init() prior to any other TA function.  
        /// This allows the TA to initialize itself.  
        /// Note that the observation of a specific target needs a separate function call, i.e. registerTarget().
        /// 
        /// Note: The UCH shall be prepared for the TA calling functions of the TA Listener during the execution of init().  For example, the TA may call setValidation to set the validation mode of the UCH.
        /// 
        /// •	TAFatalException: In case the TA cannot initialize itself, it throws a TAFatalException.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  
        /// The exception shall include a text string describing the problem that occurred.  
        /// </summary>
        /// <param name="taListener">Object in the UCH implementing ITAListener interface (see 8.2).  The TDM will call the tdmListener’s functions to communicate with the UCH.</param>
        /// <param name="taProps">Property map for the TA </param>
        /// <param name="uchProps">Property map for the UCH </param>
        void init(ITAListener taListener, Map taProps, Map uchProps);

        /// <summary>
        /// The TA gets a mandate to represent a given target with a given targetId.  
        /// From now on, until unregister() is called for this target, the TA shall expose the target’s sockets to the UCH.
        /// 
        /// •	TAException: If the TA, for any reason, cannot find or connect to the target, it throws a TAException.  In this case the UCH may try to register the target with a different TA.  The exception shall include a text string describing the problem that occurred.
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  The exception shall include a text string describing the problem that occurred.
        /// </summary>
        /// <param name="targetId">Target identifier which is unique within the UCH.  The TA is responsible for remembering the targetId in connection with the specific target</param>
        /// <param name="targetProps">Property-value pairs, created by the TDM that discovered the target.  The set of property-value pairs are implementation-specific </param>
        void registerTarget(string targetId, Map targetProps);

        /// <summary>
        /// Stop exposing a target’s sockets.  
        /// This function is typically called when a target has disappeared from the network.  
        /// If sessions are open on this target, the TA shall close these sessions prior to returning from unregisterTarget.
        /// 
        /// Note: Prior to calling unregisterTarget(), the UCH should close all existing sessions with that target by calling closeSession().  
        /// In any case, the UCH shall close all sessions that are still open on the pertaining target (this includes calling sessionAborted() for any open session).
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  
        /// The exception shall include a text string describing the problem that occurred.
        /// </summary>
        /// <param name="targetId">UCH-internal target identifier</param>
        void unregisterTarget(string targetId);

        /// <summary>
        /// Get the target identifiers that the TA is currently representing
        /// 
        /// •	Return value: Array with UCH-internal target identifiers.
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  
        /// In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  The exception shall include a text string describing the problem that occurred.
        /// </summary>
        string[] getRegisteredTargetIds();

        /// <summary>
        /// Invoke the specified locator function on a target.  
        /// This requires a prior call to registerTarget on this target.  
        /// But it is not necessary to have a session open with this target.
        /// 
        /// •	TAException: If the TA, for any reason, cannot find or trigger the locator, it throws a TAException.  
        /// The exception shall include a text string describing the problem that occurred.
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  
        /// In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  
        /// The exception shall include a text string describing the problem that occurred.
        /// </summary>
        /// <param name="targetId">UCH-internal target identifier</param>
        /// <param name="locatorId">‘id’ attribute of the locator, as specified in Target Description</param>
        void invokeLocator(string targetId, string locatorId);

        /// <summary>
        /// Get the name (URI) of a target. 
        /// Note that there may be multiple copies of targets (different targetIds) with the same target name.
        /// 
        /// •	Return value: Name (URI) of the target.
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). 
        /// The exception shall include a text string describing the problem that occurred.
        /// </summary>
        /// <param name="targetId">UCH-internal target identifier</param>
        string getTargetName(string targetId);
        
        /// <summary>
        /// Get the URI for retrieving the target description
        /// 
        /// •	Return value: URI for the target description.  
        /// The URI may point to a local or a global location, but must be resolvable.  
        /// If relative, its base shall be the base URL of the location where the TA was retrieved from (implementation-specific).  
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  
        /// The exception shall include a text string describing the problem that occurred.
        /// </summary>
        /// <param name="targetName">Name (URI) of the target</param>
        string getTargetDescriptionUri(string targetName);

        /// <summary>
        /// Get a map with locator ids and locator types for a specific target type.
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  
        /// The exception shall include a text string describing the problem that occurred.
        /// </summary>
        /// <param name="targetName">Name (URI) of the target</param>
        /// <returns>Map with:
        /// o	keys: locator ids (strings)
        /// o	values: locator types (strings), one of {“audio”, “visual”, “other”} (see ISO/IEC 24752-4:2008, section 6.7). 
        /// </returns>
        Map getLocators(string targetName);

        /// <summary>
        /// Get the target’s properties
        /// 
        /// •	Return value: Property-value pairs.   See targetDiscovered() for details.  
        /// The map shall at least contain those properties and values set by the TDM.
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). 
        /// The exception shall include a text string describing the problem that occurred.
        /// </summary>
        /// <param name="targetId">UCH-internal target identifier</param>
        Map getTargetProps(string targetId);

        /// <summary>
        /// Get property map of the TA. 
        /// </summary>
        /// <returns>Property map for the TA at runtime.  This shall be the taProps map it got when init() was called (see 8.1.1.1), optionally with additional properties added.  See also 5.6 and [RES-PROP-VOCAB].</returns>
        Map getTAProps();

        /// <summary>
        /// The UCH asks for the available values for a particular index of a dimensional socket element or set. 
        /// •	See 8.1.1.22
        /// </summary>
        /// <param name="sessionId"></param>
        /// <param name="eltIds"></param>
        /// <param name="indexNos"></param>
        /// <returns></returns>
        object[] getIndices(string sessionId, string[] eltIds, int[] indexNos);

        /// <summary>
        /// Get the names (URIs) of a target’s sockets.
        /// 
        /// Note: This function is provided for the convenience of light-weight UCHs.  
        /// In general, a UCH could glean this information from the Target Description.
        /// 
        /// •	Return value: Array with the names (URIs) of the target’s sockets.
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). 
        /// The exception shall include a text string describing the problem that occurred.
        /// </summary>
        /// <param name="targetName">Name (URI) of the target</param>
        string[] getSocketNames(string targetName);

        /// <summary>
        /// Get the socket name (URI) for a specified session.
        /// 
        /// •	Return value: socket name (URI).
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  
        /// The exception shall include a text string describing the problem that occurred.
        /// </summary>
        /// <param name="sessionId">UCH-internal session identifier</param>
        string getSocketName(string sessionId);

        /// <summary>
        /// Get the friendly name for a socket.  
        /// This is a short, human-readable name for the socket, and may be user-configured.  
        /// For example, the friendly name can be used as part of the URI for a user interface.
        /// 
        /// •	Return value: Friendly name of the socket.
        /// </summary>
        /// <param name="targetId">UCH-internal target identifier.  Note that this is needed since the TA may represent multiple targets of the same kind.</param>
        /// <param name="socketName">name (URI) of the socket</param>
        string getSocketFriendlyName(string targetId, string socketName);

        /// <summary>
        /// Get the set of session identifiers for a given socket name (URI).
        /// 
        /// •	Return value: Array with UCH-internal session identifiers.
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).
        /// The exception shall include a text string describing the problem that occurred.
        /// </summary>
        /// <param name="targetId">UCH-internal target identifier.  Note that this is needed since the TA may represent multiple targets of the same kind.</param>
        /// <param name="socketName">name (URI) of the socket</param>
        string[] getSessionIds(string targetId, string socketName);

        /// <summary>
        /// Get the URI for retrieving the socket description.
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). 
        /// The exception shall include a text string describing the problem that occurred.
        /// </summary>
        /// <param name="targetId">UCH-internal target identifier.  Note that this is needed since the TA may represent multiple targets of the same kind.</param>
        /// <param name="socketName">name (URI) of the socket</param>
        string getSocketDescriptionUri(string targetId, string socketName);

		/// <summary>
        /// The client requests to change the target state in one or more operations on specified socket elements or components thereof.  
        /// The requested operations are coded as cross-indexed arrays of paths, operation identifiers and requested new values.  
        /// “Cross-indexed” means that array elements with the same index belong together.
        /// 
        /// TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  The exception shall include a text string describing the problem that occurred.
		/// </summary>
        /// <param name="sessionId">UCH-internal session identifier</param>
		/// <param name="isValidated"></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 values and the operations array,
        /// i.e. they have the same size, and items with the same index are corresponding. </param>
        /// <param name="operations">•	operations: Array of operation codes.  The following codes are allowed:
        /// o	“S”=set value (not with path for command state, and not referencing a notification)
        /// o	“A”=add indices (only with path with given indices)
        /// o	“R”=remove indices (only with path without indices, path with given indices)
        /// o	“I”=invoke (only with path for command state)
        /// o	“K”=acknowledge (only with path without indices, or path with given indices, referencing a notification)
        /// o	Note: Invalid operation codes and operation codes that are not applicable to the pertaining paths should be ignored by the TA. </param>
        /// <param name="reqValues">Array of requested values, as strings.  Corresponding items for operation “A” (add indices) may be NULL.  Corresponding items for operations “R” (remove indices) and “K” (acknowledge) shall be NULL.</param>
        Map setValuesRequest(string sessionId, bool isValidated, string[] paths, string[] operations, string[] reqValues);

	
		/// <summary>
        /// The client asks for the values/states of specified socket elements or components thereof.
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). 
        /// The exception shall include a text string describing the problem that occurred.
		/// </summary>
        /// <param name="sessionId">UCH-internal session identifier</param>
        /// <param name="paths">Array of paths</param>
        Map getValues(string sessionId, string[] paths);

        /// <summary>
        /// Get a dynamic atomic resource from the TA.  
        /// The UCH shall specify the properties of the requested resource as much as possible.  
        /// A specific matching algorithm is implementation-specific.
        /// 
        /// •	Return value: Array of requested dynamic atomic resources, 
        /// listing the resources in the order of the requests (cross-indexed with argument resProps).  
        /// The array may contain NULL items, if no match could be found for a request,
        /// or if the requested resource is not dynamic.  
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  
        /// The exception shall include a text string describing the problem that occurred.
        /// </summary>
        /// <param name="sessionId"></param>
        /// <param name="resProps">Map with Property-value pairs, duplicate properties with different values are allowed (they are representing alternatives for the resource request).</param>
        Map[] getDynRes(string sessionId, Map[] resProps);


        /// <summary>
        /// This function allows the UCH to check whether a given socket element is available or not.  
        /// Note: Socket elements with an attribute optional=”true” may not be available at runtime. 
        /// Other socket elements are always available.
        /// 
        /// •	Return value: true= element available, false=element not available
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). 
        /// The exception shall include a text string describing the problem that occurred.
        /// </summary>
        /// <param name="targetId">target identifier</param>
        /// <param name="socketName">Name (URI) of a socket</param>
        /// <param name="eltId">element identifier, as specified by the ‘id’ attribute of a socket element in the socket description</param>
        bool isElementAvailable(string targetId, string socketName, string eltId);

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

	    /// <summary>
        /// The UCH asks for permission to open a session with a specified client on a specified socket.  
        /// Note that this function asks for permission only, and is not supposed to actually open a session.
        /// 
        /// •	Return value: Map (property-value pairs) with the following properties:
   		///     o	result: “A”=accept, “R”=reject, “F”=forward.
        ///     o	targetId or targetName (either targetId or targetName shall be present if result=”F”).  Same meaning as defined in 8.2.1.1.
        ///     o	socketName (shall be present if result=”F”): Same meaning as defined in 8.2.1.1.
        ///     o	authorizationCode (may be present if result=”F”): Same meaning as defined in 8.2.1.1.
        ///
        ///•	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.
        /// In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  
        /// The exception shall include a text string describing the problem that occurred.
		/// </summary>
        /// <param name="targetId">UCH-internal target identifier</param>
        /// <param name="socketName">Name (URI) of the socket that the client wants to connect to</param>
        /// <param name="clientProp">Property-value pairs describing the client requesting a session opening.  Property names and values shall be strings.  Property names:
        /// o	clientId (shall be included): UCH-internal identifier of the client.
        /// o	authorizationCode (may be included): Any authorization code for opening the session.  
        /// The authorization code may have been provided by a previous session that requested a forward to the specified socket.
        /// o	Other (implementation-specific) property names may occur. </param>
        Map openSessionRequest(string targetId, string socketName, Map clientProp);


		/// <summary>
        /// The UCH signals the TA that the client has closed a session with one of the TA’s targets.  
        /// The TA should do the necessary clean-up internally and with the target.  
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  
        /// The exception shall include a text string describing the problem that occurred.
		/// </summary>
        /// <param name="sessionId">UCH-internal session identifier.
        /// o	Note: From now the TA can forget the sessionId, since it will not be used by the UCH anymore.</param>
        void sessionClosed(string sessionId);

		/// <summary>
        /// If the TA has accepted an open session request (see above), 
        /// and if the UCH succeeded in the necessary steps to open a session with the client,
        /// the UCH will call sessionOpened and provide the sessionId pertaining to the new session.
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize). 
        /// The exception shall include a text string describing the problem that occurred.
		/// 
		/// </summary>
        /// <param name="targetId">UCH-internal target identifier</param>
        /// <param name="sessionId">: UCH-internal session identifier assigned to the new session.  
        /// The TA should remember the session identifier for future references.</param>
        /// <param name="socketName">Name (URI) of the socket that the session is created upon</param>
        /// <param name="clientProps">Property-value pairs describing the client requesting a session opening.</param>
        void sessionOpened(string targetId, string sessionId, string socketName, Map clientProps);

	
        #region Optionall Methods

        /// <summary>
        /// The UCH asks for permission to suspend a session.  Note that this function asks for permission only, and is not supposed to actually suspend the session.
        /// 
        /// •	Return value: true=request granted, false=request rejected.
        /// 
        ///        
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  The exception shall include a text string describing the problem that occurred.
        /// 
        /// •	TANotImplementedException: The TA does not support this function.
        /// </summary>
        /// <param name="sessionId"> UCH internal session identifier </param>
        bool suspendSessionRequest(string sessionId);

        /// <summary>
        /// The UCH signals the TA that the client has suspended a session with one of the TA’s targets.  The TA should do the necessary actions internally and with the target.  
        /// The session is now suspended until a subsequent call to resumeSessionRequest(),
        /// or until the TA terminates the session for timing out or other reasons, in which case the TA shall call sessionAborted().
        /// Note: A suspended session is in “sleep mode”. 
        /// During suspension, the TA will not send any updates to the UCH, and the UCH will not request to change the status of the target.  
        /// The suspension can be terminated by any of the following actions: UCH calls resumeSessionRequest() and sessionResumed(); UCH calls sessionClosed(); 
        /// UCH calls unregisterTarget() on the pertaining target; TA terminates session and calls sessionAborted().
        /// 
        /// •	Return value: Tentative timeout (in seconds) of the TA / 0 if the TA rejects the request.  
        /// The TA intends to hold the session for subsequent resume operation for the timeout period.  
        /// However, this is not a guaranteed value – the TA may terminate the session at any time for any reason
        /// 
        /// •	TAException: If the TA, for any reason, cannot transit the session into suspension mode, it throws a TAException.  In this case the session will stay alive until either sessionClosed() or sessionAborted() is called.  The exception shall include a text string describing the problem that occurred.  
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  The exception shall include a text string describing the problem that occurred.
        /// 
        /// •	TANotImplementedException: The TA does not support this function.
        /// </summary>
        /// <param name="sessionId"> UCH internal session identifier </param>
        /// <param name="suggestedTimeout"> Timeout (in seconds) – indicating a time period for the target to keep the session for subsequent resume operation.   </param>
        long sessionSuspended(string sessionId, long suggestedTimeout);

        /// <summary>
        /// The UCH signals the TA that the session has resumed. 
        /// A call to this function shall only occur after a resume session request has been granted by the TA 
        /// 
        /// •	TAException: If the TA, for any reason, cannot resume the session, it drops the session (without calling sessionAborted() and throws a TAException.  In this case the UCH shall remove the session, and shall not call sessionClosed().  The exception shall include a text string describing the problem that occurred.  
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  The exception shall include a text string describing the problem that occurred.
        /// 
        /// •	TANotImplementedException: The TA does not support this function.
        /// </summary>
        /// <param name="sessionId"> UCH internal session identifier </param>
        void sessionResumed(string sessionId);

        /// <summary>
        /// The UCH asks for permission to resume a session. 
        /// Note that this function asks for permission only, and is not supposed to actually resume the session.
        /// 
        /// •	Return value: true=request granted, false=request rejected.
        /// o	Note: The TA may reject the resumption for various reasons, 
        /// e.g. because it has already terminated the session.
        /// 
        /// •	TAFatalException: The TA has encountered a problem that prevents further operation, and cannot be fixed.  In this case the UCH should call no function of the TA anymore, and may unload the TA (without calling finalize).  The exception shall include a text string describing the problem that occurred.
        /// 
        /// •	TANotImplementedException: The TA does not support this function.
        /// </summary>
        /// <param name="sessionId"> UCH internal session identifier </param>
        bool resumeSessionRequest(string sessionId);


        /// <summary>
        /// The UCH calls this function if it has received a request from a target to a URI that the TA 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().
        /// </summary>
        /// <param name="request"></param>
        /// <param name="response"></param>
        void targetRequest(object request, object response);

        #endregion


	}

}