1 /*

     2 * Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: Header declaration

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 

    22 

    23 

    24 

    25 #ifndef M_SEN_PROVIDER_H

    26 #define M_SEN_PROVIDER_H

    27 

    28 #include "MSenHostlet.h" // public

    29 

    30 // FORWARD DECLARATIONS

    31 class CSenIdentifier;

    32 class MSenServiceDescription;

    33 class CSenWSDescription;

    34 class RCriticalSection;

    35 

    36 // CLASS DECLARATION

    37 

    38 /**

    39 * Class for delivering SOAP request to WSP and getting back a response

    40 *

    41 */       

    42 class MSenProvider : public MSenHostlet

    43     {

    44     friend class CSenProvider;

    45     friend class CSenLocalRequest;

    46 

    47     public: 

    48         /**

    49         * Separate session initialization method, which is called when

    50         * some session of certain requester (service consumer) is "attached"

    51         * to this provider. In case of non-sharable provider, this happens

    52         * only once. Method performs some auto-configuration to that session,

    53         * describing the capabilities (facets), that are enabled in this 

    54         * provider implementation.

    55         *

    56         * @param aRequestor identifiers the caller of the service. This

    57         * service consumer owns the actual service session. Sharable

    58         * providers may wish to use this information in order to handle

    59         * multiple service-side sessions and to map incoming messages

    60         * to provider's internal state.

    61         *

    62         * @param aSession is a handle to the client side session being served.

    63         * Some providers may want to store some service specific information

    64         * into the session, which further can be utilized by service framework.

    65         * For example, the default implementation for this method typically

    66         * sets some facets into the session, which affect on messaging and

    67         * session handling; provider may indicate, that it is sharable, or

    68         * provider may say, that it wants complete messages instead of message

    69         * bodies by changing pre-defined facets on a session. Framework (session)

    70         * can then recognize these facets and change the way it talks to the provider.

    71         *

    72         * Typically, frameworks should call this method when they find provider

    73         * to be local, in order to fully initialize their client side session 

    74         * which represents the provided service.

    75         *

    76         * So, this method is performing "auto-configuration" for service sessions,

    77         * so that caller (session itself) can read these properties of the provider

    78         * from the XML SD (aSession). This way, a deployed provider does not need

    79         * to be followed by explicit Service Management API calls configuring, lets

    80         * say, whether a provider is exposed or not.

    81         */

    82         

    83 

    84         // virtual void InitServiceSessionL(MSenServiceDescription& aSession) = 0; // @deprecated: implement inherited MSenHostlet::ServiceDescriptionL instead(!)

    85     	// virtual CSenWSDescription* SessionDescriptionLC() = 0; // @deprecated: implement inherited MSenHostlet::ServiceDescriptionL instead(!)

    86     

    87         /**

    88         * Provider implementation, which wishes to explicitly expose it's

    89         * service to outside world (outbound requests from network) should

    90         * override this method and make it return ETrue. This would cause 

    91         * "expose" facet to be added to service session (SD), granting access 

    92         * from otherwise *trusted* requester (access control is done using policies).

    93         * Even trusted identities cannot access providers in the device, if 

    94         * they don't explicitly expose their service.

    95         *

    96         * @return boolean indicating whether this provider is exposed

    97         * to any trusted digital identity, which is making requests

    98         * from outside world.

    99         *

   100         * Default implementation typically returns EFalse, which means that

   101         * the provider is meant for local service consumers only.

   102         */

   103         virtual TBool Exposed() const = 0;

   104         

   105         /**

   106         * Provider implementation should override this method and set the

   107         * value to ETrue, if it implements capability to server several 

   108         * service consumers (sessions). 

   109         *

   110         * @return boolean indicating whether this provider is sharable

   111         * between multiple service consumers (sessions) simultaneously.

   112         * Corresponding facet is KProviderSharableFacet.

   113         *

   114         * Default implementation typically returns EFalse, which means

   115         * that provider is NOT shared between multiple consumers (sessions).

   116         */

   117         virtual TBool Sharable() const = 0;    

   118     

   119         /**

   120         * Provider implementation should override this method and set the

   121         * value to ETrue, if it wants to receive complete messages instead

   122         * of plain message bodies (example: full SOAP Envelope vs. SOAP Body).

   123         *

   124         * @return boolean indicating whether this provider wants to receive

   125         * complete messages from a client.

   126         * Corresponding facet is KProviderCompleteClientMsgsFacet.

   127         *

   128         * Default implementation typically returns EFalse, which means that

   129         * provider will receive the body of the message only.

   130         */

   131         virtual TBool CompleteClientMessages() const = 0;

   132 

   133         /**

   134         * Provider implementation should override this method and make it

   135         * return ETrue, if it wants to speed up the run time invocation

   136         * of this provider, performed by certain service consumer. Such

   137         * provider will be recognized and loaded when Core Service Manager

   138         * (WSF server process) starts up. Provider will be de-allocated

   139         * depending whether it is sharable and if it is multi-threaded or not

   140         * - which is similar to how providers behave in any other case, too.

   141         *

   142         * @return boolean indicating whether this provider is loaded on WSF

   143         * startup or not.

   144         * Corresponding facet is KProviderLoadOnStartupFacet.

   145         *

   146         * Default implementation typically returns EFalse, which means that

   147         * provider will not be loaded on WSF main process (Symbian server)

   148         * start-up.

   149         */

   150         virtual TBool LoadOnStartup() const = 0;

   151 

   152         /**

   153         * Provider implementation should override this method and make

   154         * it return EFalse, if it wants to implement multi-threaded,

   155         * non thread-safe  ServiceL. This typically means that such providers

   156         * will make use of RCriticalSection inside of their own implementation.

   157         *

   158         * If a provider is sharable *but not* thread-safe, it means, that

   159         * it is possible that multiple requests to ServiceL, from multiple 

   160         * consumers are executed simultaneously from separate threads.

   161         * It is strongly recommended to use critical sections inside the

   162         * provider plug-in implementation. This kind of sharable providers

   163         * might be serving under quite heave load. The requesters (threads)

   164         * should be identified by the information available in hostlet request

   165         * interface

   166         *

   167         * Then again, if provider is not sharable *but not* thread-safe,

   168         * it means that multiple request threads from *same service consumer* 

   169         * might execute ServiceL simultaneously. Provider implementation should

   170         * therefore offer thread-safe functionality inside ServiceL, possibly via

   171         * use of RCriticalSection instance, or through some other mutex.

   172         *

   173         * @see MSenHostletRequest to figure out ids for requesters / addressees

   174         *

   175         * @return boolean indicating whether this provider is thread-safe or not.

   176         * Corresponding facet is KProviderThreadsafeFacet. Default implementation

   177         * typically returns EFalse, which means that ServiceL of the provider will

   178         * not be called by several threads simultaneously. Threadsafe sharable 

   179         * providers have critical section surrounding ServiceL, which prevents 

   180         * more than one thread accessing the method simultaneously. Unsharable 

   181         * providers are typically loaded only to serve certain request, after 

   182         * which they are de-allocated. However, the non thread-safe unsharable 

   183         * providers allow multiple request threads of the *same* service consumer

   184         * to execute ServiceL simultaneously.

   185         */

   186         virtual TBool Threadsafe() const = 0;

   187 

   188         /** 

   189         * Provider implementation should override this method and make it 

   190         * return ETrue, if they are capable of returning their internal state

   191         * to one equal with state that they were right after original construction.

   192         *

   193         * @return ETrue, if ReinitL() will reset this provider, and EFalse, if

   194         * such re-init capability is not implemented (default). Corresponding

   195         * facet is KProviderReinitializableFacet.

   196         */

   197         virtual TBool Reinitializable() const = 0;

   198 

   199         /*

   200         * Provider implementation should override this method and make it

   201         * return ETrue, if they wish to keep any invoked instance on the

   202         * background, after the provider is released. Service consumer 

   203         * and it's thread executing the request typically release any unsharable

   204         * provider ECOM instance after response from such is received.

   205         *

   206         * @return ETrue, if provider wants to stay on background as long as WSF

   207         * main process thread is alive (WSF Core Service Manager). Default

   208         * implementation returns EFalse, which allows unloading and de-allocation

   209         * of any "released", non-used provider instances. Corresponding facet is

   210         * KProviderStayOnBackgroundFacet.

   211         */

   212         virtual TBool StayOnBackground() const = 0;

   213         

   214         /**

   215         * Re-init should be implemented by those Hostlets (providers), which

   216         * want to allow that instance to be re-used, that is resetted by the

   217         * invoker. For example, then some component responsible of loading of

   218         * the providers might be able to improve performance of slowly constructed

   219         * providers by calling this method, instead of de-allocating that instance

   220         * and making a ECOM lookup creating a similar, but new instance to same

   221         * service provider endpoint.

   222         * Implementations should thus reset any state variables that they have, 

   223         * and set themselves to the state in which they were right after first

   224         * construction. However, some performance benefits can be achieved if 

   225         * some class members can be treated as "stateless objects", which can

   226         * be re-used without possibly much slower re-instatiation.

   227         *

   228         * This method is a pair to Reinitializable() function, meaning that when

   229         * one develops such provider which supports reinitialization, that re-init 

   230         * should be implemented behind this ReinitL() method.

   231         *

   232         * Default implementation typically does nothing and returns KErrNotSupported,

   233         * since most of the providers don't support re-initialization.

   234         *

   235         * @return KErrNone if this provider instance is successfully reinitialized.

   236         *         Otherwise method returns some system-wide error code.

   237         */

   238         virtual TInt ReinitL() = 0;

   239 

   240         /**

   241         * Re-initializable or shared service providers, which instance is being called

   242         * from multiple threads may wish to override this method in order to act on this

   243         * signal and to properly initialize their thread specific components, like those 

   244         * which have Thread Local Store (TLS) based implementation.

   245         * 

   246         * If the method leaves, it is treaded equally as if the leave occured in the actual

   247         * ServiceL.

   248         */

   249         //virtual void ThreadInitL(const TDesC& aThreadId) = 0;

   250 

   251         /**

   252         * Re-initializable or shared service providers, which instance is being called

   253         * from multiple threads may wish to override this method in order to act on this

   254         * signal and to properly initialize their thread specific components, like those 

   255         * which have Thread Local Store (TLS) based implementation.

   256         */

   257         //virtual void ThreadDestroy(const TDesC& aThreadId) = 0;

   258 

   259 

   260     private:

   261         RCriticalSection iCriticalSection;

   262     };

   263 

   264 

   265 #endif 

   266 

   267 // End of File