diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/mw/senserviceconnection.h --- a/epoc32/include/mw/senserviceconnection.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/mw/senserviceconnection.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,1192 @@ -senserviceconnection.h +/* +* Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members +* which accompanies this distribution, and is available +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: CSenServiceConnection offers public API for +* service consumers to access invocable services, +* as a part of the Web Services Framework (WSF). +* +*/ + + + + + + + + + +#ifndef SEN_SERVICE_CONNECTION_H +#define SEN_SERVICE_CONNECTION_H + +// INCLUDES +#include // for CActive +#include +#include + +#include + +#include +#include +//#include + + +#include + +// CONSTANTS +const TInt KErrSenNotInitialized = -30291; +const TInt KErrSenServiceConnectionBusy = -30292; +const TInt KErrConnectionInitializing = -30293; +const TInt KErrConnectionExpired = -30294; +const TInt KErrSubmitting = -30295; +const TInt KErrSenSoapFault = -30296; +const TInt KErrSenInternal = -30297; +const TInt KErrSenNoEndpoint = -30298; +const TInt KErrSenNoContract = -30299; + +const TInt KErrSenProviderIdInUseByAnotherEndpoint = -30305; +const TInt KErrSenNoContractNoEndPoint = -30306; + +const TInt KErrSenBrokenSoapEnvelope = -30307; +const TInt KErrSenBrokenSoapFault = -30308; +const TInt KErrSenCancelled = -30309; + + +// HTTP transport error codes: +const TInt KErrSenNoHttpResponseBody = -30310; +const TInt KErrSenNoHttpContentType = -30311; +const TInt KErrSenHttpRedirectRequiresConfirmation = -30312; + +// SOAP message verification error codes: +const TInt KErrSenNoSoapBody = -30313; +const TInt KErrSenNoSoapHeader = -30314; +const TInt KErrSenNoPermission = -30315; + +const TInt KErrSenHostNotAvailable = -30318; + +const TInt KErrSenAuthenticationFault = -30319; +const TInt KErrSenNoEndUserPermission = -30321; + + +const TInt KSenConnectionStatusCreateFailed = -1; // post-state +const TInt KSenConnectionStatusNew = 0; // post-state +const TInt KSenConnectionStatusReady = 1; // post-state +const TInt KSenConnectionStatusExpired = 2; // post-state +const TInt KSenConnectionStatusAuthentication = 3; // pre-state +const TInt KSenConnectionStatusDiscovery = 4; // pre-state +const TInt KSenConnectionStatusMetadataExchange = 5; // pre-state + +_LIT8(KDefaultBasicWebServicesFrameworkID, "WS-I"); +_LIT8(KDefaultIdWsfFrameworkID, "ID-WSF"); +_LIT8(KDefaultRestServicesFrameworkID, "REST"); +_LIT8(KDefaultWSStarFrameworkID, "WS-STAR"); +_LIT8(KDefaultAtomPubFrameworkID, "ATOM-PUB"); +_LIT8(KDefaultOviFrameworkID, "OVI"); + +const TInt KSenTransportStatusCodeOffsetBaseHttp = 1000; +const TInt KSenTransportStatusCodeOffsetBaseVtcp = 2000; + +const TInt KSenTransportStatusCodeVtcpInit = 2001; // KSenTransportStatusCodeOffsetBaseVtcp +1 +const TInt KSenTransportStatusCodeVtcpActive = 2002; // KSenTransportStatusCodeOffsetBaseVtcp +2 +const TInt KSenTransportStatusCodeVtcpSuspended = 2003; // KSenTransportStatusCodeOffsetBaseVtcp +3 +const TInt KSenTransportStatusCodeVtcpInactive = 2004; // KSenTransportStatusCodeOffsetBaseVtcp +4 +const TInt KSenTransportStatusCodeVtcpUnavailable = 2005; // KSenTransportStatusCodeOffsetBaseVtcp +5 + +// FORWARD DECLARATIONS +class CSenServicePattern; +class CSenIdentityProvider; + +// CLASS DECLARATION + +/** + * The class for connecting to service providers + * through Web Services Framework (WSF). + * + * The class offers asynchronous construction of a + * service connection. Further, there are asynchronous + * and synchronous interaction methods for e.g. sending + * and receiving data from (possibly remote) service. + * + * WSF offers two default frameworks: + * + * 1. Identity Based Web Services Framework + * (ID-WSF). The framework ID for this is + * KDefaultIdWsfFrameworkID ("ID-WSF"). + * + * 2. Basic Web Services Framework. Framework + * ID is KDefaultBasicWebServicesFrameworkID + * ("WS-I"). + * + * The most typical use of CSenServiceConnection + * is to interact with a service of certain type + * through some invocable framework and submitting + * and receiving messages. + * + * In case of WebServices, the actual service is remote + * and submitted messages are SOAP envelopes. However, + * CSenServiceConnection supports accessing any + * ServiceInvocationFramework which ECOM plug-in + * implementation is present. These plug-ins may + * further communicate with some service, including + * local services. + * + * The link between CSenServiceConnection and any plug-in + * implementation interacting with some service is the + * framework ID, which is a property of ServiceDescription (SD) + * and accessible via MSenServiceDescription interface, which + * each SD class must implement. + * + * When creating a connection, one offers predefined SD as + * an argument for asynchronous constructor. Or, optionally + * only a Liberty Alliance ID-WSF specific contract string + * - typically some URN. If only contract is offered, then + * the created connection defaults to ID-WSF service and + * ID-WSF framework (ID) will be used. + * + * The WSF further uses the offered framework ID while looking + * up any matching framework plug-in implementation. As a + * result the SD might be offered to several plug-ins. +* +* @lib SenServConn.lib +* @since Series60 3.0 +*/ + +class CSenServiceConnection : public CActive, public MSenFragment + { + public: // Constructors and destructor + + /** + * Two-phased constructor intended for Identity based service + * consumers (like ID-WSF). The pointer is left on the cleanup stack. + * This constructor is ASYNCHRONOUS and the actual state of + * created connection has to be observed from SetStatus() AND + * HandleErrorL() functions. + * If service is found, the SetStatus() call-back is performed + * with a status value KSenConnectionStatusReady (1). + * Contract of the service (typically some URN) is provided. + * Authentication for the Web Service Provider (WSP) connection + * is resolved using one of the identity providers which have + * been associated with this contract (typically an URN). + * + * This constructor is ASYNCHRONOUS and the actual state of newly + * created connection has to be observed from SetStatus() AND + * HandleErrorL() functions. + * If service is found, a SetStatus call-back with value + * KSenConnectionStatusReady (1) is executed. + * If some error occurs, HandleErrorL() will be called to inform the + * creator of this connection (service consumer application) + * + * For example, if service is not found, a system wide error + * code of -1 is deliver via HandleErrorL() to WSC. + * + * Second example: server response HTTP 501 means, that this error + * code. 501 will be delivered via HandleErrorL() to WSC. + * This can happen in ID-WSF connection being initialized, if + * either Authentication Service (AS) or Discovery Service (DS) + * cannot be reached. + * + * @param aConsumer (web) service consumer (for call-backs) + * @param aContract contract of the service, typically an URI. + * @return a pointer to a CSenServiceConnection instance. + * + */ + IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aConsumer, + const TDesC8& aContract); + + /** + * Two-phased constructor intended for Identity based service + * consumers (like ID-WSF). + * This constructor is ASYNCHRONOUS and the actual state of + * created connection has to be observed from SetStatus() and + * HandleErrorL() functions. + * If service is found, the SetStatus() call-back is performed + * with a status value KSenConnectionStatusReady (1). + * Contract of the service (typically some URN) is provided. + * Authentication for the Web Service Provider (WSP) connection + * is resolved using one of the identity providers which have + * been associated with this contract (typically an URN). + * This constructor is ASYNCHRONOUS and the actual state of newly + * created connection has to be observed from SetStatus() AND + * HandleErrorL() functions. + * If service is found, a SetStatus call-back with value + * KSenConnectionStatusReady (1) is executed. + * If some error occurs, HandleErrorL() will be called to inform the + * creator of this connection (service consumer application) + * + * For example, if service is not found, a system wide error + * code of -1 is deliver via HandleErrorL() to WSC. + * + * Second example: server response HTTP 501 means, that this error + * code. 501 will be delivered via HandleErrorL() to WSC. + * This can happen in ID-WSF connection being initialized, if + * either Authentication Service (AS) or Discovery Service (DS) + * cannot be reached. + * + * @param aConsumer (web) service consumer (for call-backs) + * @param aContract contract of the service, typically an URI. + * @return a pointer to a CSenServiceConnection instance. + * The pointer is left on the cleanup stack. + */ + IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aObserver, + const TDesC8& aContract); + + /** + * Two-phased constructor using a service description. + * This constructor is ASYNCHRONOUS and the actual state of + * created connection has to be observed from SetStatus() and + * HandleErrorL() functions. + * If service is found, the SetStatus() call-back is executed + * with a status value KSenConnectionStatusReady (1) + * For ID-WSF connections, the authentication for the Web Service + * Provider (WSP) connection is resolved using one of the identity + * providers which have been associated with the contract found in + * the SD. At minimum, the contract of the service (typically some URN) + * has to provided in the SD. + * Basic Web Service consumers instantiate a SD where an endpoint + * and framework ID KDefaultBasicWebServicesFrameworkID are defined. + * @param aObserver connection observer. + * @param aServiceDescription is the description used to + * obtain a service connection. + * @return a pointer to a CSenServiceConnection instance. + */ + IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aObserver, + MSenServiceDescription& aServiceDescription); + + /** + * Two-phased constructor using a service description. The pointer + * is left on the cleanup stack. + * This constructor is ASYNCHRONOUS and the actual state of + * created connection has to be observed from SetStatus() AND + * HandleErrorL() functions. + * If service is found, the SetStatus() call-back is executed + * with a status value KSenConnectionStatusReady (1) + * For ID-WSF connections, the authentication for the Web Service + * Provider (WSP) connection is resolved using one of the identity + * providers which have been associated with the contract found in + * the SD. At minimum, the contract of the service (typically some URN) + * has to provided in the SD. + * Basic Web Service consumers instantiate a SD where an endpoint + * and framework ID KDefaultBasicWebServicesFrameworkID are defined. + * @param aObserver connection observer. + * @param aServiceDescription is the description used to + * obtain a service connection. + * @return a pointer to a CSenServiceConnection instance. + * The pointer is left on the cleanup stack. + */ + IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aObserver, + MSenServiceDescription& aServiceDescription); + + /* + * The ServicePattern version of two phased constructor. + * Note, that this method is intended to be used by service consumers + * wishing to initialize connection in specific context called + * consumer policy. In consumer policy, certain properties + * can be set to further define what kind of connection is acceptable + * and how the connection interacts with transport (for example, which + * Internet Access Point (IAP) will be used). + * However, any ConsumerPolicy feature is applicable in + * one-policy-per-client scope and not used as a common policy. + * To set permanent information about known WSP, please use the + * CSenXmlServiceDescription, which implements MSenProviderPolicy + * interface. + * This constructor is ASYNCHRONOUS and the actual state of + * created connection has to be observed from SetStatus() and + * HandleErrorL() functions. + * If service is found, the SetStatus() call-back is executed + * with a status value KSenConnectionStatusReady (1) + * For ID-WSF connections, the authentication for the Web Service + * Provider (WSP) connection is resolved using one of the identity + * providers which have been associated with the contract found in + * the SD. At minimum, the contract of the service (typically some URN) + * has to provided in the SD. + * Basic Web Service consumers instantiate a SD where an endpoint + * and framework ID KDefaultBasicWebServicesFrameworkID are defined. + * @param aObserver connection observer. + * @param aServiceDescription is the description used to + * obtain a service connection. + * @return a pointer to a CSenServiceConnection instance. + */ + IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aObserver, + CSenServicePattern& aServicePattern); + + /* + * The ServicePattern version of two phased constructor. + * Note, that this method is intended to be used by service consumers + * wishing to initialize connection in specific context called + * consumer policy. In consumer policy, certain properties + * can be set to further define what kind of connection is acceptable + * and how the connection interacts with transport (for example, which + * Internet Access Point (IAP) will be used). + * However, any ConsumerPolicy feature is applicable in + * one-policy-per-client scope and not used as a common policy. + * To set permanent information about known WSP, please use the + * CSenXmlServiceDescription, which implements MSenProviderPolicy + * interface. + * This constructor is ASYNCHRONOUS and the actual state of + * created connection has to be observed from SetStatus() and + * HandleErrorL() functions. + * If service is found, the SetStatus() call-back is executed + * with a status value KSenConnectionStatusReady (1) + * For ID-WSF connections, the authentication for the Web Service + * Provider (WSP) connection is resolved using one of the identity + * providers which have been associated with the contract found in + * the SD. At minimum, the contract of the service (typically some URN) + * has to provided in the SD. + * Basic Web Service consumers instantiate a SD where an endpoint + * and framework ID KDefaultBasicWebServicesFrameworkID are defined. + * @param aObserver connection observer. + * @param aServiceDescription is the description used to + * obtain a service connection. + * @return a pointer to a CSenServiceConnection instance. + * The pointer is left on the cleanup stack. + */ + IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aObserver, + CSenServicePattern& aServicePattern); + + /** + * Two-phased constructor intended for Identity based service + * consumers (like ID-WSF). The pointer is left on the cleanup stack. + * This constructor is ASYNCHRONOUS and the actual state of + * created connection has to be observed from SetStatus() AND + * HandleErrorL() functions. + * If service is found, the SetStatus() call-back is performed + * with a status value KSenConnectionStatusReady (1). + * Contract of the service (typically some URN) is provided. + * Authentication for the Web Service Provider (WSP) connection + * is resolved using one of the identity providers which have + * been associated with this contract (typically an URN). + * + * This constructor is ASYNCHRONOUS and the actual state of newly + * created connection has to be observed from SetStatus() AND + * HandleErrorL() functions. + * If service is found, a SetStatus call-back with value + * KSenConnectionStatusReady (1) is executed. + * If some error occurs, HandleErrorL() will be called to inform the + * creator of this connection (service consumer application) + * + * For example, if service is not found, a system wide error + * code of -1 is deliver via HandleErrorL() to WSC. + * + * Second example: server response HTTP 501 means, that this error + * code. 501 will be delivered via HandleErrorL() to WSC. + * This can happen in ID-WSF connection being initialized, if + * either Authentication Service (AS) or Discovery Service (DS) + * cannot be reached. + * + * @param aConsumer (web) service consumer (for call-backs) + * @param aContract contract of the service, typically an URI. + * @return a pointer to a CSenServiceConnection instance. + * @param aAuthProvider Authentication Provider + */ + IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aConsumer, + const TDesC8& aContract, + MSenExtendedConsumerInterface& aExtendedConsumer); + /** + * Two-phased constructor intended for Identity based service + * consumers (like ID-WSF). + * This constructor is ASYNCHRONOUS and the actual state of + * created connection has to be observed from SetStatus() and + * HandleErrorL() functions. + * If service is found, the SetStatus() call-back is performed + * with a status value KSenConnectionStatusReady (1). + * Contract of the service (typically some URN) is provided. + * Authentication for the Web Service Provider (WSP) connection + * is resolved using one of the identity providers which have + * been associated with this contract (typically an URN). + * This constructor is ASYNCHRONOUS and the actual state of newly + * created connection has to be observed from SetStatus() AND + * HandleErrorL() functions. + * If service is found, a SetStatus call-back with value + * KSenConnectionStatusReady (1) is executed. + * If some error occurs, HandleErrorL() will be called to inform the + * creator of this connection (service consumer application) + * + * For example, if service is not found, a system wide error + * code of -1 is deliver via HandleErrorL() to WSC. + * + * Second example: server response HTTP 501 means, that this error + * code. 501 will be delivered via HandleErrorL() to WSC. + * This can happen in ID-WSF connection being initialized, if + * either Authentication Service (AS) or Discovery Service (DS) + * cannot be reached. + * + * @param aConsumer (web) service consumer (for call-backs) + * @param aContract contract of the service, typically an URI. + * @param aAuthProvider Authentication Provider + * @return a pointer to a CSenServiceConnection instance. + * The pointer is left on the cleanup stack. + */ + IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aConsumer, + const TDesC8& aContract, + MSenExtendedConsumerInterface& aExtendedConsumer); + + /** + * Two-phased constructor using a service description. + * This constructor is ASYNCHRONOUS and the actual state of + * created connection has to be observed from SetStatus() and + * HandleErrorL() functions. + * If service is found, the SetStatus() call-back is executed + * with a status value KSenConnectionStatusReady (1) + * For ID-WSF connections, the authentication for the Web Service + * Provider (WSP) connection is resolved using one of the identity + * providers which have been associated with the contract found in + * the SD. At minimum, the contract of the service (typically some URN) + * has to provided in the SD. + * Basic Web Service consumers instantiate a SD where an endpoint + * and framework ID KDefaultBasicWebServicesFrameworkID are defined. + * @param aConsumer connection observer. + * @param aServiceDescription is the description used to + * obtain a service connection. + * @param aAuthProvider Authentication Provider + * @return a pointer to a CSenServiceConnection instance. + */ + IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aConsumer, + MSenServiceDescription& aServiceDescription, + MSenExtendedConsumerInterface& aExtendedConsumer); + + /** + * Two-phased constructor using a service description. The pointer + * is left on the cleanup stack. + * This constructor is ASYNCHRONOUS and the actual state of + * created connection has to be observed from SetStatus() AND + * HandleErrorL() functions. + * If service is found, the SetStatus() call-back is executed + * with a status value KSenConnectionStatusReady (1) + * For ID-WSF connections, the authentication for the Web Service + * Provider (WSP) connection is resolved using one of the identity + * providers which have been associated with the contract found in + * the SD. At minimum, the contract of the service (typically some URN) + * has to provided in the SD. + * Basic Web Service consumers instantiate a SD where an endpoint + * and framework ID KDefaultBasicWebServicesFrameworkID are defined. + * @param aConsumer connection observer. + * @param aServiceDescription is the description used to + * obtain a service connection. + * @param aAuthProvider Authentication Provider + * @return a pointer to a CSenServiceConnection instance. + * The pointer is left on the cleanup stack. + */ + IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aConsumer, + MSenServiceDescription& aServiceDescription, + MSenExtendedConsumerInterface& aExtendedConsumer); + + /* + * The ServicePattern version of two phased constructor. + * Note, that this method is intended to be used by service consumers + * wishing to initialize connection in specific context called + * consumer policy. In consumer policy, certain properties + * can be set to further define what kind of connection is acceptable + * and how the connection interacts with transport (for example, which + * Internet Access Point (IAP) will be used). + * However, any ConsumerPolicy feature is applicable in + * one-policy-per-client scope and not used as a common policy. + * To set permanent information about known WSP, please use the + * CSenXmlServiceDescription, which implements MSenProviderPolicy + * interface. + * This constructor is ASYNCHRONOUS and the actual state of + * created connection has to be observed from SetStatus() and + * HandleErrorL() functions. + * If service is found, the SetStatus() call-back is executed + * with a status value KSenConnectionStatusReady (1) + * For ID-WSF connections, the authentication for the Web Service + * Provider (WSP) connection is resolved using one of the identity + * providers which have been associated with the contract found in + * the SD. At minimum, the contract of the service (typically some URN) + * has to provided in the SD. + * Basic Web Service consumers instantiate a SD where an endpoint + * and framework ID KDefaultBasicWebServicesFrameworkID are defined. + * @param aConsumer connection observer. + * @param aServiceDescription is the description used to + * obtain a service connection. + * @param aAuthProvider Authentication Provider + * @return a pointer to a CSenServiceConnection instance. + */ + IMPORT_C static CSenServiceConnection* NewL(MSenServiceConsumer& aConsumer, + CSenServicePattern& aServicePattern, + MSenExtendedConsumerInterface& aExtendedConsumer); + + /* + * The ServicePattern version of two phased constructor. + * Note, that this method is intended to be used by service consumers + * wishing to initialize connection in specific context called + * consumer policy. In consumer policy, certain properties + * can be set to further define what kind of connection is acceptable + * and how the connection interacts with transport (for example, which + * Internet Access Point (IAP) will be used). + * However, any ConsumerPolicy feature is applicable in + * one-policy-per-client scope and not used as a common policy. + * To set permanent information about known WSP, please use the + * CSenXmlServiceDescription, which implements MSenProviderPolicy + * interface. + * This constructor is ASYNCHRONOUS and the actual state of + * created connection has to be observed from SetStatus() and + * HandleErrorL() functions. + * If service is found, the SetStatus() call-back is executed + * with a status value KSenConnectionStatusReady (1) + * For ID-WSF connections, the authentication for the Web Service + * Provider (WSP) connection is resolved using one of the identity + * providers which have been associated with the contract found in + * the SD. At minimum, the contract of the service (typically some URN) + * has to provided in the SD. + * Basic Web Service consumers instantiate a SD where an endpoint + * and framework ID KDefaultBasicWebServicesFrameworkID are defined. + * @param aConsumer connection observer. + * @param aServiceDescription is the description used to + * obtain a service connection. + * @param aAuthProvider Authentication Provider + * @return a pointer to a CSenServiceConnection instance. + * The pointer is left on the cleanup stack. + */ + IMPORT_C static CSenServiceConnection* NewLC(MSenServiceConsumer& aConsumer, + CSenServicePattern& aServicePattern, + MSenExtendedConsumerInterface& aExtendedConsumer); + + // New functions + + /** + * Send an ASYNCHRONOUS request to a service. + * In ID-WSF, the request data is a SOAP Body. + * Response message is received either via + * HandleMessageL() or HandleErrorL() callback. + * There are two default frameworks available - + * the Identity Based Web Service Framework (which ID is "ID-WSF") + * and the Basic Web Services Framework (which ID is "WS-I"). + * Please note, that Basic Web Services framework does NOT support this method. + * Instead, one should send complete SOAP envelopes using SendL(CSenSoapEnvelope&). + * So, currently this method is supported only in ID-WSF. + * @param aRequest outgoing request message. + * @return Transaction ID (positive integer) or error code, if method fails. + * Transaction ids: + * Positive integers SendL returns transaction ID of the request, + * which can be later on utilized inside + * HandleMessageL and HandleErrorL methods, + * in order to map request and its response + * together. + * Error codes: + * KErrSenNotInitialized Connection has not been initialized. + * KErrSenServiceConnectionBusy Connection is already busy with another + * request. + * KErrConnectionInitializing Connection is still initializing and + * cannot yet process commands. + * KErrConnectionExpired Credential for the connection is + * expired and needs to be renewed. + * This can be done by instantiating a new + * ServiceConnection. + * KErrSubmitting An error occurred + * KErrNoMemory Not enough memory to process the message. + * Other error codes are system-wide Symbian error codes. + */ + virtual TInt SendL(const TDesC8& aRequest) = 0; + + + /** + * Submit a synchronous request to a service + * (in ID-WSF, the SOAP message Body) and receive a response as XML. + * There are two default frameworks available - + * the Identity Based Web Service Framework (which ID is "ID-WSF") + * and the Basic Web Services Framework (which ID is "WS-I"). + * Please note, that Basic Web Services framework does NOT support this method. + * Instead, one must send complete SOAP envelopes using SubmitL(CSenSoapEnvelope&). + * So, currently this method is supported only in ID-WSF. + * @param aRequest outgoing request message. + * @param aResponse the resolved response message. + * The ownership of the aResponse is transfered to the caller. + * The response is service specific part of the response. + * For ID-WSF services response contents is the SOAP Body, or complete SOAP + * envelope as XML, depending on the complete server messages on/off setting + * (default is off). + * @return status/error code. + * Status codes: + * KErrNone ok + * Error codes: + * KErrSenNotInitialized Connection has not been initialized. + * KErrSenServiceConnectionBusy Connection is already busy with another request. + * KErrConnectionInitializing Connection is still initializing and + * cannot yet process commands. + * KErrConnectionExpired Credential for the connection is + * expired and needs to be renewed. + * This can be done by instantiating a new + * ServiceConnection. + * KErrSubmitting An internal error occurred. + * KErrSenInternal Internal state is invalid. + * Other error codes are system-wide Symbian error codes. + */ + virtual TInt SubmitL(const TDesC8& aRequest, HBufC8*& aResponse) = 0; + + + /** + * Consumer application can use this method to check that + * service connection is in ready state. + * In ID-WSF, this means that WSF interprets that credentials + * for the service connection are valid (not expired). + * @param aReady indicates that the connection is ready to be used. + * @return status/error code. + * Status codes: + * KErrNone ok + * Error codes are system-wide Symbian error codes. + */ + virtual TInt IsReady(TBool& aReady) = 0; + + + /** + * Check if the underlying service connection has a certain characteristic + * called a facet. + * Currently, only ID-WSF framework supports facets. + * For example, if consumer application is interested to resolve if + * initialized service connection has a facet indicating that service + * is free of charge (for e.g. "urn:framework.com.free:cost"), the + * method used to check this would be: + * _LIT8(KFacetOfFreeService, "urn:some.service.free:cost"); + * int err = HasFacetL(KFacetOfFreeService, hasFacet); + * + * In the service session of initialed connection, this would be the form + * of the facet element: + * + * + * If there is no facet in the service connection then the element is not + * present. + * @param aURI the name of the facet + * @param aHasFacet will indicate if underlying service has a certain + * characteristic. + * @return status/error code. + * Status codes: + * KErrNone ok + * Error codes: + * KErrSenNotInitialized Connection has not been initialized. + * KErrConnectionInitializing Connection is still initializing and + * cannot yet process commands. + * KErrConnectionExpired Connection is expired and needs to be + * renewed. + * KErrBadDescriptor The aUri parameter was an invalid + * descriptor. + * Other error codes are system-wide Symbian error codes. + */ + virtual TInt HasFacetL(const TDesC8& aURI, TBool& aHasFacet) = 0; + + + /** + * Consumer application can use this method to set flag which defines + * whether or not the consumer wishes to receive complete SOAP envelope + * from the service. + * If complete server messages mode is off, then only the element + * is received from the SOAP envelope, otherwise full SOAP envelope. + * Note: Calling this function must not be done before connection is + * initialized (the observer's SetStatus() has been called with value + * KSenConnectionStatusReady). + * Calling this function should be done before sending or submitting + * anything. + * @param aCompleteOnOff defines the content of HandleMessageL() callback. + * If set to ETrue (ON), then complete SOAP envelopes are + * received, including
element. + * If set to EFalse (OFF), only the service specific + * content - SOAP envelope element - is received. + * In WSF frameworks the default settings are: + * 1. In ID-WSF, the complete server messages is OFF. + * 2. In Basic Web Services, the default is ON. + * @return status/error code. + * Status codes: + * KErrNone ok + * Error codes: + * KErrSenNotInitialized Connection has not been initialized. + * KErrConnectionInitializing Connection is still initializing and + * cannot yet process commands. + * KErrConnectionExpired Connection is expired and needs to be + * renewed. + * Other error codes are system-wide Symbian error codes. + */ + virtual TInt CompleteServerMessagesOnOff(const TBool& aCompleteOnOff) = 0; + + + /* + * Sends a SOAP message to the service. The SOAP envelope may contain + * proprietary headers. The system will augment the message with the + * appropriate headers specified in the service invocation framework, + * so a client application should add only non-standard headers; and + * if it doesn't need to set such headers it is strongly recommended + * to use SendL(TDesC8&), which is meant for that. + * This is an asynchronous function, that returns immediately. + * When the service responds, the SOAP envelope content will + * be received via HandleMessageL() callback. In case of an + * error - like a SOAP fault - HandleErrorL() will be called + * with appropriate error code. + * There are two default frameworks available - + * the Identity Based Web Service Framework (which ID is "ID-WSF") + * and the Basic Web Services Framework (which ID is "WS-I"). + * Please note, that ID-WSF does NOT support this method. + * Instead, one should send SOAP envelope Bodies using + * SendL(const TDesC8&). + * So, currently this method is supported only in Basic Web Services framework. + * @param aMessage The service specific message - a full SOAP envelope + * @return Transaction ID (positive integer) or error code, if method fails. + * Transaction ids: + * Positive integers SendL returns transaction ID of the request, + * which can be later on utilized inside + * HandleMessageL and HandleErrorL methods, + * in order to map request and its response + * together. + * Error codes: + * KErrSenNotInitialized Connection has not been initialized. + * KErrSenServiceConnectionBusy Connection is already busy with another + * request. + * KErrConnectionInitializing Connection is still initializing and + * cannot yet process commands. + * KErrConnectionExpired Connection is expired and needs to be + * renewed. + * KErrSubmitting An internal error has occurred. + * KErrNoMemory Not enough memory to process the + * message. + * Other error codes are system-wide Symbian error codes. + */ + virtual TInt SendL(CSenSoapEnvelope& aMessage) = 0; + + + /* + * Submits a SOAP message to the service. This is a synchronous call, + * returning a SOAP envelope that was received from the service. + * There are two default frameworks available: + * the Identity Based Web Service Framework (which ID is "ID-WSF") + * and the Basic Web Services Framework (which ID is "WS-I"). + * Please note, that ID-WSF does NOT support this method. + * Instead, one should send SOAP envelope Bodies using SendL(const TDesC8&). + * So, currently this method is supported only in Basic Web Services framework. + * @param aMessage SOAPEnvelope with the service specific message + * without any framework wrapping + * @param aResponseTo This is a ref-to-pointer where response + * from the service will be allocated. If the + * complete server messages mode is set to OFF, + * then only element will be returned, + * otherwise a complete SOAP envelope. + * The ownership of aResponse is transfered to + * the caller. + * @return status/error code + * Status codes: + * KErrNone ok + * Error codes: + * KErrSenNotInitialized Connection has not been initialized. + * KErrSenServiceConnectionBusy Connection is already busy with another + * request. + * KErrConnectionInitializing Connection is still initializing and + * cannot yet process commands. + * KErrConnectionExpired Connection is expired and needs to be + * renewed. + * KErrSubmitting An internal error has occurred. + * KErrNoMemory Not enough memory to process the + * message. + * KErrSenInternal Internal state is invalid. + * Other error codes are system-wide Symbian error codes. + */ + virtual TInt SubmitL(CSenSoapEnvelope& aMessage, HBufC8*& aResponseTo) = 0; + + + /** + * Gets service description of current connection. + * @param aServiceDescription Contains the service description on return + * @return status/error code. + * Status codes: + * KErrNone ok + * Error codes: + * KErrSenNotInitialized Connection has not been initialized. + * KErrSenServiceConnectionBusy Connection is already busy with another + * request. + * KErrConnectionInitializing Connection is still initializing and + * cannot yet process commands. + * KErrConnectionExpired Connection is expired and needs to be + * renewed. + * KErrUnderFlow Server side returned invalid service + * description. + * KErrUnknown Client-Server request mismatch. + * Other error codes are system-wide Symbian error codes. + */ + virtual TInt ServiceDescriptionL(HBufC8*& aServiceDescription) = 0; + + + /** + * Starts an application level transaction. The consumer may now start + * to communicate with some service withing a chain of correlated messages. + * When responding to a certain SOAP message inside a transaction, the last + * received message ID is used as "refToMessageId". + * From default frameworks, only ID-WSF supports transactions. + * @return KErrNone if no errors occur. + * Other error codes are system-wide Symbian error codes. + */ + virtual TInt StartTransaction() = 0; + + + /** + * Stops application level transaction by resetting the "refToMessageId". + * After stopping a transaction the next message will have no + * "refToMessageId" + * @return KErrNone if no errors occur. + * Other error codes are system-wide Symbian error codes. + */ + virtual TInt TransactionCompleted() = 0; + + + /* + * Returns the transasction ID of this message or error. Id is guaranteed + * to return unique ID when called from inside HandleMessageL() or + * HandleErrorL callback. This transasction ID may be used to map the + * response with the preceedeing SendL() call (a request). + * @return TInt transaction ID, or KErrNotFound, if no transaction is + * on-going. + */ + virtual TInt TxnId() = 0; + + + /** + * Sets transport specific properties which apply as long as this connection + * is alive (session). Furthermore, the properties are effective for this session + * in cumulative manner: each property has unique key (name) which is associated + * to the actual value of that property. When SetTransportPropertiesL method is + * called multiple times - in sequence - the last value for each key overrides any + * previous definitions. If any latter call introduces new keys (property names), + * they are appended to the list of currently effective properties. + * Also note, that it is also possible to set message specific properties when making + * a SendL/SubmitL call. If such transport properties for message are provided, and + * those include updates to some properties, the new ones are effective only for that + * certain message, i.e. those are transaction specific. For any following message, + * that is sent over a service connection, the session specific properties apply, + * assuming that the new message does not (again) override some of the property values. + * @param aProperties contains the transport properties in serialized (UTF-8) form. + * With HTTP, this descriptor is typically created by utilizing CSenHttpProperties class. + * @return KErrNone if successful or otherwise some system-wide error code. + */ + virtual TInt SetTransportPropertiesL(const TDesC8& aProperties) = 0; + + + /* + * Method returns currently effective transport properties as a serialized + * descriptor. With HTTP, one may utilize CSenHttpProperities class in + * order to read this data into properties object. Note that returned + * list of properties also includes properties, which are defined as default + * for certain transport in the webservice framework. + */ + virtual TInt TransportPropertiesL(HBufC8*& aProperties) = 0; + + + /** + * Send an ASYNCHRONOUS request to a service. + * In ID-WSF, the request data is a SOAP Body. + * Response message is received either via + * HandleMessageL() or HandleErrorL() callback. + * There are two default frameworks available - + * the Identity Based Web Service Framework (which ID is "ID-WSF") + * and the Basic Web Services Framework (which ID is "WS-I"). + * Please note, that Basic Web Services framework does NOT support this method. + * Instead, one should send complete SOAP envelopes using SendL(CSenSoapEnvelope&). + * So, currently this method is supported only in ID-WSF. + * @param aRequest outgoing request message. + * @param aProperties contains transport spesific properties, serialized + * into descriptor. With HTTP, one can create this by utilizing specialized + * CSenHttpProperties class. + * @return Transaction ID (positive integer) or error code, if method fails. + * Transaction ids: + * Positive integers SendL returns transaction ID of the request, + * which can be later on utilized inside + * HandleMessageL and HandleErrorL methods, + * in order to map request and its response + * together. + * Error codes + * KErrSenNotInitialized Connection has not been initialized. + * KErrSenServiceConnectionBusy Connection is already busy with another + * request. + * KErrConnectionInitializing Connection is still initializing and + * cannot yet process commands. + * KErrConnectionExpired Credential for the connection is + * expired and needs to be renewed. + * This can be done by instantiating a new + * ServiceConnection. + * KErrSubmitting An error occurred + * KErrNoMemory Not enough memory to process the message. + * Other error codes are system-wide Symbian error codes. + */ + virtual TInt SendL(const TDesC8& aRequest, const TDesC8& aProperties) = 0; + + + /** + * Submit a request via SYNCHRONOUS call to a service + * (in ID-WSF, the SOAP message Body) and receive a response as XML. + * There are two default frameworks available - + * the Identity Based Web Service Framework (which ID is "ID-WSF") + * and the Basic Web Services Framework (which ID is "WS-I"). + * Please note, that Basic Web Services framework does NOT support this method. + * Instead, one must send complete SOAP envelopes using SubmitL(CSenSoapEnvelope&). + * So, currently this method is supported only in ID-WSF. + * @param aRequest outgoing request message. + * @param aResponse the resolved response message. + * The ownership of the aResponse is transfered to the caller. + * The response is service specific part of the response. + * For ID-WSF services response contents is the SOAP Body, or complete SOAP + * envelope as XML, depending on the complete server messages on/off setting + * (default is off). + * @param aProperties contains transport spesific properties, serialized + * into descriptor. With HTTP, one can create this by utilizing specialized + * CSenHttpProperties class. + * @return status/error code. + * Status codes: + * KErrNone ok + * Error codes: + * KErrSenNotInitialized Connection has not been initialized. + * KErrSenServiceConnectionBusy Connection is already busy with another request. + * KErrConnectionInitializing Connection is still initializing and + * cannot yet process commands. + * KErrConnectionExpired Credential for the connection is + * expired and needs to be renewed. + * This can be done by instantiating a new + * ServiceConnection. + * KErrSubmitting An internal error occurred. + * KErrSenInternal Internal state is invalid. + * Other error codes are system-wide Symbian error codes. + */ + virtual TInt SubmitL(const TDesC8& aRequest, const TDesC8& aProperties, HBufC8*& aResponse) = 0; + + + /* + * Sends a SOAP message to the service. The SOAP envelope may contain + * proprietary headers. The system will augment the message with the + * appropriate headers specified in the service invocation framework, + * so a client application should add only non-standard headers; and + * if it doesn't need to set such headers it is strongly recommended + * to use SendL(TDesC8&), which is meant for this. + * This is an asynchronous function, that returns immediately. + * When the service responds, the SOAP envelope content will + * be received via HandleMessageL() callback. In case of an + * error - like a SOAP fault - HandleErrorL() will be called + * with appropriate error code. + * There are two default frameworks available - + * the Identity Based Web Service Framework (which ID is "ID-WSF") + * and the Basic Web Services Framework (which ID is "WS-I"). + * Please note, that ID-WSF does NOT support this method. + * Instead, one should send SOAP envelope Bodies using + * SendL(const TDesC8&). + * So, currently this method is supported only in Basic Web Services framework. + * + * NOTE: + * Message is send as serialized XML or Soap message to SendL + * aProperties could be "HTTP GET" or "HTTP DELETE" + * HTTP GET or HTTP DELETE transport property has been enabled via CSenHttpTransportProperties. + * This scenario is not supported + * + * @param aMessage The service specific message - a full SOAP envelope + * @param aProperties contains transport spesific properties, serialized + * into descriptor. With HTTP, one can create this by utilizing specialized + * CSenHttpProperties class. + * @return Transaction ID (positive integer) or error code, if method fails. + * Transaction ids: + * Positive integers SendL returns transaction ID of the request, + * which can be later on utilized inside + * HandleMessageL and HandleErrorL methods, + * in order to map request and its response + * together. + * Error codes: + * KErrSenNotInitialized Connection has not been initialized. + * KErrSenServiceConnectionBusy Connection is already busy with another + * request. + * KErrConnectionInitializing Connection is still initializing and + * cannot yet process commands. + * KErrConnectionExpired Connection is expired and needs to be + * renewed. + * KErrSubmitting An internal error has occurred. + * KErrNoMemory Not enough memory to process the + * message. + * KErrNotSupported HTTP GET or HTTP DELETE is enabled + * Other error codes are system-wide Symbian error codes. + */ + virtual TInt SendL(CSenSoapEnvelope& aMessage, const TDesC8& aProperties) = 0; + + /* + * Submits a SOAP message to the service. This is a synchronous call, + * returning a SOAP envelope that was received from the service. + * There are two default frameworks available: + * the Identity Based Web Service Framework (which ID is "ID-WSF") + * and the Basic Web Services Framework (which ID is "WS-I"). + * Please note, that ID-WSF does NOT support this method. + * Instead, one should send SOAP envelope Bodies using SendL(const TDesC8&). + * So, currently this method is supported only in Basic Web Services framework. + * + * NOTE: + * Message is send as serialized XML or Soap message to SubmitL + * aProperties could be "HTTP GET" or "HTTP DELETE" + * HTTP GET or HTTP DELETE transport property has been enabled via CSenHttpTransportProperties. + * This scenario is not supported + * + * @param aMessage SOAPEnvelope with the service specific message + * without any framework wrapping + * @param aProperties contains transport spesific properties, serialized + * into descriptor. With HTTP, one can create this by utilizing specialized + * CSenHttpProperties class. + * @param aResponseTo This is a ref-to-pointer where response + * from the service will be allocated. If the + * complete server messages mode is set to OFF, + * then only element will be returned, + * otherwise a complete SOAP envelope. + * The ownership of aResponse is transfered to + * the caller. + * @return status/error code + * Status codes: + * KErrNone ok + * Error codes: + * KErrSenNotInitialized Connection has not been initialized. + * KErrSenServiceConnectionBusy Connection is already busy with another + * request. + * KErrConnectionInitializing Connection is still initializing and + * cannot yet process commands. + * KErrConnectionExpired Connection is expired and needs to be + * renewed. + * KErrSubmitting An internal error has occurred. + * KErrNoMemory Not enough memory to process the + * message. + * KErrSenInternal Internal state is invalid. + * KErrNotSupported HTTP GET or HTTP DELETE is enabled + * Other error codes are system-wide Symbian error codes. + */ + virtual TInt SubmitL(CSenSoapEnvelope& aMessage, const TDesC8& aProperties, HBufC8*& aResponseTo) = 0; + + /* + * Sends a SOAP message to the service. The SOAP envelope may contain + * proprietary headers. The system will augment the message with the + * appropriate headers specified in the service invocation framework, + * so a client application should add only non-standard headers. + * This is an asynchronous function, that returns immediately. + * When the service responds, the SOAP envelope content will + * be received via HandleMessageL() callback. In case of an + * error - like a SOAP fault - HandleErrorL() will be called + * with appropriate error code. + * There are two default frameworks available - + * the Identity Based Web Service Framework (which ID is "ID-WSF") + * and the Basic Web Services Framework (which ID is "WS-I"). + * Please note, that ID-WSF does NOT support this method. + * Instead, one should send SOAP envelope Bodies using + * SendL(const TDesC8&). + * So, currently this method is supported only in Basic Web Services framework. + * + * @param aMessage The service specific message - a full SOAP envelope + * @return Transaction ID (positive integer) or error code, if method fails. + * Transaction ids: + * Positive integers SendL returns transaction ID of the request, + * which can be later on utilized inside + * HandleMessageL and HandleErrorL methods, + * in order to map request and its response + * together. + * Error codes: + * KErrSenNotInitialized Connection has not been initialized. + * KErrSenServiceConnectionBusy Connection is already busy with another + * request. + * KErrConnectionInitializing Connection is still initializing and + * cannot yet process commands. + * KErrConnectionExpired Connection is expired and needs to be + * renewed. + * KErrSubmitting An internal error has occurred. + * KErrNoMemory Not enough memory to process the + * message. + * KErrNotSupported HTTP GET or HTTP DELETE is enabled + * Other error codes are system-wide Symbian error codes. + */ + virtual TInt SendL(MSenMessage& aMessage) = 0; + + /* + * Submits a SOAP message to the service. This is a synchronous call, + * returning a SOAP envelope that was received from the service. + * There are two default frameworks available: + * the Identity Based Web Service Framework (which ID is "ID-WSF") + * and the Basic Web Services Framework (which ID is "WS-I"). + * Please note, that ID-WSF does NOT support this method. + * Instead, one should send SOAP envelope Bodies using SendL(const TDesC8&). + * So, currently this method is supported only in Basic Web Services framework. + * + * @param aMessage SOAPEnvelope with the service specific message + * without any framework wrapping + * @param aResponseTo This is a ref-to-pointer where response + * from the service will be allocated. If the + * complete server messages mode is set to OFF, + * then only element will be returned, + * otherwise a complete SOAP envelope. + * The ownership of aResponse is transfered to + * the caller. + * @return status/error code + * Status codes: + * KErrNone ok + * Error codes: + * KErrSenNotInitialized Connection has not been initialized. + * KErrSenServiceConnectionBusy Connection is already busy with another + * request. + * KErrConnectionInitializing Connection is still initializing and + * cannot yet process commands. + * KErrConnectionExpired Connection is expired and needs to be + * renewed. + * KErrSubmitting An internal error has occurred. + * KErrNoMemory Not enough memory to process the + * message. + * KErrSenInternal Internal state is invalid. + * KErrNotSupported HTTP GET or HTTP DELETE is enabled + * Other error codes are system-wide Symbian error codes. + */ + virtual TInt SubmitL(MSenMessage& aMessage, CSenSoapEnvelope2*& aResponseTo) = 0; + + /** + * Getter for currently active transaction (service response) that is + * being handled by the service consumer. + * @return a pointer to currently active transaction (service response). + * It is guarenteed, that the method returns a pointer to + * transaction only when called inside HandleMessageL or + * HandleErrorL callback methods of MSenServiceConsumer, + * otherwise it will return NULL. + */ + virtual MSenMessage* Response() = 0; + + /** + * Cancels any active request, if pending transaction + * (txn) can be found with given txn ID. + * @param aTransactionID is the transaction ID to be cancelled. This id has earlier been + * acquired from a call to some of the asynchronous SendL variants. + + * @return KErrNone on success + * KErrNotFound, if there is no pending transaction (active request), + * or some of the system-wide error codes otheriwise. + */ + virtual TInt CancelTransaction(TInt aTransactionID) = 0; + + /** + * Getter for the identity provider (XML) service description. + * @param apIdentityProvider will point to a new IDP instance, + * if such is associated with this connection (and this connection + * was ready before calling this method), or NULL otherwise. + * @return KErrNone if IDP description can be found, or some + * of the system wide error code otherwise. + */ + virtual TInt IdentityProviderL(CSenIdentityProvider*& apIdentityProvider) = 0; + + /** + * Getter for the identifier of this connection. + * @return the identifier as integer. + */ + virtual TInt Identifier() = 0; + + /** + * Registers observer of BLOBs transfer progress. + * + * @param aFilesObserver Implementation of transfer progress observer. + */ + + protected: + + /** + * C++ default constructor. + */ + CSenServiceConnection(); + + }; + +#endif //SEN_SERVICE_CONNECTION_H + +// End of File +