2 * Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies).
4 * This component and the accompanying materials are made available
5 * 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
6 * which accompanies this distribution, and is available
7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: CSenServiceConnection offers public API for
15 * service consumers to access invocable services,
16 * as a part of the Web Services Framework (WSF).
28 #ifndef SEN_SERVICE_CONNECTION_H
29 #define SEN_SERVICE_CONNECTION_H
32 #include <e32base.h> // for CActive
33 #include <MSenServiceConsumer.h>
34 #include <MSenServiceDescription.h>
36 #include <MSenAuthenticationProvider.h>
38 #include <SenSoapMessage.h>
39 #include <SenSoapMessage2.h>
40 //#include <SenAtomEntry.h>
43 #include <MSenMessage.h>
46 const TInt KErrSenNotInitialized = -30291;
47 const TInt KErrSenServiceConnectionBusy = -30292;
48 const TInt KErrConnectionInitializing = -30293;
49 const TInt KErrConnectionExpired = -30294;
50 const TInt KErrSubmitting = -30295;
51 const TInt KErrSenSoapFault = -30296;
52 const TInt KErrSenInternal = -30297;
53 const TInt KErrSenNoEndpoint = -30298;
54 const TInt KErrSenNoContract = -30299;
56 const TInt KErrSenProviderIdInUseByAnotherEndpoint = -30305;
57 const TInt KErrSenNoContractNoEndPoint = -30306;
59 const TInt KErrSenBrokenSoapEnvelope = -30307;
60 const TInt KErrSenBrokenSoapFault = -30308;
61 const TInt KErrSenCancelled = -30309;
64 // HTTP transport error codes:
65 const TInt KErrSenNoHttpResponseBody = -30310;
66 const TInt KErrSenNoHttpContentType = -30311;
67 const TInt KErrSenHttpRedirectRequiresConfirmation = -30312;
69 // SOAP message verification error codes:
70 const TInt KErrSenNoSoapBody = -30313;
71 const TInt KErrSenNoSoapHeader = -30314;
72 const TInt KErrSenNoPermission = -30315;
74 const TInt KErrSenHostNotAvailable = -30318;
76 const TInt KErrSenAuthenticationFault = -30319;
77 const TInt KErrSenNoEndUserPermission = -30321;
80 const TInt KSenConnectionStatusCreateFailed = -1; // post-state
81 const TInt KSenConnectionStatusNew = 0; // post-state
82 const TInt KSenConnectionStatusReady = 1; // post-state
83 const TInt KSenConnectionStatusExpired = 2; // post-state
84 const TInt KSenConnectionStatusAuthentication = 3; // pre-state
85 const TInt KSenConnectionStatusDiscovery = 4; // pre-state
86 const TInt KSenConnectionStatusMetadataExchange = 5; // pre-state
88 _LIT8(KDefaultBasicWebServicesFrameworkID, "WS-I");
89 _LIT8(KDefaultIdWsfFrameworkID, "ID-WSF");
90 _LIT8(KDefaultRestServicesFrameworkID, "REST");
91 _LIT8(KDefaultWSStarFrameworkID, "WS-STAR");
92 _LIT8(KDefaultAtomPubFrameworkID, "ATOM-PUB");
93 _LIT8(KDefaultOviFrameworkID, "OVI");
95 const TInt KSenTransportStatusCodeOffsetBaseHttp = 1000;
96 const TInt KSenTransportStatusCodeOffsetBaseVtcp = 2000;
98 const TInt KSenTransportStatusCodeVtcpInit = 2001; // KSenTransportStatusCodeOffsetBaseVtcp +1
99 const TInt KSenTransportStatusCodeVtcpActive = 2002; // KSenTransportStatusCodeOffsetBaseVtcp +2
100 const TInt KSenTransportStatusCodeVtcpSuspended = 2003; // KSenTransportStatusCodeOffsetBaseVtcp +3
101 const TInt KSenTransportStatusCodeVtcpInactive = 2004; // KSenTransportStatusCodeOffsetBaseVtcp +4
102 const TInt KSenTransportStatusCodeVtcpUnavailable = 2005; // KSenTransportStatusCodeOffsetBaseVtcp +5
104 // FORWARD DECLARATIONS
105 class CSenServicePattern;
106 class CSenIdentityProvider;
111 * The class for connecting to service providers
112 * through Web Services Framework (WSF).
114 * The class offers asynchronous construction of a
115 * service connection. Further, there are asynchronous
116 * and synchronous interaction methods for e.g. sending
117 * and receiving data from (possibly remote) service.
119 * WSF offers two default frameworks:
121 * 1. Identity Based Web Services Framework
122 * (ID-WSF). The framework ID for this is
123 * KDefaultIdWsfFrameworkID ("ID-WSF").
125 * 2. Basic Web Services Framework. Framework
126 * ID is KDefaultBasicWebServicesFrameworkID
129 * The most typical use of CSenServiceConnection
130 * is to interact with a service of certain type
131 * through some invocable framework and submitting
132 * and receiving messages.
134 * In case of WebServices, the actual service is remote
135 * and submitted messages are SOAP envelopes. However,
136 * CSenServiceConnection supports accessing any
137 * ServiceInvocationFramework which ECOM plug-in
138 * implementation is present. These plug-ins may
139 * further communicate with some service, including
142 * The link between CSenServiceConnection and any plug-in
143 * implementation interacting with some service is the
144 * framework ID, which is a property of ServiceDescription (SD)
145 * and accessible via MSenServiceDescription interface, which
146 * each SD class must implement.
148 * When creating a connection, one offers predefined SD as
149 * an argument for asynchronous constructor. Or, optionally
150 * only a Liberty Alliance ID-WSF specific contract string
151 * - typically some URN. If only contract is offered, then
152 * the created connection defaults to ID-WSF service and
153 * ID-WSF framework (ID) will be used.
155 * The WSF further uses the offered framework ID while looking
156 * up any matching framework plug-in implementation. As a
157 * result the SD might be offered to several plug-ins.
159 * @lib SenServConn.lib
160 * @since Series60 3.0
163 class CSenServiceConnection : public CActive, public MSenFragment
165 public: // Constructors and destructor
168 * Two-phased constructor intended for Identity based service
169 * consumers (like ID-WSF). The pointer is left on the cleanup stack.
170 * This constructor is ASYNCHRONOUS and the actual state of
171 * created connection has to be observed from SetStatus() AND
172 * HandleErrorL() functions.
173 * If service is found, the SetStatus() call-back is performed
174 * with a status value KSenConnectionStatusReady (1).
175 * Contract of the service (typically some URN) is provided.
176 * Authentication for the Web Service Provider (WSP) connection
177 * is resolved using one of the identity providers which have
178 * been associated with this contract (typically an URN).
180 * This constructor is ASYNCHRONOUS and the actual state of newly
181 * created connection has to be observed from SetStatus() AND
182 * HandleErrorL() functions.
183 * If service is found, a SetStatus call-back with value
184 * KSenConnectionStatusReady (1) is executed.
185 * If some error occurs, HandleErrorL() will be called to inform the
186 * creator of this connection (service consumer application)
188 * For example, if service is not found, a system wide error
189 * code of -1 is deliver via HandleErrorL() to WSC.
191 * Second example: server response HTTP 501 means, that this error
192 * code. 501 will be delivered via HandleErrorL() to WSC.
193 * This can happen in ID-WSF connection being initialized, if
194 * either Authentication Service (AS) or Discovery Service (DS)
197 * @param aConsumer (web) service consumer (for call-backs)
198 * @param aContract contract of the service, typically an URI.
199 * @return a pointer to a CSenServiceConnection instance.
202 IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aConsumer,
203 const TDesC8& aContract);
206 * Two-phased constructor intended for Identity based service
207 * consumers (like ID-WSF).
208 * This constructor is ASYNCHRONOUS and the actual state of
209 * created connection has to be observed from SetStatus() and
210 * HandleErrorL() functions.
211 * If service is found, the SetStatus() call-back is performed
212 * with a status value KSenConnectionStatusReady (1).
213 * Contract of the service (typically some URN) is provided.
214 * Authentication for the Web Service Provider (WSP) connection
215 * is resolved using one of the identity providers which have
216 * been associated with this contract (typically an URN).
217 * This constructor is ASYNCHRONOUS and the actual state of newly
218 * created connection has to be observed from SetStatus() AND
219 * HandleErrorL() functions.
220 * If service is found, a SetStatus call-back with value
221 * KSenConnectionStatusReady (1) is executed.
222 * If some error occurs, HandleErrorL() will be called to inform the
223 * creator of this connection (service consumer application)
225 * For example, if service is not found, a system wide error
226 * code of -1 is deliver via HandleErrorL() to WSC.
228 * Second example: server response HTTP 501 means, that this error
229 * code. 501 will be delivered via HandleErrorL() to WSC.
230 * This can happen in ID-WSF connection being initialized, if
231 * either Authentication Service (AS) or Discovery Service (DS)
234 * @param aConsumer (web) service consumer (for call-backs)
235 * @param aContract contract of the service, typically an URI.
236 * @return a pointer to a CSenServiceConnection instance.
237 * The pointer is left on the cleanup stack.
239 IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aObserver,
240 const TDesC8& aContract);
243 * Two-phased constructor using a service description.
244 * This constructor is ASYNCHRONOUS and the actual state of
245 * created connection has to be observed from SetStatus() and
246 * HandleErrorL() functions.
247 * If service is found, the SetStatus() call-back is executed
248 * with a status value KSenConnectionStatusReady (1)
249 * For ID-WSF connections, the authentication for the Web Service
250 * Provider (WSP) connection is resolved using one of the identity
251 * providers which have been associated with the contract found in
252 * the SD. At minimum, the contract of the service (typically some URN)
253 * has to provided in the SD.
254 * Basic Web Service consumers instantiate a SD where an endpoint
255 * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
256 * @param aObserver connection observer.
257 * @param aServiceDescription is the description used to
258 * obtain a service connection.
259 * @return a pointer to a CSenServiceConnection instance.
261 IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aObserver,
262 MSenServiceDescription& aServiceDescription);
265 * Two-phased constructor using a service description. The pointer
266 * is left on the cleanup stack.
267 * This constructor is ASYNCHRONOUS and the actual state of
268 * created connection has to be observed from SetStatus() AND
269 * HandleErrorL() functions.
270 * If service is found, the SetStatus() call-back is executed
271 * with a status value KSenConnectionStatusReady (1)
272 * For ID-WSF connections, the authentication for the Web Service
273 * Provider (WSP) connection is resolved using one of the identity
274 * providers which have been associated with the contract found in
275 * the SD. At minimum, the contract of the service (typically some URN)
276 * has to provided in the SD.
277 * Basic Web Service consumers instantiate a SD where an endpoint
278 * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
279 * @param aObserver connection observer.
280 * @param aServiceDescription is the description used to
281 * obtain a service connection.
282 * @return a pointer to a CSenServiceConnection instance.
283 * The pointer is left on the cleanup stack.
285 IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aObserver,
286 MSenServiceDescription& aServiceDescription);
289 * The ServicePattern version of two phased constructor.
290 * Note, that this method is intended to be used by service consumers
291 * wishing to initialize connection in specific context called
292 * consumer policy. In consumer policy, certain properties
293 * can be set to further define what kind of connection is acceptable
294 * and how the connection interacts with transport (for example, which
295 * Internet Access Point (IAP) will be used).
296 * However, any ConsumerPolicy feature is applicable in
297 * one-policy-per-client scope and not used as a common policy.
298 * To set permanent information about known WSP, please use the
299 * CSenXmlServiceDescription, which implements MSenProviderPolicy
301 * This constructor is ASYNCHRONOUS and the actual state of
302 * created connection has to be observed from SetStatus() and
303 * HandleErrorL() functions.
304 * If service is found, the SetStatus() call-back is executed
305 * with a status value KSenConnectionStatusReady (1)
306 * For ID-WSF connections, the authentication for the Web Service
307 * Provider (WSP) connection is resolved using one of the identity
308 * providers which have been associated with the contract found in
309 * the SD. At minimum, the contract of the service (typically some URN)
310 * has to provided in the SD.
311 * Basic Web Service consumers instantiate a SD where an endpoint
312 * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
313 * @param aObserver connection observer.
314 * @param aServiceDescription is the description used to
315 * obtain a service connection.
316 * @return a pointer to a CSenServiceConnection instance.
318 IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aObserver,
319 CSenServicePattern& aServicePattern);
322 * The ServicePattern version of two phased constructor.
323 * Note, that this method is intended to be used by service consumers
324 * wishing to initialize connection in specific context called
325 * consumer policy. In consumer policy, certain properties
326 * can be set to further define what kind of connection is acceptable
327 * and how the connection interacts with transport (for example, which
328 * Internet Access Point (IAP) will be used).
329 * However, any ConsumerPolicy feature is applicable in
330 * one-policy-per-client scope and not used as a common policy.
331 * To set permanent information about known WSP, please use the
332 * CSenXmlServiceDescription, which implements MSenProviderPolicy
334 * This constructor is ASYNCHRONOUS and the actual state of
335 * created connection has to be observed from SetStatus() and
336 * HandleErrorL() functions.
337 * If service is found, the SetStatus() call-back is executed
338 * with a status value KSenConnectionStatusReady (1)
339 * For ID-WSF connections, the authentication for the Web Service
340 * Provider (WSP) connection is resolved using one of the identity
341 * providers which have been associated with the contract found in
342 * the SD. At minimum, the contract of the service (typically some URN)
343 * has to provided in the SD.
344 * Basic Web Service consumers instantiate a SD where an endpoint
345 * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
346 * @param aObserver connection observer.
347 * @param aServiceDescription is the description used to
348 * obtain a service connection.
349 * @return a pointer to a CSenServiceConnection instance.
350 * The pointer is left on the cleanup stack.
352 IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aObserver,
353 CSenServicePattern& aServicePattern);
356 * Two-phased constructor intended for Identity based service
357 * consumers (like ID-WSF). The pointer is left on the cleanup stack.
358 * This constructor is ASYNCHRONOUS and the actual state of
359 * created connection has to be observed from SetStatus() AND
360 * HandleErrorL() functions.
361 * If service is found, the SetStatus() call-back is performed
362 * with a status value KSenConnectionStatusReady (1).
363 * Contract of the service (typically some URN) is provided.
364 * Authentication for the Web Service Provider (WSP) connection
365 * is resolved using one of the identity providers which have
366 * been associated with this contract (typically an URN).
368 * This constructor is ASYNCHRONOUS and the actual state of newly
369 * created connection has to be observed from SetStatus() AND
370 * HandleErrorL() functions.
371 * If service is found, a SetStatus call-back with value
372 * KSenConnectionStatusReady (1) is executed.
373 * If some error occurs, HandleErrorL() will be called to inform the
374 * creator of this connection (service consumer application)
376 * For example, if service is not found, a system wide error
377 * code of -1 is deliver via HandleErrorL() to WSC.
379 * Second example: server response HTTP 501 means, that this error
380 * code. 501 will be delivered via HandleErrorL() to WSC.
381 * This can happen in ID-WSF connection being initialized, if
382 * either Authentication Service (AS) or Discovery Service (DS)
385 * @param aConsumer (web) service consumer (for call-backs)
386 * @param aContract contract of the service, typically an URI.
387 * @return a pointer to a CSenServiceConnection instance.
388 * @param aAuthProvider Authentication Provider
390 IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aConsumer,
391 const TDesC8& aContract,
392 MSenExtendedConsumerInterface& aExtendedConsumer);
394 * Two-phased constructor intended for Identity based service
395 * consumers (like ID-WSF).
396 * This constructor is ASYNCHRONOUS and the actual state of
397 * created connection has to be observed from SetStatus() and
398 * HandleErrorL() functions.
399 * If service is found, the SetStatus() call-back is performed
400 * with a status value KSenConnectionStatusReady (1).
401 * Contract of the service (typically some URN) is provided.
402 * Authentication for the Web Service Provider (WSP) connection
403 * is resolved using one of the identity providers which have
404 * been associated with this contract (typically an URN).
405 * This constructor is ASYNCHRONOUS and the actual state of newly
406 * created connection has to be observed from SetStatus() AND
407 * HandleErrorL() functions.
408 * If service is found, a SetStatus call-back with value
409 * KSenConnectionStatusReady (1) is executed.
410 * If some error occurs, HandleErrorL() will be called to inform the
411 * creator of this connection (service consumer application)
413 * For example, if service is not found, a system wide error
414 * code of -1 is deliver via HandleErrorL() to WSC.
416 * Second example: server response HTTP 501 means, that this error
417 * code. 501 will be delivered via HandleErrorL() to WSC.
418 * This can happen in ID-WSF connection being initialized, if
419 * either Authentication Service (AS) or Discovery Service (DS)
422 * @param aConsumer (web) service consumer (for call-backs)
423 * @param aContract contract of the service, typically an URI.
424 * @param aAuthProvider Authentication Provider
425 * @return a pointer to a CSenServiceConnection instance.
426 * The pointer is left on the cleanup stack.
428 IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aConsumer,
429 const TDesC8& aContract,
430 MSenExtendedConsumerInterface& aExtendedConsumer);
433 * Two-phased constructor using a service description.
434 * This constructor is ASYNCHRONOUS and the actual state of
435 * created connection has to be observed from SetStatus() and
436 * HandleErrorL() functions.
437 * If service is found, the SetStatus() call-back is executed
438 * with a status value KSenConnectionStatusReady (1)
439 * For ID-WSF connections, the authentication for the Web Service
440 * Provider (WSP) connection is resolved using one of the identity
441 * providers which have been associated with the contract found in
442 * the SD. At minimum, the contract of the service (typically some URN)
443 * has to provided in the SD.
444 * Basic Web Service consumers instantiate a SD where an endpoint
445 * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
446 * @param aConsumer connection observer.
447 * @param aServiceDescription is the description used to
448 * obtain a service connection.
449 * @param aAuthProvider Authentication Provider
450 * @return a pointer to a CSenServiceConnection instance.
452 IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aConsumer,
453 MSenServiceDescription& aServiceDescription,
454 MSenExtendedConsumerInterface& aExtendedConsumer);
457 * Two-phased constructor using a service description. The pointer
458 * is left on the cleanup stack.
459 * This constructor is ASYNCHRONOUS and the actual state of
460 * created connection has to be observed from SetStatus() AND
461 * HandleErrorL() functions.
462 * If service is found, the SetStatus() call-back is executed
463 * with a status value KSenConnectionStatusReady (1)
464 * For ID-WSF connections, the authentication for the Web Service
465 * Provider (WSP) connection is resolved using one of the identity
466 * providers which have been associated with the contract found in
467 * the SD. At minimum, the contract of the service (typically some URN)
468 * has to provided in the SD.
469 * Basic Web Service consumers instantiate a SD where an endpoint
470 * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
471 * @param aConsumer connection observer.
472 * @param aServiceDescription is the description used to
473 * obtain a service connection.
474 * @param aAuthProvider Authentication Provider
475 * @return a pointer to a CSenServiceConnection instance.
476 * The pointer is left on the cleanup stack.
478 IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aConsumer,
479 MSenServiceDescription& aServiceDescription,
480 MSenExtendedConsumerInterface& aExtendedConsumer);
483 * The ServicePattern version of two phased constructor.
484 * Note, that this method is intended to be used by service consumers
485 * wishing to initialize connection in specific context called
486 * consumer policy. In consumer policy, certain properties
487 * can be set to further define what kind of connection is acceptable
488 * and how the connection interacts with transport (for example, which
489 * Internet Access Point (IAP) will be used).
490 * However, any ConsumerPolicy feature is applicable in
491 * one-policy-per-client scope and not used as a common policy.
492 * To set permanent information about known WSP, please use the
493 * CSenXmlServiceDescription, which implements MSenProviderPolicy
495 * This constructor is ASYNCHRONOUS and the actual state of
496 * created connection has to be observed from SetStatus() and
497 * HandleErrorL() functions.
498 * If service is found, the SetStatus() call-back is executed
499 * with a status value KSenConnectionStatusReady (1)
500 * For ID-WSF connections, the authentication for the Web Service
501 * Provider (WSP) connection is resolved using one of the identity
502 * providers which have been associated with the contract found in
503 * the SD. At minimum, the contract of the service (typically some URN)
504 * has to provided in the SD.
505 * Basic Web Service consumers instantiate a SD where an endpoint
506 * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
507 * @param aConsumer connection observer.
508 * @param aServiceDescription is the description used to
509 * obtain a service connection.
510 * @param aAuthProvider Authentication Provider
511 * @return a pointer to a CSenServiceConnection instance.
513 IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aConsumer,
514 CSenServicePattern& aServicePattern,
515 MSenExtendedConsumerInterface& aExtendedConsumer);
518 * The ServicePattern version of two phased constructor.
519 * Note, that this method is intended to be used by service consumers
520 * wishing to initialize connection in specific context called
521 * consumer policy. In consumer policy, certain properties
522 * can be set to further define what kind of connection is acceptable
523 * and how the connection interacts with transport (for example, which
524 * Internet Access Point (IAP) will be used).
525 * However, any ConsumerPolicy feature is applicable in
526 * one-policy-per-client scope and not used as a common policy.
527 * To set permanent information about known WSP, please use the
528 * CSenXmlServiceDescription, which implements MSenProviderPolicy
530 * This constructor is ASYNCHRONOUS and the actual state of
531 * created connection has to be observed from SetStatus() and
532 * HandleErrorL() functions.
533 * If service is found, the SetStatus() call-back is executed
534 * with a status value KSenConnectionStatusReady (1)
535 * For ID-WSF connections, the authentication for the Web Service
536 * Provider (WSP) connection is resolved using one of the identity
537 * providers which have been associated with the contract found in
538 * the SD. At minimum, the contract of the service (typically some URN)
539 * has to provided in the SD.
540 * Basic Web Service consumers instantiate a SD where an endpoint
541 * and framework ID KDefaultBasicWebServicesFrameworkID are defined.
542 * @param aConsumer connection observer.
543 * @param aServiceDescription is the description used to
544 * obtain a service connection.
545 * @param aAuthProvider Authentication Provider
546 * @return a pointer to a CSenServiceConnection instance.
547 * The pointer is left on the cleanup stack.
549 IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aConsumer,
550 CSenServicePattern& aServicePattern,
551 MSenExtendedConsumerInterface& aExtendedConsumer);
556 * Send an ASYNCHRONOUS request to a service.
557 * In ID-WSF, the request data is a SOAP Body.
558 * Response message is received either via
559 * HandleMessageL() or HandleErrorL() callback.
560 * There are two default frameworks available -
561 * the Identity Based Web Service Framework (which ID is "ID-WSF")
562 * and the Basic Web Services Framework (which ID is "WS-I").
563 * Please note, that Basic Web Services framework does NOT support this method.
564 * Instead, one should send complete SOAP envelopes using SendL(CSenSoapEnvelope&).
565 * So, currently this method is supported only in ID-WSF.
566 * @param aRequest outgoing request message.
567 * @return Transaction ID (positive integer) or error code, if method fails.
569 * Positive integers SendL returns transaction ID of the request,
570 * which can be later on utilized inside
571 * HandleMessageL and HandleErrorL methods,
572 * in order to map request and its response
575 * KErrSenNotInitialized Connection has not been initialized.
576 * KErrSenServiceConnectionBusy Connection is already busy with another
578 * KErrConnectionInitializing Connection is still initializing and
579 * cannot yet process commands.
580 * KErrConnectionExpired Credential for the connection is
581 * expired and needs to be renewed.
582 * This can be done by instantiating a new
584 * KErrSubmitting An error occurred
585 * KErrNoMemory Not enough memory to process the message.
586 * Other error codes are system-wide Symbian error codes.
588 virtual TInt SendL(const TDesC8& aRequest) = 0;
592 * Submit a synchronous request to a service
593 * (in ID-WSF, the SOAP message Body) and receive a response as XML.
594 * There are two default frameworks available -
595 * the Identity Based Web Service Framework (which ID is "ID-WSF")
596 * and the Basic Web Services Framework (which ID is "WS-I").
597 * Please note, that Basic Web Services framework does NOT support this method.
598 * Instead, one must send complete SOAP envelopes using SubmitL(CSenSoapEnvelope&).
599 * So, currently this method is supported only in ID-WSF.
600 * @param aRequest outgoing request message.
601 * @param aResponse the resolved response message.
602 * The ownership of the aResponse is transfered to the caller.
603 * The response is service specific part of the response.
604 * For ID-WSF services response contents is the SOAP Body, or complete SOAP
605 * envelope as XML, depending on the complete server messages on/off setting
607 * @return status/error code.
611 * KErrSenNotInitialized Connection has not been initialized.
612 * KErrSenServiceConnectionBusy Connection is already busy with another request.
613 * KErrConnectionInitializing Connection is still initializing and
614 * cannot yet process commands.
615 * KErrConnectionExpired Credential for the connection is
616 * expired and needs to be renewed.
617 * This can be done by instantiating a new
619 * KErrSubmitting An internal error occurred.
620 * KErrSenInternal Internal state is invalid.
621 * Other error codes are system-wide Symbian error codes.
623 virtual TInt SubmitL(const TDesC8& aRequest, HBufC8*& aResponse) = 0;
627 * Consumer application can use this method to check that
628 * service connection is in ready state.
629 * In ID-WSF, this means that WSF interprets that credentials
630 * for the service connection are valid (not expired).
631 * @param aReady indicates that the connection is ready to be used.
632 * @return status/error code.
635 * Error codes are system-wide Symbian error codes.
637 virtual TInt IsReady(TBool& aReady) = 0;
641 * Check if the underlying service connection has a certain characteristic
643 * Currently, only ID-WSF framework supports facets.
644 * For example, if consumer application is interested to resolve if
645 * initialized service connection has a facet indicating that service
646 * is free of charge (for e.g. "urn:framework.com.free:cost"), the
647 * method used to check this would be:
648 * _LIT8(KFacetOfFreeService, "urn:some.service.free:cost");
649 * int err = HasFacetL(KFacetOfFreeService, hasFacet);
651 * In the service session of initialed connection, this would be the form
652 * of the facet element:
653 * <Facet name="urn:framework.com.free:cost"/>
655 * If there is no facet in the service connection then the element is not
657 * @param aURI the name of the facet
658 * @param aHasFacet will indicate if underlying service has a certain
660 * @return status/error code.
664 * KErrSenNotInitialized Connection has not been initialized.
665 * KErrConnectionInitializing Connection is still initializing and
666 * cannot yet process commands.
667 * KErrConnectionExpired Connection is expired and needs to be
669 * KErrBadDescriptor The aUri parameter was an invalid
671 * Other error codes are system-wide Symbian error codes.
673 virtual TInt HasFacetL(const TDesC8& aURI, TBool& aHasFacet) = 0;
677 * Consumer application can use this method to set flag which defines
678 * whether or not the consumer wishes to receive complete SOAP envelope
680 * If complete server messages mode is off, then only the <Body> element
681 * is received from the SOAP envelope, otherwise full SOAP envelope.
682 * Note: Calling this function must not be done before connection is
683 * initialized (the observer's SetStatus() has been called with value
684 * KSenConnectionStatusReady).
685 * Calling this function should be done before sending or submitting
687 * @param aCompleteOnOff defines the content of HandleMessageL() callback.
688 * If set to ETrue (ON), then complete SOAP envelopes are
689 * received, including <Header> element.
690 * If set to EFalse (OFF), only the service specific
691 * content - SOAP envelope <Body> element - is received.
692 * In WSF frameworks the default settings are:
693 * 1. In ID-WSF, the complete server messages is OFF.
694 * 2. In Basic Web Services, the default is ON.
695 * @return status/error code.
699 * KErrSenNotInitialized Connection has not been initialized.
700 * KErrConnectionInitializing Connection is still initializing and
701 * cannot yet process commands.
702 * KErrConnectionExpired Connection is expired and needs to be
704 * Other error codes are system-wide Symbian error codes.
706 virtual TInt CompleteServerMessagesOnOff(const TBool& aCompleteOnOff) = 0;
710 * Sends a SOAP message to the service. The SOAP envelope may contain
711 * proprietary headers. The system will augment the message with the
712 * appropriate headers specified in the service invocation framework,
713 * so a client application should add only non-standard headers; and
714 * if it doesn't need to set such headers it is strongly recommended
715 * to use SendL(TDesC8&), which is meant for that.
716 * This is an asynchronous function, that returns immediately.
717 * When the service responds, the SOAP envelope content will
718 * be received via HandleMessageL() callback. In case of an
719 * error - like a SOAP fault - HandleErrorL() will be called
720 * with appropriate error code.
721 * There are two default frameworks available -
722 * the Identity Based Web Service Framework (which ID is "ID-WSF")
723 * and the Basic Web Services Framework (which ID is "WS-I").
724 * Please note, that ID-WSF does NOT support this method.
725 * Instead, one should send SOAP envelope Bodies using
726 * SendL(const TDesC8&).
727 * So, currently this method is supported only in Basic Web Services framework.
728 * @param aMessage The service specific message - a full SOAP envelope
729 * @return Transaction ID (positive integer) or error code, if method fails.
731 * Positive integers SendL returns transaction ID of the request,
732 * which can be later on utilized inside
733 * HandleMessageL and HandleErrorL methods,
734 * in order to map request and its response
737 * KErrSenNotInitialized Connection has not been initialized.
738 * KErrSenServiceConnectionBusy Connection is already busy with another
740 * KErrConnectionInitializing Connection is still initializing and
741 * cannot yet process commands.
742 * KErrConnectionExpired Connection is expired and needs to be
744 * KErrSubmitting An internal error has occurred.
745 * KErrNoMemory Not enough memory to process the
747 * Other error codes are system-wide Symbian error codes.
749 virtual TInt SendL(CSenSoapEnvelope& aMessage) = 0;
753 * Submits a SOAP message to the service. This is a synchronous call,
754 * returning a SOAP envelope that was received from the service.
755 * There are two default frameworks available:
756 * the Identity Based Web Service Framework (which ID is "ID-WSF")
757 * and the Basic Web Services Framework (which ID is "WS-I").
758 * Please note, that ID-WSF does NOT support this method.
759 * Instead, one should send SOAP envelope Bodies using SendL(const TDesC8&).
760 * So, currently this method is supported only in Basic Web Services framework.
761 * @param aMessage SOAPEnvelope with the service specific message
762 * without any framework wrapping
763 * @param aResponseTo This is a ref-to-pointer where response
764 * from the service will be allocated. If the
765 * complete server messages mode is set to OFF,
766 * then only <Body> element will be returned,
767 * otherwise a complete SOAP envelope.
768 * The ownership of aResponse is transfered to
770 * @return status/error code
774 * KErrSenNotInitialized Connection has not been initialized.
775 * KErrSenServiceConnectionBusy Connection is already busy with another
777 * KErrConnectionInitializing Connection is still initializing and
778 * cannot yet process commands.
779 * KErrConnectionExpired Connection is expired and needs to be
781 * KErrSubmitting An internal error has occurred.
782 * KErrNoMemory Not enough memory to process the
784 * KErrSenInternal Internal state is invalid.
785 * Other error codes are system-wide Symbian error codes.
787 virtual TInt SubmitL(CSenSoapEnvelope& aMessage, HBufC8*& aResponseTo) = 0;
791 * Gets service description of current connection.
792 * @param aServiceDescription Contains the service description on return
793 * @return status/error code.
797 * KErrSenNotInitialized Connection has not been initialized.
798 * KErrSenServiceConnectionBusy Connection is already busy with another
800 * KErrConnectionInitializing Connection is still initializing and
801 * cannot yet process commands.
802 * KErrConnectionExpired Connection is expired and needs to be
804 * KErrUnderFlow Server side returned invalid service
806 * KErrUnknown Client-Server request mismatch.
807 * Other error codes are system-wide Symbian error codes.
809 virtual TInt ServiceDescriptionL(HBufC8*& aServiceDescription) = 0;
813 * Starts an application level transaction. The consumer may now start
814 * to communicate with some service withing a chain of correlated messages.
815 * When responding to a certain SOAP message inside a transaction, the last
816 * received message ID is used as "refToMessageId".
817 * From default frameworks, only ID-WSF supports transactions.
818 * @return KErrNone if no errors occur.
819 * Other error codes are system-wide Symbian error codes.
821 virtual TInt StartTransaction() = 0;
825 * Stops application level transaction by resetting the "refToMessageId".
826 * After stopping a transaction the next message will have no
828 * @return KErrNone if no errors occur.
829 * Other error codes are system-wide Symbian error codes.
831 virtual TInt TransactionCompleted() = 0;
835 * Returns the transasction ID of this message or error. Id is guaranteed
836 * to return unique ID when called from inside HandleMessageL() or
837 * HandleErrorL callback. This transasction ID may be used to map the
838 * response with the preceedeing SendL() call (a request).
839 * @return TInt transaction ID, or KErrNotFound, if no transaction is
842 virtual TInt TxnId() = 0;
846 * Sets transport specific properties which apply as long as this connection
847 * is alive (session). Furthermore, the properties are effective for this session
848 * in cumulative manner: each property has unique key (name) which is associated
849 * to the actual value of that property. When SetTransportPropertiesL method is
850 * called multiple times - in sequence - the last value for each key overrides any
851 * previous definitions. If any latter call introduces new keys (property names),
852 * they are appended to the list of currently effective properties.
853 * Also note, that it is also possible to set message specific properties when making
854 * a SendL/SubmitL call. If such transport properties for message are provided, and
855 * those include updates to some properties, the new ones are effective only for that
856 * certain message, i.e. those are transaction specific. For any following message,
857 * that is sent over a service connection, the session specific properties apply,
858 * assuming that the new message does not (again) override some of the property values.
859 * @param aProperties contains the transport properties in serialized (UTF-8) form.
860 * With HTTP, this descriptor is typically created by utilizing CSenHttpProperties class.
861 * @return KErrNone if successful or otherwise some system-wide error code.
863 virtual TInt SetTransportPropertiesL(const TDesC8& aProperties) = 0;
867 * Method returns currently effective transport properties as a serialized
868 * descriptor. With HTTP, one may utilize CSenHttpProperities class in
869 * order to read this data into properties object. Note that returned
870 * list of properties also includes properties, which are defined as default
871 * for certain transport in the webservice framework.
873 virtual TInt TransportPropertiesL(HBufC8*& aProperties) = 0;
877 * Send an ASYNCHRONOUS request to a service.
878 * In ID-WSF, the request data is a SOAP Body.
879 * Response message is received either via
880 * HandleMessageL() or HandleErrorL() callback.
881 * There are two default frameworks available -
882 * the Identity Based Web Service Framework (which ID is "ID-WSF")
883 * and the Basic Web Services Framework (which ID is "WS-I").
884 * Please note, that Basic Web Services framework does NOT support this method.
885 * Instead, one should send complete SOAP envelopes using SendL(CSenSoapEnvelope&).
886 * So, currently this method is supported only in ID-WSF.
887 * @param aRequest outgoing request message.
888 * @param aProperties contains transport spesific properties, serialized
889 * into descriptor. With HTTP, one can create this by utilizing specialized
890 * CSenHttpProperties class.
891 * @return Transaction ID (positive integer) or error code, if method fails.
893 * Positive integers SendL returns transaction ID of the request,
894 * which can be later on utilized inside
895 * HandleMessageL and HandleErrorL methods,
896 * in order to map request and its response
899 * KErrSenNotInitialized Connection has not been initialized.
900 * KErrSenServiceConnectionBusy Connection is already busy with another
902 * KErrConnectionInitializing Connection is still initializing and
903 * cannot yet process commands.
904 * KErrConnectionExpired Credential for the connection is
905 * expired and needs to be renewed.
906 * This can be done by instantiating a new
908 * KErrSubmitting An error occurred
909 * KErrNoMemory Not enough memory to process the message.
910 * Other error codes are system-wide Symbian error codes.
912 virtual TInt SendL(const TDesC8& aRequest, const TDesC8& aProperties) = 0;
916 * Submit a request via SYNCHRONOUS call to a service
917 * (in ID-WSF, the SOAP message Body) and receive a response as XML.
918 * There are two default frameworks available -
919 * the Identity Based Web Service Framework (which ID is "ID-WSF")
920 * and the Basic Web Services Framework (which ID is "WS-I").
921 * Please note, that Basic Web Services framework does NOT support this method.
922 * Instead, one must send complete SOAP envelopes using SubmitL(CSenSoapEnvelope&).
923 * So, currently this method is supported only in ID-WSF.
924 * @param aRequest outgoing request message.
925 * @param aResponse the resolved response message.
926 * The ownership of the aResponse is transfered to the caller.
927 * The response is service specific part of the response.
928 * For ID-WSF services response contents is the SOAP Body, or complete SOAP
929 * envelope as XML, depending on the complete server messages on/off setting
931 * @param aProperties contains transport spesific properties, serialized
932 * into descriptor. With HTTP, one can create this by utilizing specialized
933 * CSenHttpProperties class.
934 * @return status/error code.
938 * KErrSenNotInitialized Connection has not been initialized.
939 * KErrSenServiceConnectionBusy Connection is already busy with another request.
940 * KErrConnectionInitializing Connection is still initializing and
941 * cannot yet process commands.
942 * KErrConnectionExpired Credential for the connection is
943 * expired and needs to be renewed.
944 * This can be done by instantiating a new
946 * KErrSubmitting An internal error occurred.
947 * KErrSenInternal Internal state is invalid.
948 * Other error codes are system-wide Symbian error codes.
950 virtual TInt SubmitL(const TDesC8& aRequest, const TDesC8& aProperties, HBufC8*& aResponse) = 0;
954 * Sends a SOAP message to the service. The SOAP envelope may contain
955 * proprietary headers. The system will augment the message with the
956 * appropriate headers specified in the service invocation framework,
957 * so a client application should add only non-standard headers; and
958 * if it doesn't need to set such headers it is strongly recommended
959 * to use SendL(TDesC8&), which is meant for this.
960 * This is an asynchronous function, that returns immediately.
961 * When the service responds, the SOAP envelope content will
962 * be received via HandleMessageL() callback. In case of an
963 * error - like a SOAP fault - HandleErrorL() will be called
964 * with appropriate error code.
965 * There are two default frameworks available -
966 * the Identity Based Web Service Framework (which ID is "ID-WSF")
967 * and the Basic Web Services Framework (which ID is "WS-I").
968 * Please note, that ID-WSF does NOT support this method.
969 * Instead, one should send SOAP envelope Bodies using
970 * SendL(const TDesC8&).
971 * So, currently this method is supported only in Basic Web Services framework.
974 * Message is send as serialized XML or Soap message to SendL
975 * aProperties could be "HTTP GET" or "HTTP DELETE"
976 * HTTP GET or HTTP DELETE transport property has been enabled via CSenHttpTransportProperties.
977 * This scenario is not supported
979 * @param aMessage The service specific message - a full SOAP envelope
980 * @param aProperties contains transport spesific properties, serialized
981 * into descriptor. With HTTP, one can create this by utilizing specialized
982 * CSenHttpProperties class.
983 * @return Transaction ID (positive integer) or error code, if method fails.
985 * Positive integers SendL returns transaction ID of the request,
986 * which can be later on utilized inside
987 * HandleMessageL and HandleErrorL methods,
988 * in order to map request and its response
991 * KErrSenNotInitialized Connection has not been initialized.
992 * KErrSenServiceConnectionBusy Connection is already busy with another
994 * KErrConnectionInitializing Connection is still initializing and
995 * cannot yet process commands.
996 * KErrConnectionExpired Connection is expired and needs to be
998 * KErrSubmitting An internal error has occurred.
999 * KErrNoMemory Not enough memory to process the
1001 * KErrNotSupported HTTP GET or HTTP DELETE is enabled
1002 * Other error codes are system-wide Symbian error codes.
1004 virtual TInt SendL(CSenSoapEnvelope& aMessage, const TDesC8& aProperties) = 0;
1007 * Submits a SOAP message to the service. This is a synchronous call,
1008 * returning a SOAP envelope that was received from the service.
1009 * There are two default frameworks available:
1010 * the Identity Based Web Service Framework (which ID is "ID-WSF")
1011 * and the Basic Web Services Framework (which ID is "WS-I").
1012 * Please note, that ID-WSF does NOT support this method.
1013 * Instead, one should send SOAP envelope Bodies using SendL(const TDesC8&).
1014 * So, currently this method is supported only in Basic Web Services framework.
1017 * Message is send as serialized XML or Soap message to SubmitL
1018 * aProperties could be "HTTP GET" or "HTTP DELETE"
1019 * HTTP GET or HTTP DELETE transport property has been enabled via CSenHttpTransportProperties.
1020 * This scenario is not supported
1022 * @param aMessage SOAPEnvelope with the service specific message
1023 * without any framework wrapping
1024 * @param aProperties contains transport spesific properties, serialized
1025 * into descriptor. With HTTP, one can create this by utilizing specialized
1026 * CSenHttpProperties class.
1027 * @param aResponseTo This is a ref-to-pointer where response
1028 * from the service will be allocated. If the
1029 * complete server messages mode is set to OFF,
1030 * then only <Body> element will be returned,
1031 * otherwise a complete SOAP envelope.
1032 * The ownership of aResponse is transfered to
1034 * @return status/error code
1038 * KErrSenNotInitialized Connection has not been initialized.
1039 * KErrSenServiceConnectionBusy Connection is already busy with another
1041 * KErrConnectionInitializing Connection is still initializing and
1042 * cannot yet process commands.
1043 * KErrConnectionExpired Connection is expired and needs to be
1045 * KErrSubmitting An internal error has occurred.
1046 * KErrNoMemory Not enough memory to process the
1048 * KErrSenInternal Internal state is invalid.
1049 * KErrNotSupported HTTP GET or HTTP DELETE is enabled
1050 * Other error codes are system-wide Symbian error codes.
1052 virtual TInt SubmitL(CSenSoapEnvelope& aMessage, const TDesC8& aProperties, HBufC8*& aResponseTo) = 0;
1055 * Sends a SOAP message to the service. The SOAP envelope may contain
1056 * proprietary headers. The system will augment the message with the
1057 * appropriate headers specified in the service invocation framework,
1058 * so a client application should add only non-standard headers.
1059 * This is an asynchronous function, that returns immediately.
1060 * When the service responds, the SOAP envelope content will
1061 * be received via HandleMessageL() callback. In case of an
1062 * error - like a SOAP fault - HandleErrorL() will be called
1063 * with appropriate error code.
1064 * There are two default frameworks available -
1065 * the Identity Based Web Service Framework (which ID is "ID-WSF")
1066 * and the Basic Web Services Framework (which ID is "WS-I").
1067 * Please note, that ID-WSF does NOT support this method.
1068 * Instead, one should send SOAP envelope Bodies using
1069 * SendL(const TDesC8&).
1070 * So, currently this method is supported only in Basic Web Services framework.
1072 * @param aMessage The service specific message - a full SOAP envelope
1073 * @return Transaction ID (positive integer) or error code, if method fails.
1075 * Positive integers SendL returns transaction ID of the request,
1076 * which can be later on utilized inside
1077 * HandleMessageL and HandleErrorL methods,
1078 * in order to map request and its response
1081 * KErrSenNotInitialized Connection has not been initialized.
1082 * KErrSenServiceConnectionBusy Connection is already busy with another
1084 * KErrConnectionInitializing Connection is still initializing and
1085 * cannot yet process commands.
1086 * KErrConnectionExpired Connection is expired and needs to be
1088 * KErrSubmitting An internal error has occurred.
1089 * KErrNoMemory Not enough memory to process the
1091 * KErrNotSupported HTTP GET or HTTP DELETE is enabled
1092 * Other error codes are system-wide Symbian error codes.
1094 virtual TInt SendL(MSenMessage& aMessage) = 0;
1097 * Submits a SOAP message to the service. This is a synchronous call,
1098 * returning a SOAP envelope that was received from the service.
1099 * There are two default frameworks available:
1100 * the Identity Based Web Service Framework (which ID is "ID-WSF")
1101 * and the Basic Web Services Framework (which ID is "WS-I").
1102 * Please note, that ID-WSF does NOT support this method.
1103 * Instead, one should send SOAP envelope Bodies using SendL(const TDesC8&).
1104 * So, currently this method is supported only in Basic Web Services framework.
1106 * @param aMessage SOAPEnvelope with the service specific message
1107 * without any framework wrapping
1108 * @param aResponseTo This is a ref-to-pointer where response
1109 * from the service will be allocated. If the
1110 * complete server messages mode is set to OFF,
1111 * then only <Body> element will be returned,
1112 * otherwise a complete SOAP envelope.
1113 * The ownership of aResponse is transfered to
1115 * @return status/error code
1119 * KErrSenNotInitialized Connection has not been initialized.
1120 * KErrSenServiceConnectionBusy Connection is already busy with another
1122 * KErrConnectionInitializing Connection is still initializing and
1123 * cannot yet process commands.
1124 * KErrConnectionExpired Connection is expired and needs to be
1126 * KErrSubmitting An internal error has occurred.
1127 * KErrNoMemory Not enough memory to process the
1129 * KErrSenInternal Internal state is invalid.
1130 * KErrNotSupported HTTP GET or HTTP DELETE is enabled
1131 * Other error codes are system-wide Symbian error codes.
1133 virtual TInt SubmitL(MSenMessage& aMessage, CSenSoapEnvelope2*& aResponseTo) = 0;
1136 * Getter for currently active transaction (service response) that is
1137 * being handled by the service consumer.
1138 * @return a pointer to currently active transaction (service response).
1139 * It is guarenteed, that the method returns a pointer to
1140 * transaction only when called inside HandleMessageL or
1141 * HandleErrorL callback methods of MSenServiceConsumer,
1142 * otherwise it will return NULL.
1144 virtual MSenMessage* Response() = 0;
1147 * Cancels any active request, if pending transaction
1148 * (txn) can be found with given txn ID.
1149 * @param aTransactionID is the transaction ID to be cancelled. This id has earlier been
1150 * acquired from a call to some of the asynchronous SendL variants.
1152 * @return KErrNone on success
1153 * KErrNotFound, if there is no pending transaction (active request),
1154 * or some of the system-wide error codes otheriwise.
1156 virtual TInt CancelTransaction(TInt aTransactionID) = 0;
1159 * Getter for the identity provider (XML) service description.
1160 * @param apIdentityProvider will point to a new IDP instance,
1161 * if such is associated with this connection (and this connection
1162 * was ready before calling this method), or NULL otherwise.
1163 * @return KErrNone if IDP description can be found, or some
1164 * of the system wide error code otherwise.
1166 virtual TInt IdentityProviderL(CSenIdentityProvider*& apIdentityProvider) = 0;
1169 * Getter for the identifier of this connection.
1170 * @return the identifier as integer.
1172 virtual TInt Identifier() = 0;
1175 * Registers observer of BLOBs transfer progress.
1177 * @param aFilesObserver Implementation of transfer progress observer.
1183 * C++ default constructor.
1185 CSenServiceConnection();
1189 #endif //SEN_SERVICE_CONNECTION_H