include/geocoder.h

   1 /*
   2  * Copyright (c) 2011-2013 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __TIZEN_LOCATION_GEOCODER_H__
  18 #define __TIZEN_LOCATION_GEOCODER_H__
  19
  20 #include <tizen_type.h>
  21 #include <tizen_error.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27
  28 /**
  29  * @addtogroup CAPI_LOCATION_GEOCODER_MODULE
  30  * @{
  31  */
  32
  33 /**
  34  * @brief The geocoder handle
  35  */
  36 typedef struct geocoder_s *geocoder_h;
  37 typedef struct geocoder_preference_s *geocoder_preference_h;
  38
  39
  40 /**
  41  * @brief Enumerations of error code for Geocoder
  42  */
  43 typedef enum
  44 {
  45     GEOCODER_ERROR_NONE = TIZEN_ERROR_NONE,                             /**< Successful */
  46     GEOCODER_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,           /**< Out of memory */
  47     GEOCODER_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,                   /**< Invalid parameter */
  48     GEOCODER_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT,  /**< Timeout error, no answer */
  49     GEOCODER_ERROR_NETWORK_FAILED = TIZEN_ERROR_LOCATION_CLASS | 0x02,                  /**< Network unavailable*/
  50     GEOCODER_ERROR_SERVICE_NOT_AVAILABLE = TIZEN_ERROR_LOCATION_CLASS | 0x03,   /**< Service unavailable */
  51     GEOCODER_ERROR_NOT_FOUND = TIZEN_ERROR_LOCATION_CLASS | 0x04,       /**< Result not found */
  52     GEOCODER_ERROR_INVALID_KEY = TIZEN_ERROR_LOCATION_CLASS | 0x05,   /**< Invalid key */
  53 } geocoder_error_e;
  54
  55 /**
  56  * @brief       Called once for each position information converted from the given address information.
  57  * @param[in] result The result of request
  58  * @param[in] latitude The latitude [-90.0 ~ 90.0] (degrees)
  59  * @param[in] longitude The longitude [-180.0 ~ 180.0] (degrees)
  60  * @param[in] user_data The user data passed from the foreach function
  61  * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
  62  * @pre geocoder_foreach_positions_from_address() will invoke this callback.
  63  * @see geocoder_foreach_positions_from_address()
  64  */
  65 typedef bool(*geocoder_get_position_cb)(geocoder_error_e result, double latitude, double longitude, void *user_data);
  66
  67
  68 /**
  69  * @brief   Called when the address information has converted from position information.
  70  * @remarks You should not free all string values.
  71  * @param[in] result The result of request
  72  * @param[in] building_number    The building number
  73  * @param[in] postal_code       The postal delivery code
  74  * @param[in] street    The full street name
  75  * @param[in] city      The city name
  76  * @param[in] district  The municipal district name
  77  * @param[in] state     The state or province region of a nation
  78  * @param[in] country_code      The country code
  79  * @param[in] user_data The user data passed from the foreach function
  80  * @pre geocoder_get_address_from_position() will invoke this callback.
  81  * @see geocoder_get_address_from_position()
  82  */
  83 typedef void (*geocoder_get_address_cb)(geocoder_error_e result, const char *building_number, const char *postal_code, const char *street, const  char *city, const char *district, const char *state, const char *country_code, void *user_data);
  84
  85 /**
  86  * @brief Called once for each available keys
  87  * @remarks @a key is valid only in this function.
  88  * @param   [in] key  The key string
  89  * @param   [in] uesr_data  The user data passed from the foreach function
  90  * @return @c true to continue with the next iteration of the loop, \n @c false to break outsp of the loop.
  91  */
  92 typedef bool (*geocoder_preference_available_key_cb)(const char *key , void *user_data);
  93
  94 /**
  95  * @brief Creates a new geocoder handle.
  96  * @details
  97  * A geocoder handle can be used to change position information to address information and vice versa.
  98  * @remarks @a geocoder must be released geocoder_destroy() by you.
  99  * @param   [out] geocoder  A handle of a new geocoder handle on success
 100  * @return 0 on success, otherwise a negative error value.
 101  * @retval #GEOCODER_ERROR_NONE Successful
 102  * @retval #GEOCODER_ERROR_OUT_OF_MEMORY Out of memory
 103  * @retval #GEOCODER_ERROR_INVALID_PARAMETER    Invalid parameter
 104  * @retval #GEOCODER_ERROR_SERVICE_NOT_AVAILABLE Service not available
 105  * @see geocoder_destroy()
 106  */
 107 int geocoder_create(geocoder_h *geocoder);
 108
 109 /**
 110  * @brief       Destroys the geocoder handle and releases all its resources.
 111  * @param   [in] geocoder       The geocoder handle to destroy
 112  * @return  0 on success, otherwise a negative error value.
 113  * @retval #GEOCODER_ERROR_NONE Successful
 114  * @retval #GEOCODER_ERROR_INVALID_PARAMETER    Invalid parameter
 115  * @see geocoder_create()
 116  */
 117 int geocoder_destroy(geocoder_h geocoder);
 118
 119 /**
 120  * @brief Gets the address for a given position, asynchronously.
 121  * @remarks This function requires network access.
 122  * @param[in] geocoder The geocoder handle
 123  * @param[in] latitude The latitude [-90.0 ~ 90.0] (degrees)
 124  * @param[in] longitude The longitude [-180.0 ~ 180.0] (degrees)
 125  * @param[in] callback The callback which will receive address information
 126  * @param[in] user_data The user data to be passed to the callback function
 127  * @return 0 on success, otherwise a negative error value.
 128  * @retval #GEOCODER_ERROR_NONE Successful
 129  * @retval #GEOCODER_ERROR_INVALID_PARAMETER    Invalid parameter
 130  * @retval #GEOCODER_ERROR_NETWORK_FAILED       Network connection failed
 131  * @retval #GEOCODER_ERROR_SERVICE_NOT_AVAILABLE Service not available
 132  * @post This function invokes geocoder_get_address_cb().
 133  * @see geocoder_get_address_cb()
 134  * @see geocoder_foreach_positions_from_address()
 135  */
 136 int geocoder_get_address_from_position(geocoder_h geocoder, double latitude, double longitude, geocoder_get_address_cb callback, void *user_data);
 137
 138 /**
 139  * @brief Gets the positions for a given address, asynchronously.
 140  * @details This function gets positions for a given free-formed address string.
 141  * @remarks This function requires network access.
 142  * @param[in] geocoder  The geocoder handle
 143  * @param[in] address   The free-formed address
 144  * @param[in] callback  The geocoder get positions callback function
 145  * @param[in] user_data The user data to be passed to the callback function
 146  * @return 0 on success, otherwise a negative error value.
 147  * @retval #GEOCODER_ERROR_NONE Successful
 148  * @retval #GEOCODER_ERROR_INVALID_PARAMETER    Invalid parameter
 149  * @retval #GEOCODER_ERROR_NETWORK_FAILED       Network connection failed
 150  * @retval #GEOCODER_ERROR_SERVICE_NOT_AVAILABLE Service not available
 151  * @post It invokes geocoder_get_position_cb() to get changes in position.
 152  * @see geocoder_get_position_cb()
 153  * @see geocoder_get_address_from_position()
 154  */
 155 int geocoder_foreach_positions_from_address(geocoder_h geocoder, const char *address, geocoder_get_position_cb callback, void *user_data);
 156
 157 /**
 158  * @brief Called once for each position information converted from the given address information.
 159  * @param[in] result The result of request
 160  * @param[in] request_id The id of request
 161  * @param[in] index The current index of request
 162  * @param[in] total_count The total number of request
 163  * @param[in] latitude The latitude [-90.0 ~ 90.0] (degrees)
 164  * @param[in] longitude The longitude [-180.0 ~ 180.0] (degrees)
 165  * @param[in] user_data The user data passed from the foreach function
 166  * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
 167  * @pre geocoder_geocode() will invoke this callback.
 168  * @see geocoder_geocode()
 169  */
 170 typedef void (*geocoder_get_geocode_cb)(geocoder_error_e result, int request_id, int index, int total_count, double latitude, double longitude, void *user_data);
 171
 172 /**
 173  * @brief Called when the address information has converted from position information.
 174  * @remarks You should not free all string values.
 175  * @param[in] result The result of request
 176  * @param[in] request_id The id of request
 177  * @param[in] index The current index of request
 178  * @param[in] total_count The total number of request
 179  * @param[in] building_number The building number
 180  * @param[in] postal_code The postal delivery code
 181  * @param[in] street The full street name
 182  * @param[in] city The city name
 183  * @param[in] district The municipal district name
 184  * @param[in] state The state or province region of a nation
 185  * @param[in] country_code The country code
 186  * @param[in] country The country
 187  * @param[in] county The county
 188  * @param[in] text The description
 189  * @param[in] user_data The user data passed from the foreach function
 190  * @pre geocoder_reverse_geocode() will invoke this callback.
 191  * @see geocoder_reverse_geocode()
 192  */
 193 typedef void (*geocoder_get_reverse_geocode_cb)(geocoder_error_e result, int request_id, int index, int total_count, const char *building_number, const char *postal_code, const char *street, const  char *city, const char *district, const char *state, const char *country_code, const char *country, const char *county, const char *text, void *user_data);
 194
 195 /**
 196  * @brief Gets the positions for a given address, asynchronously.
 197  * @details This function gets positions for a given free-formed address string.
 198  * @remarks This function requires network access.
 199  * @param[in] geocoder The geocoder handle
 200  * @param[in] address The free-formed address
 201  * @param[in] callback The geocoder get positions callback function
 202  * @param[in] user_data The user data to be passed to the callback function
 203  * @param[out] request_id The id of request
 204  * @return 0 on success, otherwise a negative error value.
 205  * @retval #GEOCODER_ERROR_NONE Successful
 206  * @retval #GEOCODER_ERROR_INVALID_PARAMETER Invalid parameter
 207  * @retval #GEOCODER_ERROR_NETWORK_FAILED Network connection failed
 208  * @retval #GEOCODER_ERROR_SERVICE_NOT_AVAILABLE Service not available
 209  * @post It invokes geocoder_get_geocode_cb() to get changes in position.
 210  * @see geocoder_get_geocode_cb()
 211  * @see geocoder_reverse_geocode()
 212  */
 213 int geocoder_geocode(geocoder_h geocoder, const char *address, geocoder_get_geocode_cb callback, void *user_data, int *request_id);
 214
 215 /**
 216  * @brief Gets the address for a given position, asynchronously.
 217  * @remarks This function requires network access.
 218  * @param[in] geocoder The geocoder handle
 219  * @param[in] latitude The latitude [-90.0 ~ 90.0] (degrees)
 220  * @param[in] longitude The longitude [-180.0 ~ 180.0] (degrees)
 221  * @param[in] callback The callback which will receive address information
 222  * @param[in] user_data The user data to be passed to the callback function
 223  * @param[out] request_id The id of request
 224  * @return 0 on success, otherwise a negative error value.
 225  * @retval #GEOCODER_ERROR_NONE Successful
 226  * @retval #GEOCODER_ERROR_INVALID_PARAMETER Invalid parameter
 227  * @retval #GEOCODER_ERROR_NETWORK_FAILED Network connection failed
 228  * @retval #GEOCODER_ERROR_SERVICE_NOT_AVAILABLE Service not available
 229  * @post This function invokes geocoder_get_reverse_geocode_cb().
 230  * @see geocoder_get_reverse_geocode_cb()
 231  * @see geocoder_geocode()
 232  */
 233 int geocoder_reverse_geocode(geocoder_h geocoder, double latitude, double longitude, geocoder_get_reverse_geocode_cb callback, void *user_data, int *request_id);
 234
 235 /**
 236  * @brief Cancels the reuqest.
 237  * @remarks This function requires network access.
 238  * @param[in] geocoder The geocoder handle
 239  * @param[in] request_id The id of request
 240  * @return 0 on success, otherwise a negative error value.
 241  * @retval #GEOCODER_ERROR_NONE Successful
 242  * @retval #GEOCODER_ERROR_INVALID_PARAMETER Invalid parameter
 243  * @retval #GEOCODER_ERROR_NETWORK_FAILED Network connection failed
 244  * @retval #GEOCODER_ERROR_SERVICE_NOT_AVAILABLE Service not available
 245  * @see geocoder_reverse_geocode()
 246  * @see geocoder_geocode()
 247  */
 248 int geocoder_cancel(geocoder_h geocoder, int request_id);
 249
 250
 251 /**
 252  * @brief Creates a new geocoder preference handle.
 253  * @remarks @a preference must be released geocoder_preference_destroy() by you.
 254  * @param[out] preference A handle of a new geocoder preference handle on success
 255  * @return 0 on success, otherwise a negative error value.
 256  * @retval #GEOCODER_ERROR_NONE Successful
 257  * @retval #GEOCODER_ERROR_INVALID_PARAMETER Invalid parameter
 258  * @retval #GEOCODER_ERROR_NETWORK_FAILED Network connection failed
 259  * @retval #GEOCODER_ERROR_SERVICE_NOT_AVAILABLE Service not available
 260  * @see geocoder_preference_destroy()
 261  */
 262 int geocoder_preference_create (geocoder_preference_h *preference);
 263
 264 /**
 265  * @brief Destroys the geocoder preference handle and releases all its resources.
 266  * @param[in] preference The geocoder preference handle to destroy
 267  * @return 0 on success, otherwise a negative error value.
 268  * @retval #GEOCODER_ERROR_NONE Successful
 269  * @retval #GEOCODER_ERROR_INVALID_PARAMETER Invalid parameter
 270  * @see geocoder_preference_create()
 271  */
 272 int geocoder_preference_destroy (geocoder_preference_h preference);
 273
 274 /**
 275  * @brief Gets the preference value
 276  * @remarks @a value must be released @c free() by you.
 277  * @param[in] preference The geocoder preference handle
 278  * @param[in] key The key of preference
 279  * @param[out] value The preference value
 280  * @return 0 on success, otherwise a negative error value.
 281  * @retval #GEOCODER_ERROR_NONE Successful
 282  * @retval #GEOCODER_ERROR_INVALID_PARAMETER Invalid parameter
 283  * @see geocoder_preference_set()
 284  */
 285 int geocoder_preference_get(geocoder_preference_h preference, const char *key, char **value);
 286
 287 /**
 288  * @brief Sets the preference value
 289  * @param[in] preference The geocoder preference handle
 290  * @param[in] key The key of preference
 291  * @param[in] value The preference value to set, could be NULL if want to remove value
 292  * @return 0 on success, otherwise a negative error value.
 293  * @retval #GEOCODER_ERROR_NONE Successful
 294  * @retval #GEOCODER_ERROR_INVALID_PARAMETER Invalid parameter
 295  * @see geocoder_preference_get()
 296  */
 297 int geocoder_preference_set(geocoder_preference_h preference, const char *key, const char *value);
 298
 299 /**
 300  * @brief Gets the number of maximum result
 301  * @param[in] preference The geocoder preference handle
 302  * @param[out] max_result The number of maximum result
 303  * @return 0 on success, otherwise a negative error value.
 304  * @retval #GEOCODER_ERROR_NONE Successful
 305  * @retval #GEOCODER_ERROR_INVALID_PARAMETER Invalid parameter
 306  * @see geocoder_preference_set_max_result()
 307  */
 308 int geocoder_preference_get_max_result(geocoder_preference_h preference, int *max_result);
 309
 310 /**
 311  * @brief Sets the number of maximum result
 312  * @param[in] preference The geocoder preference handle
 313  * @param[in] max_result The number of maximum result
 314  * @return 0 on success, otherwise a negative error value.
 315  * @retval #GEOCODER_ERROR_NONE Successful
 316  * @retval #GEOCODER_ERROR_INVALID_PARAMETER Invalid parameter
 317  * @see geocoder_preference_get_max_result()
 318  */
 319 int geocoder_preference_set_max_result(geocoder_preference_h preference, int max_result);
 320
 321 /**
 322  * @brief Retrieves all available preference keys
 323  * @param[in] preference The geocoder preference handle
 324  * @param[in] key The key of preference
 325  * @param[out] value The preference value
 326  * @return 0 on success, otherwise a negative error value.
 327  * @retval #GEOCODER_ERROR_NONE Successful
 328  * @retval #GEOCODER_ERROR_INVALID_PARAMETER Invalid parameter
 329  * @see geocoder_preference_set()
 330  * @see geocoder_preference_get()
 331  */
 332 int geocoder_preference_foreach_available_keys(geocoder_h geocoder, geocoder_preference_available_key_cb callback , void * user_data);
 333
 334 /**
 335  * @brief Gets the geocoder preference
 336  * @param[in] geocoder The geocoder handle
 337  * @param[out] preference The geocoder preference handle
 338  * @return 0 on success, otherwise a negative error value.
 339  * @retval #GEOCODER_ERROR_NONE Successful
 340  * @retval #GEOCODER_ERROR_INVALID_PARAMETER Invalid parameter
 341  * @see geocoder_service_set_preference()
 342  */
 343 int geocoder_service_get_preference(geocoder_h geocoder, geocoder_preference_h *preference);
 344
 345 /**
 346  * @brief Sets the geocoder preference
 347  * @param[in] geocoder The geocoder handle
 348  * @param[in] preference The geocoder preference handle
 349  * @return 0 on success, otherwise a negative error value.
 350  * @retval #GEOCODER_ERROR_NONE Successful
 351  * @retval #GEOCODER_ERROR_INVALID_PARAMETER Invalid parameter
 352  * @see geocoder_service_get_preference()
 353  */
 354 int geocoder_service_set_preference(geocoder_h geocoder, geocoder_preference_h preference);
 355
 356
 357
 358 /**
 359  * @}
 360  */
 361
 362 #ifdef __cplusplus
 363 }
 364 #endif
 365
 366 #endif /* __TIZEN_LOCATION_GEOCODER_H__ */