--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/webservices/wsframework/inc/msenprovider.h Thu Jan 07 16:19:19 2010 +0200
@@ -0,0 +1,267 @@
+/*
+* 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