inc/engine/tilefetcher/TileFetcherQuery.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 TILEFETCHERQUERY_H
  19 #define TILEFETCHERQUERY_H
  20
  21 #include "common/HereMaps_global.h"
  22 #include "common/BaseQuery.h"
  23 #include "common/TileKey.h"
  24
  25 HERE_MAPS_BEGIN_NAMESPACE
  26
  27 class TileFetcherQueryListener;
  28
  29 /**
  30  * This class encapsulates a query representing a request for a map tile.
  31  *
  32  * Map tiles form a grid reflecting the normalized Mercator projection, which
  33  * represents the surface of the globe as a set of squares. The size of the grid
  34  * depends on the map zoom level. At the lowest zoom level, the entire globe is
  35  * shown in one square, which means that the tile grid consists of one row and
  36  * one column. At the next higher zoom level, the tile grid contains two rows
  37  * and two columns per row, at the next, four rows and four columns per row, and
  38  * so on -- in other words, the number of rows and columns doubles at each
  39  * higher zoom level.
  40  *
  41  * The map tiles are available in resolutions of 128 x 128 pixels or 256 x 256
  42  * pixels, depending on the size of the available memory on the target device.
  43  *
  44  * \ingroup tilefetcher
  45  */
  46 class TileFetcherQuery : public BaseQuery
  47 {
  48 public:
  49     /**
  50      * This method is the default constructor.
  51      */
  52     TileFetcherQuery();
  53
  54     /**
  55      * This method is a constructor that sets the class attributes using the
  56      * arguments provided by the caller.
  57      *
  58      * @param rKey A constant reference to an object that specifies the map tile
  59      *        row, column and zoom level.
  60      *
  61      * @param uSize A value indicating the tile size.
  62      */
  63     TileFetcherQuery(const TileKey& rKey, size_t uSize);
  64
  65     /**
  66      * This method is the (virtual) destructor.
  67      */
  68     virtual ~TileFetcherQuery();
  69
  70     /**
  71      * This method sets the hash key which is used for the query.
  72      * If not set or string is empty, "newest" will be used.
  73      *
  74      * @param hash A string containing the hash key to be used.
  75      */
  76     void SetHash(String hash);
  77
  78     /**
  79      * This method retrieves an object specifying the map tile row, column and
  80      * zoom level.
  81      *
  82      * @return  A constant reference to an object that specifies the map tile
  83      *        row, column and zoom level.
  84      */
  85     const TileKey& GetKey() const;
  86
  87     /**
  88      * This method sets an object specifying the map tile row, column and zoom
  89      * level.
  90      *
  91      * @return rKey A constant reference to an object that specifies the map tile
  92      *        row, column and zoom level.
  93      */
  94     void SetKey(const TileKey& rKey);
  95
  96     /**
  97      * This method sets the size of the map tile (resolution) in pixels.
  98      *
  99      * @param uTileSize A value indicating the tile size.
 100      */
 101     void SetTileSize(size_t uTileSize);
 102
 103     /**
 104      * This method retrieves the size of the map tile (resolution) in pixels.
 105      *
 106      * @param uTileSize A value indicating the tile size.
 107      */
 108     size_t GetTileSize() const;
 109
 110     /**
 111      * This method attempts to establish a connection with the server and then,
 112      * if the connection has been established, it builds and submits a query.
 113      *
 114      * @param rListener A reference to a an object that is to be notified when
 115      *        the reply to the query has arrived from the server.
 116      *
 117      * @param pUserData A pointer to an object containing user passed, which is
 118      *        to be echoed back through the reply object.
 119      *
 120      * @return A value representing the identifier of issued request.
 121      */
 122     virtual RestItemHandle::RequestId Execute(TileFetcherQueryListener& rListener, Tizen::Maps::HereObject* pUserData = NULL) const;
 123
 124     /**
 125      * This method returns the base URI to be used for all subsequent
 126      * tile fetcher queries based on the current setting of map type in the
 127      * <code>TileKey</code> object.
 128      *
 129      * @return A string containing the base URI.
 130      */
 131 #ifdef TIZEN_MIGRATION
 132     String GetBaseUri() const;
 133 #else
 134     static String GetBaseUri();
 135 #endif
 136
 137     /**
 138      * This method returns the base URI to be used for all subsequent
 139      * tile fetcher queries based on the current setting of map type in the
 140      * <code>TileKey</code> object.
 141      *
 142      * @param sUri A constant reference to a string containing the base URI.
 143      */
 144 #ifdef TIZEN_MIGRATION
 145     void SetBaseUri(const String& sUri);
 146 #else
 147     static void SetBaseUri(const String& sUri);
 148 #endif
 149
 150 private:
 151     /**
 152      * This method creates the URI for the request.
 153      *
 154      * @return URI request string.
 155      */
 156     String CreateUri() const;
 157
 158 private:
 159     HERE_MAPS_NO_COPY_NO_ASSIGN(TileFetcherQuery);
 160
 161     class TileFetcherQueryImpl;
 162     TileFetcherQueryImpl* m_pImpl;
 163 };
 164
 165 HERE_MAPS_END_NAMESPACE
 166
 167 #endif