diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/mw/senxmlservicedescription.h --- a/epoc32/include/mw/senxmlservicedescription.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/mw/senxmlservicedescription.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,578 @@ -senxmlservicedescription.h +/* +* 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 +#include +#include +#include +#include +#include + +// 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 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 &). + * 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 &). + * 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 &). + * 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 element: + * + * + * + * local://urn:nokia.com.test.hostlet + * + * + * + * 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 or + * 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 + * 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. + * http://schemas.xmlsoap.org/ws/2004/03/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 + * 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. + * http://www.mypolicyendpoint.com/policy2/ + * @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 + +