/*

* 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