location/map-service/location-poi.h

   1 /*
   2  * libslp-location
   3  *
   4  * Copyright (c) 2010-2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Youngae Kang <youngae.kang@samsung.com>, Yunhan Kim <yhan.kim@samsung.com>,
   7  *          Genie Kim <daejins.kim@samsung.com>, Minjune Kim <sena06.kim@samsung.com>
   8  *
   9  * Licensed under the Apache License, Version 2.0 (the "License");
  10  * you may not use this file except in compliance with the License.
  11  * You may obtain a copy of the License at
  12  *
  13  * http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  * Unless required by applicable law or agreed to in writing, software
  16  * distributed under the License is distributed on an "AS IS" BASIS,
  17  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  * See the License for the specific language governing permissions and
  19  * limitations under the License.
  20  */
  21
  22 #ifndef __LOCATION_POI_H__
  23 #define __LOCATION_POI_H__
  24
  25 #include <location-types.h>
  26
  27 G_BEGIN_DECLS
  28
  29 /**
  30  * @file location-poi.h
  31  * @brief This file contains the internal definitions and structures related to POI.
  32  */
  33
  34 /**
  35  * @addtogroup LocationMapService
  36  * @{
  37  * @defgroup LocationMapServicePOI Location POI
  38  * @brief This is a location POI for providing location map services.
  39  * @addtogroup LocationMapServicePOI
  40  * @{
  41  */
  42
  43 typedef enum {
  44         LOCATION_POI_PRE_SO_NONE,       ///< None of sorting the results in order.
  45         LOCATION_POI_PREF_SO_ASC,       ///< A constant for sorting the results in ascending order
  46         LOCATION_POI_PREF_SO_DESC       ///< A constant for sorting the results in descending order
  47 } LocationPOIPrefSortOrder;
  48
  49 /**
  50  * @brief Retrive LocationPreperence that the given LocationPOIPreference inherits.
  51  */
  52
  53 /**
  54  * @brief Create a new LocationPOIPreference
  55  * @remarks None.
  56  * @pre None
  57  * @post None.
  58  * @return #LocationPOIPreference
  59  * @retval NULL              if error occured
  60  * @see location_location_poi_pref_free
  61  *
  62  */
  63 LocationPOIPreference *location_poi_pref_new (void);
  64
  65 /**
  66  * @brief Copy a LocationPOIPreference
  67  * @remarks None.
  68  * @pre None
  69  * @post None.
  70  * @return #LocationPOIPreference
  71  * @retval NULL              if error occured
  72  * @see location_location_poi_pref_free
  73  *
  74  */
  75 LocationPOIPreference *location_poi_pref_copy (LocationPOIPreference *pref);
  76
  77 /**
  78  * @brief Free a LocationPOIPreference
  79  * @remarks None.
  80  * @pre #location_poi_pref_new should be called before.
  81  * @post None.
  82  * @param [in] pref - #LocationPOIPreference
  83  * @return #LocationPreference
  84  * @retval NULL              if error occured
  85  * @see location_location_poi_pref_set_pref
  86  */
  87 void location_poi_pref_free (LocationPOIPreference * pref);
  88
  89 /**
  90  * @brief Get the maximum number of results for poi service.
  91  * @remarks None.
  92  * @pre #location_poi_pref_new should be called before.
  93  * @post None.
  94  * @param [in] pref - #LocationPOIPreference
  95  * @return guint
  96  * @retval 0              if error occured
  97  * @see location_poi_pref_set_max_result
  98  */
  99 guint location_poi_pref_get_max_result (const LocationPOIPreference * pref);
 100
 101 /**
 102  * @brief Get the sort criterion for poi service.
 103  * @remarks None.
 104  * @pre #location_poi_pref_new should be called before.
 105  * @post None.
 106  * @param [in] pref - #LocationPOIPreference
 107  * @return gchar
 108  * @retval sorting item
 109  * @see location_poi_pref_set_sort_by
 110  */
 111 gchar *location_poi_pref_get_sort_by (const LocationPOIPreference * pref);
 112
 113 /**
 114  * @brief Get the sort order for poi service.
 115  * @remarks None.
 116  * @pre #location_poi_pref_new should be called before.
 117  * @post None.
 118  * @param [in] pref - #LocationPOIPreference
 119  * @return LocationPOIPrefSortOrder
 120  * @retval sort order
 121  * @see location_poi_pref_set_sort_order
 122  */
 123 LocationPOIPrefSortOrder location_poi_pref_get_sort_order (const LocationPOIPreference * pref);
 124
 125 /**
 126  * @brief Get the property keys of poi preference
 127  * @remarks None.
 128  * @pre #location_poi_pref_new should be called before.
 129  * @post None.
 130  * @param [in] pref - #LocationPOIPreference
 131  * @return GList
 132  * @retval list of property key
 133  * @see location_poi_pref_set_property
 134  */
 135 GList *location_poi_pref_get_property_key (const LocationPOIPreference *pref);
 136
 137 /**
 138  * @brief Get the property of poi preference
 139  * @remarks None.
 140  * @pre #location_poi_pref_new should be called before.
 141  * @post None.
 142  * @param [in] pref - #LocationPOIPreference
 143  * @param [in] key - gconstpointer
 144  * @return gconstpointer
 145  * @retval property value
 146  * @see location_poi_pref_set_property
 147  */
 148 gpointer location_poi_pref_get_property (const LocationPOIPreference *pref, gconstpointer key);
 149
 150
 151 /**
 152  * @brief Set the maximum number of results for poi service.
 153  * @remarks None.
 154  * @pre #location_poi_pref_new should be called before.
 155  * @post None.
 156  * @param [in] pref - #LocationPOIPreference
 157  * @return gboolean
 158  * @retval TRUE              if success
 159  * @see location_poi_pref_get_max_result
 160  */
 161 gboolean location_poi_pref_set_max_result (LocationPOIPreference * pref, guint max_num);
 162
 163 /**
 164  * @brief Set the sort criterion for poi service.
 165  * @remarks None.
 166  * @pre #location_poi_pref_new should be called before.
 167  * @post None.
 168  * @param [in] pref - #LocationPOIPreference
 169  * @param [in] item - gchar or NULL if reset
 170  * @return gboolean
 171  * @retval TRUE              if success
 172  * @see location_poi_pref_get_sort_by
 173  */
 174 gboolean location_poi_pref_set_sort_by (LocationPOIPreference * pref, const gchar * item);
 175
 176 /**
 177  * @brief Set the sort order for poi service.
 178  * @remarks None.
 179  * @pre #location_poi_pref_new should be called before.
 180  * @post None.
 181  * @param [in] pref - #LocationPOIPreference
 182  * @param [in] sort_order - #LocationPOIPrefSortOrder
 183  * @return gboolean
 184  * @retval TRUE              if success
 185  * @see location_poi_pref_get_sort_order
 186  */
 187 gboolean location_poi_pref_set_sort_order (LocationPOIPreference *pref, LocationPOIPrefSortOrder sort_order);
 188
 189 /**
 190  * @brief Set property of poi preference.
 191  * @remarks None.
 192  * @pre #location_poi_pref_new should be called before.
 193  * @post None.
 194  * @param [in] pref - #LocationPOIPreference
 195  * @param [in] key - gconstpoiner
 196  * @param [in] value - gconstpointer or NULL if reset
 197  * @return gboolean
 198  * @retval TRUE              if success
 199  * @see location_poi_pref_get_property
 200  */
 201 gboolean location_poi_pref_set_property (LocationPOIPreference *pref, gconstpointer key, gconstpointer value);
 202
 203 /**
 204  * @brief Create a new LocationPOIFilter
 205  * @remarks None
 206  * @pre #location_init should be called before.
 207  * @post None.
 208  * @return a new #LocationPOIFilter
 209  * @retval NULL              if error occured
 210  * @see location_poi_filter_free
 211  */
 212 LocationPOIFilter *location_poi_filter_new (void);
 213
 214 /**
 215  * @brief Copy a LocationPOIFilter
 216  * @remarks None
 217  * @pre #location_init should be called before.
 218  * @post None.
 219  * @return a #LocationPOIFilter
 220  * @retval NULL              if error occured
 221  * @see location_poi_filter_new
 222  */
 223 LocationPOIFilter *location_poi_filter_copy (LocationPOIFilter *filter);
 224
 225 /**
 226  * @brief Free a LocationPOIFilter
 227  * @remarks None
 228  * @pre #location_new should be called before.
 229  * @post None.
 230  * @param [in] filter - #LocationPOIFilter
 231  * @return None
 232  * @see location_poi_filter_new
 233  */
 234 void location_poi_filter_free (LocationPOIFilter *filter);
 235
 236 /**
 237  * @brief Set filter for poi service
 238  * @remarks None
 239  * @pre #location_poi_filter_new should be called before.
 240  * @post None.
 241  * @param [in] filter - #LocationPOIFilter
 242  * @param [in] key - gconstpointer
 243  * @param [in] value - gconstpointer or NULL if reset
 244  * @return gboolean
 245  * @retval TRUE              if success
 246  * @see location_poi_filter_get
 247  */
 248 gboolean location_poi_filter_set (const LocationPOIFilter *filter, gconstpointer key, gconstpointer value);
 249
 250 /**
 251  * @brief Get filter for poi service
 252  * @remarks None
 253  * @pre #location_poi_filter_new should be called before.
 254  * @post None.
 255  * @param [in] filter - #LocationPOIFilter
 256  * @param [in] key - gconstpointer
 257  * @return gconstpointer
 258  * @retval Filter property key
 259  * @see location_poi_filter_set
 260  */
 261 gpointer location_poi_filter_get (const LocationPOIFilter *filter, gconstpointer key);
 262
 263 /**
 264  * @brief Get keys in the given filter
 265  * @remarks The content of returned list is owned by the poi filter and should not be modified or freed. \n
 266  * Use g_list_free when done using the returned.
 267  * @pre #location_poi_filter_new should be called before.
 268  * @post None.
 269  * @param [in] filter - #LocationPOIFilter
 270  * @return GList
 271  * @retval Filter key
 272  * @see None
 273  */
 274 GList *location_poi_filter_get_key (const LocationPOIFilter *filter);
 275
 276 /**
 277  * @} @}
 278  */
 279
 280 G_END_DECLS
 281
 282 #endif