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