/*
 *
 * Copyright (C) 2006-2008  Board of Regents of the University of Wisconsin System (Univ. of Wisconsin-Madison, Trace R&D Center).
 *
 * This piece of the software package, developed by the Trace Center - University of Wisconsin is released to the public domain with only the following restrictions:
 *
 * 1) That the following acknowledgement be included in the source code and documentation for the program or package that use this code:
 *
 * "Parts of this program were based on software developed by the Trace Center, University of Wisconsin-Madison under funding from NIDRR / US Dept of Education."
 *
 * 2) That this program not be modified unless it is plainly marked as modified from the original distributed by Trace.
 *
 * NOTE: This license agreement does not cover third-party components bundled with this software, which have their own license agreement with them. A list of included third-party components with references to their license files is provided with this distribution.
 *
 * This software was developed under funding from NIDRR / US Dept of Education under grant # H133E030012.
 *
 * THIS SOFTWARE IS EXPERIMENTAL/DEMONSTRATION IN NATURE. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Note: This file is based on the UCH 1.0 specification of the URC Consortium, http://myurc.org/TR/uch1.0/.
 *
 */

#ifndef _IUIPMListENER_H
#define	_IUIPMListENER_H

#include <list>
#include <string>
#include <map>
#include "IUCHStore.h"
//#include "IUIPM.h"

using std::string;
using std::map;
using std::list;
using namespace std;
using namespace org::myurc::uch;

namespace org {
    namespace myurc{
        namespace uch{
            
            
            class IUIPM;
            
            /**
             * IUIPMListener receives calls from UIPM. UCH implements this interface.
             *
             * @author Parikshit Thakur & Team, Trace R&D Center
             * @version $Revision: 1.1 $
             */
            
            class IUIPMListener{
            private:
            public:
                /**
                 * Get the identifiers of the available targets.
                 *
                 * @return List<String>
                 */
                virtual list<string> *getAvailableTargetIds(){}
                /**
                 * Get the name of a target for the specified targetId.
                 *
                 * @param targetId a String value of targetId
                 * @return a String
                 */
                virtual string getTargetName(string targetId){}
                /**
                 * Get the target Properties for the specified targetId.
                 *
                 * @param targetId a String value of targetId
                 * @return Map<String, Object>
                 */
                virtual map<string, void *> *getTargetProps(string targetId){}
                /**
                 * Returns List of socket Names for the specified Target Name.
                 *
                 * @param targetName a String value of targetName
                 * @return List<String>
                 */
                virtual list<string> *getSocketNames(string targetName){}
                /**
                 * Get the URI for retrieving the Socket Description of the specified targetName and socketName.
                 *
                 * @param targetName a String value of targetName
                 * @param socketName a String value of socketName
                 * @return a String representing Socket Description URI
                 * @throws TAFatalException
                 */
                virtual string getSocketDescriptionUri(string socketName){}
                
                /**
                 * Returns the matching Resource with the Resource Properties specified by 'resProps'.
                 *
                 * @param sessionId a String value of SessionId
                 * @param resProps List<Map<String, String>> of Resource Properties
                 * @return an List<Map<String,Object>> representing Resources
                 */
                virtual list<map<string, void*>*> *getResources(string sessionId, list<map<string, string>*> *resPropsList){}
                /**
                 * Request for opening a session with the specified target and socket.
                 *
                 * @param targetId a String value of targetId
                 * @param socketName a String value of socketName
                 * @param clientProps Map<String,String>
                 * @return Map<String,String>
                 */
                virtual map<string, string> *openSessionRequest(IUIPM *uipm, string targetId, string socketName, map<string, string> *clientProps){}
                /**
                 * Closes a Session for the specified sessionId.
                 *
                 * @param sessionId a String value of sessionId
                 */
                virtual void closeSession(string sessionId){}
                /**
                 * Returns a value/state of the specified socket elements.
                 *
                 * @param sessionId a String value of sessionId
                 * @param paths a List<String> of elementPath
                 * @return a Map<String, String> of values
                 * @throws TAFatalException
                 */
                virtual map<string, string> *getValues(string sessionId, list<string> *paths){}
                /**
                 * The UIPM requests to change the target state in one or more operations on specified socket elements.
                 * The requested operations are coded as cross-indexed arrays of paths, operation identifiers and requested new values.
                 *
                 * @param sessionId a String value of sessionId
                 * @param paths List<String> a List of elementPaths
                 * @param operations List<String> a List of operations (allowed operations are "S", "A", "R", "I" or "K" )
                 * @param reqValues List<String> a List of Requested Values
                 * @return Map<String, List<String>> a  Map of set Values
                 */
                virtual map<string, list<string>*> *setValuesRequest(string sessionId, list<string> *paths, list<string> *operations, list<string> *reqValues){}
                
                /**
                 * Returns the URI for the Socket Description for specified Target Name.
                 *
                 * @param targetName a String value of targetName
                 * @param socketName a String value of socketName
                 * @return a Socket Description URI String
                 */
                virtual string getSocketDescriptionUri(string targetName, string socketName){}
                /**
                 * Get the URI for retrieving the Target Description for the specified targetName.
                 *
                 * @param targetName a String value of targetName
                 * @return a Target Description URI String
                 */
                virtual string getTargetDescriptionUri(string targetName){}
                /**
                 * Get Friendly Name of the Socket for the specified socketName and targetId.
                 *
                 * @param targetId a String value of targetId
                 * @param socketName a String value of socketName
                 * @return a String value of Socket Friendly Name
                 */
                virtual string getSocketFriendlyName(string targetId, string socketName){}
                /**
                 * Get the SocketName for the specified sessionId.
                 *
                 * @param sessionId a String value of sessionId
                 * @return a String of SocketName
                 * @throws TAFatalException
                 */
                virtual string getSocketName(string sessionId){}
                
                /**
                 * Checks whether specified function is implemented or not.
                 *
                 * @param functionName a String value of function Name
                 * @return whether the function is implemented or not
                 */
                virtual bool isImplemented(string functionName){}
                
                
                /**
                 * Tell the UCH to add a user interface item (advertised by the UIPM) to its UIList which is exposed to controllers on request.
                 *
                 * @param targetId a String value of targetId
                 * @param socketNames a List<String> value of socketNames
                 * @param protocolShortName a String value of protocolShortName
                 * @param uris a List<String> value of uris
                 * @param protocolInfo a Map<String, String> of protocol Information
                 *
                 * @return whether CompatibleUI is added or not.
                 * @throws UCHException
                 */
                virtual bool addCompatibleUI(string targetId, list<string> *socketNames, string protocolShortName, list<string> *uris, map<string, string> *protocolInfo){}
                /**
                 * Get specified document through HTTP GET or POST.
                 *
                 * @param uri a String value of URI
                 * @param postData a String value of postData
                 * @return a String value of requested Document
                 * @throws UCHException
                 */
                
                virtual string getDocument(string uri, string postData) {}
                /**
                 * Tells the UCH to remove user interface URIs from the UIList that were previously added by addCompatibleUI().
                 *
                 * @param uris a List<String> of URIs
                 * @throws UCHException
                 */
                virtual void removeCompatibleUIs(list<string>*uris){}
                /**
                 * 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().
                 *
                 * @param uipm an IUIPM object
                 * @param scheme a String value of schema
                 * @param port a port no
                 * @param portIsFlexible a boolean value
                 * @param basePath a String value of basePath
                 * @param basePathIsFlexible a boolean value
                 * @return a String value of URI
                 * @throws UCHException
                 */
                virtual string startUriService(IUIPM *uipm, string scheme, int port, bool portIsFlexible, string basePath, bool basePathIsFlexible){}
                
                /**
                 * The UIPM requests the UCH to stop servicing a URI that was requested to be serviced in a previous call to startUriService().
                 *
                 * @param uri a String value of URI
                 * @throws UCHException
                 */
                virtual void stopUriService(string uri){}
                
                /**
                 * Get the IP address of the UCH.
                 *
                 * @return return a string value
                 */
                virtual string getIpAddress(){}
                /**
                 * Checks whether a given socketElement is available in the specified Socket of specified Target or not.
                 *
                 * @param targetId a String value of targetId
                 * @param socketName a String value of socketName
                 * @param eltId a String value of eltId
                 * @return boolean whether specified socketElement is exists or not
                 * @throws TAFatalException
                 */
                virtual bool isElementAvailable(string targetId, string socketName, string elementId){}
                /**
                 * Get the Local UCH Store.
                 *
                 * @return an Object of IUCHStore
                 */
                virtual IUCHStore *getLocalUCHStore(){}
                
                /**
                 * Get a map of locatores containing locatorId and locatorType for a specified target Name.
                 *
                 * @param targetName a String value of targetName
                 * @return a Map<string, String> of  LocatorID V/S Locator Type
                 */
                virtual map<string, string> *getLocators(string targetName){}
                /**
                 * Invoke the specified locator function of the specified targetId.
                 *
                 * @param targetId a String value of TargetId
                 * @param locatorId a String value of LocatorId
                 */
                virtual void invokeLocator(string targetId, string locatorId){}
                
                /**
                 * Get Indices available on specific level of dimension of dimensional Element.
                 *
                 * @param sessionId a String value of sessionId
                 * @param eltIds a List<String> of elementIds
                 * @param indexNos a List<Integer> of indexNo
                 * @return a List<Set<Integer> of indices
                 */
                virtual list<list<string>*>*getIndices(string sessionId, list<string>*eltIds, list<string>*indexNos){}
                
                /**
                 * Get a Map of UCH Properties.
                 *
                 * @return an object of Map<String, String> or UCH Properties
                 */
                virtual map<string, string>* getUCHProps(){}
                ///////////////optional methods/////////////////////////////
                
                /**
                 * Checks whether value is valid or not.
                 * If IUIPMListener does not support this functionality then UCHNotImplementedException is thrown by this function.
                 *
                 * @param sessionId a String value of sessionId
                 * @param path a String value of path
                 * @param value a String value
                 * @return whether the value is valid or not.
                 * @throws UCHNotImplementedException
                 */
                virtual bool validateValue(string sessionId, string path, string value){}
                
                /**
                 * Get the actual value of a dependency.
                 * If IUIPMListener does not support this functionality then UCHNotImplementedException is thrown by this function.
                 *
                 * @param sessionId a String value of sessionId
                 * @param path a String value of path
                 * @param dependency a String value of dependency
                 * @return whether the dependency is true or false.
                 * @throws UCHNotImplementedException
                 */
                virtual bool getDependencyValue(string sessionId, string path, string dependency) {}
                /**
                 * Get the elementRef URI that points to a particular socket element/set.
                 * If IUIPMListener does not support this functionality then UCHNotImplementedException is thrown by this function.
                 *
                 * @param sessionId a String value of sessionId
                 * @param path a String value of path
                 * @return a String value of elementRef
                 * @throws UCHNotImplementedException
                 */
                virtual string getElementRef(string sessionId, string path) {}
                
                /**
                 * Check whether the given session can be suspended.
                 * If IUIPMListener does not support this functionality then UCHNotImplementedException is thrown by this function.
                 *
                 * @param sessionId a String value of sessionId
                 * @return whether the given session can be suspended or not
                 * @throws UCHNotImplementedException
                 */
                virtual bool isSessionSuspendable(string sessionId) {}
                
                /**
                 * The target is requested to suspend the given session with a suggested timeout value.
                 * If IUIPMListener does not support this functionality then UCHNotImplementedException is thrown by this function.
                 *
                 * @param sessionId a String value of sessionId
                 * @param suggestedTimeout a long value
                 * @return a long value of timeOut
                 * @throws UCHNotImplementedException
                 */
                virtual long suspendSession(string sessionId, long suggestedTimeout) {}
                
                /**
                 * Checks whether the given session can be resumed.
                 * If IUIPMListener does not support this functionality then UCHNotImplementedException is thrown by this function.
                 *
                 * @param sessionId a String value of sessionId
                 * @return whether the given session can be resumed or not
                 * @throws UCHNotImplementedException
                 */
                virtual bool isSessionResumable(string sessionId) {}
                
                /**
                 * The target is requested to resume the given session.
                 * If IUIPMListener does not support this functionality then UCHNotImplementedException is thrown by this function.
                 *
                 * @param sessionId a String value of sessionId
                 * @return whether request for resume session is granted or not.
                 * @throws UCHNotImplementedException
                 */
                virtual bool resumeSession(string sessionId) {}
                
                /**
                 * Removes the specified uipm from the UCH.
                 *
                 * @param uipm an Object of IUIPM
                 */
                virtual void removeUIPM(IUIPM* uipm){}
            };
        }
    }
}


#endif	/* _IUIPMListENER_H */