/*

* Copyright (c) 2005-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:  CMnServiceBase class

*

*/

#ifndef MN_SERVICEBASE_H

#define MN_SERVICEBASE_H

class CPosLandmark;

/** @brief Base class for all Map and Navigation services.

 *

 *  Its only purpose is to provide common base functionality for Map and Navigation

 *  service classes.

 *

 *  There are both synchronous and asynchronous request handlers defined in derived

 *  service base classes. Implementations of handlers shall behave as follows.

 *  <ul>

 *  <li>For Synchronous requests:</li>

 *  <ul>

 *  <li>Exit normally to report successful completion</li>

 *  <li>Leave with error code to report error</li>

 *  </ul>

 *  <li>For Asynchronous requests:</li>

 *  <ul>

 *  <li>Exit normally as soon as possible. Call dedicated Complete method

 *      to report successful completion</li>

 *  <li>Leave with error code to report error found during execution of

 *      Handle method</li>

 *  <li>Call CompleteRequest method with error code to report error

 *      found after execution of Handle method</li>

 *  <li>Call CancelRequest method to report that user has cancelled

 *      execution</li>

 *  </ul>

 *  </ul>

 *

 *  Following error codes shall be used by implementation to report specific cases:

 *  - KErrCancel - If user has cancelled operation.

 *  - KErrArgument - If given argument cannot be used for operation. For example, landmark has

 *          no coordinate or address and cannot be shown on map or address information

 *          is not sufficient for geocoding.

 *  - KErrNotSupported - If service feature is not supported, or cannot be executed with given parameters.

 *          For example, map content not available for specified area etc.

 *

 *  @since 3.1

 *  @lib mnservicelib.lib

 *  @ingroup MnProviderAPI

 */

class CMnServiceBase : public CAknAppServiceBase

    {

    public :

        /** @brief Completes current asynchronous request.

         *

         *  Called by implementations to complete client's request. Used

         *  by service implementations to report errors during execution

         *  of asynchronous requests. To report successful completion,

         *  special methods defined by service base classes should be used

         *  (e.g. @ref CMnMapViewServiceBase::CompleteSelectionRequest)

         *

         *  For synchronous requests, handler should

         *  just leave if error is detected.

         *

         *  @param aResult Error code.

         *

         *  @panic "MnPanicServer"-KMnPanicAttemptToCompleteNoRequest

         *      This method called during execution of synchronous request.

         */

        IMPORT_C void CompleteRequest( TInt aResult );

    protected :

        /** C++ constructor */

        CMnServiceBase();

        /** Destructor */

        ~CMnServiceBase();

        /** \internal */

        void BaseConstructL();

        /** @brief Reports that client cancelled request.

         *

         *  Called by framework to report that request was

         *  cancelled by client application. Service implementations

         *  must implement this method. It is not needed to call

         *  @ref CompleteRequest() in this case.

         */

        virtual void DoCancel() =0;

    protected: // internal methods

        /** \internal

         *  Completes client's message

         */

        void Complete( const RMessage2& aMsg, TInt aResult );

        /** \internal

         *  Informs derived implementation (by calling DoCancel())

         *  that current async request has been cancelled by client and

         *  completes it with KErrCancel.

         */

        void HandleCancelRequestL( const RMessage2& aMsg );

        /** \internal

        * Copies an 8-bit buffer from the address space of the client and puts

        * the result in the returned argument.

        *

        * @param aMessage the message from the client.

        * @param aClientBufferParam index of message parameter to read as buffer

        * @return a copy of the client buffer.

        */

        static HBufC8* CopyClientBuffer8LC(

            const RMessage2& aMessage,

            const TInt aClientBufferParam );

        /** \internal

        * Copies a 16-bit buffer from the address space of the client and puts

        * the result in the returned argument.

        *

        * @param aMessage the message from the client.

        * @param aClientBufferParam index of message parameter to read as buffer

        * @return a copy of the client buffer.

        */

        static HBufC* CopyClientBufferLC(

            const RMessage2& aMessage,

            const TInt aClientBufferParam );

        /** \internal

         *  Unpacks landmark from client's message.

         *  @param  aMsg client's message

         *  @param  aParamIndex index of landmark parameter in message

         *  @return new copy instance of client's landmark

         */

        CPosLandmark* UnpackLandmarkLC( const RMessage2& aMsg, TInt aParamIndex );

        /** @internal */

        TInt CurrentAsyncRequest();

        /** @internal */

        TBool IsAsyncRequestActive();

        /** @internal */

        void PrepareAsyncRequestL( const RMessage2& aMessage );

    protected:  // from CApaAppServiceBase

        /** @internal */

        IMPORT_C void ServiceError( const RMessage2 &aMessage, TInt aError );

    protected:

        RMessage2   iMessage;

    private:

        TInt        iCurrentRequest;

    };

#endif // MN_SERVICEBASE_H