4 * Copyright (c) 2010-2011 Samsung Electronics Co., Ltd. All rights reserved.
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>
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
13 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #ifndef __LOCATION_POI_H__
23 #define __LOCATION_POI_H__
25 #include <location-map-types.h>
30 * @file location-poi.h
31 * @brief This file contains the internal definitions and structures related to POI.
35 * @addtogroup LocationMapService
37 * @defgroup LocationMapServicePOI Location POI
38 * @brief This is a location POI for providing location map services.
39 * @addtogroup LocationMapServicePOI
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;
50 * @brief Retrive LocationPreperence that the given LocationPOIPreference inherits.
54 * @brief Create a new LocationPOIPreference
58 * @return #LocationPOIPreference
59 * @retval NULL if error occured
60 * @see location_location_poi_pref_free
63 LocationPOIPreference *location_poi_pref_new (void);
66 * @brief Copy a LocationPOIPreference
70 * @return #LocationPOIPreference
71 * @retval NULL if error occured
72 * @see location_location_poi_pref_free
75 LocationPOIPreference *location_poi_pref_copy (LocationPOIPreference *pref);
78 * @brief Free a LocationPOIPreference
80 * @pre #location_poi_pref_new should be called before.
82 * @param [in] pref - #LocationPOIPreference
84 * @retval NULL if error occured
85 * @see location_location_poi_pref_set_pref
87 void location_poi_pref_free (LocationPOIPreference * pref);
90 * @brief Get the maximum number of results for poi service.
92 * @pre #location_poi_pref_new should be called before.
94 * @param [in] pref - #LocationPOIPreference
96 * @retval 0 if error occured
97 * @see location_poi_pref_set_max_result
99 guint location_poi_pref_get_max_result (const LocationPOIPreference * pref);
102 * @brief Get the sort criterion for poi service.
104 * @pre #location_poi_pref_new should be called before.
106 * @param [in] pref - #LocationPOIPreference
108 * @retval sorting item
109 * @see location_poi_pref_set_sort_by
111 gchar *location_poi_pref_get_sort_by (const LocationPOIPreference * pref);
114 * @brief Get the sort order for poi service.
116 * @pre #location_poi_pref_new should be called before.
118 * @param [in] pref - #LocationPOIPreference
119 * @return LocationPOIPrefSortOrder
121 * @see location_poi_pref_set_sort_order
123 LocationPOIPrefSortOrder location_poi_pref_get_sort_order (const LocationPOIPreference * pref);
126 * @brief Get the property keys of poi preference
128 * @pre #location_poi_pref_new should be called before.
130 * @param [in] pref - #LocationPOIPreference
132 * @retval list of property key
133 * @see location_poi_pref_set_property
135 GList *location_poi_pref_get_property_key (const LocationPOIPreference *pref);
138 * @brief Get the property of poi preference
140 * @pre #location_poi_pref_new should be called before.
142 * @param [in] pref - #LocationPOIPreference
143 * @param [in] key - gconstpointer
144 * @return gconstpointer
145 * @retval property value
146 * @see location_poi_pref_set_property
148 gpointer location_poi_pref_get_property (const LocationPOIPreference *pref, gconstpointer key);
152 * @brief Set the maximum number of results for poi service.
154 * @pre #location_poi_pref_new should be called before.
156 * @param [in] pref - #LocationPOIPreference
158 * @retval TRUE if success
159 * @see location_poi_pref_get_max_result
161 gboolean location_poi_pref_set_max_result (LocationPOIPreference * pref, guint max_num);
164 * @brief Set the sort criterion for poi service.
165 * @remarks The previous item of the #LocationPOIPreference will be removed if an item is NULL.
166 * @pre #location_poi_pref_new should be called before.
168 * @param [in] pref - #LocationPOIPreference
169 * @param [in] item - gchar or NULL if reset
171 * @retval TRUE if success
172 * @see location_poi_pref_get_sort_by
174 gboolean location_poi_pref_set_sort_by (LocationPOIPreference * pref, const gchar * item);
177 * @brief Set the sort order for poi service.
179 * @pre #location_poi_pref_new should be called before.
181 * @param [in] pref - #LocationPOIPreference
182 * @param [in] sort_order - #LocationPOIPrefSortOrder
184 * @retval TRUE if success
185 * @see location_poi_pref_get_sort_order
187 gboolean location_poi_pref_set_sort_order (LocationPOIPreference *pref, LocationPOIPrefSortOrder sort_order);
190 * @brief Set property of poi preference.
191 * @remarks The previous value of the #LocationPOIPreference matching to key will be removed if an value is NULL.
192 * @pre #location_poi_pref_new should be called before.
194 * @param [in] pref - #LocationPOIPreference
195 * @param [in] key - gconstpoiner
196 * @param [in] value - gconstpointer or NULL if reset
198 * @retval TRUE if success
199 * @see location_poi_pref_get_property
201 gboolean location_poi_pref_set_property (LocationPOIPreference *pref, gconstpointer key, gconstpointer value);
204 * @brief Create a new LocationPOIFilter
206 * @pre #location_init should be called before.
208 * @return a new #LocationPOIFilter
209 * @retval NULL if error occured
210 * @see location_poi_filter_free
212 LocationPOIFilter *location_poi_filter_new (void);
215 * @brief Copy a LocationPOIFilter
217 * @pre #location_init should be called before.
219 * @return a #LocationPOIFilter
220 * @retval NULL if error occured
221 * @see location_poi_filter_new
223 LocationPOIFilter *location_poi_filter_copy (LocationPOIFilter *filter);
226 * @brief Free a LocationPOIFilter
228 * @pre #location_new should be called before.
230 * @param [in] filter - #LocationPOIFilter
232 * @see location_poi_filter_new
234 void location_poi_filter_free (LocationPOIFilter *filter);
237 * @brief Set filter for poi service
238 * @remarks The previous value of the #LocationPOIFilter matching to key will be removed if an value is NULL.
239 * @pre #location_poi_filter_new should be called before.
241 * @param [in] filter - #LocationPOIFilter
242 * @param [in] key - gconstpointer
243 * @param [in] value - gconstpointer or NULL if reset
245 * @retval TRUE if success
246 * @see location_poi_filter_get
248 gboolean location_poi_filter_set (const LocationPOIFilter *filter, gconstpointer key, gconstpointer value);
251 * @brief Get filter for poi service
253 * @pre #location_poi_filter_new should be called before.
255 * @param [in] filter - #LocationPOIFilter
256 * @param [in] key - gconstpointer
257 * @return gconstpointer
258 * @retval Filter property key
259 * @see location_poi_filter_set
261 gpointer location_poi_filter_get (const LocationPOIFilter *filter, gconstpointer key);
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.
269 * @param [in] filter - #LocationPOIFilter
274 GList *location_poi_filter_get_key (const LocationPOIFilter *filter);