/*

 * 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:        Interface (abstract) class for subclasses implementing the 

 *                most common value objects used in WSF, which are used to

 *                describe some invocable service. 

 *

 */

 #ifndef M_SEN_SERVICE_DESCRIPTION_H

 #define M_SEN_SERVICE_DESCRIPTION_H

 //  INCLUDES

 #include <e32base.h>

 #include <e32des8.h>    

 #include <s32strm.h>

 // CONSTANTS

 _LIT8(KSenFacetValFalse,                "false");

 _LIT8(KSenFacetValTrue,                 "true");

 // Facet identifier (URN) constants:

 _LIT8(KCompleteMessagesFacet,           "urn:nokia.com.serene:complete-messages");

 _LIT8(KExposeLocalServiceFacet,         "urn:nokia.com.serene:expose");

 _LIT8(KProviderSharableFacet,           "urn:nokia.com.serene.provider:sharable");

 _LIT8(KProviderCompleteClientMsgsFacet, "urn:nokia.com.serene.provider:complete-client-messages") ;

 _LIT8(KProviderLoadOnStartupFacet,      "urn:nokia.com.serene.provider:load-on-startup") ;

 _LIT8(KProviderThreadsafeFacet,         "urn:nokia.com.serene.provider:threadsafe") ;

 _LIT8(KProviderReinitializableFacet,    "urn:nokia.com.serene.provider:re-initializable") ;

 _LIT8(KProviderStayOnBackgroundFacet,   "urn:nokia.com.serene.provider:stay-on-background") ;

 _LIT8(KTransportClassFacet,             "urn:nokia.com:serene:transport:class");

 // Transport plug-in types (ECOM cues / class types):

 _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");

 // Transport schemes

 _LIT8(KSenTransportSchemeHTTP,              "http");

 _LIT8(KSenTransportSchemeTCP,               "tcp");

 _LIT8(KSenTransportSchemeLocal,             "local");

 _LIT8(KSenTransportSchemeHostlet,           "hostlet");

 //_LIT8(KSenTransportSchemeVirtualTCP,        "vtcp"); 

 const TInt KSenServiceDescriptionBaseScore = 100;

 // FORWARD DECLARATIONS

 class CSenFacet;

 // DATA TYPES

 typedef RPointerArray<CSenFacet> RFacetArray;

 // CLASS DECLARATION

 /**

 * Interface (abstract) class for subclasses implementing the  most common value

 * objects used in WSF, which are used to describe some invocable service. 

 * All of the subclasses are capable of representing themselves in XML.

 * @lib SenServDesc.lib

 * @since Series60 3.0

 */

 class MSenServiceDescription

     {

     public: 

         /**

         * DescriptionClassType enumeration.

         */

         IMPORT_C enum TDescriptionClassType

             {

             ERoot                               = 0, // not in use

             EBaseServiceDescription             = 1, // not in use

             EXmlServiceDescription              = 2,

             EIdentityProvider                   = 3, 

             EServicePattern                     = 4, 

             EServiceSession                     = 5,

             EWebServiceSession                  = 6,

             EBasicWebServiceSession             = 7,

             EIdWSFServiceSession                = 8,

             EIdWsfServiceInstance               = 9, 

             ECoreServiceConsumer                = 10,

             ESenInternalServiceConsumer         = 11,

             EIdWsfAuthenticationServiceClient   = 12,

             EIdWsfDiscoveryServiceClient        = 13,

             ERestServiceSession                 = 14,

             EWSStarServiceSession               = 15,

             EWSStarSTSClient                    = 16,

             EWSStarPolicyClient                 = 17,

             EWSDescription                      = 18,

             EWSPattern                          = 19,

             EAtomPubServiceSession              = 20,

             EAtomPubAuthClient                  = 21,

             EAccount                            = 22,

             EOviServiceSession                  = 23,

             EOviOAuthClient                     = 24

             };

         // New functions

         /**

         * The DescriptionClassType() method is used to resolve the real

         * subclass type in cases where instance of that class is seen

         * through one of its superclass interfaces. 

         * @since Series60 3.0

         * @return TDescriptionClassType enumeration identifying the class.

         */

         virtual TDescriptionClassType DescriptionClassType() = 0;

         /**

         * Method returns ETrue if this service description matches the given 

         * pattern.

         * The bits of information that are in the pattern are read and compared

         * to corresponding fields in this service description. Note that a pattern

         * may have far fewer fields and that only the non-null and non-zero-length

         * 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

         * service description with the same contract will match the pattern,

         * even if such a service description has non-null/non-zero-length fields

         * for other aspects.

         * @since Series60 3.0

         * @param    aPattern is a Service Description, typically with partial

         *           information.

         * @return TBool ETrue if match, EFalse otherwise. If the value is

         * not found from current instance, it is not used in comparison

         * (even if offered in the given pattern).

         */

         virtual TBool Matches(MSenServiceDescription& aPattern) = 0;

         /**

         * Getter for contract, which is typically some URI.

         * @since Series60 3.0

         * @return the Contract

         */

         virtual TPtrC8 Contract() = 0;

         /**

         * 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.

         */

         virtual TInt HasFacetL(const TDesC8& aURI, TBool& aHasFacet) = 0;

         /*

         * Method for getting a facet value  from the service description 

         * @since Series60 3.0

         * @param aURI           the facet to get

         * @param aValueTo       a ref-to-pointer into which the value will

         *                       be allocated, which ownership is transferred

         *                       to the caller.

         * @return       KErrNone 

         *               KErrNoMemory value couldn't be allocated due to lack 

         *               of memory

         *               KErrNotFound if the wanted facet was not found.

         *               Other system-wide Symbian error codes.

         */

         virtual TInt FacetValue(TDesC8& aURI, HBufC8*& aValueTo) = 0;

         /**

         * Method for adding a facet. Will NOT override an already

         * existing facet with a same name.

         * @since Series60 3.0

         * @param        aFacet is the one to be added. A copy of the 

         *               the original facet instance will be added.

         * @return       KErrNone or other system-wide Symbian error codes.

         *               KErrAlreadyExists if a facet with same name exists

         */

         virtual TInt AddFacetL(const CSenFacet& aFacet) = 0;

         /**

         * Method for setting a facet.Adds a new facet, if non-existent.

         * But, if a facet with same name exists, it will be overridden.

         * @since Series60 3.0

         * @param        aFacet to be set. A copy of the original will be

         *               created.

         * @return       KErrNotFound if facet can not be found

         *               KErrNone     if facet was found

         *               KErrNoMemory if no memory could be allocated for the value

         *               Other system-wide Symbian error codes.

         */

         virtual TInt SetFacetL(const CSenFacet& aFacet) = 0;

         /**

         * Removes a characteristic (Facet) from the description

         * @since Series60 3.0

         * @param        aURI of the facet to be removed. 

         * @return       KErrNone     if a Facet was successfully removed

         *               KErrNotFound if a Facet could not be found

         *               Other system-wide Symbian error codes.

         */

         virtual TInt RemoveFacet(const TDesC8& aURI) = 0;

         /**

         * Method for getting all facets. Copies characteristics (Facets)

         * from the description into array. For each characteristic (Facet)

         * found in array the HasFacetL() method should return "ETrue".

         * @since Series60 3.0

         * @param        aFacetArray is typically an empty array, into where 

         *               copies of facets will be added. Ownership of the 

         *               items in this array is transferred to the caller.

         * @return       KErrNone or other system-wide Symbian error codes.

         */

         virtual TInt FacetsL(RFacetArray& aFacetArray) = 0;

         /**

         * This leaving variant of ScoreMatch() always returns a positive integer 

         * if this service description matches with the given pattern in at

         * least one aspect. Higher numbers mean closer match.

         *

         * In case of system error, method leaves.

         *

         * 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. If nothing matches, returns 0

         */

         virtual TInt ScoreMatchL(MSenServiceDescription& aPattern) = 0;

         /**

         * Getter for endpoint.

         * @since Series60 3.0

         * @return The endpoint.

         */

         virtual TPtrC8 Endpoint() = 0;

         /**

         * Getter for the framework ID.

         * @since Series60 3.0

         * @return The framework ID or KNullDesC8 if no framework is set

         */

         virtual TPtrC8 FrameworkId() = 0;

         /**

         * Getter for the framework version.

         * @since Series60 3.0

         * @return The framework version or KNullDesC8 if not set.

         */

         virtual TPtrC8 FrameworkVersion() = 0;

         /**

         * Setter for contract.

         * @since Series60 3.0

         * @param aContract  the contract to be set.

         */

         virtual void SetContractL(const TDesC8& aContract) = 0;

         /**

         * Setter for endpoint.

         * @since Series60 3.0

         * @param aEndpoint to the service. 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.

         */

         virtual void SetEndPointL(const TDesC8& aEndPoint) = 0;

         /**

         * 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.

         */

         virtual HBufC8* AsXmlL() = 0;

         /**

         * 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.

         */

         virtual HBufC* AsXmlUnicodeL() = 0;

         /**

         * Writes this service description as XML, in UTF-8 form to a stream

         * @since Series60 3.0

         * @param aWriteStream   to write into.

         */

         virtual void WriteAsXMLToL(RWriteStream& aWriteStream) = 0;

     };

 #endif // M_SEN_SERVICE_DESCRIPTION_H

 // End of File