/*
* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: Hostlet call back interface
*
*/


#ifndef M_SEN_HOSTLET_H
#define M_SEN_HOSTLET_H

//  INCLUDES
#include <e32base.h> // for CBase
#include <badesca.h>

#include <MSenHostletRequest.h>
#include <MSenHostletResponse.h>
#include <SenXmlServiceDescription.h>
#include <SenServiceConnection.h> 

// FORWARD DECLARE

// CLASS DECLARATION
class MSenHostlet
    {
    public:
        /**
         * Main method for receiving incoming messages, which are typically SOAP / XML,
         * and for providing service for these requests.
         *  @param aRequestUtf8 the request that needs to be be processed by the
         *   hostlet application (local service provider).
         *  @param aResponse is where response data is to be set. 
         *   CSenHostletConnection::ResponsdL should be called 
         *   in order to send the response back to the requester
         *   (service consumer).
         */
        virtual TInt ServiceL(MSenHostletRequest& aRequest, MSenHostletResponse& aResponse) = 0;

        /**
        * Defines the service endpoint for this hostlet
        * @return endpoint that this hostlet has specified. If hostlet
        * implementation does not wish to define any endpoint, but to
        * use contract only, it should return KNullDesC8 (zero-length descriptor).
        * In such case, CSenHostletConnection constructor will attempt to resolve
        * secure identifier (UID3) of the application, and use that to generate
        * a locally unique endpoint. If the UID3 is not available, then the
        * constructor of CSenHostletConnection will leave with the following
        * error code: KErrSenNoContractNoEndPoint     
        *
        * Note: Hostlets, which don't provide endpoint and don't have UID3, cannot 
        * create hostlet connection: instead, CSenHostletConnection constructor
        * will leave with the following code: KErrSenNoContractNoEndPoint
        *
        * If endpoint is not specified, hostlet connection itself
        * will generate an endpoint from applications secure ID (UID3) if such is available,
        * and consumers can invoke the service via the provided contract ("service type" 
        * identifier).
        *
        */
        virtual TPtrC8 Endpoint() const = 0;

        /**
        * Defines the service constract URI for this hostlet
        * @return the URI identifier for the provided service, for example
        * "urn:liberty:id-sis-pp:2003-08". Note that there might be multiple
        * hostlets (local service providers) which all share common service
        * type, that is, they all have same service contract URI.
        *
        * Note: Hostlets, which don't provide endpoint and don't have UID3, cannot 
        * create hostlet connection: instead, CSenHostletConnection constructor
        * will leave with the following error code: KErrSenNoContractNoEndPoint
        */
        virtual TPtrC8 Contract() const = 0;

        /**
        * Defines the framework for this hostlet.
        * @return the framework ID. Default inline implementation 
        * returns RESTful service invocation framework ID, 
        * KDefaultRestServicesFrameworkID, as defined in SenServiceConnection.h
        */
        inline virtual TPtrC8 FrameworkId() const { return KDefaultRestServicesFrameworkID(); }

        /**
        * Each Hostlet implementation may further describes its service via this callback.
        * @param aSD is the description, where service specific attributes can be defined.
        * Default, inline implementation sets the endpoint, contract and framework ID
        * by calling the other, more simple callbacks.
        *
        * It is mandatory for each hostlet to define either endpoint or contract.
        * Otherwise, the constuctor of CSenHostletConnection will leave with the
        * following error code:
        *     KErrSenNoContractNoEndPoint - neither endpoint or contract was 
        *     specified. This is illegal, since the service would lack an identifier. 
        * 
        * @param aSD is the service description into which this hostlet may further
        * define other service specific information, like facets. Note that this 
        * call back is "stronger" than Endpoint() and Contract(), and thus any
        * value specified in this method will be in effect for the hostlet connection.
        */
        inline virtual void DescribeServiceL(CSenXmlServiceDescription& aSD) 
            { 
            aSD.SetEndPointL(Endpoint());
            aSD.SetContractL(Contract()); 
            aSD.SetFrameworkIdL(FrameworkId());
            } 

        /**
        * This callback function is invoked each time when any hostlet connection's
        * asynchronous RespondL is completed. Method can be used to trigger the 
        * release of some response releated system resources, as it is invoked 
        * after the response has been delivered to the consumer (application
        * may wish to close handles to reserved file or memory).
        *
        * @param aTxnId identifies what transaction (service message) was completed
        * @param aCompletionCode indicates whether transaction completed ok (KErrNone)
        * or not (error code).
        * @param aDesc may provide additional information about completed transaction,
        * typically this description is provided, if an error has occured.
        * It is optional for hostlet implementation to implement this method. 
        */
        inline virtual void OnServiceCompleteL(TInt /* aTxnId */, 
                                               TInt /* aCompletionCode */, 
                                               const TDesC8& /* aDesc*/ ) { ; }
                                             
				/**
        * Hostlet connection calls this method several times, passing a different
        * UID per each call. If application wants to provide particular interface
        * to hostlet connection (web services stack), it needs to return a pointer
        * to such M-class as a return value of this method. For any interface, that
        * application has not implemented, it is supposed to return NULL.
        * @param aUID is the unique identifier of some interface
        * @return value should be a valid (void) pointer to any interface implemented
        * by the application. NULL signalizes that application does not provide interface
        * for give UID. 
        */    
	    inline virtual TAny* GetInterfaceByUid( TUid /* aUID */ ) { return NULL; };                                             
    };


#endif // M_SEN_HOSTLET_H

// End of File