diff -r 000000000000 -r 62f9d29f7211 webservices/wsframework/inc/msenremoteservicesession.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/webservices/wsframework/inc/msenremoteservicesession.h Thu Jan 07 16:19:19 2010 +0200 @@ -0,0 +1,348 @@ +/* +* 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 "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: Header declaration +* +*/ + + + + + + + + +#ifndef M_SEN_REMOTE_SERVICE_SESSION +#define M_SEN_REMOTE_SERVICE_SESSION + + +/* + * MSenRemoteServiceSession is a non-public remote interface that is only + * implemented by the CSenServiceSession class. The methods of this interface + * are called upon by instances of CSenClientSession. + * + * @see RService in Java reference implementation (2005) - regardless of + * name-mismatch methods of this interface *equal* with RService. + * +*/ + +// INCLUDES +#include "MSenServiceDescription.h" +#include "msentransport.h" +#include "MSenFragment.h" + +// FORWARD DECLARE +class CSenTransportBase; +class MSenRemoteServiceConsumer; +class MSenRemoteHostlet; +class CSenChunk; + +//enum TDescriptionClassType; + + +// CLASS DECLARATION +class MSenRemoteServiceSession //: public MSenFragment + { + public: + + // New functions + + virtual MSenServiceDescription& AsServiceDescription() = 0; + /* + * + * + * + */ + virtual void WriteAsXMLToL(RWriteStream& aWriteStream) = 0; + + + /* + * StatusL() will compute and return the status code. + * + * @return current status of this service session. Basic + * constants are defined in public MSenServiceConsumer.h: + * + * KSenConnectionStatusNew Connection is being initialized, but not yet ready. + * KSenConnectionStatusReady Connection is ready to be used. For example, SubmitL() + * and SendL() methods (depending of framework) are in + * invocable state. + * KSenConnectionStatusExpired Connection is expired. Typically, a new connection + * needs next to be initialized in order to communicate + * with the underlying service behind this service + * connection. + * If any error should occur in this method, it leaves. + * + */ + virtual TInt StatusL() = 0; + + /* + * Method synchronously submits a message to (remote) service + * via the transport of this session. Method will block until + * the response is received. + * + * @param aMessage is the actual request body to be sent to + * the remote service via the transport of this session. + * @param aTransportProperties are the properties to be passed + * to the transport. Transport properties further define + * how the message should be carried out to the service + * provider. In HTTP transport's case, properties could + * dictate what HTTP method, header(s) and proxy params + * are to be used in the transport layer. + * @param aConsumer is a reference to the actual caller of the + * service, which is consuming this session. Transport + * might be interested to resolve identifier, and other + * aspects of the consumer via this handle. + * @param aResponse is reference to a pointer where transport + * is expected to reserve memory for tha actual response. + * @return KErrNone if submit is successfull or otherwise some + * system-wide error code. + */ + virtual TInt SubmitL(const TDesC8& aMessage, + const TDesC8& aTransportProperties, + MSenRemoteServiceConsumer& aConsumer, + HBufC8*& aResponse) = 0; + + /* + * Method asynchronously sends a message to (remote) service + * via the transport of this session. Function will typically + * return almost immediately, since the service response will + * be received via spesific callback methods. + * + * @param aMessage is the actual request body to be sent to + * the remote service via the transport of this session. + * @param aTransportProperties are the properties to be passed + * to the transport. Transport properties further define + * how the message should be carried out to the service + * provider. In HTTP transport's case, properties could + * dictate what HTTP method, header(s) and proxy params + * are to be used in the transport layer. + * @param aConsumer is a reference to the actual caller of the + * service, which is consuming this session. Transport + * might be interested to resolve identifier, and other + * aspects of the consumer via this handle. + * @param aTxnId is reference to transaction id, + * to be set by the transport to identify + * this request. + * @param aRevalidationError contains error / SOAP Fault from + * authentication service (like WS-* STS or Liberty AS / IDP) + * @return KErrNone if send is successfull or otherwise some + * system-wide error code. + */ + virtual TInt SendL( const TDesC8& aMessage, + const TDesC8& aTransportProperties, + MSenRemoteServiceConsumer& aConsumer, + TInt& aTxnId, + HBufC8*& aRevalidationError ) = 0; + + /* + * Method synchronously submits a message to (remote) service + * via the transport of this session. + * + * @param aSoapMessage is the actual request body - a SOAP + * envelope, which is to be sent to remote service + * via the transport of this session. + * @param aTransportProperties are the properties to be passed + * to the transport. Transport properties further define + * how the message should be carried out to the service + * provider. In HTTP transport's case, properties could + * dictate what HTTP method, header(s) and proxy params + * are to be used in the transport layer. + * @param aConsumer is a reference to the actual caller of the + * service, which is consuming this session. Transport + * might be interested to resolve identifier, and other + * aspects of the consumer via this handle. + * @param aResponse is reference to a pointer where transport + * is expected to reserve memory for tha actual response. + * @return KErrNone if submit is successfull or otherwise some + * system-wide error code. + */ + virtual TInt SubmitSoapL(const TDesC8& aSoapMessage, + const TDesC8& aTransportProperties, + MSenRemoteServiceConsumer& aConsumer, + HBufC8*& aResponse) = 0; + /* + * Method asynchronously sends a message to (remote) service + * via the transport of this session. Function will typically + * return almost immediately, since the service response will + * be received via spesific callback methods. + * + * @param aSoapMessage is the actual request body - a SOAP + * envelope, which is to be sent to remote service + * via the transport of this session. + * @param aTransportProperties are the properties to be passed + * to the transport. Transport properties further define + * how the message should be carried out to the service + * provider. In HTTP transport's case, properties could + * dictate what HTTP method, header(s) and proxy params + * are to be used in the transport layer. + * @param aConsumer is a reference to the actual caller of the + * service, which is consuming this session. Transport + * might be interested to resolve identifier, and other + * aspects of the consumer via this handle. + * @param aTxnId is reference to transaction id, + * to be set by the transport to identify + * this request. + * @param aRevalidationError contains error / SOAP Fault from + * authentication service (like WS-* STS or Liberty AS / IDP) + * @return KErrNone if send is successfull or otherwise some + * system-wide error code. + */ + virtual TInt SendSoapL( const TDesC8& aSoapMessage, + const TDesC8& aTransportProperties, + MSenRemoteServiceConsumer& aConsumer, + TInt& aTxnId, + HBufC8*& aRevalidationError ) = 0; + + + /** + * Method checks if this session is ready to interact with (remote) + * service. Typically, if service invocation framework requires + * credentials, they are checked inside this method. +< * @return boolean indicating if this session is ready (ETrue) or + * not (EFalse) to interact with (possibly remote) service. + */ + virtual TBool IsReadyL() = 0; + + virtual TInt HasFacetL(const TDesC8& aURI, TBool& aHasFacet) = 0; + virtual TInt FacetValue(TDesC8& aURI, HBufC8*& aValueTo) = 0; + virtual TInt CompleteServerMessagesOnOffL(const TBool& aCompleteOnOff) = 0; + virtual TPtrC8 Endpoint() = 0; + virtual TPtrC8 Contract() = 0; + virtual TPtrC8 FrameworkId() = 0; + virtual void StartTransaction() = 0; + virtual void TransactionCompleted() = 0; + virtual MSenServiceDescription::TDescriptionClassType DescriptionClassType() = 0; + + /** + * Method is used to apply transport properties for this service session. + * In basic implementation, the properties information is passed to + * transport of this session. + * @param aProperties contains transport properties properties as descriptor + * @param aConsumer is the "actor", typically the remote consumer which is + * invoking this method. + * @return KErrNone if successful, or otherwise some system-wide error code + */ + virtual TInt SetTransportPropertiesL(const TDesC8& aProperties, + MSenRemoteServiceConsumer& aConsumer) = 0; + + virtual TInt TransportPropertiesL(HBufC8*& aProperties, + MSenRemoteServiceConsumer& aConsumer) = 0; + + + + /** + * Sets the transport plug-in instance, + * passing the ownership to this + * session. + * @param aTransport is the new transport for this session. + * Note that if a Transport instance is already owned, it + * will be deleted. + */ + virtual void SetTransportL(CSenTransportBase* aTransport) = 0; + + /** + * Getter for currently effective transport instance. + * It is strongly recommended, that service sessions + * themselves acquire transport via TransportL -variant, + * which is capable of factoring a transport in case + * that it does not exist already. + * @return currently set transport, or NULL + * + */ + virtual MSenTransport* Transport() const = 0; + + /** + * Returns the transport of this session. If transport is not + * yet known (owned), an attempt to create a transport for this + * session will be performed, and this attempt may result this + * method to leave. + * @param aRequestor is the consumer of this session, which is + * about to utilize the transport of this session. + * Leaves with system-wide error code in case that a new transport + * cannot be instantiated. + */ + virtual MSenTransport& TransportL(MSenRemoteServiceConsumer& aRequestor) = 0; + + /** + * Sets the hostlet for this session. HostletConnection server-side + * sessions (CSenClientSessions) call this method in order to provide + * their own reference to session, which can be utilized by HostletTransport + * plug-ins, so that the messages from remote service consumers can be routed. + * @param aHostlet is a reference to MSenRemoteHostlet implementation, typically + * to CSenClientSession class. Note that it is perfectly legal to pass + * NULL as aHostlet - that call just means, that any existing MSenRemoteHostlet + * will be "unset" / detached from this session. + * @return KErrNone if successful, or otherwise some system-wide error code. + * Method may leave, if aHostlet is found invalid. + */ + virtual TInt SetHostletL(MSenRemoteHostlet* aHostlet) = 0; + + + virtual MSenRemoteHostlet* Hostlet() const = 0; + + /** + * Removes a service consumer from this session. + * + * Removed consumer will no longer receive any callbacks + * from the service provider it used to communicate with. + * Typically, MSenRemoteServiceConsumer implementations call + * this method from their destructors. When the count of + * session consumers is decreased to zero, and session + * does not hold any reference to a MSenRemoteHostlet either + * the default implementation provided in here will also + * delete the associated transport plug-in instance, in order + * to save (memory, messaging stack etc) resources . + * @param aConsumer is the service consumer to be removed. + * @return positive index of successfully removed consumer or + * KErrNotFound - if consumer was not found + */ + virtual TInt RemoveConsumerL(MSenRemoteServiceConsumer& aConsumer) = 0; + + /** + * This method is invoked by WS-stack Core on each call to + * CSenHostletConnection::RespondL. The typical implementation + * in service session class will use associated transport plug-in + * to complete the pending transaction. If contents of the message + * do not require any modification, then the session can rely that + * the response set by the hostlet application (MSenHostlet) is + * already in place. If there is need to modify the response in + * SIF spesific way, then the message can be resolved using the + * txn ID (before completing this transaction). + * @param aProvider is the interface to the hostlet that is providing + * this response -- via RespondL issued inside (or after) + * MSenHostlet::ServiceL. + * @param aTxnId is the transaction ID of this request/response pair + * @param aServiceCode is the code that was set to MSenHostletResponse + * by the hostlet application + * @param aRecipientsConsumerId may be used to resolve interested + * service consumer, which issued the request to the hostlet + * @param aMessageChunk contains the message as raw 8-bit data, + * plus it's other properties + * @return TInt KErrNone on success, or otherwise some of the system-wide + * error codes. + */ + virtual TInt ProvideHostletResponseL(MSenRemoteHostlet& aProvider, + const TInt aTxnId, + const TInt aServiceCode, + const TDesC8& aRecipientsConsumerId, + CSenChunk& aMessageChunk) = 0; + + + //virtual HBufC8* AsXmlL() = 0; + + //virtual TInt SignMessages(const TDesC8& aAlgoritm, + // const TDesC8& aSigningKey) = 0; + }; +#endif // M_SEN_REMOTE_SERVICE_SESSION + +