location/manager/location.h

   1 /*
   2  * libslp-location
   3  *
   4  * Copyright (c) 2010-2013 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18
  19
  20 #ifndef __LOCATION_H__
  21 #define __LOCATION_H__
  22
  23
  24 #include <glib.h>
  25 #include <location-types.h>
  26 #include <location-position.h>
  27 #include <location-batch.h>
  28 #include <location-velocity.h>
  29 #include <location-accuracy.h>
  30 #include <location-boundary.h>
  31 #include <location-satellite.h>
  32
  33 G_BEGIN_DECLS
  34
  35 /**
  36  * @file location.h
  37  * @brief This file contains the Location API and related structure and enumeration.
  38  */
  39 /**
  40  * @defgroup LocationFW LocationFW
  41  * @brief This is a Location Framework for providing location based services.
  42  * @addtogroup LocationFW
  43  * @{
  44  * @defgroup LocationAPI Location API
  45  * @brief This sub module provides the Location API.
  46  * @addtogroup LocationAPI
  47  * @{
  48  */
  49
  50 /**
  51  * @brief Initialize location sub module.
  52  * @remarks None. This API should be called before any other Location APIs.
  53  * @pre None.
  54  * @post None.
  55  * @return int
  56  * @retval 0                                                    Success
  57  * Please refer #LocationError for more information.
  58  * @see None.
  59  */
  60 int location_init(void);
  61
  62 /**
  63  * @brief Create a new #LocationObject by using given #LocationMethod.
  64  * @remarks Returned object is necessary for other APIs.
  65  * @pre #location_init should be called before.
  66  * @post None.
  67  * @param [in] method - Location method to be used.
  68  * @return a new #LocationObject
  69  * @retval NULL                 if error occured
  70  * @see location_free
  71  */
  72 LocationObject *location_new(LocationMethod method, gboolean multi_handle);
  73
  74 /**
  75  * @brief Free memory of given #LocationObject.
  76  * @remarks None.
  77  * @pre #location_init should be called before.
  78  * @post None.
  79  * @param [in] obj - a #LocationObject created by #location_new.
  80  * @return int
  81  * @retval 0                                                    Success.
  82  * Please refer #LocationError for more information.
  83  */
  84 int location_free(LocationObject *obj, gboolean multi_handle);
  85
  86 /**
  87  * @brief Start the location service by using given #LocationObject.
  88  * @remarks If you want to recieve signals, you should use this API.
  89  * @pre #location_init should be called before.
  90  * @post None.
  91  * @param [in] obj - a #LocationObject created by #location_new
  92  * @return int
  93  * @retval 0                                                    Success.
  94  * Please refer #LocationError for more information.
  95  */
  96 int location_start(LocationObject *obj);
  97
  98 /**
  99  * @brief Stop the location service by using given #LocationObject.
 100  * @remarks After call this API, you can not recieve signals.
 101  * @pre #location_init should be called before.\n
 102  * #location_start should be called before.
 103  * @post None.
 104  * @param [in] obj - a #LocationObject created by #location_new
 105  * @return int
 106  * @retval 0                                                    Success
 107  * Please refer #LocationError for more information.
 108  */
 109 int location_stop(LocationObject *obj);
 110
 111 int location_request_single_location(LocationObject *obj, int timeout);
 112
 113 int location_cancel_single_location(LocationObject *obj);
 114
 115 /**
 116  * @brief Check wheither a method is available.
 117  * @remarks
 118  * @pre #location_init should be called before.\n
 119  * @post None.
 120  * @param [in] method - a #LocationMethod
 121  * @return int
 122  * @retval True         Supported
 123  *              False           Not supported
 124  */
 125 gboolean location_is_supported_method(LocationMethod method);
 126
 127 int location_is_enabled_method(LocationMethod method, int *is_enabled);
 128
 129 int location_enable_method(const LocationMethod method, const int enable);
 130
 131
 132 /**
 133  * @brief Get current position information with estimate of the accuracy.
 134  * @remarks Out parameters are should be freed.
 135  * @pre #location_init should be called before.\n #location_start should be called before.
 136  * @post None.
 137  * @param [in] obj - a #LocationObject created by #location_new
 138  * @param [out] position - a new #LocationPosition
 139  * @param [out] accuracy - a new #LocationAccuracy
 140  * @return int
 141  * @retval 0                                                    Success
 142  * Please refer #LocationError for more information.
 143  */
 144 int location_get_position(LocationObject *obj, LocationPosition **position, LocationAccuracy **accuracy);
 145
 146 /**
 147  * @brief Get current position & velocity information with estimate of the accuracy.
 148  * @remarks Out parameters are should be freed.
 149  * @pre #location_init should be called before.\n #location_start should be called before.
 150  * @post None.
 151  * @param [in] obj - a #LocationObject created by #location_new
 152  * @param [out] position - a new #LocationPosition
 153  * @param [out] velocity - a new #LocationVelocity
 154  * @param [out] accuracy - a new #LocationAccuracy
 155  * @return int
 156  * @retval 0                                                    Success
 157  * Please refer #LocationError for more information.
 158  */
 159 int location_get_position_ext(LocationObject *obj, LocationPosition **position, LocationVelocity **velocity, LocationAccuracy **accuracy);
 160
 161 /**
 162  * @brief Get last position information with estimate of the accuracy.
 163  * @remarks Out parameters are should be freed.
 164  * @pre #location_init should be called before.
 165  * @post None.
 166  * @param [in] obj - a #LocationObject created by #location_new
 167  * @param [out] position - a new #LocationPosition
 168  * @param [out] accuracy - a new #LocationAccuracy
 169  * @return int
 170  * @retval 0                                                    Success
 171  * Please refer #LocationError for more information.
 172  */
 173 int location_get_last_position(LocationObject *obj, LocationPosition **position, LocationAccuracy **accuracy);
 174
 175 /**
 176  * @brief Get last position & velocity information with estimate of the accuracy.
 177  * @remarks Out parameters are should be freed.
 178  * @pre #location_init should be called before.
 179  * @post None.
 180  * @param [in] obj - a #LocationObject created by #location_new
 181  * @param [out] position - a new #LocationPosition
 182  * @param [out] velocity - a new #LocationVelocity
 183  * @param [out] accuracy - a new #LocationAccuracy
 184  * @return int
 185  * @retval 0                                                    Success
 186  * Please refer #LocationError for more information.
 187  */
 188 int location_get_last_position_ext(LocationObject *obj, LocationPosition **position, LocationVelocity **velocity, LocationAccuracy **accuracy);
 189 /**
 190  * @brief Get last satellite information.
 191  * @remarks This API is not implemented now. \n Out parameters are should be freed.
 192  * @pre #location_init should be called before.
 193  * @post None.
 194  * @param [in] obj - a #LocationObject created by #location_new
 195  * @param [out] satellite - a new #LocationSatellite
 196  * @return int
 197  * @retval 0                                                    Success
 198  * Please refer #LocationError for more information.
 199  */
 200 int location_get_satellite(LocationObject *obj, LocationSatellite **satellite);
 201
 202
 203 int location_start_batch(LocationObject *obj);
 204
 205 int location_stop_batch(LocationObject *obj);
 206
 207 int location_get_batch(LocationObject *obj, LocationBatch **batch);
 208
 209
 210 /**
 211  * @brief Get last satellite information.
 212  * @remarks This API is not implemented now. \n Out parameters are should be freed.
 213  * @pre #location_init should be called before.
 214  * @post None.
 215  * @param [in] obj - a #LocationObject created by #location_new
 216  * @param [out] satellite - a new #LocationSatellite
 217  * @return int
 218  * @retval 0                                                    Success
 219  * Please refer #LocationError for more information.
 220  */
 221 int location_get_last_satellite(LocationObject *obj, LocationSatellite **satellite);
 222
 223 /**
 224  * @brief Get current velocity information with estimate of the accuracy.
 225  * @remarks Out parameters are should be freed.
 226  * @pre #location_init should be called before.\n #location_start should be called before.
 227  * @post None.
 228  * @param [in] obj - a #LocationObject created by #location_new
 229  * @param [out] velocity - a new #LocationVelocity
 230  * @param [out] accuracy - a new #LocationAccuracy
 231  * @return int
 232  * @retval 0                                                    Success
 233  * Please refer #LocationError for more information.
 234  */
 235 int location_get_velocity(LocationObject *obj, LocationVelocity **velocity, LocationAccuracy **accuracy);
 236
 237 /**
 238  * @brief Get last velocity information with estimate of the accuracy.
 239  * @remarks Out parameters are should be freed.
 240  * @pre #location_init should be called before.
 241  * @post None.
 242  * @param [in] obj - a #LocationObject created by #location_new
 243  * @param [out] velocity - a new #LocationVelocity
 244  * @param [out] accuracy - a new #LocationAccuracy
 245  * @return int
 246  * @retval 0                                                    Success
 247  * Please refer #LocationError for more information.
 248  */
 249 int location_get_last_velocity(LocationObject *obj, LocationVelocity **velocity, LocationAccuracy **accuracy);
 250
 251 /**
 252  * @brief Get the accessibility state of an application
 253  * @remarks None.
 254  * @pre #location_init should be called before.\n
 255  * @post None.
 256  * @param [out] state - a #LocationAccessState
 257  * @return int
 258  * @retval 0                                                    Success
 259  * Please refer #LocationError for more information.
 260  */
 261 int location_get_accessibility_state(LocationAccessState *state);
 262
 263 /**
 264  * @brief Send command to the server.
 265  * @pre #location_init should be called before.\n
 266  * Calling application must have glib or ecore main loop.\n
 267  * Calling application must have an active data connection.
 268  * @post None.
 269  * @param [in] cmd - a #char
 270  * @return int
 271  * @retval 0                                                    Success
 272  * Please refer #LocationError for more information.
 273  */
 274 int location_send_command(const char *cmd);
 275
 276 /**
 277  * @brief Set option of server.
 278  * @pre #location_init should be called before.\n
 279  * Calling application must have glib or ecore main loop.\n
 280  * Calling application must have an active data connection.
 281  * @post None.
 282  * @param [in]  obj - a #LocationObject created by #location_new
 283  * @param [in]  option - a #char
 284  * @return int
 285  * @retval 0                                                    Success
 286  * Please refer #LocationError for more information.
 287  */
 288 int location_set_option(LocationObject *obj, const char *option);
 289
 290 int location_add_setting_notify(LocationMethod method, LocationSettingCb callback, void *user_data);
 291
 292 int location_ignore_setting_notify(LocationMethod method, LocationSettingCb callback);
 293
 294 int location_get_nmea(LocationObject *obj, char **nmea_data);
 295
 296
 297 /* Tizen 3.0 */
 298
 299 int location_enable_mock(const int enable);
 300
 301 int location_set_mock_location(LocationObject *obj, const LocationPosition *position, const LocationVelocity *velocity, const LocationAccuracy *accuracy);
 302
 303 int location_clear_mock_location(LocationObject *obj);
 304
 305 int location_enable_restriction(const int enable);
 306
 307 /**
 308  * @} @}
 309  */
 310
 311 G_END_DECLS
 312
 313 #endif /* __LOCATION_H__ */