1.1 --- a/epoc32/include/mw/msenservicedescription.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/msenservicedescription.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,312 @@
1.4 -msenservicedescription.h
1.5 +/*
1.6 +* Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: Interface (abstract) class for subclasses implementing the
1.19 +* most common value objects used in WSF, which are used to
1.20 +* describe some invocable service.
1.21 +*
1.22 +*/
1.23 +
1.24 +
1.25 +
1.26 +
1.27 +
1.28 +
1.29 +
1.30 +
1.31 +#ifndef M_SEN_SERVICE_DESCRIPTION_H
1.32 +#define M_SEN_SERVICE_DESCRIPTION_H
1.33 +
1.34 +// INCLUDES
1.35 +#include <e32base.h>
1.36 +#include <e32des8.h>
1.37 +#include <s32strm.h>
1.38 +
1.39 +// CONSTANTS
1.40 +_LIT8(KSenFacetValFalse, "false");
1.41 +_LIT8(KSenFacetValTrue, "true");
1.42 +
1.43 +// Facet identifier (URN) constants:
1.44 +_LIT8(KCompleteMessagesFacet, "urn:nokia.com.serene:complete-messages");
1.45 +_LIT8(KExposeLocalServiceFacet, "urn:nokia.com.serene:expose");
1.46 +_LIT8(KProviderSharableFacet, "urn:nokia.com.serene.provider:sharable");
1.47 +_LIT8(KProviderCompleteClientMsgsFacet, "urn:nokia.com.serene.provider:complete-client-messages") ;
1.48 +_LIT8(KProviderLoadOnStartupFacet, "urn:nokia.com.serene.provider:load-on-startup") ;
1.49 +_LIT8(KProviderThreadsafeFacet, "urn:nokia.com.serene.provider:threadsafe") ;
1.50 +_LIT8(KProviderReinitializableFacet, "urn:nokia.com.serene.provider:re-initializable") ;
1.51 +_LIT8(KProviderStayOnBackgroundFacet, "urn:nokia.com.serene.provider:stay-on-background") ;
1.52 +_LIT8(KTransportClassFacet, "urn:nokia.com:serene:transport:class");
1.53 +
1.54 +// Transport plug-in types (ECOM cues / class types):
1.55 +_LIT8(KSenTransportCueHTTP, "com.nokia.wsf.transport.plugin.httpchannel");
1.56 +_LIT8(KSenTransportCueVirtualTCP, "com.nokia.wsf.transport.plugin.virtualtcp");
1.57 +_LIT8(KSenTransportCueLocalEcom, "com.nokia.wsf.transport.plugin.local");
1.58 +_LIT8(KSenTransportCueHostletConnection, "com.nokia.wsf.transport.plugin.hostlet");
1.59 +
1.60 +// Transport schemes
1.61 +_LIT8(KSenTransportSchemeHTTP, "http");
1.62 +_LIT8(KSenTransportSchemeTCP, "tcp");
1.63 +_LIT8(KSenTransportSchemeLocal, "local");
1.64 +_LIT8(KSenTransportSchemeHostlet, "hostlet");
1.65 +//_LIT8(KSenTransportSchemeVirtualTCP, "vtcp");
1.66 +
1.67 +const TInt KSenServiceDescriptionBaseScore = 100;
1.68 +
1.69 +// FORWARD DECLARATIONS
1.70 +class CSenFacet;
1.71 +
1.72 +// DATA TYPES
1.73 +typedef RPointerArray<CSenFacet> RFacetArray;
1.74 +
1.75 +// CLASS DECLARATION
1.76 +
1.77 +/**
1.78 +* Interface (abstract) class for subclasses implementing the most common value
1.79 +* objects used in WSF, which are used to describe some invocable service.
1.80 +* All of the subclasses are capable of representing themselves in XML.
1.81 +* @lib SenServDesc.lib
1.82 +* @since Series60 3.0
1.83 +*/
1.84 +class MSenServiceDescription
1.85 + {
1.86 + public:
1.87 +
1.88 + /**
1.89 + * DescriptionClassType enumeration.
1.90 + */
1.91 + IMPORT_C enum TDescriptionClassType
1.92 + {
1.93 + ERoot = 0, // not in use
1.94 + EBaseServiceDescription = 1, // not in use
1.95 + EXmlServiceDescription = 2,
1.96 + EIdentityProvider = 3,
1.97 + EServicePattern = 4,
1.98 + EServiceSession = 5,
1.99 + EWebServiceSession = 6,
1.100 + EBasicWebServiceSession = 7,
1.101 + EIdWSFServiceSession = 8,
1.102 + EIdWsfServiceInstance = 9,
1.103 + ECoreServiceConsumer = 10,
1.104 + ESenInternalServiceConsumer = 11,
1.105 + EIdWsfAuthenticationServiceClient = 12,
1.106 + EIdWsfDiscoveryServiceClient = 13,
1.107 + ERestServiceSession = 14,
1.108 + EWSStarServiceSession = 15,
1.109 + EWSStarSTSClient = 16,
1.110 + EWSStarPolicyClient = 17,
1.111 + EWSDescription = 18,
1.112 + EWSPattern = 19,
1.113 + EAtomPubServiceSession = 20,
1.114 + EAtomPubAuthClient = 21,
1.115 + EAccount = 22,
1.116 + EOviServiceSession = 23,
1.117 + EOviOAuthClient = 24
1.118 + };
1.119 +
1.120 + // New functions
1.121 +
1.122 + /**
1.123 + * The DescriptionClassType() method is used to resolve the real
1.124 + * subclass type in cases where instance of that class is seen
1.125 + * through one of its superclass interfaces.
1.126 + * @since Series60 3.0
1.127 + * @return TDescriptionClassType enumeration identifying the class.
1.128 + */
1.129 + virtual TDescriptionClassType DescriptionClassType() = 0;
1.130 +
1.131 + /**
1.132 + * Method returns ETrue if this service description matches the given
1.133 + * pattern.
1.134 + * The bits of information that are in the pattern are read and compared
1.135 + * to corresponding fields in this service description. Note that a pattern
1.136 + * may have far fewer fields and that only the non-null and non-zero-length
1.137 + * fields are compared.
1.138 + * For example, assume that a pattern with only a contract was defined;
1.139 + * with the contract set to "urn:example.com:service". Each
1.140 + * service description with the same contract will match the pattern,
1.141 + * even if such a service description has non-null/non-zero-length fields
1.142 + * for other aspects.
1.143 + * @since Series60 3.0
1.144 + * @param aPattern is a Service Description, typically with partial
1.145 + * information.
1.146 + * @return TBool ETrue if match, EFalse otherwise. If the value is
1.147 + * not found from current instance, it is not used in comparison
1.148 + * (even if offered in the given pattern).
1.149 + */
1.150 + virtual TBool Matches(MSenServiceDescription& aPattern) = 0;
1.151 +
1.152 + /**
1.153 + * Getter for contract, which is typically some URI.
1.154 + * @since Series60 3.0
1.155 + * @return the Contract
1.156 + */
1.157 + virtual TPtrC8 Contract() = 0;
1.158 +
1.159 + /**
1.160 + * Method for checking if service description has a certain facet.
1.161 + * @since Series60 3.0
1.162 + * @param aURI the facet to check, typically some URI.
1.163 + * @param aHasFacet is ETrue if facet is found and EFalse, if not.
1.164 + * @return KErrNone or other system-wide Symbian error codes.
1.165 + */
1.166 + virtual TInt HasFacetL(const TDesC8& aURI, TBool& aHasFacet) = 0;
1.167 +
1.168 + /*
1.169 + * Method for getting a facet value from the service description
1.170 + * @since Series60 3.0
1.171 + * @param aURI the facet to get
1.172 + * @param aValueTo a ref-to-pointer into which the value will
1.173 + * be allocated, which ownership is transferred
1.174 + * to the caller.
1.175 + * @return KErrNone
1.176 + * KErrNoMemory value couldn't be allocated due to lack
1.177 + * of memory
1.178 + * KErrNotFound if the wanted facet was not found.
1.179 + * Other system-wide Symbian error codes.
1.180 + */
1.181 + virtual TInt FacetValue(TDesC8& aURI, HBufC8*& aValueTo) = 0;
1.182 +
1.183 + /**
1.184 + * Method for adding a facet. Will NOT override an already
1.185 + * existing facet with a same name.
1.186 + * @since Series60 3.0
1.187 + * @param aFacet is the one to be added. A copy of the
1.188 + * the original facet instance will be added.
1.189 + * @return KErrNone or other system-wide Symbian error codes.
1.190 + * KErrAlreadyExists if a facet with same name exists
1.191 + */
1.192 + virtual TInt AddFacetL(const CSenFacet& aFacet) = 0;
1.193 +
1.194 + /**
1.195 + * Method for setting a facet.Adds a new facet, if non-existent.
1.196 + * But, if a facet with same name exists, it will be overridden.
1.197 + * @since Series60 3.0
1.198 + * @param aFacet to be set. A copy of the original will be
1.199 + * created.
1.200 + * @return KErrNotFound if facet can not be found
1.201 + * KErrNone if facet was found
1.202 + * KErrNoMemory if no memory could be allocated for the value
1.203 + * Other system-wide Symbian error codes.
1.204 + */
1.205 + virtual TInt SetFacetL(const CSenFacet& aFacet) = 0;
1.206 +
1.207 + /**
1.208 + * Removes a characteristic (Facet) from the description
1.209 + * @since Series60 3.0
1.210 + * @param aURI of the facet to be removed.
1.211 + * @return KErrNone if a Facet was successfully removed
1.212 + * KErrNotFound if a Facet could not be found
1.213 + * Other system-wide Symbian error codes.
1.214 + */
1.215 + virtual TInt RemoveFacet(const TDesC8& aURI) = 0;
1.216 +
1.217 + /**
1.218 + * Method for getting all facets. Copies characteristics (Facets)
1.219 + * from the description into array. For each characteristic (Facet)
1.220 + * found in array the HasFacetL() method should return "ETrue".
1.221 + * @since Series60 3.0
1.222 + * @param aFacetArray is typically an empty array, into where
1.223 + * copies of facets will be added. Ownership of the
1.224 + * items in this array is transferred to the caller.
1.225 + * @return KErrNone or other system-wide Symbian error codes.
1.226 + */
1.227 + virtual TInt FacetsL(RFacetArray& aFacetArray) = 0;
1.228 +
1.229 + /**
1.230 + * This leaving variant of ScoreMatch() always returns a positive integer
1.231 + * if this service description matches with the given pattern in at
1.232 + * least one aspect. Higher numbers mean closer match.
1.233 + *
1.234 + * In case of system error, method leaves.
1.235 + *
1.236 + * The bits of information that are in the pattern are read and compared
1.237 + * to corresponding fields in this ServiceDescription. Note that a pattern
1.238 + * may have far fewer fields and that only the non-null fields are compared.
1.239 + * For example, assume that a pattern with only a contract was defined;
1.240 + * with the contract set to "urn:example.com:service".
1.241 + * Each ServiceDescription with the same contract will match the pattern,
1.242 + * even if such a ServiceDescription has non-null fields for other aspects.
1.243 + * @since Series60 3.0
1.244 + * @param aPattern a ServiceDescription, typically with partial
1.245 + * information.
1.246 + * @return the score. If nothing matches, returns 0
1.247 + */
1.248 + virtual TInt ScoreMatchL(MSenServiceDescription& aPattern) = 0;
1.249 +
1.250 + /**
1.251 + * Getter for endpoint.
1.252 + * @since Series60 3.0
1.253 + * @return The endpoint.
1.254 + */
1.255 + virtual TPtrC8 Endpoint() = 0;
1.256 +
1.257 + /**
1.258 + * Getter for the framework ID.
1.259 + * @since Series60 3.0
1.260 + * @return The framework ID or KNullDesC8 if no framework is set
1.261 + */
1.262 + virtual TPtrC8 FrameworkId() = 0;
1.263 +
1.264 + /**
1.265 + * Getter for the framework version.
1.266 + * @since Series60 3.0
1.267 + * @return The framework version or KNullDesC8 if not set.
1.268 + */
1.269 + virtual TPtrC8 FrameworkVersion() = 0;
1.270 +
1.271 + /**
1.272 + * Setter for contract.
1.273 + * @since Series60 3.0
1.274 + * @param aContract the contract to be set.
1.275 + */
1.276 + virtual void SetContractL(const TDesC8& aContract) = 0;
1.277 +
1.278 + /**
1.279 + * Setter for endpoint.
1.280 + * @since Series60 3.0
1.281 + * @param aEndpoint to the service. Note that endpoint cannot
1.282 + * include characters which are illegal in XML. If endpoint
1.283 + * is an URL which contains illegal characters (like '&'-char),
1.284 + * those need to be encoded into XML entity form (like &).
1.285 + * EncodeHttpCharactersLC() method from XmlUtils can be used
1.286 + * for encoding of basic XML entities.
1.287 + */
1.288 + virtual void SetEndPointL(const TDesC8& aEndPoint) = 0;
1.289 +
1.290 + /**
1.291 + * Gets the service description as XML fragment in UTF-8 format.
1.292 + * @since Series60 3.0
1.293 + * @return the service description as XML, which ownership is
1.294 + * transferred to the caller.
1.295 + */
1.296 + virtual HBufC8* AsXmlL() = 0;
1.297 +
1.298 + /**
1.299 + * Gets the service description as XML, in Unicode (UCS-2)
1.300 + * @since Series60 3.0
1.301 + * @return the service description as XML, in Unicode (UCS-2)
1.302 + * encoding form.
1.303 + */
1.304 + virtual HBufC* AsXmlUnicodeL() = 0;
1.305 +
1.306 + /**
1.307 + * Writes this service description as XML, in UTF-8 form to a stream
1.308 + * @since Series60 3.0
1.309 + * @param aWriteStream to write into.
1.310 + */
1.311 + virtual void WriteAsXMLToL(RWriteStream& aWriteStream) = 0;
1.312 + };
1.313 +
1.314 +#endif // M_SEN_SERVICE_DESCRIPTION_H
1.315 +
1.316 +// End of File