--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/locsrv_plat/map_image_api/inc/mnmapimage.h Tue Feb 02 01:06:48 2010 +0200
@@ -0,0 +1,298 @@
+/*
+* Copyright (c) 2007 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: CMnMapImage class
+*
+*/
+
+
+#ifndef MN_MAPIMAGE_H_
+#define MN_MAPIMAGE_H_
+
+#include <e32base.h>
+#include <lbsposition.h>
+#include <mnmapimageparams.h>
+
+class CApaServerAppExitMonitor;
+class MAknServerAppExitObserver;
+class CMnProvider;
+class RMnMapImageServiceClient;
+class CMnMapImage;
+class CFbsBitmap;
+class CMnCoordinateConverterBase;
+
+/** Abstract class to be inherited by classes, which want to receive
+ * notification, when image rendering is completed.
+ * @see CMnMapImage
+ * @since 5.0 */
+class MMnMapImageRenderCallback
+ {
+ public:
+ /** This callback is called when CMnMapImage has completed rendering
+ * map image. It is not called if rendering was cancelled by client.
+ * @param aStatus Result of the rendering operation:
+ * - @p KErrNone - rendering was completed successfully.
+ * - @p KErrNotSupported - rendering is not possible in specified area
+ * or one of mandatory options are not supported (see @ref TShowOption).
+ * - Other system-wide error codes also possible.
+ * @param aMapImage Instance of CMnMapImage, through which the request has
+ * been issued. */
+ virtual void HandleRenderingCompletedL( TInt aStatus, CMnMapImage& aMapImage ) = 0;
+ };
+
+/** Provides access to map image rendering features.
+ *
+ * The RenderL() method allows to get bitmap image of some area, which is specified
+ * by SetCenterPoint() and SetScale(). Size of the bitmap is defined by SetSize().
+ *
+ * To create an instance of the class, use @ref NewL method. It
+ * requires instance of CMnProvider, defined in Map and Navigation Provider Discovery API.
+ *
+ * Only one asynchronous request can be issued at a time, otherwise client
+ * will be panicked with KMnPanicDuplicateRequest.
+ *
+ * @since 5.0
+ * @lib mnclientlib.dll
+ * @ingroup MapNavAPI
+ */
+class CMnMapImage : public CBase
+ {
+ public:
+
+ /** Creates new instance of the class. Provider Application
+ * will be executed standalone.
+ *
+ * @param[in] aProvider Provider Application to be used for map rendering.
+ * @return Pointer to new instance of the class.
+ *
+ * @leave KErrNotSupported Selected Provider Application does not support
+ * map image services (@ref CMnProvider::EServiceMapImage). */
+ IMPORT_C static CMnMapImage* NewL( CMnProvider& aProvider );
+
+ /** Destructor */
+ virtual ~CMnMapImage();
+
+ enum TShowOption
+ {
+ /** No options set, just plain image is requested. */
+ EShowOptionNone = 0x00,
+
+ /** Texts such as street, city, country names should be drawn */
+ EShowOptionText = 0x01,
+
+ /** POIs should be marked on the map */
+ EShowOptionPois = 0x02,
+
+ /** Landmarks should be marked on the map */
+ EShowOptionLandmarks = 0x04,
+
+ /** Current location should be marked on the map.
+ * Client must have Location capability, otherwise
+ * this option will be ignored. */
+ EShowOptionCurrentLocation = 0x08,
+
+ /** Country borders should be shown */
+ EShowOptionCountryBorders = 0x10,
+
+ /** If this flag is set, it is required to draw
+ * items specified by other flags, otherwise all
+ * of them are optional. */
+ EShowOptionsMandatory = 0xF000
+ };
+
+ /** Type for bitmap of options defined in @ref TShowOption */
+ typedef TUint32 TShowOptions;
+
+ /** Returns what types of map images are supported by provider
+ * application given at construction (see NewL()).
+ * @return Bitmap of values defined by @ref TMapImageType. */
+ IMPORT_C TMnMapImageParams::TMapImageTypes SupportedImageTypes();
+
+ /** Returns map image parameters object.
+ * Client can modify it, but all modification will be
+ * applied only for next and following RenderL requests.
+ * @return Modifiable map image parameters object */
+ IMPORT_C TMnMapImageParams& MapImageParams();
+
+ /** @overload
+ * @return Non-modifiable map image parameters object */
+ IMPORT_C const TMnMapImageParams& MapImageParams() const;
+
+ /** Sets all map image drawing parameters at once.
+ * New options will be applied only for next and following
+ * RenderL requests.
+ * @param aImageParams Image parameters to take into use for
+ * following RenderL requests */
+ IMPORT_C void SetMapImageParams( TMnMapImageParams& aImageParams );
+
+ /** Specifies the origin of image in the target bitmap, see
+ * RenderL(). By default it is TPoint( 0, 0 ), i.e. left top
+ * corner of the bitmap.
+ * This setting takes effect only from next RenderL request.
+ * @param[in] aOrigin Origin of the map in the target bitmap.*/
+ IMPORT_C void SetTargetOrigin( const TPoint& aOrigin );
+
+ /** Returns current setting of map image origin in target bitmap.
+ * @returns Origin of map image in the target bitmap.*/
+ IMPORT_C TPoint TargetOrigin();
+
+ /** Sets additional options to be used in rendering. Renderer will
+ * take them into account if possible.
+ * This setting takes effect only from next RenderL request.
+ * @param[in] aOptions Bitmap of options defined in @ref TOption. */
+ IMPORT_C void SetShowOptions( const TShowOptions& aOptions );
+
+ /** Returns additional options set to be used in rendering.
+ * @return Bitmap of options defined in @ref TShowOption. */
+ IMPORT_C TShowOptions ShowOptions() const;
+
+ /** Intiates rendering of map image.
+ * This is asynchronous request, which completion is informed via
+ * aStatus parameter. Client should use active object to wait for completion.
+ *
+ * This function may leave if some error occurs during initiating of the request.
+ * If so, then no asynchronous request will be left ongoing.
+ *
+ * @param[in,out] aBitmap Bitmap object, which the map image will be drawn into.
+ * Its size in pixels must be sufficient to fit the image
+ * defined by @ref SetSize() taking @ref SetTargetOrigin()
+ * into account as well.
+ * @param[out] aStatus This status will be completed, when rendering is finished.
+ * - @p KErrNone - rendering was completed successfully.
+ * - @p KErrNotSupported - rendering is not possible in specified area
+ * or one of mandatory options are not supported (see @ref TShowOption).
+ * - Other system-wide error codes also possible.
+ *
+ * @leave KErrArgument
+ * - If target bitmap size is too small.
+ * - If requested image type is not supported by provider application
+ *
+ * @panic "MnPanicClient"-KMnPanicDuplicateRequest if request is already
+ * ongoing. */
+ IMPORT_C void RenderL( CFbsBitmap& aBitmap, TRequestStatus& aStatus );
+
+ /** Intiates rendering of map image.
+ * This is asynchronous request, which completion is informed via aCallback.
+ *
+ * Client must provide callback as class derived from MMnMapImageRenderCallback.
+ * This is asynchronous request also. An active object will be executed to handle
+ * completion of rendering request, so client must have active scheduler installed.
+ *
+ * This function may leave if some error occurs during initiating of the request.
+ * If so, then no asynchronous request will be left ongoing.
+ *
+ * @param[in,out] aBitmap Bitmap object, which the map image will be drawn into.
+ * Its size in pixels must be sufficient to fit the image
+ * defined by @ref SetSize() taking @ref SetTargetOrigin()
+ * into account as well.
+ * @param[in] aCallback Callback object to call when rendering is completed.
+ * See @ref MMnMapImageRenderCallback::HandleRenderingCompletedL for details
+ * on possible operation result error codes.
+ *
+ * @leave KErrArgument
+ * - If target bitmap size is too small.
+ * - If requested image type is not supported by provider application
+ *
+ * @panic "MnPanicClient"-KMnPanicDuplicateRequest if request is already
+ * ongoing. */
+ IMPORT_C void RenderL( CFbsBitmap& aBitmap, MMnMapImageRenderCallback& aCallback );
+
+ /** Cancels current ongoing asynchronous rendering request.
+ * Note that callback, set in @ref RenderL(CFbsBitmap&, MMnMapImageRenderCallback&)
+ * is <i>not</i> called, if request is cancelled. */
+ IMPORT_C void CancelRendering();
+
+ /** Calculates coordinate in pixels of the point corresponding to given
+ * world coordinate.
+ *
+ * Given world coordinate is allowed to be beyond
+ * image borders. In that case negative values in result value
+ * describe point to the left of left border and/or above top border of the
+ * image and values bigger than width or height describe point to the right
+ * of right image border or below its bottom border.
+ *
+ * Sometimes such calculation is not possible (e.e given world coordinate
+ * is not part of the image) and this function returns @c KErrUnknown.
+ *
+ * Map image parameters are necessary be set in order for this function
+ * to operate successfully. Default values are not sufficient, so client
+ * is responsible to override them before calling this method. Note though,
+ * that it is not required to call RenderL before calling this method.
+ *
+ * @param[in] aWorldCoordinate World coordinate (in WGS-84)
+ * @param[out] aImagePoint On successful return, coordinate of corresponding
+ * pixel in image relative to image top left corner.
+ * @return Error code of the operation:
+ * - @c KErrNone if calculation is successful
+ * - @c KErrArgument if map image parameters in are invalid.
+ * - @c KErrUnknown if calculation is not possible */
+ IMPORT_C TInt GetImageCoordinate(
+ const TCoordinate& aWorldCoordinate,
+ TPoint& aImagePoint ) const;
+
+ /** Calculates world coordinate of the given image point.
+ *
+ * Given image point coordinate must be within the rectangle
+ * ( TPoint( 0, 0 ), @ref Size() ).
+ *
+ * Map image parameters are necessary be set in order for this function
+ * to operate successfully. Default values are not sufficient, so client
+ * is responsible to override them before calling this method. Note though,
+ * that it is not required to call RenderL before calling this method.
+ *
+ * Sometimes such calculation is not possible (e.g. given image coordinate
+ * does not match any world coordinate) and this function returns @c KErrUnknown.
+ *
+ * @param[in] aImagePoint Coordinate of a point on map image in pixels,
+ * relative to image top left corner.
+ * @param[out] aWorldCoordinate On successful return, corresponding
+ * world coordinate (in WGS-84).
+ * @return Error code of the operation:
+ * - @c KErrNone if calculation is successful
+ * - @c KErrArgument if image coordinate is out of bounds
+ * - @c KErrArgument if map image parameters in are invalid.
+ * - @c KErrUnknown if calculation is not possible */
+ IMPORT_C TInt GetWorldCoordinate(
+ const TPoint& aImagePoint,
+ TCoordinate& aWorldCoordinate ) const;
+
+ /** Sets observer of provider application lifetime.
+ * Client will receive exit event from provider application.
+ * By default exit events from provider application are not monitored.
+ * @param[in] aObserver Exit observer.
+ * @leave KErrAlreadyExists if observer is already set.
+ */
+ IMPORT_C void SetExitObserverL( MAknServerAppExitObserver& aObserver );
+
+ /** Removes observer of provider application lifetime. */
+ IMPORT_C void RemoveExitObserver();
+
+ protected:
+ CMnMapImage();
+ void ConstructL( CMnProvider& aProvider );
+
+ private:
+ TUint32 iProviderFeatures;
+
+ TPoint iTargetOrigin;
+ TMnMapImageParams iMapImageParams;
+ TShowOptions iShowOptions;
+
+ RMnMapImageServiceClient* iSession;
+ CApaServerAppExitMonitor* iExitMonitor;
+ CActive* iActiveCallback;
+
+ CMnCoordinateConverterBase* iCoordConverter;
+ };
+
+#endif /*MN_MAPIMAGE_H_*/