1.1 --- a/epoc32/include/mw/senserviceconnection.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/senserviceconnection.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,1192 @@
1.4 -senserviceconnection.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: CSenServiceConnection offers public API for
1.19 +* service consumers to access invocable services,
1.20 +* as a part of the Web Services Framework (WSF).
1.21 +*
1.22 +*/
1.23 +
1.24 +
1.25 +
1.26 +
1.27 +
1.28 +
1.29 +
1.30 +
1.31 +
1.32 +#ifndef SEN_SERVICE_CONNECTION_H
1.33 +#define SEN_SERVICE_CONNECTION_H
1.34 +
1.35 +// INCLUDES
1.36 +#include <e32base.h> // for CActive
1.37 +#include <MSenServiceConsumer.h>
1.38 +#include <MSenServiceDescription.h>
1.39 +
1.40 +#include <MSenAuthenticationProvider.h>
1.41 +
1.42 +#include <SenSoapMessage.h>
1.43 +#include <SenSoapMessage2.h>
1.44 +//#include <SenAtomEntry.h>
1.45 +
1.46 +
1.47 +#include <MSenMessage.h>
1.48 +
1.49 +// CONSTANTS
1.50 +const TInt KErrSenNotInitialized = -30291;
1.51 +const TInt KErrSenServiceConnectionBusy = -30292;
1.52 +const TInt KErrConnectionInitializing = -30293;
1.53 +const TInt KErrConnectionExpired = -30294;
1.54 +const TInt KErrSubmitting = -30295;
1.55 +const TInt KErrSenSoapFault = -30296;
1.56 +const TInt KErrSenInternal = -30297;
1.57 +const TInt KErrSenNoEndpoint = -30298;
1.58 +const TInt KErrSenNoContract = -30299;
1.59 +
1.60 +const TInt KErrSenProviderIdInUseByAnotherEndpoint = -30305;
1.61 +const TInt KErrSenNoContractNoEndPoint = -30306;
1.62 +
1.63 +const TInt KErrSenBrokenSoapEnvelope = -30307;
1.64 +const TInt KErrSenBrokenSoapFault = -30308;
1.65 +const TInt KErrSenCancelled = -30309;
1.66 +
1.67 +
1.68 +// HTTP transport error codes:
1.69 +const TInt KErrSenNoHttpResponseBody = -30310;
1.70 +const TInt KErrSenNoHttpContentType = -30311;
1.71 +const TInt KErrSenHttpRedirectRequiresConfirmation = -30312;
1.72 +
1.73 +// SOAP message verification error codes:
1.74 +const TInt KErrSenNoSoapBody = -30313;
1.75 +const TInt KErrSenNoSoapHeader = -30314;
1.76 +const TInt KErrSenNoPermission = -30315;
1.77 +
1.78 +const TInt KErrSenHostNotAvailable = -30318;
1.79 +
1.80 +const TInt KErrSenAuthenticationFault = -30319;
1.81 +const TInt KErrSenNoEndUserPermission = -30321;
1.82 +
1.83 +
1.84 +const TInt KSenConnectionStatusCreateFailed = -1; // post-state
1.85 +const TInt KSenConnectionStatusNew = 0; // post-state
1.86 +const TInt KSenConnectionStatusReady = 1; // post-state
1.87 +const TInt KSenConnectionStatusExpired = 2; // post-state
1.88 +const TInt KSenConnectionStatusAuthentication = 3; // pre-state
1.89 +const TInt KSenConnectionStatusDiscovery = 4; // pre-state
1.90 +const TInt KSenConnectionStatusMetadataExchange = 5; // pre-state
1.91 +
1.92 +_LIT8(KDefaultBasicWebServicesFrameworkID, "WS-I");
1.93 +_LIT8(KDefaultIdWsfFrameworkID, "ID-WSF");
1.94 +_LIT8(KDefaultRestServicesFrameworkID, "REST");
1.95 +_LIT8(KDefaultWSStarFrameworkID, "WS-STAR");
1.96 +_LIT8(KDefaultAtomPubFrameworkID, "ATOM-PUB");
1.97 +_LIT8(KDefaultOviFrameworkID, "OVI");
1.98 +
1.99 +const TInt KSenTransportStatusCodeOffsetBaseHttp = 1000;
1.100 +const TInt KSenTransportStatusCodeOffsetBaseVtcp = 2000;
1.101 +
1.102 +const TInt KSenTransportStatusCodeVtcpInit = 2001; // KSenTransportStatusCodeOffsetBaseVtcp +1
1.103 +const TInt KSenTransportStatusCodeVtcpActive = 2002; // KSenTransportStatusCodeOffsetBaseVtcp +2
1.104 +const TInt KSenTransportStatusCodeVtcpSuspended = 2003; // KSenTransportStatusCodeOffsetBaseVtcp +3
1.105 +const TInt KSenTransportStatusCodeVtcpInactive = 2004; // KSenTransportStatusCodeOffsetBaseVtcp +4
1.106 +const TInt KSenTransportStatusCodeVtcpUnavailable = 2005; // KSenTransportStatusCodeOffsetBaseVtcp +5
1.107 +
1.108 +// FORWARD DECLARATIONS
1.109 +class CSenServicePattern;
1.110 +class CSenIdentityProvider;
1.111 +
1.112 +// CLASS DECLARATION
1.113 +
1.114 +/**
1.115 + * The class for connecting to service providers
1.116 + * through Web Services Framework (WSF).
1.117 + *
1.118 + * The class offers asynchronous construction of a
1.119 + * service connection. Further, there are asynchronous
1.120 + * and synchronous interaction methods for e.g. sending
1.121 + * and receiving data from (possibly remote) service.
1.122 + *
1.123 + * WSF offers two default frameworks:
1.124 + *
1.125 + * 1. Identity Based Web Services Framework
1.126 + * (ID-WSF). The framework ID for this is
1.127 + * KDefaultIdWsfFrameworkID ("ID-WSF").
1.128 + *
1.129 + * 2. Basic Web Services Framework. Framework
1.130 + * ID is KDefaultBasicWebServicesFrameworkID
1.131 + * ("WS-I").
1.132 + *
1.133 + * The most typical use of CSenServiceConnection
1.134 + * is to interact with a service of certain type
1.135 + * through some invocable framework and submitting
1.136 + * and receiving messages.
1.137 + *
1.138 + * In case of WebServices, the actual service is remote
1.139 + * and submitted messages are SOAP envelopes. However,
1.140 + * CSenServiceConnection supports accessing any
1.141 + * ServiceInvocationFramework which ECOM plug-in
1.142 + * implementation is present. These plug-ins may
1.143 + * further communicate with some service, including
1.144 + * local services.
1.145 + *
1.146 + * The link between CSenServiceConnection and any plug-in
1.147 + * implementation interacting with some service is the
1.148 + * framework ID, which is a property of ServiceDescription (SD)
1.149 + * and accessible via MSenServiceDescription interface, which
1.150 + * each SD class must implement.
1.151 + *
1.152 + * When creating a connection, one offers predefined SD as
1.153 + * an argument for asynchronous constructor. Or, optionally
1.154 + * only a Liberty Alliance ID-WSF specific contract string
1.155 + * - typically some URN. If only contract is offered, then
1.156 + * the created connection defaults to ID-WSF service and
1.157 + * ID-WSF framework (ID) will be used.
1.158 + *
1.159 + * The WSF further uses the offered framework ID while looking
1.160 + * up any matching framework plug-in implementation. As a
1.161 + * result the SD might be offered to several plug-ins.
1.162 +*
1.163 +* @lib SenServConn.lib
1.164 +* @since Series60 3.0
1.165 +*/
1.166 +
1.167 +class CSenServiceConnection : public CActive, public MSenFragment
1.168 + {
1.169 + public: // Constructors and destructor
1.170 +
1.171 + /**
1.172 + * Two-phased constructor intended for Identity based service
1.173 + * consumers (like ID-WSF). The pointer is left on the cleanup stack.
1.174 + * This constructor is ASYNCHRONOUS and the actual state of
1.175 + * created connection has to be observed from SetStatus() AND
1.176 + * HandleErrorL() functions.
1.177 + * If service is found, the SetStatus() call-back is performed
1.178 + * with a status value KSenConnectionStatusReady (1).
1.179 + * Contract of the service (typically some URN) is provided.
1.180 + * Authentication for the Web Service Provider (WSP) connection
1.181 + * is resolved using one of the identity providers which have
1.182 + * been associated with this contract (typically an URN).
1.183 + *
1.184 + * This constructor is ASYNCHRONOUS and the actual state of newly
1.185 + * created connection has to be observed from SetStatus() AND
1.186 + * HandleErrorL() functions.
1.187 + * If service is found, a SetStatus call-back with value
1.188 + * KSenConnectionStatusReady (1) is executed.
1.189 + * If some error occurs, HandleErrorL() will be called to inform the
1.190 + * creator of this connection (service consumer application)
1.191 + *
1.192 + * For example, if service is not found, a system wide error
1.193 + * code of -1 is deliver via HandleErrorL() to WSC.
1.194 + *
1.195 + * Second example: server response HTTP 501 means, that this error
1.196 + * code. 501 will be delivered via HandleErrorL() to WSC.
1.197 + * This can happen in ID-WSF connection being initialized, if
1.198 + * either Authentication Service (AS) or Discovery Service (DS)
1.199 + * cannot be reached.
1.200 + *
1.201 + * @param aConsumer (web) service consumer (for call-backs)
1.202 + * @param aContract contract of the service, typically an URI.
1.203 + * @return a pointer to a CSenServiceConnection instance.
1.204 + *
1.205 + */
1.206 + IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aConsumer,
1.207 + const TDesC8& aContract);
1.208 +
1.209 + /**
1.210 + * Two-phased constructor intended for Identity based service
1.211 + * consumers (like ID-WSF).
1.212 + * This constructor is ASYNCHRONOUS and the actual state of
1.213 + * created connection has to be observed from SetStatus() and
1.214 + * HandleErrorL() functions.
1.215 + * If service is found, the SetStatus() call-back is performed
1.216 + * with a status value KSenConnectionStatusReady (1).
1.217 + * Contract of the service (typically some URN) is provided.
1.218 + * Authentication for the Web Service Provider (WSP) connection
1.219 + * is resolved using one of the identity providers which have
1.220 + * been associated with this contract (typically an URN).
1.221 + * This constructor is ASYNCHRONOUS and the actual state of newly
1.222 + * created connection has to be observed from SetStatus() AND
1.223 + * HandleErrorL() functions.
1.224 + * If service is found, a SetStatus call-back with value
1.225 + * KSenConnectionStatusReady (1) is executed.
1.226 + * If some error occurs, HandleErrorL() will be called to inform the
1.227 + * creator of this connection (service consumer application)
1.228 + *
1.229 + * For example, if service is not found, a system wide error
1.230 + * code of -1 is deliver via HandleErrorL() to WSC.
1.231 + *
1.232 + * Second example: server response HTTP 501 means, that this error
1.233 + * code. 501 will be delivered via HandleErrorL() to WSC.
1.234 + * This can happen in ID-WSF connection being initialized, if
1.235 + * either Authentication Service (AS) or Discovery Service (DS)
1.236 + * cannot be reached.
1.237 + *
1.238 + * @param aConsumer (web) service consumer (for call-backs)
1.239 + * @param aContract contract of the service, typically an URI.
1.240 + * @return a pointer to a CSenServiceConnection instance.
1.241 + * The pointer is left on the cleanup stack.
1.242 + */
1.243 + IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aObserver,
1.244 + const TDesC8& aContract);
1.245 +
1.246 + /**
1.247 + * Two-phased constructor using a service description.
1.248 + * This constructor is ASYNCHRONOUS and the actual state of
1.249 + * created connection has to be observed from SetStatus() and
1.250 + * HandleErrorL() functions.
1.251 + * If service is found, the SetStatus() call-back is executed
1.252 + * with a status value KSenConnectionStatusReady (1)
1.253 + * For ID-WSF connections, the authentication for the Web Service
1.254 + * Provider (WSP) connection is resolved using one of the identity
1.255 + * providers which have been associated with the contract found in
1.256 + * the SD. At minimum, the contract of the service (typically some URN)
1.257 + * has to provided in the SD.
1.258 + * Basic Web Service consumers instantiate a SD where an endpoint
1.259 + * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
1.260 + * @param aObserver connection observer.
1.261 + * @param aServiceDescription is the description used to
1.262 + * obtain a service connection.
1.263 + * @return a pointer to a CSenServiceConnection instance.
1.264 + */
1.265 + IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aObserver,
1.266 + MSenServiceDescription& aServiceDescription);
1.267 +
1.268 + /**
1.269 + * Two-phased constructor using a service description. The pointer
1.270 + * is left on the cleanup stack.
1.271 + * This constructor is ASYNCHRONOUS and the actual state of
1.272 + * created connection has to be observed from SetStatus() AND
1.273 + * HandleErrorL() functions.
1.274 + * If service is found, the SetStatus() call-back is executed
1.275 + * with a status value KSenConnectionStatusReady (1)
1.276 + * For ID-WSF connections, the authentication for the Web Service
1.277 + * Provider (WSP) connection is resolved using one of the identity
1.278 + * providers which have been associated with the contract found in
1.279 + * the SD. At minimum, the contract of the service (typically some URN)
1.280 + * has to provided in the SD.
1.281 + * Basic Web Service consumers instantiate a SD where an endpoint
1.282 + * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
1.283 + * @param aObserver connection observer.
1.284 + * @param aServiceDescription is the description used to
1.285 + * obtain a service connection.
1.286 + * @return a pointer to a CSenServiceConnection instance.
1.287 + * The pointer is left on the cleanup stack.
1.288 + */
1.289 + IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aObserver,
1.290 + MSenServiceDescription& aServiceDescription);
1.291 +
1.292 + /*
1.293 + * The ServicePattern version of two phased constructor.
1.294 + * Note, that this method is intended to be used by service consumers
1.295 + * wishing to initialize connection in specific context called
1.296 + * consumer policy. In consumer policy, certain properties
1.297 + * can be set to further define what kind of connection is acceptable
1.298 + * and how the connection interacts with transport (for example, which
1.299 + * Internet Access Point (IAP) will be used).
1.300 + * However, any ConsumerPolicy feature is applicable in
1.301 + * one-policy-per-client scope and not used as a common policy.
1.302 + * To set permanent information about known WSP, please use the
1.303 + * CSenXmlServiceDescription, which implements MSenProviderPolicy
1.304 + * interface.
1.305 + * This constructor is ASYNCHRONOUS and the actual state of
1.306 + * created connection has to be observed from SetStatus() and
1.307 + * HandleErrorL() functions.
1.308 + * If service is found, the SetStatus() call-back is executed
1.309 + * with a status value KSenConnectionStatusReady (1)
1.310 + * For ID-WSF connections, the authentication for the Web Service
1.311 + * Provider (WSP) connection is resolved using one of the identity
1.312 + * providers which have been associated with the contract found in
1.313 + * the SD. At minimum, the contract of the service (typically some URN)
1.314 + * has to provided in the SD.
1.315 + * Basic Web Service consumers instantiate a SD where an endpoint
1.316 + * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
1.317 + * @param aObserver connection observer.
1.318 + * @param aServiceDescription is the description used to
1.319 + * obtain a service connection.
1.320 + * @return a pointer to a CSenServiceConnection instance.
1.321 + */
1.322 + IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aObserver,
1.323 + CSenServicePattern& aServicePattern);
1.324 +
1.325 + /*
1.326 + * The ServicePattern version of two phased constructor.
1.327 + * Note, that this method is intended to be used by service consumers
1.328 + * wishing to initialize connection in specific context called
1.329 + * consumer policy. In consumer policy, certain properties
1.330 + * can be set to further define what kind of connection is acceptable
1.331 + * and how the connection interacts with transport (for example, which
1.332 + * Internet Access Point (IAP) will be used).
1.333 + * However, any ConsumerPolicy feature is applicable in
1.334 + * one-policy-per-client scope and not used as a common policy.
1.335 + * To set permanent information about known WSP, please use the
1.336 + * CSenXmlServiceDescription, which implements MSenProviderPolicy
1.337 + * interface.
1.338 + * This constructor is ASYNCHRONOUS and the actual state of
1.339 + * created connection has to be observed from SetStatus() and
1.340 + * HandleErrorL() functions.
1.341 + * If service is found, the SetStatus() call-back is executed
1.342 + * with a status value KSenConnectionStatusReady (1)
1.343 + * For ID-WSF connections, the authentication for the Web Service
1.344 + * Provider (WSP) connection is resolved using one of the identity
1.345 + * providers which have been associated with the contract found in
1.346 + * the SD. At minimum, the contract of the service (typically some URN)
1.347 + * has to provided in the SD.
1.348 + * Basic Web Service consumers instantiate a SD where an endpoint
1.349 + * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
1.350 + * @param aObserver connection observer.
1.351 + * @param aServiceDescription is the description used to
1.352 + * obtain a service connection.
1.353 + * @return a pointer to a CSenServiceConnection instance.
1.354 + * The pointer is left on the cleanup stack.
1.355 + */
1.356 + IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aObserver,
1.357 + CSenServicePattern& aServicePattern);
1.358 +
1.359 + /**
1.360 + * Two-phased constructor intended for Identity based service
1.361 + * consumers (like ID-WSF). The pointer is left on the cleanup stack.
1.362 + * This constructor is ASYNCHRONOUS and the actual state of
1.363 + * created connection has to be observed from SetStatus() AND
1.364 + * HandleErrorL() functions.
1.365 + * If service is found, the SetStatus() call-back is performed
1.366 + * with a status value KSenConnectionStatusReady (1).
1.367 + * Contract of the service (typically some URN) is provided.
1.368 + * Authentication for the Web Service Provider (WSP) connection
1.369 + * is resolved using one of the identity providers which have
1.370 + * been associated with this contract (typically an URN).
1.371 + *
1.372 + * This constructor is ASYNCHRONOUS and the actual state of newly
1.373 + * created connection has to be observed from SetStatus() AND
1.374 + * HandleErrorL() functions.
1.375 + * If service is found, a SetStatus call-back with value
1.376 + * KSenConnectionStatusReady (1) is executed.
1.377 + * If some error occurs, HandleErrorL() will be called to inform the
1.378 + * creator of this connection (service consumer application)
1.379 + *
1.380 + * For example, if service is not found, a system wide error
1.381 + * code of -1 is deliver via HandleErrorL() to WSC.
1.382 + *
1.383 + * Second example: server response HTTP 501 means, that this error
1.384 + * code. 501 will be delivered via HandleErrorL() to WSC.
1.385 + * This can happen in ID-WSF connection being initialized, if
1.386 + * either Authentication Service (AS) or Discovery Service (DS)
1.387 + * cannot be reached.
1.388 + *
1.389 + * @param aConsumer (web) service consumer (for call-backs)
1.390 + * @param aContract contract of the service, typically an URI.
1.391 + * @return a pointer to a CSenServiceConnection instance.
1.392 + * @param aAuthProvider Authentication Provider
1.393 + */
1.394 + IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aConsumer,
1.395 + const TDesC8& aContract,
1.396 + MSenExtendedConsumerInterface& aExtendedConsumer);
1.397 + /**
1.398 + * Two-phased constructor intended for Identity based service
1.399 + * consumers (like ID-WSF).
1.400 + * This constructor is ASYNCHRONOUS and the actual state of
1.401 + * created connection has to be observed from SetStatus() and
1.402 + * HandleErrorL() functions.
1.403 + * If service is found, the SetStatus() call-back is performed
1.404 + * with a status value KSenConnectionStatusReady (1).
1.405 + * Contract of the service (typically some URN) is provided.
1.406 + * Authentication for the Web Service Provider (WSP) connection
1.407 + * is resolved using one of the identity providers which have
1.408 + * been associated with this contract (typically an URN).
1.409 + * This constructor is ASYNCHRONOUS and the actual state of newly
1.410 + * created connection has to be observed from SetStatus() AND
1.411 + * HandleErrorL() functions.
1.412 + * If service is found, a SetStatus call-back with value
1.413 + * KSenConnectionStatusReady (1) is executed.
1.414 + * If some error occurs, HandleErrorL() will be called to inform the
1.415 + * creator of this connection (service consumer application)
1.416 + *
1.417 + * For example, if service is not found, a system wide error
1.418 + * code of -1 is deliver via HandleErrorL() to WSC.
1.419 + *
1.420 + * Second example: server response HTTP 501 means, that this error
1.421 + * code. 501 will be delivered via HandleErrorL() to WSC.
1.422 + * This can happen in ID-WSF connection being initialized, if
1.423 + * either Authentication Service (AS) or Discovery Service (DS)
1.424 + * cannot be reached.
1.425 + *
1.426 + * @param aConsumer (web) service consumer (for call-backs)
1.427 + * @param aContract contract of the service, typically an URI.
1.428 + * @param aAuthProvider Authentication Provider
1.429 + * @return a pointer to a CSenServiceConnection instance.
1.430 + * The pointer is left on the cleanup stack.
1.431 + */
1.432 + IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aConsumer,
1.433 + const TDesC8& aContract,
1.434 + MSenExtendedConsumerInterface& aExtendedConsumer);
1.435 +
1.436 + /**
1.437 + * Two-phased constructor using a service description.
1.438 + * This constructor is ASYNCHRONOUS and the actual state of
1.439 + * created connection has to be observed from SetStatus() and
1.440 + * HandleErrorL() functions.
1.441 + * If service is found, the SetStatus() call-back is executed
1.442 + * with a status value KSenConnectionStatusReady (1)
1.443 + * For ID-WSF connections, the authentication for the Web Service
1.444 + * Provider (WSP) connection is resolved using one of the identity
1.445 + * providers which have been associated with the contract found in
1.446 + * the SD. At minimum, the contract of the service (typically some URN)
1.447 + * has to provided in the SD.
1.448 + * Basic Web Service consumers instantiate a SD where an endpoint
1.449 + * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
1.450 + * @param aConsumer connection observer.
1.451 + * @param aServiceDescription is the description used to
1.452 + * obtain a service connection.
1.453 + * @param aAuthProvider Authentication Provider
1.454 + * @return a pointer to a CSenServiceConnection instance.
1.455 + */
1.456 + IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aConsumer,
1.457 + MSenServiceDescription& aServiceDescription,
1.458 + MSenExtendedConsumerInterface& aExtendedConsumer);
1.459 +
1.460 + /**
1.461 + * Two-phased constructor using a service description. The pointer
1.462 + * is left on the cleanup stack.
1.463 + * This constructor is ASYNCHRONOUS and the actual state of
1.464 + * created connection has to be observed from SetStatus() AND
1.465 + * HandleErrorL() functions.
1.466 + * If service is found, the SetStatus() call-back is executed
1.467 + * with a status value KSenConnectionStatusReady (1)
1.468 + * For ID-WSF connections, the authentication for the Web Service
1.469 + * Provider (WSP) connection is resolved using one of the identity
1.470 + * providers which have been associated with the contract found in
1.471 + * the SD. At minimum, the contract of the service (typically some URN)
1.472 + * has to provided in the SD.
1.473 + * Basic Web Service consumers instantiate a SD where an endpoint
1.474 + * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
1.475 + * @param aConsumer connection observer.
1.476 + * @param aServiceDescription is the description used to
1.477 + * obtain a service connection.
1.478 + * @param aAuthProvider Authentication Provider
1.479 + * @return a pointer to a CSenServiceConnection instance.
1.480 + * The pointer is left on the cleanup stack.
1.481 + */
1.482 + IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aConsumer,
1.483 + MSenServiceDescription& aServiceDescription,
1.484 + MSenExtendedConsumerInterface& aExtendedConsumer);
1.485 +
1.486 + /*
1.487 + * The ServicePattern version of two phased constructor.
1.488 + * Note, that this method is intended to be used by service consumers
1.489 + * wishing to initialize connection in specific context called
1.490 + * consumer policy. In consumer policy, certain properties
1.491 + * can be set to further define what kind of connection is acceptable
1.492 + * and how the connection interacts with transport (for example, which
1.493 + * Internet Access Point (IAP) will be used).
1.494 + * However, any ConsumerPolicy feature is applicable in
1.495 + * one-policy-per-client scope and not used as a common policy.
1.496 + * To set permanent information about known WSP, please use the
1.497 + * CSenXmlServiceDescription, which implements MSenProviderPolicy
1.498 + * interface.
1.499 + * This constructor is ASYNCHRONOUS and the actual state of
1.500 + * created connection has to be observed from SetStatus() and
1.501 + * HandleErrorL() functions.
1.502 + * If service is found, the SetStatus() call-back is executed
1.503 + * with a status value KSenConnectionStatusReady (1)
1.504 + * For ID-WSF connections, the authentication for the Web Service
1.505 + * Provider (WSP) connection is resolved using one of the identity
1.506 + * providers which have been associated with the contract found in
1.507 + * the SD. At minimum, the contract of the service (typically some URN)
1.508 + * has to provided in the SD.
1.509 + * Basic Web Service consumers instantiate a SD where an endpoint
1.510 + * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
1.511 + * @param aConsumer connection observer.
1.512 + * @param aServiceDescription is the description used to
1.513 + * obtain a service connection.
1.514 + * @param aAuthProvider Authentication Provider
1.515 + * @return a pointer to a CSenServiceConnection instance.
1.516 + */
1.517 + IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aConsumer,
1.518 + CSenServicePattern& aServicePattern,
1.519 + MSenExtendedConsumerInterface& aExtendedConsumer);
1.520 +
1.521 + /*
1.522 + * The ServicePattern version of two phased constructor.
1.523 + * Note, that this method is intended to be used by service consumers
1.524 + * wishing to initialize connection in specific context called
1.525 + * consumer policy. In consumer policy, certain properties
1.526 + * can be set to further define what kind of connection is acceptable
1.527 + * and how the connection interacts with transport (for example, which
1.528 + * Internet Access Point (IAP) will be used).
1.529 + * However, any ConsumerPolicy feature is applicable in
1.530 + * one-policy-per-client scope and not used as a common policy.
1.531 + * To set permanent information about known WSP, please use the
1.532 + * CSenXmlServiceDescription, which implements MSenProviderPolicy
1.533 + * interface.
1.534 + * This constructor is ASYNCHRONOUS and the actual state of
1.535 + * created connection has to be observed from SetStatus() and
1.536 + * HandleErrorL() functions.
1.537 + * If service is found, the SetStatus() call-back is executed
1.538 + * with a status value KSenConnectionStatusReady (1)
1.539 + * For ID-WSF connections, the authentication for the Web Service
1.540 + * Provider (WSP) connection is resolved using one of the identity
1.541 + * providers which have been associated with the contract found in
1.542 + * the SD. At minimum, the contract of the service (typically some URN)
1.543 + * has to provided in the SD.
1.544 + * Basic Web Service consumers instantiate a SD where an endpoint
1.545 + * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
1.546 + * @param aConsumer connection observer.
1.547 + * @param aServiceDescription is the description used to
1.548 + * obtain a service connection.
1.549 + * @param aAuthProvider Authentication Provider
1.550 + * @return a pointer to a CSenServiceConnection instance.
1.551 + * The pointer is left on the cleanup stack.
1.552 + */
1.553 + IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aConsumer,
1.554 + CSenServicePattern& aServicePattern,
1.555 + MSenExtendedConsumerInterface& aExtendedConsumer);
1.556 +
1.557 + // New functions
1.558 +
1.559 + /**
1.560 + * Send an ASYNCHRONOUS request to a service.
1.561 + * In ID-WSF, the request data is a SOAP Body.
1.562 + * Response message is received either via
1.563 + * HandleMessageL() or HandleErrorL() callback.
1.564 + * There are two default frameworks available -
1.565 + * the Identity Based Web Service Framework (which ID is "ID-WSF")
1.566 + * and the Basic Web Services Framework (which ID is "WS-I").
1.567 + * Please note, that Basic Web Services framework does NOT support this method.
1.568 + * Instead, one should send complete SOAP envelopes using SendL(CSenSoapEnvelope&).
1.569 + * So, currently this method is supported only in ID-WSF.
1.570 + * @param aRequest outgoing request message.
1.571 + * @return Transaction ID (positive integer) or error code, if method fails.
1.572 + * Transaction ids:
1.573 + * Positive integers SendL returns transaction ID of the request,
1.574 + * which can be later on utilized inside
1.575 + * HandleMessageL and HandleErrorL methods,
1.576 + * in order to map request and its response
1.577 + * together.
1.578 + * Error codes:
1.579 + * KErrSenNotInitialized Connection has not been initialized.
1.580 + * KErrSenServiceConnectionBusy Connection is already busy with another
1.581 + * request.
1.582 + * KErrConnectionInitializing Connection is still initializing and
1.583 + * cannot yet process commands.
1.584 + * KErrConnectionExpired Credential for the connection is
1.585 + * expired and needs to be renewed.
1.586 + * This can be done by instantiating a new
1.587 + * ServiceConnection.
1.588 + * KErrSubmitting An error occurred
1.589 + * KErrNoMemory Not enough memory to process the message.
1.590 + * Other error codes are system-wide Symbian error codes.
1.591 + */
1.592 + virtual TInt SendL(const TDesC8& aRequest) = 0;
1.593 +
1.594 +
1.595 + /**
1.596 + * Submit a synchronous request to a service
1.597 + * (in ID-WSF, the SOAP message Body) and receive a response as XML.
1.598 + * There are two default frameworks available -
1.599 + * the Identity Based Web Service Framework (which ID is "ID-WSF")
1.600 + * and the Basic Web Services Framework (which ID is "WS-I").
1.601 + * Please note, that Basic Web Services framework does NOT support this method.
1.602 + * Instead, one must send complete SOAP envelopes using SubmitL(CSenSoapEnvelope&).
1.603 + * So, currently this method is supported only in ID-WSF.
1.604 + * @param aRequest outgoing request message.
1.605 + * @param aResponse the resolved response message.
1.606 + * The ownership of the aResponse is transfered to the caller.
1.607 + * The response is service specific part of the response.
1.608 + * For ID-WSF services response contents is the SOAP Body, or complete SOAP
1.609 + * envelope as XML, depending on the complete server messages on/off setting
1.610 + * (default is off).
1.611 + * @return status/error code.
1.612 + * Status codes:
1.613 + * KErrNone ok
1.614 + * Error codes:
1.615 + * KErrSenNotInitialized Connection has not been initialized.
1.616 + * KErrSenServiceConnectionBusy Connection is already busy with another request.
1.617 + * KErrConnectionInitializing Connection is still initializing and
1.618 + * cannot yet process commands.
1.619 + * KErrConnectionExpired Credential for the connection is
1.620 + * expired and needs to be renewed.
1.621 + * This can be done by instantiating a new
1.622 + * ServiceConnection.
1.623 + * KErrSubmitting An internal error occurred.
1.624 + * KErrSenInternal Internal state is invalid.
1.625 + * Other error codes are system-wide Symbian error codes.
1.626 + */
1.627 + virtual TInt SubmitL(const TDesC8& aRequest, HBufC8*& aResponse) = 0;
1.628 +
1.629 +
1.630 + /**
1.631 + * Consumer application can use this method to check that
1.632 + * service connection is in ready state.
1.633 + * In ID-WSF, this means that WSF interprets that credentials
1.634 + * for the service connection are valid (not expired).
1.635 + * @param aReady indicates that the connection is ready to be used.
1.636 + * @return status/error code.
1.637 + * Status codes:
1.638 + * KErrNone ok
1.639 + * Error codes are system-wide Symbian error codes.
1.640 + */
1.641 + virtual TInt IsReady(TBool& aReady) = 0;
1.642 +
1.643 +
1.644 + /**
1.645 + * Check if the underlying service connection has a certain characteristic
1.646 + * called a facet.
1.647 + * Currently, only ID-WSF framework supports facets.
1.648 + * For example, if consumer application is interested to resolve if
1.649 + * initialized service connection has a facet indicating that service
1.650 + * is free of charge (for e.g. "urn:framework.com.free:cost"), the
1.651 + * method used to check this would be:
1.652 + * _LIT8(KFacetOfFreeService, "urn:some.service.free:cost");
1.653 + * int err = HasFacetL(KFacetOfFreeService, hasFacet);
1.654 + *
1.655 + * In the service session of initialed connection, this would be the form
1.656 + * of the facet element:
1.657 + * <Facet name="urn:framework.com.free:cost"/>
1.658 + *
1.659 + * If there is no facet in the service connection then the element is not
1.660 + * present.
1.661 + * @param aURI the name of the facet
1.662 + * @param aHasFacet will indicate if underlying service has a certain
1.663 + * characteristic.
1.664 + * @return status/error code.
1.665 + * Status codes:
1.666 + * KErrNone ok
1.667 + * Error codes:
1.668 + * KErrSenNotInitialized Connection has not been initialized.
1.669 + * KErrConnectionInitializing Connection is still initializing and
1.670 + * cannot yet process commands.
1.671 + * KErrConnectionExpired Connection is expired and needs to be
1.672 + * renewed.
1.673 + * KErrBadDescriptor The aUri parameter was an invalid
1.674 + * descriptor.
1.675 + * Other error codes are system-wide Symbian error codes.
1.676 + */
1.677 + virtual TInt HasFacetL(const TDesC8& aURI, TBool& aHasFacet) = 0;
1.678 +
1.679 +
1.680 + /**
1.681 + * Consumer application can use this method to set flag which defines
1.682 + * whether or not the consumer wishes to receive complete SOAP envelope
1.683 + * from the service.
1.684 + * If complete server messages mode is off, then only the <Body> element
1.685 + * is received from the SOAP envelope, otherwise full SOAP envelope.
1.686 + * Note: Calling this function must not be done before connection is
1.687 + * initialized (the observer's SetStatus() has been called with value
1.688 + * KSenConnectionStatusReady).
1.689 + * Calling this function should be done before sending or submitting
1.690 + * anything.
1.691 + * @param aCompleteOnOff defines the content of HandleMessageL() callback.
1.692 + * If set to ETrue (ON), then complete SOAP envelopes are
1.693 + * received, including <Header> element.
1.694 + * If set to EFalse (OFF), only the service specific
1.695 + * content - SOAP envelope <Body> element - is received.
1.696 + * In WSF frameworks the default settings are:
1.697 + * 1. In ID-WSF, the complete server messages is OFF.
1.698 + * 2. In Basic Web Services, the default is ON.
1.699 + * @return status/error code.
1.700 + * Status codes:
1.701 + * KErrNone ok
1.702 + * Error codes:
1.703 + * KErrSenNotInitialized Connection has not been initialized.
1.704 + * KErrConnectionInitializing Connection is still initializing and
1.705 + * cannot yet process commands.
1.706 + * KErrConnectionExpired Connection is expired and needs to be
1.707 + * renewed.
1.708 + * Other error codes are system-wide Symbian error codes.
1.709 + */
1.710 + virtual TInt CompleteServerMessagesOnOff(const TBool& aCompleteOnOff) = 0;
1.711 +
1.712 +
1.713 + /*
1.714 + * Sends a SOAP message to the service. The SOAP envelope may contain
1.715 + * proprietary headers. The system will augment the message with the
1.716 + * appropriate headers specified in the service invocation framework,
1.717 + * so a client application should add only non-standard headers; and
1.718 + * if it doesn't need to set such headers it is strongly recommended
1.719 + * to use SendL(TDesC8&), which is meant for that.
1.720 + * This is an asynchronous function, that returns immediately.
1.721 + * When the service responds, the SOAP envelope content will
1.722 + * be received via HandleMessageL() callback. In case of an
1.723 + * error - like a SOAP fault - HandleErrorL() will be called
1.724 + * with appropriate error code.
1.725 + * There are two default frameworks available -
1.726 + * the Identity Based Web Service Framework (which ID is "ID-WSF")
1.727 + * and the Basic Web Services Framework (which ID is "WS-I").
1.728 + * Please note, that ID-WSF does NOT support this method.
1.729 + * Instead, one should send SOAP envelope Bodies using
1.730 + * SendL(const TDesC8&).
1.731 + * So, currently this method is supported only in Basic Web Services framework.
1.732 + * @param aMessage The service specific message - a full SOAP envelope
1.733 + * @return Transaction ID (positive integer) or error code, if method fails.
1.734 + * Transaction ids:
1.735 + * Positive integers SendL returns transaction ID of the request,
1.736 + * which can be later on utilized inside
1.737 + * HandleMessageL and HandleErrorL methods,
1.738 + * in order to map request and its response
1.739 + * together.
1.740 + * Error codes:
1.741 + * KErrSenNotInitialized Connection has not been initialized.
1.742 + * KErrSenServiceConnectionBusy Connection is already busy with another
1.743 + * request.
1.744 + * KErrConnectionInitializing Connection is still initializing and
1.745 + * cannot yet process commands.
1.746 + * KErrConnectionExpired Connection is expired and needs to be
1.747 + * renewed.
1.748 + * KErrSubmitting An internal error has occurred.
1.749 + * KErrNoMemory Not enough memory to process the
1.750 + * message.
1.751 + * Other error codes are system-wide Symbian error codes.
1.752 + */
1.753 + virtual TInt SendL(CSenSoapEnvelope& aMessage) = 0;
1.754 +
1.755 +
1.756 + /*
1.757 + * Submits a SOAP message to the service. This is a synchronous call,
1.758 + * returning a SOAP envelope that was received from the service.
1.759 + * There are two default frameworks available:
1.760 + * the Identity Based Web Service Framework (which ID is "ID-WSF")
1.761 + * and the Basic Web Services Framework (which ID is "WS-I").
1.762 + * Please note, that ID-WSF does NOT support this method.
1.763 + * Instead, one should send SOAP envelope Bodies using SendL(const TDesC8&).
1.764 + * So, currently this method is supported only in Basic Web Services framework.
1.765 + * @param aMessage SOAPEnvelope with the service specific message
1.766 + * without any framework wrapping
1.767 + * @param aResponseTo This is a ref-to-pointer where response
1.768 + * from the service will be allocated. If the
1.769 + * complete server messages mode is set to OFF,
1.770 + * then only <Body> element will be returned,
1.771 + * otherwise a complete SOAP envelope.
1.772 + * The ownership of aResponse is transfered to
1.773 + * the caller.
1.774 + * @return status/error code
1.775 + * Status codes:
1.776 + * KErrNone ok
1.777 + * Error codes:
1.778 + * KErrSenNotInitialized Connection has not been initialized.
1.779 + * KErrSenServiceConnectionBusy Connection is already busy with another
1.780 + * request.
1.781 + * KErrConnectionInitializing Connection is still initializing and
1.782 + * cannot yet process commands.
1.783 + * KErrConnectionExpired Connection is expired and needs to be
1.784 + * renewed.
1.785 + * KErrSubmitting An internal error has occurred.
1.786 + * KErrNoMemory Not enough memory to process the
1.787 + * message.
1.788 + * KErrSenInternal Internal state is invalid.
1.789 + * Other error codes are system-wide Symbian error codes.
1.790 + */
1.791 + virtual TInt SubmitL(CSenSoapEnvelope& aMessage, HBufC8*& aResponseTo) = 0;
1.792 +
1.793 +
1.794 + /**
1.795 + * Gets service description of current connection.
1.796 + * @param aServiceDescription Contains the service description on return
1.797 + * @return status/error code.
1.798 + * Status codes:
1.799 + * KErrNone ok
1.800 + * Error codes:
1.801 + * KErrSenNotInitialized Connection has not been initialized.
1.802 + * KErrSenServiceConnectionBusy Connection is already busy with another
1.803 + * request.
1.804 + * KErrConnectionInitializing Connection is still initializing and
1.805 + * cannot yet process commands.
1.806 + * KErrConnectionExpired Connection is expired and needs to be
1.807 + * renewed.
1.808 + * KErrUnderFlow Server side returned invalid service
1.809 + * description.
1.810 + * KErrUnknown Client-Server request mismatch.
1.811 + * Other error codes are system-wide Symbian error codes.
1.812 + */
1.813 + virtual TInt ServiceDescriptionL(HBufC8*& aServiceDescription) = 0;
1.814 +
1.815 +
1.816 + /**
1.817 + * Starts an application level transaction. The consumer may now start
1.818 + * to communicate with some service withing a chain of correlated messages.
1.819 + * When responding to a certain SOAP message inside a transaction, the last
1.820 + * received message ID is used as "refToMessageId".
1.821 + * From default frameworks, only ID-WSF supports transactions.
1.822 + * @return KErrNone if no errors occur.
1.823 + * Other error codes are system-wide Symbian error codes.
1.824 + */
1.825 + virtual TInt StartTransaction() = 0;
1.826 +
1.827 +
1.828 + /**
1.829 + * Stops application level transaction by resetting the "refToMessageId".
1.830 + * After stopping a transaction the next message will have no
1.831 + * "refToMessageId"
1.832 + * @return KErrNone if no errors occur.
1.833 + * Other error codes are system-wide Symbian error codes.
1.834 + */
1.835 + virtual TInt TransactionCompleted() = 0;
1.836 +
1.837 +
1.838 + /*
1.839 + * Returns the transasction ID of this message or error. Id is guaranteed
1.840 + * to return unique ID when called from inside HandleMessageL() or
1.841 + * HandleErrorL callback. This transasction ID may be used to map the
1.842 + * response with the preceedeing SendL() call (a request).
1.843 + * @return TInt transaction ID, or KErrNotFound, if no transaction is
1.844 + * on-going.
1.845 + */
1.846 + virtual TInt TxnId() = 0;
1.847 +
1.848 +
1.849 + /**
1.850 + * Sets transport specific properties which apply as long as this connection
1.851 + * is alive (session). Furthermore, the properties are effective for this session
1.852 + * in cumulative manner: each property has unique key (name) which is associated
1.853 + * to the actual value of that property. When SetTransportPropertiesL method is
1.854 + * called multiple times - in sequence - the last value for each key overrides any
1.855 + * previous definitions. If any latter call introduces new keys (property names),
1.856 + * they are appended to the list of currently effective properties.
1.857 + * Also note, that it is also possible to set message specific properties when making
1.858 + * a SendL/SubmitL call. If such transport properties for message are provided, and
1.859 + * those include updates to some properties, the new ones are effective only for that
1.860 + * certain message, i.e. those are transaction specific. For any following message,
1.861 + * that is sent over a service connection, the session specific properties apply,
1.862 + * assuming that the new message does not (again) override some of the property values.
1.863 + * @param aProperties contains the transport properties in serialized (UTF-8) form.
1.864 + * With HTTP, this descriptor is typically created by utilizing CSenHttpProperties class.
1.865 + * @return KErrNone if successful or otherwise some system-wide error code.
1.866 + */
1.867 + virtual TInt SetTransportPropertiesL(const TDesC8& aProperties) = 0;
1.868 +
1.869 +
1.870 + /*
1.871 + * Method returns currently effective transport properties as a serialized
1.872 + * descriptor. With HTTP, one may utilize CSenHttpProperities class in
1.873 + * order to read this data into properties object. Note that returned
1.874 + * list of properties also includes properties, which are defined as default
1.875 + * for certain transport in the webservice framework.
1.876 + */
1.877 + virtual TInt TransportPropertiesL(HBufC8*& aProperties) = 0;
1.878 +
1.879 +
1.880 + /**
1.881 + * Send an ASYNCHRONOUS request to a service.
1.882 + * In ID-WSF, the request data is a SOAP Body.
1.883 + * Response message is received either via
1.884 + * HandleMessageL() or HandleErrorL() callback.
1.885 + * There are two default frameworks available -
1.886 + * the Identity Based Web Service Framework (which ID is "ID-WSF")
1.887 + * and the Basic Web Services Framework (which ID is "WS-I").
1.888 + * Please note, that Basic Web Services framework does NOT support this method.
1.889 + * Instead, one should send complete SOAP envelopes using SendL(CSenSoapEnvelope&).
1.890 + * So, currently this method is supported only in ID-WSF.
1.891 + * @param aRequest outgoing request message.
1.892 + * @param aProperties contains transport spesific properties, serialized
1.893 + * into descriptor. With HTTP, one can create this by utilizing specialized
1.894 + * CSenHttpProperties class.
1.895 + * @return Transaction ID (positive integer) or error code, if method fails.
1.896 + * Transaction ids:
1.897 + * Positive integers SendL returns transaction ID of the request,
1.898 + * which can be later on utilized inside
1.899 + * HandleMessageL and HandleErrorL methods,
1.900 + * in order to map request and its response
1.901 + * together.
1.902 + * Error codes
1.903 + * KErrSenNotInitialized Connection has not been initialized.
1.904 + * KErrSenServiceConnectionBusy Connection is already busy with another
1.905 + * request.
1.906 + * KErrConnectionInitializing Connection is still initializing and
1.907 + * cannot yet process commands.
1.908 + * KErrConnectionExpired Credential for the connection is
1.909 + * expired and needs to be renewed.
1.910 + * This can be done by instantiating a new
1.911 + * ServiceConnection.
1.912 + * KErrSubmitting An error occurred
1.913 + * KErrNoMemory Not enough memory to process the message.
1.914 + * Other error codes are system-wide Symbian error codes.
1.915 + */
1.916 + virtual TInt SendL(const TDesC8& aRequest, const TDesC8& aProperties) = 0;
1.917 +
1.918 +
1.919 + /**
1.920 + * Submit a request via SYNCHRONOUS call to a service
1.921 + * (in ID-WSF, the SOAP message Body) and receive a response as XML.
1.922 + * There are two default frameworks available -
1.923 + * the Identity Based Web Service Framework (which ID is "ID-WSF")
1.924 + * and the Basic Web Services Framework (which ID is "WS-I").
1.925 + * Please note, that Basic Web Services framework does NOT support this method.
1.926 + * Instead, one must send complete SOAP envelopes using SubmitL(CSenSoapEnvelope&).
1.927 + * So, currently this method is supported only in ID-WSF.
1.928 + * @param aRequest outgoing request message.
1.929 + * @param aResponse the resolved response message.
1.930 + * The ownership of the aResponse is transfered to the caller.
1.931 + * The response is service specific part of the response.
1.932 + * For ID-WSF services response contents is the SOAP Body, or complete SOAP
1.933 + * envelope as XML, depending on the complete server messages on/off setting
1.934 + * (default is off).
1.935 + * @param aProperties contains transport spesific properties, serialized
1.936 + * into descriptor. With HTTP, one can create this by utilizing specialized
1.937 + * CSenHttpProperties class.
1.938 + * @return status/error code.
1.939 + * Status codes:
1.940 + * KErrNone ok
1.941 + * Error codes:
1.942 + * KErrSenNotInitialized Connection has not been initialized.
1.943 + * KErrSenServiceConnectionBusy Connection is already busy with another request.
1.944 + * KErrConnectionInitializing Connection is still initializing and
1.945 + * cannot yet process commands.
1.946 + * KErrConnectionExpired Credential for the connection is
1.947 + * expired and needs to be renewed.
1.948 + * This can be done by instantiating a new
1.949 + * ServiceConnection.
1.950 + * KErrSubmitting An internal error occurred.
1.951 + * KErrSenInternal Internal state is invalid.
1.952 + * Other error codes are system-wide Symbian error codes.
1.953 + */
1.954 + virtual TInt SubmitL(const TDesC8& aRequest, const TDesC8& aProperties, HBufC8*& aResponse) = 0;
1.955 +
1.956 +
1.957 + /*
1.958 + * Sends a SOAP message to the service. The SOAP envelope may contain
1.959 + * proprietary headers. The system will augment the message with the
1.960 + * appropriate headers specified in the service invocation framework,
1.961 + * so a client application should add only non-standard headers; and
1.962 + * if it doesn't need to set such headers it is strongly recommended
1.963 + * to use SendL(TDesC8&), which is meant for this.
1.964 + * This is an asynchronous function, that returns immediately.
1.965 + * When the service responds, the SOAP envelope content will
1.966 + * be received via HandleMessageL() callback. In case of an
1.967 + * error - like a SOAP fault - HandleErrorL() will be called
1.968 + * with appropriate error code.
1.969 + * There are two default frameworks available -
1.970 + * the Identity Based Web Service Framework (which ID is "ID-WSF")
1.971 + * and the Basic Web Services Framework (which ID is "WS-I").
1.972 + * Please note, that ID-WSF does NOT support this method.
1.973 + * Instead, one should send SOAP envelope Bodies using
1.974 + * SendL(const TDesC8&).
1.975 + * So, currently this method is supported only in Basic Web Services framework.
1.976 + *
1.977 + * NOTE:
1.978 + * Message is send as serialized XML or Soap message to SendL
1.979 + * aProperties could be "HTTP GET" or "HTTP DELETE"
1.980 + * HTTP GET or HTTP DELETE transport property has been enabled via CSenHttpTransportProperties.
1.981 + * This scenario is not supported
1.982 + *
1.983 + * @param aMessage The service specific message - a full SOAP envelope
1.984 + * @param aProperties contains transport spesific properties, serialized
1.985 + * into descriptor. With HTTP, one can create this by utilizing specialized
1.986 + * CSenHttpProperties class.
1.987 + * @return Transaction ID (positive integer) or error code, if method fails.
1.988 + * Transaction ids:
1.989 + * Positive integers SendL returns transaction ID of the request,
1.990 + * which can be later on utilized inside
1.991 + * HandleMessageL and HandleErrorL methods,
1.992 + * in order to map request and its response
1.993 + * together.
1.994 + * Error codes:
1.995 + * KErrSenNotInitialized Connection has not been initialized.
1.996 + * KErrSenServiceConnectionBusy Connection is already busy with another
1.997 + * request.
1.998 + * KErrConnectionInitializing Connection is still initializing and
1.999 + * cannot yet process commands.
1.1000 + * KErrConnectionExpired Connection is expired and needs to be
1.1001 + * renewed.
1.1002 + * KErrSubmitting An internal error has occurred.
1.1003 + * KErrNoMemory Not enough memory to process the
1.1004 + * message.
1.1005 + * KErrNotSupported HTTP GET or HTTP DELETE is enabled
1.1006 + * Other error codes are system-wide Symbian error codes.
1.1007 + */
1.1008 + virtual TInt SendL(CSenSoapEnvelope& aMessage, const TDesC8& aProperties) = 0;
1.1009 +
1.1010 + /*
1.1011 + * Submits a SOAP message to the service. This is a synchronous call,
1.1012 + * returning a SOAP envelope that was received from the service.
1.1013 + * There are two default frameworks available:
1.1014 + * the Identity Based Web Service Framework (which ID is "ID-WSF")
1.1015 + * and the Basic Web Services Framework (which ID is "WS-I").
1.1016 + * Please note, that ID-WSF does NOT support this method.
1.1017 + * Instead, one should send SOAP envelope Bodies using SendL(const TDesC8&).
1.1018 + * So, currently this method is supported only in Basic Web Services framework.
1.1019 + *
1.1020 + * NOTE:
1.1021 + * Message is send as serialized XML or Soap message to SubmitL
1.1022 + * aProperties could be "HTTP GET" or "HTTP DELETE"
1.1023 + * HTTP GET or HTTP DELETE transport property has been enabled via CSenHttpTransportProperties.
1.1024 + * This scenario is not supported
1.1025 + *
1.1026 + * @param aMessage SOAPEnvelope with the service specific message
1.1027 + * without any framework wrapping
1.1028 + * @param aProperties contains transport spesific properties, serialized
1.1029 + * into descriptor. With HTTP, one can create this by utilizing specialized
1.1030 + * CSenHttpProperties class.
1.1031 + * @param aResponseTo This is a ref-to-pointer where response
1.1032 + * from the service will be allocated. If the
1.1033 + * complete server messages mode is set to OFF,
1.1034 + * then only <Body> element will be returned,
1.1035 + * otherwise a complete SOAP envelope.
1.1036 + * The ownership of aResponse is transfered to
1.1037 + * the caller.
1.1038 + * @return status/error code
1.1039 + * Status codes:
1.1040 + * KErrNone ok
1.1041 + * Error codes:
1.1042 + * KErrSenNotInitialized Connection has not been initialized.
1.1043 + * KErrSenServiceConnectionBusy Connection is already busy with another
1.1044 + * request.
1.1045 + * KErrConnectionInitializing Connection is still initializing and
1.1046 + * cannot yet process commands.
1.1047 + * KErrConnectionExpired Connection is expired and needs to be
1.1048 + * renewed.
1.1049 + * KErrSubmitting An internal error has occurred.
1.1050 + * KErrNoMemory Not enough memory to process the
1.1051 + * message.
1.1052 + * KErrSenInternal Internal state is invalid.
1.1053 + * KErrNotSupported HTTP GET or HTTP DELETE is enabled
1.1054 + * Other error codes are system-wide Symbian error codes.
1.1055 + */
1.1056 + virtual TInt SubmitL(CSenSoapEnvelope& aMessage, const TDesC8& aProperties, HBufC8*& aResponseTo) = 0;
1.1057 +
1.1058 + /*
1.1059 + * Sends a SOAP message to the service. The SOAP envelope may contain
1.1060 + * proprietary headers. The system will augment the message with the
1.1061 + * appropriate headers specified in the service invocation framework,
1.1062 + * so a client application should add only non-standard headers.
1.1063 + * This is an asynchronous function, that returns immediately.
1.1064 + * When the service responds, the SOAP envelope content will
1.1065 + * be received via HandleMessageL() callback. In case of an
1.1066 + * error - like a SOAP fault - HandleErrorL() will be called
1.1067 + * with appropriate error code.
1.1068 + * There are two default frameworks available -
1.1069 + * the Identity Based Web Service Framework (which ID is "ID-WSF")
1.1070 + * and the Basic Web Services Framework (which ID is "WS-I").
1.1071 + * Please note, that ID-WSF does NOT support this method.
1.1072 + * Instead, one should send SOAP envelope Bodies using
1.1073 + * SendL(const TDesC8&).
1.1074 + * So, currently this method is supported only in Basic Web Services framework.
1.1075 + *
1.1076 + * @param aMessage The service specific message - a full SOAP envelope
1.1077 + * @return Transaction ID (positive integer) or error code, if method fails.
1.1078 + * Transaction ids:
1.1079 + * Positive integers SendL returns transaction ID of the request,
1.1080 + * which can be later on utilized inside
1.1081 + * HandleMessageL and HandleErrorL methods,
1.1082 + * in order to map request and its response
1.1083 + * together.
1.1084 + * Error codes:
1.1085 + * KErrSenNotInitialized Connection has not been initialized.
1.1086 + * KErrSenServiceConnectionBusy Connection is already busy with another
1.1087 + * request.
1.1088 + * KErrConnectionInitializing Connection is still initializing and
1.1089 + * cannot yet process commands.
1.1090 + * KErrConnectionExpired Connection is expired and needs to be
1.1091 + * renewed.
1.1092 + * KErrSubmitting An internal error has occurred.
1.1093 + * KErrNoMemory Not enough memory to process the
1.1094 + * message.
1.1095 + * KErrNotSupported HTTP GET or HTTP DELETE is enabled
1.1096 + * Other error codes are system-wide Symbian error codes.
1.1097 + */
1.1098 + virtual TInt SendL(MSenMessage& aMessage) = 0;
1.1099 +
1.1100 + /*
1.1101 + * Submits a SOAP message to the service. This is a synchronous call,
1.1102 + * returning a SOAP envelope that was received from the service.
1.1103 + * There are two default frameworks available:
1.1104 + * the Identity Based Web Service Framework (which ID is "ID-WSF")
1.1105 + * and the Basic Web Services Framework (which ID is "WS-I").
1.1106 + * Please note, that ID-WSF does NOT support this method.
1.1107 + * Instead, one should send SOAP envelope Bodies using SendL(const TDesC8&).
1.1108 + * So, currently this method is supported only in Basic Web Services framework.
1.1109 + *
1.1110 + * @param aMessage SOAPEnvelope with the service specific message
1.1111 + * without any framework wrapping
1.1112 + * @param aResponseTo This is a ref-to-pointer where response
1.1113 + * from the service will be allocated. If the
1.1114 + * complete server messages mode is set to OFF,
1.1115 + * then only <Body> element will be returned,
1.1116 + * otherwise a complete SOAP envelope.
1.1117 + * The ownership of aResponse is transfered to
1.1118 + * the caller.
1.1119 + * @return status/error code
1.1120 + * Status codes:
1.1121 + * KErrNone ok
1.1122 + * Error codes:
1.1123 + * KErrSenNotInitialized Connection has not been initialized.
1.1124 + * KErrSenServiceConnectionBusy Connection is already busy with another
1.1125 + * request.
1.1126 + * KErrConnectionInitializing Connection is still initializing and
1.1127 + * cannot yet process commands.
1.1128 + * KErrConnectionExpired Connection is expired and needs to be
1.1129 + * renewed.
1.1130 + * KErrSubmitting An internal error has occurred.
1.1131 + * KErrNoMemory Not enough memory to process the
1.1132 + * message.
1.1133 + * KErrSenInternal Internal state is invalid.
1.1134 + * KErrNotSupported HTTP GET or HTTP DELETE is enabled
1.1135 + * Other error codes are system-wide Symbian error codes.
1.1136 + */
1.1137 + virtual TInt SubmitL(MSenMessage& aMessage, CSenSoapEnvelope2*& aResponseTo) = 0;
1.1138 +
1.1139 + /**
1.1140 + * Getter for currently active transaction (service response) that is
1.1141 + * being handled by the service consumer.
1.1142 + * @return a pointer to currently active transaction (service response).
1.1143 + * It is guarenteed, that the method returns a pointer to
1.1144 + * transaction only when called inside HandleMessageL or
1.1145 + * HandleErrorL callback methods of MSenServiceConsumer,
1.1146 + * otherwise it will return NULL.
1.1147 + */
1.1148 + virtual MSenMessage* Response() = 0;
1.1149 +
1.1150 + /**
1.1151 + * Cancels any active request, if pending transaction
1.1152 + * (txn) can be found with given txn ID.
1.1153 + * @param aTransactionID is the transaction ID to be cancelled. This id has earlier been
1.1154 + * acquired from a call to some of the asynchronous SendL variants.
1.1155 +
1.1156 + * @return KErrNone on success
1.1157 + * KErrNotFound, if there is no pending transaction (active request),
1.1158 + * or some of the system-wide error codes otheriwise.
1.1159 + */
1.1160 + virtual TInt CancelTransaction(TInt aTransactionID) = 0;
1.1161 +
1.1162 + /**
1.1163 + * Getter for the identity provider (XML) service description.
1.1164 + * @param apIdentityProvider will point to a new IDP instance,
1.1165 + * if such is associated with this connection (and this connection
1.1166 + * was ready before calling this method), or NULL otherwise.
1.1167 + * @return KErrNone if IDP description can be found, or some
1.1168 + * of the system wide error code otherwise.
1.1169 + */
1.1170 + virtual TInt IdentityProviderL(CSenIdentityProvider*& apIdentityProvider) = 0;
1.1171 +
1.1172 + /**
1.1173 + * Getter for the identifier of this connection.
1.1174 + * @return the identifier as integer.
1.1175 + */
1.1176 + virtual TInt Identifier() = 0;
1.1177 +
1.1178 + /**
1.1179 + * Registers observer of BLOBs transfer progress.
1.1180 + *
1.1181 + * @param aFilesObserver Implementation of transfer progress observer.
1.1182 + */
1.1183 +
1.1184 + protected:
1.1185 +
1.1186 + /**
1.1187 + * C++ default constructor.
1.1188 + */
1.1189 + CSenServiceConnection();
1.1190 +
1.1191 + };
1.1192 +
1.1193 +#endif //SEN_SERVICE_CONNECTION_H
1.1194 +
1.1195 +// End of File
1.1196 +