inc/engine/maps/GeoProviderManager.h

   1 /*
   2  * Copyright (C) 2013 HERE Global B.V. All rights reserved.
   3  * This software, including documentation, is protected by copyright controlled by
   4  * HERE Global B.V. (“Software”). All rights are reserved. Copying, including reproducing,
   5  * storing, adapting or translating, any or all of this material requires the prior
   6  * written consent of HERE Global B.V. You may use this
   7  * Software in accordance with the terms and conditions defined in the
   8  * HERE Location Platform Services Terms and Conditions, available at
   9  * http://developer.here.com/terms-conditions-base
  10  *
  11  * As an additional permission to the above, you may distribute Software,
  12  * in object code format as part of an Application, according to, and subject to, terms and
  13  * conditions defined in the Tizen Software Development kit (“SDK”) License Agreement.
  14  * You may distribute such object code format Application under terms of your choice,
  15  * provided that the header and source files of the Software have not been modified.
  16  */
  17
  18 #ifndef GEOPROVIDERMANAGER_P_H_
  19 #define GEOPROVIDERMANAGER_P_H_
  20
  21 #include <vector>
  22
  23 #include "common/HereMaps_global.h"
  24
  25 #include "maps/GeoTile.h"
  26 #include "maps/GeoProvider.h"
  27
  28 #ifdef TIZEN_MIGRATION
  29 #include "base/Timer.h"
  30 #endif
  31
  32 HERE_MAPS_BEGIN_NAMESPACE
  33
  34 class GeoTiledMap;
  35 class QueryListener;
  36
  37 /**
  38  * This class encapsulates management of all the providers of tiles and map
  39  * objects. It registers providers and requests tiles and objects on their
  40  * behalf, eventually compositing each tile in the map to ensure the tiles
  41  * contain not only the map tile bitmaps, but also any markers, polylines and
  42  * polygons that must be drawn on top of the bitmaps.
  43  *
  44  * The virtual methods defined on this class require implementation by derived
  45  * classes.
  46  *
  47  * \ingroup maps
  48  */
  49 class GeoProviderManager : public Tizen::Maps::ITimerEventListener
  50 {
  51 public:
  52     /**
  53      * This method retrieves an object representing the key for a tile on the
  54      * basis of the zoom level and coordinates of the tile in the tile grid at
  55      * that zoom level.
  56      *
  57      * @param level A value indicating the zoom level.
  58      *
  59      * @param x A value representing the x-coordinate in the tile grid.
  60      *
  61      * @param y A value representing the y-coordinate in the tile grid.
  62      *
  63      * @return An object representing the tile key.
  64      */
  65     TileKey GetKey(int level, int x, int y);
  66
  67     /**
  68      * This method is the default constructor.
  69      */
  70     GeoProviderManager();
  71
  72     /**
  73      * This method is a constructor.
  74      *
  75      * @param rMap A reference to the tile map whose tiles are processed by the
  76      *        given manager object.
  77      */
  78     GeoProviderManager(GeoTiledMap& rMap);
  79
  80     /**
  81      * This method is the (virtual) destructor.
  82      */
  83     virtual ~GeoProviderManager();
  84
  85     /**
  86      * This method is invoked when the timer expires.
  87      *
  88      * @param timer A reference to the timer object.
  89      */
  90     virtual void OnTimerExpired(Tizen::Maps::Timer& timer);
  91
  92     /**
  93      * This method checks if a previously requested tile is available.
  94      *
  95      * @param level A value indicating the zoom level.
  96      *
  97      * @param x A value representing the x-coordinate in the tile grid.
  98      *
  99      * @param y A value representing the y-coordinate in the tile grid.
 100      *
 101      * @return A pointer to the tile object (which is <code>NULL</code> if the
 102      *         tile is not available).
 103      */
 104     TilePtr PeekTile(int level, int x, int y);
 105
 106     /**
 107      * This method checks if a previously requested tile is available.
 108      *
 109      * @param key An object representing the key that identifies the tile to check.
 110      *
 111      * @return A pointer to the tile object (which is <code>NULL</code> if the
 112      *         tile is not available).
 113      */
 114     TilePtr PeekTile(const TileKey& key);
 115
 116     /**
 117      * This method requests a tile.
 118      *
 119      * @param level A value indicating the zoom level.
 120      *
 121      * @param x A value representing the x-coordinate in the tile grid.
 122      *
 123      * @param y A value representing the y-coordinate in the tile grid.
 124      *
 125      * @return A pointer to the tile object (which is <code>NULL</code> if the
 126      *         tile is not available).
 127      */
 128     TilePtr RequestTile(int level, int x, int y);
 129
 130     /**
 131      * This method removes the tile specified by the caller from the cache.
 132      *
 133      * @param tile A constant reference to the tile object to remove from the cache.
 134      */
 135     void RemoveCachedTile(const TilePtr& tile);
 136
 137     /**
 138      * This method clears the map tile cache.
 139      */
 140     void ClearCache();
 141
 142     /**
 143      * This method clears any map objects from the cache.
 144      *
 145      * @param bClearAndRequest A Boolean indicating if the map objects should be
 146      *        rerequested when they have been cleared (<code>true</code>,
 147      *        default) or not <code>fault</code>.
 148      */
 149     void ClearCachedMapObjectsOnly(bool bClearAndRequest=true);
 150
 151     /**
 152      * This method retrieves a count of cached map tiles.
 153      *
 154      * @return A value indicating the number of cached map tiles.
 155      */
 156     size_t GetNumCachedTiles() const;
 157
 158     /**
 159      * This method adds a provider to those managed by the given manager instance.
 160      *
 161      * @param provider A pointer to a provider object to add.
 162      */
 163     void AddProvider(GeoProvider* provider);
 164
 165     /**
 166      * This method removes the provider identified by the caller to those
 167      * managed by the given manager instance.
 168      *
 169      * @param provider A pointer to a provider object to remove.
 170      */
 171     bool RemoveProvider(GeoProvider* pProvider);
 172
 173     /**
 174      * This method retrieves a provider matching the index supplied by the caller.
 175      *
 176      * @param idx A value of the index from which to retrieve the provider.
 177      *
 178      * @return A pointer to the provider object or <code>NULL</code> if the
 179      *         supplied index is invalid.
 180      */
 181     GeoProvider* GetProvider(size_t idx) const;
 182
 183     /**
 184      * This method obtains the count of providers managed by the given
 185      * instance of <code>GeoProviderManager</code>.
 186      *
 187      * @return A value representing the count of providers.
 188      */
 189     size_t GetNumProviders() const;
 190
 191     /**
 192      * This method is invoked when a tile has been loaded. It adds the
 193      * tile to the list of loaded files, removes it from the list of loading
 194      * tiles and the cache, and ensures it is displayed.
 195      *
 196      * @param rKey A constant reference to a key object that identifies the
 197      *        loaded tile.
 198      *
 199      * @param image A pointer to the tile image object.
 200      *
 201      * @param rProvider The provider for which the tile has been acquired.
 202      */
 203     void HandleTileLoaded(const TileKey& rKey, DrawableBitmapPtr image, GeoProvider& rProvider);
 204
 205     /**
 206      * This method is invoked when a tile has been loaded. It adds the
 207      * tile to the list of loaded files, removes it from the list of loading
 208      * tiles and the cache, and ensures it is displayed.
 209      *
 210      * @param rKey A constant reference to a key object that identifies the
 211      *        tile.
 212      *
 213      * @param rError A constant reference to an object containing information
 214      *        about the error that occurred.
 215      */
 216     void HandleTileFailed(const TileKey& rKey, const ErrorBase& rError);
 217
 218     /**
 219      * This method starts the process of loading the next requested file.
 220      */
 221     void StartNextTileLoad();
 222
 223     /**
 224      * This method sets a value indicating the maximum number of pending
 225      * requests.
 226      *
 227      * @param uLimit A value indicating the maximum number of pending requests.
 228      */
 229     void SetPendingRequestsLimit(size_t uLimit);
 230
 231     /**
 232      * This method retrieves a value indicating the maximum number of pending
 233      * requests.
 234      *
 235      * @return A value indicating the maximum number of pending requests.
 236      */
 237     size_t GetPendingRequestsLimit() const;
 238
 239     /**
 240      * This method retrieves a value indicating the count of pending
 241      * requests.
 242      *
 243      * @return A value indicating how many requests are pending.
 244      */
 245     size_t GetNumPendingRequests() const;
 246
 247     /**
 248      * This method sets a value indicating the maximum number of tiles that can
 249      * be cached.
 250      *
 251      * @param uLimit A value indicating the maximum number of cached tiles.
 252      */
 253     void SetCachedTilesLimit(size_t uLimit);
 254
 255     /**
 256      * This method retrieves a value indicating the maximum number of tiles that
 257      * can be cached.
 258      *
 259      * @return A value indicating the maximum number of cached tiles.
 260      */
 261     size_t GetCachedTilesLimit() const;
 262
 263 private:
 264     void LoadTile(const TilePtr tile, unsigned int uProviderLevel);
 265     void AbortTile(const TilePtr tile);
 266     void LogTile(const String& text,const TilePtr& tile);
 267     void LogTile(const String& text,int level,int x,int y);
 268
 269     void BeginMarking();
 270     void EndMarking();
 271
 272 private:
 273     HERE_MAPS_NO_COPY_NO_ASSIGN(GeoProviderManager);
 274     friend class GeoTiledMap;
 275     friend class TestGeoProviderManager;
 276     class GeoProviderManagerImpl;
 277     GeoProviderManagerImpl* m_pImpl;
 278 };
 279
 280 HERE_MAPS_END_NAMESPACE
 281
 282 #endif