--- /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
+
+