--- 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 <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 &).
+ * 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 <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
+
+