/*
* Copyright (c) 2006 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:        Defines the ECOM interface for Handler plug-in implementation
*
*/








#ifndef SEN_SESSION_HANDLER_H
#define SEN_SESSION_HANDLER_H

// INCLUDES
#include <ecom/ecom.h>

#include "senhandlerbase.h"     // internal Framework\inc
#include "msenhandlercontext.h" // internal Framework\inc
#include "msensessioncontext.h" // internal Framework\inc

// CLASS DECLARATION

/**
* Custom ECOM interface definition. This interface is used by
* clients to find specific handler plugins which implement 
* pure virtual functions defined in MSenTranport interface.
*/
class CSenSessionHandler : public CSenHandlerBase
    {
    public:
        
        // Constructors and destructor:

        /**
        * Wraps ECom object instantiation, which returns the
        * default ECOM implementation for this interface.
        * Note: This is not a "normal" NewL method, since 
        * normally NewL methods are only defined for concrete
        * classes. Note that the implementations of this interface
        * also provide NewL methods.
        * 
        * Additionally, this static constructor performs InitL()
        * using the provided handler context for the newly allocated
        * handler instance.
        *
        * @param aCtx is handle to the handler specific context
        */
        static CSenSessionHandler* NewL(MSenHandlerContext& aCtx);

        /**
        * Wraps ECom object instantitation, which returns the
        * interface implementation matching to given aCue,
        * IMPLEMENTATION_INFO::default_data.
        * For details, see EcomSIFDefinition.inl comments.
        * Note: This is not a "normal" NewL method, since normally NewL
        * methods are only defined for concrete classes.
        * Note that the implementations of this interface 
        * also provide NewL methods. 
        *
        * Additionally, this static constructor performs InitL()
        * using the provided handler context for the newly allocated
        * handler instance.
        *
        * @param aCue is the "name" of the requested implementation.
        *             Implementations advertise their cue as specified
        *             in their resource file field
        * @param aCtx is handle to the handler specific context
        */
        static CSenSessionHandler* NewL(const TDesC8& aCue,
                                        MSenHandlerContext& aCtx);
        /**
        * Destructor.
        */
        virtual ~CSenSessionHandler();

        // From MSenHandler:
        /**
        * Method is used to resolve concrete type (class)
        * for this handler instance.
        * 
        * @return the class type of this handler
        */
        inline SenHandler::THandlerType Type() const;        
        /**
        * Method is used to resolve real, system-wide
        * unique name for this handler. By default, this
        * typically returns the ECOM cue (default_data)
        * of the concrete plug-in instance.
        * 
        * @return the unique name of this handler
        */
        inline TPtrC8 Name() const;        
        

        // New functions:
        
        /**
        * InvokeL is the most emergent method in message handler interface.
        * Each sub-class must implement this method thus providing message
        * processing routine.
        * 
        * @param aCtx is the session context that will be accessed and 
        * typically altered by implemented handler, in order to provide
        * modifications on the layer of the session construction, validation,
        * or some other, focused area that the handler was intended to take
        * responsibility for. For example, certain handler can itself create
        * a session of its own, send message(s) to (authentication) service
        * (invoking other handlers), and finally access session context in 
        * order to update credentials. One example of such session handler
        * could be WS-TRUST client type handler, an "internal service consumer".
        * @return KErrNone or some WSF specific, or system-wide error code
        */
        virtual TInt InvokeL(MSenSessionContext& aCtx) = 0;

    protected:

        /**
        * C++ default constructor.
        * 
        * @param aCtx is handle to the handler specific context
        */
        CSenSessionHandler(MSenHandlerContext& aCtx);

    protected: // Data
        MSenHandlerContext& iHandlerContext;    

    private: // Data
        /** 
        * Instance identifier key. When instance of an implementation is created 
        * by ECOM framework, the framework will assign UID for it. 
        * The UID is used in destructor to notify framework that this instance is
        * being destroyed and resources can be released.
        */
        TUid iDtor_ID_Key;
        
        HBufC8* iName;
    };

// This includes the implementation of the instantiation functions and destructor
#include "sensessionhandler.inl"

#endif // SEN_SESSION_HANDLER_H

// End of File