/*
* 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_PROVIDER_H
#define M_SEN_PROVIDER_H
#include "MSenHostlet.h" // public
// FORWARD DECLARATIONS
class CSenIdentifier;
class MSenServiceDescription;
class CSenWSDescription;
class RCriticalSection;
// CLASS DECLARATION
/**
* Class for delivering SOAP request to WSP and getting back a response
*
*/
class MSenProvider : public MSenHostlet
{
friend class CSenProvider;
friend class CSenLocalRequest;
public:
/**
* Separate session initialization method, which is called when
* some session of certain requester (service consumer) is "attached"
* to this provider. In case of non-sharable provider, this happens
* only once. Method performs some auto-configuration to that session,
* describing the capabilities (facets), that are enabled in this
* provider implementation.
*
* @param aRequestor identifiers the caller of the service. This
* service consumer owns the actual service session. Sharable
* providers may wish to use this information in order to handle
* multiple service-side sessions and to map incoming messages
* to provider's internal state.
*
* @param aSession is a handle to the client side session being served.
* Some providers may want to store some service specific information
* into the session, which further can be utilized by service framework.
* For example, the default implementation for this method typically
* sets some facets into the session, which affect on messaging and
* session handling; provider may indicate, that it is sharable, or
* provider may say, that it wants complete messages instead of message
* bodies by changing pre-defined facets on a session. Framework (session)
* can then recognize these facets and change the way it talks to the provider.
*
* Typically, frameworks should call this method when they find provider
* to be local, in order to fully initialize their client side session
* which represents the provided service.
*
* So, this method is performing "auto-configuration" for service sessions,
* so that caller (session itself) can read these properties of the provider
* from the XML SD (aSession). This way, a deployed provider does not need
* to be followed by explicit Service Management API calls configuring, lets
* say, whether a provider is exposed or not.
*/
// virtual void InitServiceSessionL(MSenServiceDescription& aSession) = 0; // @deprecated: implement inherited MSenHostlet::ServiceDescriptionL instead(!)
// virtual CSenWSDescription* SessionDescriptionLC() = 0; // @deprecated: implement inherited MSenHostlet::ServiceDescriptionL instead(!)
/**
* Provider implementation, which wishes to explicitly expose it's
* service to outside world (outbound requests from network) should
* override this method and make it return ETrue. This would cause
* "expose" facet to be added to service session (SD), granting access
* from otherwise *trusted* requester (access control is done using policies).
* Even trusted identities cannot access providers in the device, if
* they don't explicitly expose their service.
*
* @return boolean indicating whether this provider is exposed
* to any trusted digital identity, which is making requests
* from outside world.
*
* Default implementation typically returns EFalse, which means that
* the provider is meant for local service consumers only.
*/
virtual TBool Exposed() const = 0;
/**
* Provider implementation should override this method and set the
* value to ETrue, if it implements capability to server several
* service consumers (sessions).
*
* @return boolean indicating whether this provider is sharable
* between multiple service consumers (sessions) simultaneously.
* Corresponding facet is KProviderSharableFacet.
*
* Default implementation typically returns EFalse, which means
* that provider is NOT shared between multiple consumers (sessions).
*/
virtual TBool Sharable() const = 0;
/**
* Provider implementation should override this method and set the
* value to ETrue, if it wants to receive complete messages instead
* of plain message bodies (example: full SOAP Envelope vs. SOAP Body).
*
* @return boolean indicating whether this provider wants to receive
* complete messages from a client.
* Corresponding facet is KProviderCompleteClientMsgsFacet.
*
* Default implementation typically returns EFalse, which means that
* provider will receive the body of the message only.
*/
virtual TBool CompleteClientMessages() const = 0;
/**
* Provider implementation should override this method and make it
* return ETrue, if it wants to speed up the run time invocation
* of this provider, performed by certain service consumer. Such
* provider will be recognized and loaded when Core Service Manager
* (WSF server process) starts up. Provider will be de-allocated
* depending whether it is sharable and if it is multi-threaded or not
* - which is similar to how providers behave in any other case, too.
*
* @return boolean indicating whether this provider is loaded on WSF
* startup or not.
* Corresponding facet is KProviderLoadOnStartupFacet.
*
* Default implementation typically returns EFalse, which means that
* provider will not be loaded on WSF main process (Symbian server)
* start-up.
*/
virtual TBool LoadOnStartup() const = 0;
/**
* Provider implementation should override this method and make
* it return EFalse, if it wants to implement multi-threaded,
* non thread-safe ServiceL. This typically means that such providers
* will make use of RCriticalSection inside of their own implementation.
*
* If a provider is sharable *but not* thread-safe, it means, that
* it is possible that multiple requests to ServiceL, from multiple
* consumers are executed simultaneously from separate threads.
* It is strongly recommended to use critical sections inside the
* provider plug-in implementation. This kind of sharable providers
* might be serving under quite heave load. The requesters (threads)
* should be identified by the information available in hostlet request
* interface
*
* Then again, if provider is not sharable *but not* thread-safe,
* it means that multiple request threads from *same service consumer*
* might execute ServiceL simultaneously. Provider implementation should
* therefore offer thread-safe functionality inside ServiceL, possibly via
* use of RCriticalSection instance, or through some other mutex.
*
* @see MSenHostletRequest to figure out ids for requesters / addressees
*
* @return boolean indicating whether this provider is thread-safe or not.
* Corresponding facet is KProviderThreadsafeFacet. Default implementation
* typically returns EFalse, which means that ServiceL of the provider will
* not be called by several threads simultaneously. Threadsafe sharable
* providers have critical section surrounding ServiceL, which prevents
* more than one thread accessing the method simultaneously. Unsharable
* providers are typically loaded only to serve certain request, after
* which they are de-allocated. However, the non thread-safe unsharable
* providers allow multiple request threads of the *same* service consumer
* to execute ServiceL simultaneously.
*/
virtual TBool Threadsafe() const = 0;
/**
* Provider implementation should override this method and make it
* return ETrue, if they are capable of returning their internal state
* to one equal with state that they were right after original construction.
*
* @return ETrue, if ReinitL() will reset this provider, and EFalse, if
* such re-init capability is not implemented (default). Corresponding
* facet is KProviderReinitializableFacet.
*/
virtual TBool Reinitializable() const = 0;
/*
* Provider implementation should override this method and make it
* return ETrue, if they wish to keep any invoked instance on the
* background, after the provider is released. Service consumer
* and it's thread executing the request typically release any unsharable
* provider ECOM instance after response from such is received.
*
* @return ETrue, if provider wants to stay on background as long as WSF
* main process thread is alive (WSF Core Service Manager). Default
* implementation returns EFalse, which allows unloading and de-allocation
* of any "released", non-used provider instances. Corresponding facet is
* KProviderStayOnBackgroundFacet.
*/
virtual TBool StayOnBackground() const = 0;
/**
* Re-init should be implemented by those Hostlets (providers), which
* want to allow that instance to be re-used, that is resetted by the
* invoker. For example, then some component responsible of loading of
* the providers might be able to improve performance of slowly constructed
* providers by calling this method, instead of de-allocating that instance
* and making a ECOM lookup creating a similar, but new instance to same
* service provider endpoint.
* Implementations should thus reset any state variables that they have,
* and set themselves to the state in which they were right after first
* construction. However, some performance benefits can be achieved if
* some class members can be treated as "stateless objects", which can
* be re-used without possibly much slower re-instatiation.
*
* This method is a pair to Reinitializable() function, meaning that when
* one develops such provider which supports reinitialization, that re-init
* should be implemented behind this ReinitL() method.
*
* Default implementation typically does nothing and returns KErrNotSupported,
* since most of the providers don't support re-initialization.
*
* @return KErrNone if this provider instance is successfully reinitialized.
* Otherwise method returns some system-wide error code.
*/
virtual TInt ReinitL() = 0;
/**
* Re-initializable or shared service providers, which instance is being called
* from multiple threads may wish to override this method in order to act on this
* signal and to properly initialize their thread specific components, like those
* which have Thread Local Store (TLS) based implementation.
*
* If the method leaves, it is treaded equally as if the leave occured in the actual
* ServiceL.
*/
//virtual void ThreadInitL(const TDesC& aThreadId) = 0;
/**
* Re-initializable or shared service providers, which instance is being called
* from multiple threads may wish to override this method in order to act on this
* signal and to properly initialize their thread specific components, like those
* which have Thread Local Store (TLS) based implementation.
*/
//virtual void ThreadDestroy(const TDesC& aThreadId) = 0;
private:
RCriticalSection iCriticalSection;
};
#endif
// End of File