--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/locsrv_plat/map_and_navigation_provider_api/inc/mnservicebase.h Tue Feb 02 01:06:48 2010 +0200
@@ -0,0 +1,169 @@
+/*
+* 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
+
+#include <aknserverapp.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
+