/*
* Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies). 
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:        Class implements the most common value object used in WSF, 
*                which is used to  describe some invocable service. 
*
*/








#ifndef SEN_XML_SERVICE_DESCRIPTION_H
#define SEN_XML_SERVICE_DESCRIPTION_H

//  INCLUDES
#include <e32base.h>
#include <e32des8.h>
#include <e32std.h>
#include <MSenServiceDescription.h>
#include <MSenProviderPolicy.h>
#include <SenDomFragment.h>

// CONSTANTS
const TInt KStateParsingCredentials         = 12;
const TInt KStateParsingSingleCredential    = 122;
const TInt KStateParsingProviderPolicy      = 1222;
const TInt KStateParsingServicePolicy       = 12222;

_LIT8( KSenAttrSoap12,                  "SOAP12"               );
_LIT8( KSenAttrAddressing,              "Addressing"           );
_LIT8( KSenAttrClientEntropy,           "ClientEntropy"        );
_LIT8( KSenAttrTokenType,               "TokenType"            );
_LIT8( KSenAttrPassportExtensions,      "PassportExtensions"   );
_LIT8( KSenAttrMetadataEndpoint,        "MetadataEndpoint"     );
_LIT8( KSenAttrUsernameTokenOverTLS,    "UsernameTokenOverTLS" );
_LIT8( KSenAttrPromptUserInfo,          "promptUserInfo"       );

// FORWARD DECLARATIONS
class CSenCredential;
class CSenProviderPolicy;
class CSenServicePolicy;
class MSenServicePolicy;

// DATA TYPES
typedef RPointerArray<CSenCredential> RCredentialList;

// CLASS DECLARATION

/**
* CSenXmlServiceDescription class implements the most
* common value object used in WSF, which is used to 
* describe some invocable service. 
*
* Class offers basic properties which describe some
* service and methods to manipulate this info. These
* properties are stored in XML fragment format and 
* a class instance can be represented as one XML tree.
*
* The main properties for service description are:
*    - contract (typically some URI)
*    - endpoint (typically some URL)
*    - frameworkID
*
*  @lib SenServDesc.lib
*  @since Series60 3.0
*/
class CSenXmlServiceDescription : public CSenDomFragment,
                                  public MSenServiceDescription,
                                  public MSenProviderPolicy
    {
    public:  // Constructors and destructor
        
        /**
        * Standard 2 phase constructor
        * @return a pointer to a new CSenXmlServiceDescription instance.
        */
        IMPORT_C static CSenXmlServiceDescription* NewL();

        /**
        * Standard 2 phase constructor
        * @return a pointer to a new CSenXmlServiceDescription instance,
        *        which is left on cleanup stack.
        */
        IMPORT_C static CSenXmlServiceDescription* NewLC();

        /**
        * Standard 2 phase constructor
        * @param aNamespaceURI namespace URI for the service description.
        * @return a pointer to a new CSenXmlServiceDescription instance
        */
        IMPORT_C static CSenXmlServiceDescription* NewL(const TDesC8& aNamespaceURI);

        /**
        * Standard 2 phase constructor
        * @param aNamespaceURI namespace URI for the service description.
        * @return a pointer to a new CSenXmlServiceDescription instance,
        *        which is left on cleanup stack.
        */
        IMPORT_C static CSenXmlServiceDescription* NewLC(const TDesC8& aNamespaceURI);

        /**
        * Standard 2 phase constructors
        * @param aEndpoint the service endpoint. Note that endpoint cannot 
        *        include characters which are illegal in XML. If endpoint
        *        is an URL which contains illegal characters (like '&'-char),
        *        those need to be encoded into XML entity form (like &amp;).
        *        EncodeHttpCharactersLC() method from XmlUtils can be used
        *        for encoding of basic XML entities.
        * @param aContract identifies the service type. 
        * @return a pointer to a new CSenXmlServiceDescription instance
        */
        IMPORT_C static CSenXmlServiceDescription* NewL(const TDesC8& aEndPoint,
                                                        const TDesC8& aContract);

        /**
        * Standard 2 phase constructors
        * @param aEndpoint the service endpoint. Note that endpoint cannot 
        *        include characters which are illegal in XML. If endpoint
        *        is an URL which contains illegal characters (like '&'-char),
        *        those need to be encoded into XML entity form (like &amp;).
        *        EncodeHttpCharactersLC() method from XmlUtils can be used
        *        for encoding of basic XML entities.
        * @param aContract identifies the service type. 
        * @return a pointer to a new CSenXmlServiceDescription instance,
        *        which is left on cleanup stack.
        */
        IMPORT_C static CSenXmlServiceDescription* NewLC(const TDesC8& aEndPoint,
                                                         const TDesC8& aContract);
        
        /**
        * Destructor.
        */
        IMPORT_C virtual ~CSenXmlServiceDescription();

        // New functions

        /**
        * Setter for the framework ID.
        * The developer may use a FrameworkID to search for a session of    
        * (i.e. connection to) a certain service invocation framework.
        * @since Series60 3.0
        * @param aFrameworkId
        * If set to KNullDesC8, then any matching framework may be used.
        * The default frameworkID in WSF is "ID-WSF" 
        * (KDefaultIdWsfFrameworkID).
        * Note that Basic Web Services MUST use "WS-I" 
        * (KDefaultBasicWebServicesFrameworkID).
        */
        IMPORT_C void SetFrameworkIdL(const TDesC8& aFrameworkID);

        /**
        * Method returns the localname for this service description.
        * This is the localname of the element, when this class is
        * represented as an XML element.
        * @since Series60 3.0
        * @return descriptor to XML localname of this service description
        */
        IMPORT_C virtual const TDesC8& NewElementName();
        
        /**
        * Returns list of credentials. Ownership is not transferred, any
        * modifications to the contents of the list modify the real objects.
        * @since Series60 3.0
        * @return the list of credentials (CSenCredential objects).
        */
        IMPORT_C  RCredentialList& Credentials();        

        // Functions from base classes
    
        // From MSenProviderPolicy
        IMPORT_C virtual void SetIapIdL(TUint32 aIapId);
        IMPORT_C virtual TInt IapId(TUint32& aCurrentIapId);
        IMPORT_C virtual void SetIdentityProviderIdsL(
                                        CSenIdentityProviderIdArray8& aList);
		IMPORT_C TInt SetTransportPropertiesL(const TDesC8& aProperties);

        IMPORT_C virtual TInt AddIdentityProviderIdL(TDesC8& aProviderId);
        IMPORT_C virtual TInt RebuildFrom(MSenProviderPolicy& aTemplate);
        IMPORT_C virtual const CSenIdentityProviderIdArray8&
                                                    IdentityProviderIds8L();
	    IMPORT_C TInt TransportPropertiesL(HBufC8*& aProperties);
        
        IMPORT_C virtual TBool Accepts(MSenProviderPolicy& aPolicyPattern);
        
        // From MSenServiceDescription:
        IMPORT_C TDescriptionClassType DescriptionClassType();
        IMPORT_C TBool Matches(MSenServiceDescription& aPattern);
        IMPORT_C TPtrC8 Contract();

        // New method
         /**
        * Method for checking if service description has a certain facet.
        * @since Series60 3.0
        * @param aURI       the facet to check, typically some URI.
        * @param aHasFacet  is ETrue if facet is found and EFalse, if not.
        * @return       KErrNone or other system-wide Symbian error codes.
        */
        IMPORT_C virtual TInt HasFacetL(const TDesC8& aURI, TBool& aHasFacet);
        
        // From MSenServiceDescription
        IMPORT_C virtual TInt FacetValue(TDesC8& aURI, HBufC8*& aValueTo);
        IMPORT_C virtual TInt AddFacetL(const CSenFacet& aFacet);
        IMPORT_C virtual TInt SetFacetL(const CSenFacet& aFacet);
        IMPORT_C virtual TInt RemoveFacet(const TDesC8& aURI);
        IMPORT_C virtual TInt FacetsL(RFacetArray& aFacetArray);
        
        // New method
        /**
        * On success, this method returns a positive integer if this 
        * service description matches with the given pattern in at 
        * least one aspect. Higher numbers mean a closer match.
        *
        * The bits of information that are in the pattern are read and compared
        * to corresponding fields in this ServiceDescription. Note that a pattern
        * may have far fewer fields and that only the non-null fields are compared.
        * For example, assume that a pattern with only a contract was defined;
        * with the contract set to "urn:example.com:service". 
        * Each ServiceDescription with the same contract will match the pattern,
        * even if such a ServiceDescription has non-null fields for other aspects.
        * @since Series60 3.0
        * @param    aPattern a ServiceDescription, typically with partial
        *           information.
        * @return the score or error. If nothing matches, returns 0. In case of 
        *  any error, a negative value is returned. 
        */
        IMPORT_C virtual TInt ScoreMatchL(MSenServiceDescription& aPattern);

        // From MSenServiceDescription

        IMPORT_C TPtrC8 Endpoint();
        IMPORT_C TPtrC8 FrameworkId();
        IMPORT_C TPtrC8 FrameworkVersion();
        IMPORT_C void SetContractL(const TDesC8& aContract);
        IMPORT_C void SetEndPointL(const TDesC8& aEndPoint);
        
        // From CSenBaseFragment 
        
        /** 
        * Gets the service description as XML fragment in UTF-8 format.
        * @since Series60 3.0
        * @return the service description as XML, which ownership is
        *         transferred to the caller.
        */
        IMPORT_C virtual HBufC8* AsXmlL();

        /**
        * Gets the service description as XML, in Unicode (UCS-2)
        * @since Series60 3.0
        * @return the service description as XML, in Unicode (UCS-2)
        *         encoding form.
        */
        IMPORT_C virtual HBufC* AsXmlUnicodeL();

        /**
        * Writes this service description as XML, in UTF-8 form to a stream
        * @since Series60 3.0
        * @param aWriteStream   to write into.
        */
        IMPORT_C virtual void WriteAsXMLToL(RWriteStream& aWriteStream);


        // From CSenDomFragment 
        
        /**
        * Method looks for FrameworkID attribute from the given XML attribute
        * array and if one is found, sets its value for this instance. In
        * addition, all the namespace attributes are copied. All other
        * attributes are discarded.
        * @since Series60 3.0
        * @param aAttributes    the attribute list.
        */
        IMPORT_C void SetAttributesL(const RAttributeArray& aAttributes);

        /**
        * Resumes the parsing. Called by the delegate fragment 
        * in order to notify owner, which needs to regain 
        * (take over) parsing. For example, when a policy fragment
        * is parsed, the service description fragment should
        * resume parsing the rest of its own XML document 
        * representation.
        * @since Series60 3.0
        * @param aNsUri     The namespace URI of the current element
        * @param aLocalName The local name of the current element
        * @param aQName     The qualified name of the current element
        */
        IMPORT_C void ResumeParsingFromL(const TDesC8& aNsUri,
                                         const TDesC8& aLocalName,
                                         const TDesC8& aQName);
                
    protected:  // New functions
        
        /**
        * C++ default constructor.
        * @param aType enumeration defining the type of this class.
        */
        IMPORT_C CSenXmlServiceDescription(TDescriptionClassType aType);
        
        /**
         * Basic ConstructL function.
         */
        IMPORT_C void ConstructL();

        /**
        * Basic ConstructL function.
        * @since Series60 3.0
        * @param aNamespaceURI for this service description, which is
        *        also an XML element.
        */
        IMPORT_C void ConstructL(const TDesC8& aNamespaceURI);

        /**
        * Basic ConstructL function.
        * @since Series60 3.0
        * @param aEndpoint the service endpoint. Note that endpoint cannot 
        *        include characters which are illegal in XML. If endpoint
        *        is an URL which contains illegal characters (like '&'-char),
        *        those need to be encoded into XML entity form (like &amp;).
        *        EncodeHttpCharactersLC() method from XmlUtils can be used
        *        for encoding of basic XML entities.
        * @param aContract identifies the service type, typically some URN.
        */
        IMPORT_C void ConstructL(const TDesC8& aEndPoint, const TDesC8& aContract);

        // Functions from base classes
        
        // From CSenDomFragment 
        
        /**
        * Callback function which implements the XML content handler interface.
        * @since Series60 3.0
        * @param aNsURI     The namespace URI of the new element
        * @param aLocalName The local name of the new element
        * @param aQName     The qualified name of the new element
        * @param aAttributes    The attributes of the new element
        */
        IMPORT_C virtual void StartElementL(const TDesC8& aNsUri,
                                            const TDesC8& aLocalName,
                                            const TDesC8& aQName,
                                            const RAttributeArray& aAttributes);

        // From CSenBaseFragment 
        /**
        * Callback function which implement the XML content handler interface.
        * @since Series60 3.0
        * @param aNsUri     The namespace URI of the new element
        * @param aLocalName The local name of the new element
        * @param aQName     The qualified name of the new element
        */
        IMPORT_C virtual void EndElementL(const TDesC8& aNsUri,
                                          const TDesC8& aLocalName,
                                      const TDesC8& aQName);
                                          
    public:
        /**
        * Method returns ETrue if the primary keys of this service description
        * are equal. Definition of primary keys varies on concrete implementations.
        *
        * In a typical XML sub class implementation the primary keys are Contract 
        * and Endpoint elements. 
        *
        * Difference to Match() method is that primary keys - often descriptors - 
        * MUST be equal both in this service description and in aCandidate, unlike
        * in Match(), where argument is more like wildcard pattern matching even
        * in cases where it includes fewer fields (less information).
        *
        * @since Series60
        * @param    aCandidate is a service description, which primary keys are
        *           checked in this comparison.
        *
        * @return TBool ETrue if primary keys are equal, EFalse otherwise. 
        */
        IMPORT_C TBool HasEqualPrimaryKeysL(MSenServiceDescription& aCandidate);

        /*
        * Method checks specific pieces of information to determine, whether this
        * service description is local or not. Typically this is defined by the
        * endpoint's scheme, which is KSenTransportSchemeLocal in most of the cases,
        * when this method returns true.
        * @return boolean indicating whether this endpoint is local or not.
        */
        IMPORT_C TBool IsLocalL(); 


        /*
        * Method for binding transport plug-in type with the endpoint in question.
        * Function adds/sets XML attribute called "cue" for <Endpoint> element:
        *  
        *  <ServiceDescription>
        *    <Endpoint cue="com.nokia.wsf.transport.plugin.hostlet">
        *        local://urn:nokia.com.test.hostlet
        *    </Endpoint>
        *  </ServiceDescription>
        *
        * In above example, eventhough endpoint scheme "local://" would normally
        * invoke different type of plug-in (ECOM hostlet), the "cue" attribute 
        * overrides this, and forces hostlet connection transport plug-in to be
        * loaded.
        *
        * Transport plug-in types (cues):
        *
        *    _LIT8(KSenTransportCueHTTP,              "com.nokia.wsf.transport.plugin.httpchannel");
        *    _LIT8(KSenTransportCueVirtualTCP,        "com.nokia.wsf.transport.plugin.virtualtcp");
        *    _LIT8(KSenTransportCueLocalEcom,         "com.nokia.wsf.transport.plugin.local");  
        *    _LIT8(KSenTransportCueHostletConnection, "com.nokia.wsf.transport.plugin.hostlet");
        *
        *
        * Note that this method does not attempt to load the plug-in - it might not
        * even exist in the system. Neither is this attribute checked when XML service
        * description is parsed. As a conclusion, if non-existant plug-ins are bind 
        * to endpoints, they will be ignored, and the transport is created in normal
        * way and plug-in is chosen based on endpoint scheme and/or defaults.
        * 
        * @param aTransportCue is the ECOM cue of CSenTransport implementation.
        * In ECOM resource files, cue is the value of "default_data" property.
        * @return KErrNone on success
        *         KErrSenNoEndpoint, if  endpoint element does not exist in this XML
        *         service description.
        */
        IMPORT_C TInt SetTransportCueL(const TDesC8& aTransportCue);


        /**
        * Getter for transport cue, assuming that attribute has been set,
        * and that has "cue" -attribute.
        * @return transport plug-in ECOM cue, or KNullDesC8, if it has
        * not been set in this service description. In each ECOM resource
        * file the cue is defined by "default_data" property.
        */
        IMPORT_C TPtrC8 TransportCue();

        /**
        * Getter for (web) service policy
        * @return pointer to service policy, or NULL, if it is not available
        */
        IMPORT_C MSenServicePolicy* ServicePolicy();

        /**
        * Method provides convenient way to add a new value in Client Policy
        * This method will add elements such as <SOAP12> or <UsernameTokenOverTLS>
        * in the Policy to be used by stack. Infact this method adds a new element 
        * in xml representation of ServicePolicy.
        * @param aName is the Name of the attribute.
        * @return KErrNone on success, KErrArgument if any of the arguments 
        * (descriptors) is of zero-length, or one of the system-wide 
        * error codes otherwise.
        */
        IMPORT_C TInt SetPolicyL(const TDesC8& aName);

        /**
        * Method provides convenient way to add a new value in Client Policy
        * This method will add elements such as <Addressing>
        * in the Policy to be used by stack. Infact this method adds a new element 
        * in xml representation of ServicePolicy and adds its value as contents of the element.
        * <Addressing>http://schemas.xmlsoap.org/ws/2004/03/addressing</Addressing>
        * @param aName is the Name of the Policy attribute.
        * @param aValue is the Contents of the Policy attribute.
        * @return KErrNone on success, KErrArgument if any of the arguments 
        * (descriptors) is of zero-length, or one of the system-wide 
        * error codes otherwise.
        */
        IMPORT_C TInt SetPolicyL(const TDesC8& aName, const TDesC8& aValue);

        /**
        * Method provides convenient way to add a new value in Client Policy
        * This method will add elements such as <Addressing>
        * in the Policy to be used by stack, plus it will add one specified
        * attribute (name and value) for that element. Infact this method adds
        * a new element - and it's attribute - in the xml representation of 
        * ServicePolicy element, which is direct child to ServiceDescription
        * (root element) document.
        * <MetadataEndpoint method = "GET">http://www.mypolicyendpoint.com/policy2/</MetadataEndpoint>
        * @param aName is the Name of the Policy attribute.
        * @param aValue is the Contents of the Policy attribute.
        * @param aAttribName is the Name of the attribute in element aName
        * @param aAttribValue is the Contents of the aAttribName attribute.
        * @return KErrNone on success, KErrArgument if any of the arguments 
        * (descriptors) is of zero-length, or one of the system-wide 
        * error codes otherwise.
        */
        IMPORT_C TInt SetPolicyL(const TDesC8& aName, const TDesC8& aValue, const TDesC8& aAttribName, const TDesC8& aAttribValue);

        /**
        * Setter for (identity) provider ID
        * @since Series60 5.0
        * @param aProviderID the unique identifier of the (identity) provider
        * @return KErrNone on success, KErrArgument if aProviderID is of zero-length,
        * or one of the system-wide Symbian error codes otherwise.
        */
        IMPORT_C TInt SetProviderIdL( const TDesC8& aProviderID );
        
        /**
        * Getter for (identity) provider ID
        * @since Series60 5.0
        * @return the (locally) unique identifier of the (identity) provider
        * @return KErrNone on success, KErrArgument if aProviderID is of zero-length,
        * or one of the system-wide Symbian error codes otherwise.
        */
        IMPORT_C TPtrC8 ProviderId();

        /**
        * Setter for userinfo (KSenAttrPromptUserInfo) attribute, which 
        * - password notifier dialog is shown to end-user or not, when 
        * authentication fails (due wrong, or incomplete userinfo).
        * @param aPromptUserInfoMode 
        *  EFalse dictates that an error must be returned when creating
        *         a service connection and userinfo is not accepted by 
        *         (remote) authentication, instead of showing the dialog.
        *  ETrue (or if attribute does not exist in this XML SD) means that
        *         end-user should be prompted (default behaviour). The number
        *         of retry attempts (each showing a dialog) is service invocation
        *         framework spesific; typically 3 retries are permitted.     
        */
        IMPORT_C void CSenXmlServiceDescription::SetPromptUserInfoL( TBool aPromptUserInfoMode );

        /**
        * Getter for current userinfo mode (KSenAttrPromptUserInfo attribute).
        * @return Boolean that indicates the mode:
        *  EFalse means that end-user prompts (notifier dialogs) have been 
        *  explicitely surpressed, and thus will not be shown to end-user:
        *  attribute value is exactly as follows: "false"
        *  ETrue means that attribute named as KSenAttrPromptUserInfo 
        *  does not exist (default), or it has ANY value OTHER than "false"
        */
        IMPORT_C TBool PromptUserInfo();

	public:
		/**
        * Sets the SNAP ID.
        * @param aIapId  A TUint32 Snap ID
        */
        IMPORT_C void SetSnapIdL(TUint32 aIapId); 
		/**
        * Gets the SNAP ID.
        * @param aCurrentSnapId  A TUint32 reference to be filled in with the
        *                       value of the SNAP ID.
        * @return               KErrNone if no error, or some of the system
        *                       wide error codes.
        */
        IMPORT_C TInt SnapId(TUint32& aCurrentIapId); 
		
    private:
        TInt FacetValueL(TDesC8& aURI, HBufC8*& aValueTo);
        TInt RemoveFacetL(const TDesC8& aURI);

    protected: // Data
        // the type of this class instance
        const TDescriptionClassType iType;

    private: // Data
        CSenServicePolicy* iServicePolicy;
        CSenCredential* iCredential;
        RCredentialList iCredentialList;

        // Timestamp indicating validity of credentials. Using SenDateUtils 
        // FromXmlDateTimeL and ToXmlDateTimeUtf8L is recommended for conversions.
        TTime iNotOnOrAfter;
        CSenProviderPolicy* iProviderPolicy;
    };

#endif // SEN_XML_SERVICE_DESCRIPTION_H

// End of File


