/*

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


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

		/// <summary>
		/// The UIPM 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.
        /// Note: The UCH may validate the requests and block those that would violate a socket element’s type or dependencies.  
        /// Blocking means that the UCH removes invalid requests before passing them on to the pertaining TA.
        /// 
        /// •	Return value: Map contains all path-values that were updated in response to the request,
        /// including new values for variables, new states for commands, and new states for notifications.  
        /// Note that the indices of the returned map do not necessarily correspond to the indices of the arguments path, operations and reqValues.
		/// </summary>
        /// <param name="sessionId">UCH internal session identifier</param>
        /// <param name="paths">Array of paths.  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">: Array of operation codes.  The following codes are allowed:
        /// o	“S”=set value of variable or local command parameter (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).  Pertaining local parameters shall be, and global parameters may be specified by preceding array elements (with an “S” operation) of the same call.
        /// 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 UCH. </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, string[] paths, string[] operations, string[] reqValues);

		/// <summary>
        /// Request for opening a session with the specified target and socket.  
        /// 
        /// •	Return value: Map (property-value pairs) with the following properties:
        ///     •	result: “A”=accept, “R”=reject, “F”=forward.
        ///     •	sessionId (shall be present if result=”A”): UCH-internal identifier for the new session.
        ///     •	targetId or targetName (either one shall be present if result=”F”)
        ///     •	socketName (shall be present if result=”F”)
        ///     •	authorizationCode (may be present if result=”F”)
		/// </summary>
        /// <param name="uipm">UIPM object (caller) that is opening a session with the UCH.</param>
        /// <param name="targetId">Globally unique target instance identifier</param>
        /// <param name="socketName">Name (URI) of the socket that the UIPM wants to connect to.</param>
        /// <param name="clientProps"> Property-value pairs describing the client requesting a session opening.  Property names and values shall be strings.  
        /// Property names:
        /// •	clientId (shall be included): UCH-internal identifier of the client.
        /// •	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.
        /// •	Other (implementation-specific) property names may occur.</param>
        Map openSessionRequest(IUIPM uipm, string targetId, string socketName, Map clientProps);

		/// <summary>
        /// The UIPM closes a session with the UCH.
		/// </summary>
        /// <param name="sessionId">UCH-internal session identifier</param>
		void closeSession(string sessionId);


		/// <summary>
        /// Get the identifiers of the available targets.
        /// 
        /// •	Return value: Array with globally unique target instance identifiers.
		/// </summary>
		string[] getAvailableTargetIds();


        /// <summary>
		/// Get any kind of resource from the TA which should relay the request to a resource server if it cannot handle it locally. 
        /// The UIPM shall specify the properties of the requested resource as much as possible.  
        /// A specific matching algorithm is implementation-specific. 
        /// 
        /// •	Return value: Array of requested resources in their pertaining type (e.g. string for textual resource), 
        /// listing the resources in the order of the requests (i.e. for every request item in the ‘resProps’ array, 
        /// there shall be a response item in the returned array).  If no match can be found for a request item, 
        /// the corresponding response item shall be NULL.  
		/// </summary>
        /// <param name="sessionId">UCH-internal session identifier.  May be NULL (in which case dynamic atomic resources are not included in the returned result). </param>
        /// <param name="resProps"> Map with Property-value pairs, duplicate properties with different values are allowed (they are representing alternatives for the resource request).  Property names are absolute URIs of RDF properties.  
        /// •	For atomic resources, an extensible set of RDF properties is defined in ISO/IEC 24752-5, Resource Description.  Note that this assumes a flattened structure of an atomic resource description, for a single context only.   
        /// •	For other resources, RDF properties and their URIs may be defined by other standards or documents, preferably under the URC Consortium.  
        /// Example: The following map instance requests an English text label for the value “true” of the ‘power’ element in the socket description “http://example.com/socket”, and the label being published by “MyCorp”.  
        /// •	Property=”http://myurc.org/ns/res#eltRef”, [”http://example.com/socket#power”]
        /// •	Property=”http://myurc.org/ns/res#role”, Values=[“http://myurc.org/ns/res#label”]
        /// •	Property=”http://myurc.org/ns/res#forLang”, Values=[“en”]
        /// •	Property=”http://myurc.org/ns/res#valRef”, Values=[“true”]
        /// •	Property=”http://purl.org/dc/elements/1.1/type”, Values=[“Text”]
        /// •	Property=”http://purl.org/dc/elements/1.1/publisher”, Values=[“MyCorp”]
        /// Note that the values in this map are arrays of strings.  Thus multiple values can be assigned to one property, if appropriate.</param>
        Map[] getResources(string sessionId, Map[] resProps);

        /// <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>
        /// The UIPM requests the UCH to be finalized and unloaded. 
        /// UIPMs should call this function if they cannot operate anymore because of the currently available set of targets or other reasons.
	    /// The UCH may follow this request.  In any case, the UCH shall call finalize() on the UIPM before it unloads the UIPM.
        /// </summary>
        /// <param name="uipm">UIPM object (caller) that wants to be removed</param>
        void removeUIPM(IUIPM uipm);

        /// <summary>
        /// The UIPM asks for the available values for a particular index of a dimensional socket element or set.  
        /// 
        /// Note: This function looks at the actual value for a specific index of a socket element, 
        /// isolated from other indices that are part of all actual paths for the given element.  
        /// For sparse arrays, the index value may not occur in any possible combination with values of other indices.
        /// </summary>
        /// <param name="sessionId">UCH-internal session identifier.</param>
        /// <param name="eltIds">Array of element ids (‘id’ attribute values of socket elements or sets).</param>
        /// <param name="indexNos">Array of 0-based index numbers (0 specifies the first index). Note that the index number refers to the dimensions of a single socket element or set, not to its path (i.e. indices of dimensional ancestor sets do not count here).
        /// •	Example: A set with id=”set” and dim=”xsd:integer xsd:string” has two indices.  getIndices(sessionId, [“set”], [1]) would request the available values for the second index (which is of type xsd:string).
        /// </param>
        /// <returns>Array with index ranges, each array item corresponding (in their order) to the elements of 
        /// arguments ‘eltIds’ and ‘indexNos’.  Each item shall be either NULL (for an invalid eltIds item or indexNos item) 
        /// or an array containing the requested index values as items,
        /// which should be in ascending order as specified by their pertaining types, if applicable.  </returns>
        object[] getIndices(string sessionId, string[] eltIds, int[] indexNos);

        
		/// <summary>
        /// Get a map with target-specific property-value pairs.
        /// 
        /// •	Return value: 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.  
		/// </summary>
        /// <param name="targetId">Globally unique target instance identifier.</param>
        Map getTargetProps(string targetId);


		/// <summary>
		/// The UIPM asks for the values/states of specified socket elements or components thereof
        /// 
        /// •	Return value: Map containing path-values corresponding (in their order) to the elements of argument paths.  
        /// However, invalid paths shall be omitted in the returned map.
		/// </summary>
		/// <param name="sessionId">UCH-internal session identifier</param>
		/// <param name="paths">Array of paths</param>
        Map getValues(string sessionId, string[] paths);


		/// <summary>
        /// Check whether a specified socket element is available at runtime
        /// 
        /// 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.
		/// </summary>
        /// <param name="targetId">Globally unique target instance 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>
        /// Get the name (URI) of a target. 
        /// Note that the target name is not necessarily unique within the UCH since there may be multiple copies of one target type (with the same target name).
        /// 
        /// •	Return value: Name (URI) of the target.
        /// </summary>
        /// <param name="targetId">Globally unique target instance identifier.</param>
        string getTargetName(string targetId);

        /// <summary>
        /// Get the URI for retrieving the target description
        /// 
        ///    
        /// •	Return value: Absolute URI for the target description.  The URI may point to a local or a global location, but must be resolvable.  
        /// 
        /// NOTE – 	The function getDocument() can be used to retrieve the actual Target Description document.
        /// </summary>
        /// <param name="targetName">Name (URI) of the target</param>
        string getTargetDescriptionUri(string targetName);

        /// <summary>
        /// Get description document through HTTP GET or POST (HTTP proxy function).  
        /// Default values should be used for HTTP header data.
        /// 
        /// •	Return value: Received document as string.
        /// 
        /// 
        /// •	UCHException: An HTTP error occurred.  Should contain the error message as text, e.g. “404 Not found”.
        /// </summary>
        /// <param name="uri">URI of HTTP request (may include query parameters).</param>
        /// <param name="postData">Data for POST method as string.  NULL if GET method requested</param>
        string getDocument(string uri, string postData);

        /// <summary>
        /// Get the socket names (URIs) for a target type. 
        /// Note that this is a convenience function for the UIPM since the socket names are specified in the target description.
        /// 
        /// •	Return value: Array with socket names (URI) of the target type.
        /// </summary>
        /// <param name="targetName">Name (URI) of the target</param>
        string[] getSocketNames(string targetName);

        /// <summary>
        /// Get the URI for retrieving the socket description.
        /// 
        /// •	Return value: Absolute URI for the socket description.  The URI may point to a local or a global location, but must be resolvable.  
        /// 
        /// NOTE – 	NOTE – 	The function getDocument() (see 6.2.1.5) can be used to retrieve the actual Target Socket Description document.
        /// NOTE – 	Strictly, targetName is not needed since a socket description is already identified by its socket name.  However, UCH implementations may be simpler if they don’t need to keep track of a cross-target list of socket names.
        /// </summary>
        /// <param name="targetName">Name (URI) of the target</param>
        /// <param name="socketName">Name (URI) of the socket</param>
        string getSocketDescriptionUri(string targetName, string socketName);

        /// <summary>
        /// Get the socket name (URI) for a specified session.
        /// 
        /// •	Return value: socket name (URI).
        /// </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.  
        /// 
        /// Note: 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">internal target identifier</param>
        /// <param name="socketName"></param>
        string getSocketFriendlyName(string targetId, string socketName);

        /// <summary>
        /// The UIPM 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 controllerRequest().   
        /// If the UIPM indicates that the base path is flexible, the UCH can modify the base path in case it is not available any more.
        /// throws UCHException: Invalid request
        /// </summary>
        /// <param name="uipm">UIPM object (caller) that is requesting service for a URI with the UCH.  The controllerRequest() function of this object will be called upon a controller 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 controller requests. 0 if no preference for port number</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 UIPM (e.g. “http://192.168.0.10/UCH/URC/”).  
        /// 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 “Flash” to “Flash01”, etc.).  
        /// Returns NULL if the UCH cannot service the specified URI.</returns>
        string startUriService(IUIPM uipm, string scheme, int port, bool portIsFlexible, string basePath, bool basePathIsFlexible);

        /// <summary>
        /// The UIPM requests the UCH to stop servicing a URI that was requested to be serviced in a previous call to startUriService().  
        /// throws 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>
        /// Tell the UCH to add a user interface items (advertised by the UIPM) to its UIList which is exposed to controllers on request. 
        /// If the UIPM wants to advertise multiple user interfaces at the same time, it needs to call addCompatibleUI() multiple times.
        /// 
        /// UCHException: Invalid request.
		/// </summary>
        /// <param name="targetId">Globally unique target instance identifier for the target that the UI controls.  If the UI is for multiple target instances, addCompatibleUI() has to be called multiple times, once for each targetId. </param>
        /// <param name="socketNames">Names (URIs) of the sockets that the UI connects to.  Empty array if the UI connects to all available sockets.   </param>
        /// <param name="protocolShortName">Short name for the UI protocol used, to be used as value of the ‘shortName’ attribute of the <protocol> element in the UIList [UPnP RUI]. 
        /// Examples: “URC-HTTP”, “HTTP/HTML”, “CE-HTML-1.0”, “VNC”.</param>
        /// <param name="uris">URIs for controllers to communicate with the UIPM (e.g. opening a control session).  
        /// All URIs shall contain identical scheme, port and base URL (that was previously assigned to the UIPM by the UCH, see 6.2.1.10). 
        /// The UCH will include the URIs in the UIList as element content of the uri tags [UPnP RUI].  </param>
        /// <param name="protocolInfo">Map with property-value pairs to be advertised by the UCH as subelements of the <protocolInfo> element in a UIList (see 10.2).  
        /// Property names shall be strings, each reflecting the tag name of a pertaining XML element (default namespace assumed).  
        /// Values shall be strings.  
        /// The default mandatory properties for maps (specified in 5.6.1) do not apply to protocolInfo.    </param>
        /// <returns>true - UCH has added UI to UIList.   
        /// false - UCH port could not add the UI to the UIList.</returns>
        bool addCompatibleUI(string targetId, string[] socketNames, string protocolShortName, string[] uris, Map protocolInfo);

         /// <summary>
        /// Tells the UCH to remove user interface URIs from the UIList that were previously added by one call to addCompatibleUI().  Note that the UCH may have to remove the 
        /// pertaining protocol or ui element from the UList if no uri element is remaining in it.
        /// 
        /// •	UCHException: Invalid URIs, or owned by a different UIPM.  The exception shall include a text string describing the problem that occurred.
		/// </summary>
        /// <param name="uris">array of URIs to pull from the UIList. 
        /// This must be identical as used for a previous call to addCompatibleUI().</param>
        void removeCompatibleUI(string[] uris); 

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

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

        /// <summary>
        /// Get the IP address of the UCH.  A UIPM 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</returns>
        string getIpAddress();

        #region Optionall Methods

        /// <summary>
        /// Optional implementation.
        /// The UCH validates a given value for a given path with regard to the pertaining XSD type, or runtime constraints by dependencies.  The following runtime constraints are considered: length, minLength, maxLength, pattern, minInclusive, maxInclusive, minExclusive, maxExclusive 
        /// UCHNotImplementedException: Thrown if UCH does not support this function.
        /// </summary>
        /// <param name="sessionId"> UCH internal session identifier </param>
        /// <param name="path"> Path of a pertaining socket variable or local parameter (or component thereof) </param>
        /// <param name="value"> Value to be checked against the variables/parameter’s type and runtime constraints. </param>
        /// <returns>true - valid value, false - invalid value.</returns>
        bool validateValue(string sessionId, string path, string value);

        /// <summary>
        /// Optional implementation.
        /// Get the actual value of a dependency, pertaining to a socket set or element.
        /// 
        /// Note: This function does not work for ‘calculate’ dependencies.  See function updateValues() in 6.1.1.7 for how a UCH may use the ‘calculate’ dependency.
        /// 
        /// UCHNotImplementedException: Thrown if UCH does not support this function.
        /// </summary>
        /// <param name="sessionId"> UCH internal session identifier </param>
        /// <param name="path"> Path of a pertaining socket variable or local parameter (or component thereof) </param>
        /// <param name="dependency">One of the following strings:“relevant” “write” “insert” (only allowed if path specifies a dimensional set or element)</param>
        /// <returns>Current value of the specified dependency.  NULL if ‘insert’ dependency asked for a non-dimensional set of element.</returns>
        bool? getDependencyValue(string sessionId, string path, string dependency);

        /// <summary>
        /// Get the elementRef URI that points to a particular socket element/set.  The elementRef can be used as part of the query for the label of the socket element/set
        /// 
        /// Note: This is a convenience function for light-weight UIPMs.
        ///
        /// </summary>
        /// <param name="sessionId"> UCH internal session identifier </param>
        /// <param name="path"> Path of a pertaining socket variable or local parameter (or component thereof) </param>
        /// <returns>URI pointing to the socket element/set, consisting of a domain URI and the element’s identifier (as fragment identifier), separated by a ‘#’ character.  
        /// Example: “http://example.com/socket#power”</returns>
        string getElementRef(string sessionId, string path);


        /// <summary>
        /// Asks whether the given session can be suspended
        /// 
        /// UCHNotImplementedException: Thrown if UCH does not support this function.
        /// </summary>
        /// <param name="sessionId"> UCH internal session identifier</param>
        /// <returns>true - session can be suspended, false=session cannot be suspended.</returns>
        bool isSessionSuspendable(string sessionId);

        /// <summary>
        /// The target is requested to suspend the given session with a suggested timeout value
        /// 
        /// UCHNotImplementedException: Thrown if UCH does not support this function.
        /// </summary>
        /// <param name="sessionId"> UCH internal session identifier </param>
        /// <param name="suggestedTimeout"> Timeout (in seconds) the UIPM suggests – indicating a time period for the target to keep the session for subsequent resume operation.   </param>
        /// <returns>Tentative timeout (in seconds) from the target / 0 if the target has rejected the request.  
        /// The target intends to hold the session for subsequent resume operation for the timeout period. 
        /// However, this is not a guaranteed value – the target may terminate the session at any time for any reason.</returns>
        long suspendSession(string sessionId, long suggestedTimeout);

        /// <summary>
        /// Asks whether the given session can be resumed.
        /// 
        /// UCHNotImplementedException: Thrown if UCH does not support this function.
        /// </summary>
        /// <param name="sessionId"> UCH internal session identifier </param>
        /// <returns>true - session can be resumed, false - session cannot be resumed</returns>
        bool isSessionResumable(string sessionId);

        /// <summary>
        /// The target is requested to resume the given session.
        /// 
        /// UCHNotImplementedException: Thrown if UCH does not support this function.
        /// </summary>
        /// <param name="sessionId"> UCH internal session identifier </param>
        /// <returns>true - session resumed, false - session could not be resumed.
        /// If false, the session has terminated, and the UIPM shall not call resumeSession() or closeSession() any more on this session.</returns>
        bool resumeSession(string sessionId);

        /// <summary>
        /// Get a map with locator ids and locator types for a specific target type
        /// </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>
        /// Invoke the specified locator function on the specified target.  
        /// Note that it is not necessary to have a session open with the target.
        /// </summary>
        /// <param name="targetId">Globally unique target instance identifier</param>
        /// <param name="locatorId">'id' attribute of the locator, as specified in returned map of getLocators() (see 6.2.1.10).</param>
        void invokeLocator(string targetId, string locatorId);
        
        #endregion
        
    }

}