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