williamr@2: /*
williamr@2: * Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies). 
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:        Interface (abstract) class for subclasses implementing the 
williamr@2: *                most common value objects used in WSF, which are used to
williamr@2: *                describe some invocable service. 
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef M_SEN_SERVICE_DESCRIPTION_H
williamr@2: #define M_SEN_SERVICE_DESCRIPTION_H
williamr@2: 
williamr@2: //  INCLUDES
williamr@2: #include <e32base.h>
williamr@2: #include <e32des8.h>    
williamr@2: #include <s32strm.h>
williamr@2: 
williamr@2: // CONSTANTS
williamr@2: _LIT8(KSenFacetValFalse,                "false");
williamr@2: _LIT8(KSenFacetValTrue,                 "true");
williamr@2: 
williamr@2: // Facet identifier (URN) constants:
williamr@2: _LIT8(KCompleteMessagesFacet,           "urn:nokia.com.serene:complete-messages");
williamr@2: _LIT8(KExposeLocalServiceFacet,         "urn:nokia.com.serene:expose");
williamr@2: _LIT8(KProviderSharableFacet,           "urn:nokia.com.serene.provider:sharable");
williamr@2: _LIT8(KProviderCompleteClientMsgsFacet, "urn:nokia.com.serene.provider:complete-client-messages") ;
williamr@2: _LIT8(KProviderLoadOnStartupFacet,      "urn:nokia.com.serene.provider:load-on-startup") ;
williamr@2: _LIT8(KProviderThreadsafeFacet,         "urn:nokia.com.serene.provider:threadsafe") ;
williamr@2: _LIT8(KProviderReinitializableFacet,    "urn:nokia.com.serene.provider:re-initializable") ;
williamr@2: _LIT8(KProviderStayOnBackgroundFacet,   "urn:nokia.com.serene.provider:stay-on-background") ;
williamr@2: _LIT8(KTransportClassFacet,             "urn:nokia.com:serene:transport:class");
williamr@2: 
williamr@2: // Transport plug-in types (ECOM cues / class types):
williamr@2: _LIT8(KSenTransportCueHTTP,              "com.nokia.wsf.transport.plugin.httpchannel");
williamr@2: _LIT8(KSenTransportCueVirtualTCP,        "com.nokia.wsf.transport.plugin.virtualtcp"); 
williamr@2: _LIT8(KSenTransportCueLocalEcom,         "com.nokia.wsf.transport.plugin.local");  
williamr@2: _LIT8(KSenTransportCueHostletConnection, "com.nokia.wsf.transport.plugin.hostlet");
williamr@2: 
williamr@2: // Transport schemes
williamr@2: _LIT8(KSenTransportSchemeHTTP,              "http");
williamr@2: _LIT8(KSenTransportSchemeTCP,               "tcp");
williamr@2: _LIT8(KSenTransportSchemeLocal,             "local");
williamr@2: _LIT8(KSenTransportSchemeHostlet,           "hostlet");
williamr@2: //_LIT8(KSenTransportSchemeVirtualTCP,        "vtcp"); 
williamr@2: 
williamr@2: const TInt KSenServiceDescriptionBaseScore = 100;
williamr@2: 
williamr@2: // FORWARD DECLARATIONS
williamr@2: class CSenFacet;
williamr@2: 
williamr@2: // DATA TYPES
williamr@2: typedef RPointerArray<CSenFacet> RFacetArray;
williamr@2: 
williamr@2: // CLASS DECLARATION
williamr@2: 
williamr@2: /**
williamr@2: * Interface (abstract) class for subclasses implementing the  most common value
williamr@2: * objects used in WSF, which are used to describe some invocable service. 
williamr@2: * All of the subclasses are capable of representing themselves in XML.
williamr@2: * @lib SenServDesc.lib
williamr@2: * @since Series60 3.0
williamr@2: */
williamr@2: class MSenServiceDescription
williamr@2:     {
williamr@2:     public: 
williamr@2:         
williamr@2:         /**
williamr@2:         * DescriptionClassType enumeration.
williamr@2:         */
williamr@2:         IMPORT_C enum TDescriptionClassType
williamr@2:             {
williamr@2:             ERoot                               = 0, // not in use
williamr@2:             EBaseServiceDescription             = 1, // not in use
williamr@2:             EXmlServiceDescription              = 2,
williamr@2:             EIdentityProvider                   = 3, 
williamr@2:             EServicePattern                     = 4, 
williamr@2:             EServiceSession                     = 5,
williamr@2:             EWebServiceSession                  = 6,
williamr@2:             EBasicWebServiceSession             = 7,
williamr@2:             EIdWSFServiceSession                = 8,
williamr@2:             EIdWsfServiceInstance               = 9, 
williamr@2:             ECoreServiceConsumer                = 10,
williamr@2:             ESenInternalServiceConsumer         = 11,
williamr@2:             EIdWsfAuthenticationServiceClient   = 12,
williamr@2:             EIdWsfDiscoveryServiceClient        = 13,
williamr@2:             ERestServiceSession                 = 14,
williamr@2:             EWSStarServiceSession               = 15,
williamr@2:             EWSStarSTSClient                    = 16,
williamr@2:             EWSStarPolicyClient                 = 17,
williamr@2:             EWSDescription                      = 18,
williamr@2:             EWSPattern                          = 19,
williamr@2:             EAtomPubServiceSession              = 20,
williamr@2:             EAtomPubAuthClient                  = 21,
williamr@2:             EAccount                            = 22,
williamr@2:             EOviServiceSession                  = 23,
williamr@2:             EOviOAuthClient                     = 24
williamr@2:             };
williamr@2: 
williamr@2:         // New functions
williamr@2:     
williamr@2:         /**
williamr@2:         * The DescriptionClassType() method is used to resolve the real
williamr@2:         * subclass type in cases where instance of that class is seen
williamr@2:         * through one of its superclass interfaces. 
williamr@2:         * @since Series60 3.0
williamr@2:         * @return TDescriptionClassType enumeration identifying the class.
williamr@2:         */
williamr@2:         virtual TDescriptionClassType DescriptionClassType() = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Method returns ETrue if this service description matches the given 
williamr@2:         * pattern.
williamr@2:         * The bits of information that are in the pattern are read and compared
williamr@2:         * to corresponding fields in this service description. Note that a pattern
williamr@2:         * may have far fewer fields and that only the non-null and non-zero-length
williamr@2:         * fields are compared.
williamr@2:         * For example, assume that a pattern with only a contract was defined;
williamr@2:         * with  the contract set to "urn:example.com:service". Each
williamr@2:         * service description with the same contract will match the pattern,
williamr@2:         * even if such a service description has non-null/non-zero-length fields
williamr@2:         * for other aspects.
williamr@2:         * @since Series60 3.0
williamr@2:         * @param    aPattern is a Service Description, typically with partial
williamr@2:         *           information.
williamr@2:         * @return TBool ETrue if match, EFalse otherwise. If the value is
williamr@2:         * not found from current instance, it is not used in comparison
williamr@2:         * (even if offered in the given pattern).
williamr@2:         */
williamr@2:         virtual TBool Matches(MSenServiceDescription& aPattern) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Getter for contract, which is typically some URI.
williamr@2:         * @since Series60 3.0
williamr@2:         * @return the Contract
williamr@2:         */
williamr@2:         virtual TPtrC8 Contract() = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Method for checking if service description has a certain facet.
williamr@2:         * @since Series60 3.0
williamr@2:         * @param aURI       the facet to check, typically some URI.
williamr@2:         * @param aHasFacet  is ETrue if facet is found and EFalse, if not.
williamr@2:         * @return       KErrNone or other system-wide Symbian error codes.
williamr@2:         */
williamr@2:         virtual TInt HasFacetL(const TDesC8& aURI, TBool& aHasFacet) = 0;
williamr@2: 
williamr@2:         /*
williamr@2:         * Method for getting a facet value  from the service description 
williamr@2:         * @since Series60 3.0
williamr@2:         * @param aURI           the facet to get
williamr@2:         * @param aValueTo       a ref-to-pointer into which the value will
williamr@2:         *                       be allocated, which ownership is transferred
williamr@2:         *                       to the caller.
williamr@2:         * @return       KErrNone 
williamr@2:         *               KErrNoMemory value couldn't be allocated due to lack 
williamr@2:         *               of memory
williamr@2:         *               KErrNotFound if the wanted facet was not found.
williamr@2:         *               Other system-wide Symbian error codes.
williamr@2:         */
williamr@2:         virtual TInt FacetValue(TDesC8& aURI, HBufC8*& aValueTo) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Method for adding a facet. Will NOT override an already
williamr@2:         * existing facet with a same name.
williamr@2:         * @since Series60 3.0
williamr@2:         * @param        aFacet is the one to be added. A copy of the 
williamr@2:         *               the original facet instance will be added.
williamr@2:         * @return       KErrNone or other system-wide Symbian error codes.
williamr@2:         *               KErrAlreadyExists if a facet with same name exists
williamr@2:         */
williamr@2:         virtual TInt AddFacetL(const CSenFacet& aFacet) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Method for setting a facet.Adds a new facet, if non-existent.
williamr@2:         * But, if a facet with same name exists, it will be overridden.
williamr@2:         * @since Series60 3.0
williamr@2:         * @param        aFacet to be set. A copy of the original will be
williamr@2:         *               created.
williamr@2:         * @return       KErrNotFound if facet can not be found
williamr@2:         *               KErrNone     if facet was found
williamr@2:         *               KErrNoMemory if no memory could be allocated for the value
williamr@2:         *               Other system-wide Symbian error codes.
williamr@2:         */
williamr@2:         virtual TInt SetFacetL(const CSenFacet& aFacet) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Removes a characteristic (Facet) from the description
williamr@2:         * @since Series60 3.0
williamr@2:         * @param        aURI of the facet to be removed. 
williamr@2:         * @return       KErrNone     if a Facet was successfully removed
williamr@2:         *               KErrNotFound if a Facet could not be found
williamr@2:         *               Other system-wide Symbian error codes.
williamr@2:         */
williamr@2:         virtual TInt RemoveFacet(const TDesC8& aURI) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Method for getting all facets. Copies characteristics (Facets)
williamr@2:         * from the description into array. For each characteristic (Facet)
williamr@2:         * found in array the HasFacetL() method should return "ETrue".
williamr@2:         * @since Series60 3.0
williamr@2:         * @param        aFacetArray is typically an empty array, into where 
williamr@2:         *               copies of facets will be added. Ownership of the 
williamr@2:         *               items in this array is transferred to the caller.
williamr@2:         * @return       KErrNone or other system-wide Symbian error codes.
williamr@2:         */
williamr@2:         virtual TInt FacetsL(RFacetArray& aFacetArray) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * This leaving variant of ScoreMatch() always returns a positive integer 
williamr@2:         * if this service description matches with the given pattern in at
williamr@2:         * least one aspect. Higher numbers mean closer match.
williamr@2:         *
williamr@2:         * In case of system error, method leaves.
williamr@2:         *
williamr@2:         * The bits of information that are in the pattern are read and compared
williamr@2:         * to corresponding fields in this ServiceDescription. Note that a pattern
williamr@2:         * may have far fewer fields and that only the non-null fields are compared.
williamr@2:         * For example, assume that a pattern with only a contract was defined;
williamr@2:         * with the contract set to "urn:example.com:service". 
williamr@2:         * Each ServiceDescription with the same contract will match the pattern,
williamr@2:         * even if such a ServiceDescription has non-null fields for other aspects.
williamr@2:         * @since Series60 3.0
williamr@2:         * @param    aPattern a ServiceDescription, typically with partial
williamr@2:         *           information.
williamr@2:         * @return the score. If nothing matches, returns 0
williamr@2:         */
williamr@2:         virtual TInt ScoreMatchL(MSenServiceDescription& aPattern) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Getter for endpoint.
williamr@2:         * @since Series60 3.0
williamr@2:         * @return The endpoint.
williamr@2:         */
williamr@2:         virtual TPtrC8 Endpoint() = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Getter for the framework ID.
williamr@2:         * @since Series60 3.0
williamr@2:         * @return The framework ID or KNullDesC8 if no framework is set
williamr@2:         */
williamr@2:         virtual TPtrC8 FrameworkId() = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Getter for the framework version.
williamr@2:         * @since Series60 3.0
williamr@2:         * @return The framework version or KNullDesC8 if not set.
williamr@2:         */
williamr@2:         virtual TPtrC8 FrameworkVersion() = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Setter for contract.
williamr@2:         * @since Series60 3.0
williamr@2:         * @param aContract  the contract to be set.
williamr@2:         */
williamr@2:         virtual void SetContractL(const TDesC8& aContract) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Setter for endpoint.
williamr@2:         * @since Series60 3.0
williamr@2:         * @param aEndpoint to the service. Note that endpoint cannot 
williamr@2:         *        include characters which are illegal in XML. If endpoint
williamr@2:         *        is an URL which contains illegal characters (like '&'-char),
williamr@2:         *        those need to be encoded into XML entity form (like &amp;).
williamr@2:         *        EncodeHttpCharactersLC() method from XmlUtils can be used
williamr@2:         *        for encoding of basic XML entities.
williamr@2:         */
williamr@2:         virtual void SetEndPointL(const TDesC8& aEndPoint) = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Gets the service description as XML fragment in UTF-8 format.
williamr@2:         * @since Series60 3.0
williamr@2:         * @return the service description as XML, which ownership is
williamr@2:         *         transferred to the caller.
williamr@2:         */
williamr@2:         virtual HBufC8* AsXmlL() = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Gets the service description as XML, in Unicode (UCS-2)
williamr@2:         * @since Series60 3.0
williamr@2:         * @return the service description as XML, in Unicode (UCS-2)
williamr@2:         *         encoding form.
williamr@2:         */
williamr@2:         virtual HBufC* AsXmlUnicodeL() = 0;
williamr@2: 
williamr@2:         /**
williamr@2:         * Writes this service description as XML, in UTF-8 form to a stream
williamr@2:         * @since Series60 3.0
williamr@2:         * @param aWriteStream   to write into.
williamr@2:         */
williamr@2:         virtual void WriteAsXMLToL(RWriteStream& aWriteStream) = 0;
williamr@2:     };
williamr@2: 
williamr@2: #endif // M_SEN_SERVICE_DESCRIPTION_H
williamr@2: 
williamr@2: // End of File