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
  38
  39 /**
  40  * @brief Enumerations of error code for Geocoder
  41  */
  42 typedef enum
  43 {
  44     GEOCODER_ERROR_NONE = TIZEN_ERROR_NONE,                             /**< Successful */
  45     GEOCODER_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,           /**< Out of memory */
  46     GEOCODER_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,                   /**< Invalid parameter */
  47     GEOCODER_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT,  /**< Timeout error, no answer */
  48     GEOCODER_ERROR_NETWORK_FAILED = TIZEN_ERROR_LOCATION_CLASS | 0x02,                  /**< Network unavailable*/
  49     GEOCODER_ERROR_SERVICE_NOT_AVAILABLE = TIZEN_ERROR_LOCATION_CLASS | 0x03,   /**< Service unavailable */
  50     GEOCODER_ERROR_NOT_FOUND = TIZEN_ERROR_LOCATION_CLASS | 0x04,       /**< Result not found */
  51 } geocoder_error_e;
  52
  53 /**
  54  * @brief       Called once for each position information converted from the given address information.
  55  * @param[in] result The result of request
  56  * @param[in] latitude The latitude [-90.0 ~ 90.0] (degrees)
  57  * @param[in] longitude The longitude [-180.0 ~ 180.0] (degrees)
  58  * @param[in] user_data The user data passed from the foreach function
  59  * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
  60  * @pre geocoder_foreach_positions_from_address() will invoke this callback.
  61  * @see geocoder_foreach_positions_from_address()
  62  */
  63 typedef bool(*geocoder_get_position_cb)(geocoder_error_e result, double latitude, double longitude, void *user_data);
  64
  65
  66 /**
  67  * @brief   Called when the address information has converted from position information.
  68  * @remarks You should not free all string values.
  69  * @param[in] result The result of request
  70  * @param[in] building_number    The building number
  71  * @param[in] postal_code       The postal delivery code
  72  * @param[in] street    The full street name
  73  * @param[in] city      The city name
  74  * @param[in] district  The municipal district name
  75  * @param[in] state     The state or province region of a nation
  76  * @param[in] country_code      The country code
  77  * @param[in] user_data The user data passed from the foreach function
  78  * @pre geocoder_get_address_from_position() will invoke this callback.
  79  * @see geocoder_get_address_from_position()
  80  */
  81 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);
  82
  83 /**
  84  * @brief Creates a new geocoder handle.
  85  * @details
  86  * A geocoder handle can be used to change position information to address information and vice versa.
  87  * @remarks @a geocoder must be released geocoder_destroy() by you.
  88  * @param   [out] geocoder  A handle of a new geocoder handle on success
  89  * @return 0 on success, otherwise a negative error value.
  90  * @retval #GEOCODER_ERROR_NONE Successful
  91  * @retval #GEOCODER_ERROR_OUT_OF_MEMORY Out of memory
  92  * @retval #GEOCODER_ERROR_INVALID_PARAMETER    Invalid parameter
  93  * @retval #GEOCODER_ERROR_SERVICE_NOT_AVAILABLE Service not available
  94  * @see geocoder_destroy()
  95  */
  96 int geocoder_create(geocoder_h *geocoder);
  97
  98 /**
  99  * @brief       Destroys the geocoder handle and releases all its resources.
 100  * @param   [in] geocoder       The geocoder handle to destroy
 101  * @return  0 on success, otherwise a negative error value.
 102  * @retval #GEOCODER_ERROR_NONE Successful
 103  * @retval #GEOCODER_ERROR_INVALID_PARAMETER    Invalid parameter
 104  * @see geocoder_create()
 105  */
 106 int geocoder_destroy(geocoder_h geocoder);
 107
 108 /**
 109  * @brief Gets the address for a given position, asynchronously.
 110  * @remarks This function requires network access.
 111  * @param[in] geocoder The geocoder handle
 112  * @param[in] latitude The latitude [-90.0 ~ 90.0] (degrees)
 113  * @param[in] longitude The longitude [-180.0 ~ 180.0] (degrees)
 114  * @param[in] callback The callback which will receive address information
 115  * @param[in] user_data The user data to be passed to the callback function
 116  * @return 0 on success, otherwise a negative error value.
 117  * @retval #GEOCODER_ERROR_NONE Successful
 118  * @retval #GEOCODER_ERROR_INVALID_PARAMETER    Invalid parameter
 119  * @retval #GEOCODER_ERROR_NETWORK_FAILED       Network connection failed
 120  * @retval #GEOCODER_ERROR_SERVICE_NOT_AVAILABLE Service not available
 121  * @post This function invokes geocoder_get_address_cb().
 122  * @see geocoder_get_address_cb()
 123  * @see geocoder_foreach_positions_from_address()
 124  */
 125 int geocoder_get_address_from_position(geocoder_h geocoder, double latitude, double longitude, geocoder_get_address_cb callback, void *user_data);
 126
 127 /**
 128  * @brief Gets the positions for a given address, asynchronously.
 129  * @details This function gets positions for a given free-formed address string.
 130  * @remarks This function requires network access.
 131  * @param[in] geocoder  The geocoder handle
 132  * @param[in] address   The free-formed address
 133  * @param[in] callback  The geocoder get positions callback function
 134  * @param[in] user_data The user data to be passed to the callback function
 135  * @return 0 on success, otherwise a negative error value.
 136  * @retval #GEOCODER_ERROR_NONE Successful
 137  * @retval #GEOCODER_ERROR_INVALID_PARAMETER    Invalid parameter
 138  * @retval #GEOCODER_ERROR_NETWORK_FAILED       Network connection failed
 139  * @retval #GEOCODER_ERROR_SERVICE_NOT_AVAILABLE Service not available
 140  * @post It invokes geocoder_get_position_cb() to get changes in position.
 141  * @see geocoder_get_position_cb()
 142  * @see geocoder_get_address_from_position()
 143  */
 144 int geocoder_foreach_positions_from_address(geocoder_h geocoder, const char *address, geocoder_get_position_cb callback, void *user_data);
 145
 146 /**
 147  * @}
 148  */
 149
 150 #ifdef __cplusplus
 151 }
 152 #endif
 153
 154 #endif /* __TIZEN_LOCATION_GEOCODER_H__ */