include/location_preference.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_LOCATION_PREFERENCE_H__
  18 #define __TIZEN_LOCATION_LOCATION_PREFERENCE_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_PREF_MODULE
  30  * @{
  31  */
  32
  33 /**
  34  * @brief The handle of location service
  35  */
  36 typedef void* location_service_h;
  37
  38
  39 /**
  40  * @brief Gets a handle of location service from x
  41  */
  42 #define GET_LOCATION_SERVICE(x) (location_service_h)(x)
  43
  44
  45 /**
  46  * @brief Enumerations of error code for Location Preference
  47  */
  48 typedef enum
  49 {
  50     LOCATION_PREFERENCE_ERROR_NONE = TIZEN_ERROR_NONE,    /**< Successful */
  51     LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,    /**< Invalid parameter */
  52     LOCATION_PREFERENCE_ERROR_RESULT_NOT_FOUND = TIZEN_ERROR_LOCATION_CLASS|0x0101,    /**<  Result not found */
  53     LOCATION_PREFERENCE_ERROR_NETWORK_FAILED = TIZEN_ERROR_LOCATION_CLASS|0x0102,    /**< Network unavailable */
  54     LOCATION_PREFERENCE_ERROR_INVALID_KEY = TIZEN_ERROR_LOCATION_CLASS | 0x0103,   /**< Invalid key */
  55 } location_preference_error_e;
  56
  57 /**
  58  * @brief Enumerations of distance unit
  59  */
  60 typedef enum
  61 {
  62     LOCATION_PREFERENCE_DISTANCE_UNIT_M = 0,  /**< Meter */
  63     LOCATION_PREFERENCE_DISTANCE_UNIT_KM = 1,  /**< Kilometer */
  64     LOCATION_PREFERENCE_DISTANCE_UNIT_FT = 2,  /**< Feet */
  65     LOCATION_PREFERENCE_DISTANCE_UNIT_YD = 3,  /**< Mile */
  66     LOCATION_PREFERENCE_DISTANCE_UNIT_MI = 4,  /**< Mile */
  67 } location_preference_distance_unit_e;
  68
  69 /**
  70  * @brief Called repeatedly when you get the available property keys.
  71  * @param[in] key The property key of location preference
  72  * @param[in] user_data The user data passed from foreach function
  73  * @pre location_preference_foreach_available_property_keys() will invoke this callback.
  74  * @return  @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
  75  * @see location_preference_foreach_available_property_keys()
  76  */
  77 typedef bool (*location_preference_available_property_key_cb)(const char* key, void* user_data);
  78
  79 /**
  80  * @brief Called repeatedly when you get the available property values.
  81  * @param[in] value The property value of location preference
  82  * @param[in] user_data The user data passed from foreach function
  83  * @pre location_preference_foreach_available_property_values() will invoke this callback.
  84  * @return  @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
  85  * @see location_preference_foreach_available_property_values()
  86  */
  87 typedef bool (*location_preference_available_property_value_cb)(const char* value, void* user_data);
  88
  89 /**
  90  * @brief Called repeatedly when you get the available languages.
  91  * @param[in] language The language of location preference
  92  * @param[in] user_data The user data passed from foreach function
  93  * @pre location_preference_foreach_available_languages() will invoke this callback.
  94  * @return  @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
  95  * @see location_preference_foreach_available_languages()
  96  */
  97 typedef bool (*location_preference_available_language_cb)(const char* language, void* user_data);
  98
  99 /**
 100  * @brief Called repeatedly when you get the available country code.
 101  * @param[in] country_code The country code of location preference
 102  * @param[in] user_data The user data passed from foreach function
 103  * @pre location_preference_foreach_available_country_code() will invoke this callback.
 104  * @return  @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
 105  * @see location_preference_foreach_available_country_code()
 106  */
 107 typedef bool (*location_preference_available_country_code_cb)(const char* country_code, void* user_data);
 108
 109 /**
 110  * @brief Called repeatedly when you get the properties that was set in location preference.
 111  * @param[in] key The property key of location preference
 112  * @param[in] value The property value of location preference
 113  * @param[in] user_data The user data passed from foreach function
 114  * @pre location_preference_foreach_properties() will invoke this callback.
 115  * @return  @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
 116  * @see location_preference_foreach_properties()
 117  */
 118 typedef bool (*location_preference_property_cb)(const char* key, const char* value, void* user_data);
 119
 120 /**
 121  * @brief Called repeatedly to get each supported providers.
 122  * @param[in] provider The supported provider name
 123  * @param[in] user_data The user data passed from the foreach function
 124  * @return @c true to continue with the next iteration of the loop, \n @c false to break outsp of the loop.
 125  * @pre location_preference_foreach_supported_provider() will invoke this callback.
 126  * @see location_preference_foreach_supported_provider()
 127  */
 128 typedef bool (*location_preference_supported_provider_cb)(const char* provider, void *user_data);
 129
 130 /**
 131  * @brief Retrieves the available property keys of location preference.
 132  * @param[in] location_service The memory pointer of location service handle.
 133  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 134  * @param[in] callback The callback function to be invoked
 135  * @param[in] user_data The user data passed to the callback function
 136  * @return 0 on success, otherwise a negative error value.
 137  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 138  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 139  * @retval #LOCATION_PREFERENCE_ERROR_NETWORK_FAILED Network unavailable
 140  * @retval #LOCATION_PREFERENCE_ERROR_RESULT_NOT_FOUND Result not found
 141  * @post location_preference_available_property_key_cb() will be invoked.
 142  * @see GET_LOCATION_SERVICE()
 143  * @see location_preference_available_property_key_cb()
 144  * @see location_preference_foreach_available_property_values()
 145  */
 146 int location_preference_foreach_available_property_keys(location_service_h service, location_preference_available_property_key_cb callback, void* user_data);
 147
 148 /**
 149  * @brief Retrieves the available property values of location preference.
 150  * @param[in] location_service The memory pointer of location service handle.
 151  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 152  * @param[in] key The property of location preference
 153  * @param[in] callback The callback function to be invoked
 154  * @param[in] user_data The user data passed to the callback function
 155  * @return 0 on success, otherwise a negative error value.
 156  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 157  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 158  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_KEY Invalid key
 159  * @retval #LOCATION_PREFERENCE_ERROR_RESULT_NOT_FOUND Result not found
 160  * @post location_preference_available_property_value_cb() will be invoked.
 161  * @see GET_LOCATION_SERVICE()
 162  * @see location_preference_available_property_value_cb()
 163  * @see location_preference_foreach_available_property_keys()
 164  */
 165 int location_preference_foreach_available_property_values(location_service_h service, const char* key, location_preference_available_property_value_cb callback, void* user_data);
 166
 167 /**
 168  * @brief Retrieves the available languages of location preference.
 169  * @param[in] location_service The memory pointer of location service handle.
 170  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 171  * @param[in] callback The callback function to be invoked
 172  * @param[in] user_data The user data passed to the callback function
 173  * @return 0 on success, otherwise a negative error value.
 174  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 175  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 176  * @retval #LOCATION_PREFERENCE_ERROR_NETWORK_FAILED Network unavailable
 177  * @retval #LOCATION_PREFERENCE_ERROR_RESULT_NOT_FOUND Result not found
 178  * @post location_preference_available_language_cb() will be invoked.
 179  * @see GET_LOCATION_SERVICE()
 180  * @see location_preference_available_language_cb()
 181  */
 182 int location_preference_foreach_available_languages(location_service_h service, location_preference_available_language_cb callback, void* user_data);
 183
 184 /**
 185  * @brief Retrieves the available country code of location preference.
 186  * @param[in] location_service The memory pointer of location service handle.
 187  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 188  * @param[in] callback The callback function to be invoked
 189  * @param[in] user_data The user data passed to the callback function
 190  * @return 0 on success, otherwise a negative error value.
 191  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 192  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 193  * @retval #LOCATION_PREFERENCE_ERROR_NETWORK_FAILED Network unavailable
 194  * @retval #LOCATION_PREFERENCE_ERROR_RESULT_NOT_FOUND Result not found
 195  * @post location_preference_available_country_code_cb() will be invoked.
 196  * @see GET_LOCATION_SERVICE()
 197  * @see location_preference_available_country_code_cb()
 198  */
 199 int location_preference_foreach_available_country_code(location_service_h service, location_preference_available_country_code_cb callback, void* user_data);
 200
 201 /**
 202  * @brief Gets the location preference that was set in location preference.
 203  * @param[in] location_service The memory pointer of location service handle.
 204  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 205  * @param[in] key The property of location preference
 206  * @param[in] callback The callback function to be invoked
 207  * @param[in] user_data The user data passed to the callback function
 208  * @return 0 on success, otherwise a negative error value.
 209  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 210  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 211  * @see GET_LOCATION_SERVICE()
 212  */
 213 int location_preference_foreach_properties(location_service_h service, location_preference_property_cb callback, void* user_data);
 214
 215 /**
 216  * @brief Sets the location preference value.
 217  * @param[in] location_service The memory pointer of location service handle.
 218  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 219  * @param[in] property The property of location preference
 220  * @param[in] value The value of  location preference
 221  * @return 0 on success, otherwise a negative error value.
 222  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 223  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 224  * @see GET_LOCATION_SERVICE()
 225  * @see location_preference_foreach_available_property_keys()
 226  * @see location_preference_foreach_available_property_values()
 227  * @see location_preference_get()
 228  */
 229 int location_preference_set(location_service_h service, const char* key, const char* value);
 230
 231 /**
 232  * @brief Gets the location preference value.
 233  * @param[in] location_service The memory pointer of location service handle.
 234  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 235  * @param[in] property The property of location preference
 236  * @param[out] value The value of  location preference
 237  * @return 0 on success, otherwise a negative error value.
 238  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 239  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 240  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_KEY Invalid key
 241  * @see GET_LOCATION_SERVICE()
 242  * @see location_preference_foreach_available_property_keys()
 243  * @see location_preference_set()
 244  */
 245 int location_preference_get(location_service_h service, const char* key, char** value);
 246
 247 __attribute__ ((deprecated)) int location_preference_get_provider_name(location_service_h service, char** provider);
 248
 249 /**
 250  * @brief Sets the provider of location service.
 251  * @param[in] location_service The memory pointer of location service handle.
 252  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 253  * @param[in] provider The provider name of location service
 254  * @return 0 on success, otherwise a negative error value.
 255  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 256  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 257  * @see GET_LOCATION_SERVICE()
 258  * @see location_preference_get_provider()
 259  */
 260 int location_preference_set_provider(location_service_h service, char* provider);
 261
 262 /**
 263  * @brief Gets the provider of location service.
 264  * @remarks The @a provider must be released with free() by you.
 265  * @param[in] location_service The memory pointer of location service handle.
 266  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 267  * @param[out] provider The provider name of location service
 268  * @return 0 on success, otherwise a negative error value.
 269  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 270  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 271  * @see GET_LOCATION_SERVICE()
 272  * @see location_preference_set_provider()
 273  */
 274 int location_preference_get_provider(location_service_h service, char** provider);
 275
 276 /**
 277  * @brief Gets the default provider of location service.
 278  * @remarks The @a provider must be released with free() by you.
 279  * @param[in] location_service The memory pointer of location service handle.
 280  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 281  * @param[out] provider The default provider name of location service
 282  * @return 0 on success, otherwise a negative error value.
 283  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 284  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 285  * @see GET_LOCATION_SERVICE()
 286  */
 287 int location_preference_get_default_provider(location_service_h service, char** provider);
 288
 289 /**
 290  * @brief Gets the provider of location service.
 291  * @param[in] location_service The memory pointer of location service handle.
 292  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 293  * @param[in] callback The callback function to be invoked
 294  * @param[in] user_data The user data passed to the callback function
 295  * @return 0 on success, otherwise a negative error value.
 296  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 297  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 298  * @post        This function invokes location_preference_supported_provider_cb() to get all supported providers.
 299  * @see GET_LOCATION_SERVICE()
 300  * @see location_preference_set_provider()
 301  */
 302 int location_preference_foreach_supported_provider(location_service_h service, location_preference_supported_provider_cb callback , void *user_data);
 303
 304 /**
 305  * @brief Gets the distance unit of location service.
 306  * @param[in] location_service The memory pointer of location service handle.
 307  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 308  * @param[out] unit The distance unit
 309  * @return 0 on success, otherwise a negative error value.
 310  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 311  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 312  * @retval #LOCATION_PREFERENCE_ERROR_RESULT_NOT_FOUND Result not found
 313  * @see GET_LOCATION_SERVICE()
 314  * @see location_preference_set_distance_unit()
 315  */
 316 int location_preference_get_distance_unit(location_service_h service, location_preference_distance_unit_e* unit);
 317
 318 /**
 319  * @brief Sets the distance unit of location service.
 320  * @param[in] location_service The memory pointer of location service handle.
 321  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 322  * @param[in] unit The distance unit
 323  * @return 0 on success, otherwise a negative error value.
 324  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 325  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 326  * @see GET_LOCATION_SERVICE()
 327  * @see location_preference_get_distance_unit()
 328  */
 329 int location_preference_set_distance_unit(location_service_h service, location_preference_distance_unit_e unit);
 330
 331 /**
 332  * @brief Gets the language of location service.
 333  * @param[in] location_service The memory pointer of location service handle.
 334  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 335  * @param[out] language The language
 336  * @return 0 on success, otherwise a negative error value.
 337  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 338  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 339  * @see GET_LOCATION_SERVICE()
 340  * @see location_preference_set_language()
 341  */
 342 int location_preference_get_language(location_service_h service, char** language);
 343
 344 /**
 345  * @brief Sets the language of location service.
 346  * @param[in] location_service The memory pointer of location service handle.
 347  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 348  * @param[in] language The language
 349  * @return 0 on success, otherwise a negative error value.
 350  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 351  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 352  * @see GET_LOCATION_SERVICE()
 353  * @see location_preference_get_language()
 354  */
 355 int location_preference_set_language(location_service_h service, const char* language);
 356
 357 /**
 358  * @brief Sets the country code.
 359  * @param[in] location_service The memory pointer of location service handle.
 360  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 361  * @param[in] country_code The country code
 362  * @return 0 on success, otherwise a negative error value.
 363  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 364  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 365  * @see GET_LOCATION_SERVICE()
 366  * @see location_preference_get_country_code()
 367  */
 368 int location_preference_set_country_code(location_service_h service, const char* country_code);
 369
 370 /**
 371  * @brief Gets the country code.
 372  * @param[in] location_service The memory pointer of location service handle.
 373  *                 It must be converted into location_service_h by GET_LOCATION_SERVICE().
 374  * @param[out] country_code The country code
 375  * @return 0 on success, otherwise a negative error value.
 376  * @retval #LOCATION_PREFERENCE_ERROR_NONE Successful
 377  * @retval #LOCATION_PREFERENCE_ERROR_INVALID_PARAMETER Invalid parameter
 378  * @see GET_LOCATION_SERVICE()
 379  * @see location_preference_set_country_code()
 380  */
 381 int location_preference_get_country_code(location_service_h service, char** country_code);
 382
 383 /**
 384  * @}
 385  */
 386
 387 #ifdef __cplusplus
 388 }
 389 #endif
 390
 391 #endif /* __TIZEN_LOCATION_LOCATION_PREFERENCE_H__ */