location/manager/location.h

   1 /*
   2  * libslp-location
   3  *
   4  * Copyright (c) 2010-2013 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Youngae Kang <youngae.kang@samsung.com>, Minjune Kim <sena06.kim@samsung.com>
   7  *          Genie Kim <daejins.kim@samsung.com>
   8  *
   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
  12  *
  13  * http://www.apache.org/licenses/LICENSE-2.0
  14  *
  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.
  20  */
  21
  22
  23 #ifndef __LOCATION_H__
  24 #define __LOCATION_H__
  25
  26
  27 #include <glib.h>
  28 #include <location-types.h>
  29 #include <location-position.h>
  30 #include <location-velocity.h>
  31 #include <location-accuracy.h>
  32 #include <location-address.h>
  33 #include <location-boundary.h>
  34 #include <location-satellite.h>
  35
  36 G_BEGIN_DECLS
  37
  38 /**
  39  * @file location.h
  40  * @brief This file contains the Location API and related structure and enumeration.
  41  */
  42 /**
  43  * @defgroup LocationFW LocationFW
  44  * @brief This is a Location Framework for providing location based services.
  45  * @addtogroup LocationFW
  46  * @{
  47  * @defgroup LocationAPI Location API
  48  * @brief This sub module provides the Location API.
  49  * @addtogroup LocationAPI
  50  * @{
  51  */
  52
  53 /**
  54  * @brief
  55  * Initialize location sub module.
  56  * @remarks None.
  57  * This API should be called before any other Location APIs.
  58  * @pre None.
  59  * @post None.
  60  * @return int
  61  * @retval 0                              Success
  62  *
  63  * Please refer #LocationError for more information.
  64  * @see None.
  65  */
  66 int location_init (void);
  67
  68 /**
  69  * @brief
  70  * Create a new #LocationObject by using given #LocationMethod.
  71  * @remarks
  72  * Returned object is necessary for other APIs.
  73  * @pre
  74  * #location_init should be called before.
  75  * @post None.
  76  * @param [in]
  77  * method - Location method to be used.
  78  * @return a new #LocationObject
  79  * @retval NULL              if error occured
  80  * @see location_free
  81  */
  82 LocationObject *location_new (LocationMethod method);
  83
  84 /**
  85  * @brief
  86  * Free memory of given #LocationObject.
  87  * @remarks None.
  88  * @pre
  89  * #location_init should be called before.
  90  * @post None.
  91  * @param [in]
  92  * obj - a #LocationObject created by #location_new.
  93  * @return int
  94  * @retval 0                              Success.
  95  *
  96  * Please refer #LocationError for more information.
  97  * @see location_new
  98  * @par Example
  99  * @code
 100 #include <location.h>
 101 int main (int argc, char *argv[])
 102 {
 103         LocationObject *loc = NULL;
 104         location_init ();
 105         loc  = location_new (LOCATION_METHOD_GPS);
 106         if(!loc)
 107                 return -1;
 108
 109         // ... Implement your code
 110
 111         location_free (loc);
 112         // You must free LocationObject when you don't need to use anymore.
 113         return 0;
 114 }
 115  * @endcode
 116  */
 117 int location_free (LocationObject *obj);
 118
 119 /**
 120  * @brief
 121  * Start the location service by using given #LocationObject.
 122  * @remarks
 123  * If you want to recieve signals, you should use this API.
 124  * @pre
 125  * #location_init should be called before.
 126  * @post None.
 127  * @param [in]
 128  * obj - a #LocationObject created by #location_new
 129  * @return int
 130  * @retval 0                              Success.
 131  *
 132  * Please refer #LocationError for more information.
 133  * @see location_stop
 134  * @par Example
 135  * @code
 136 #include <location.h>
 137 static GMainLoop *loop = NULL;
 138
 139 static void cb_service_enabled (GObject *self, guint status, gpointer userdata)
 140 {
 141         LocationObject *loc = (LocationObject*)userdata;
 142         LocationAccuracy *acc = NULL;
 143         LocationPosition *pos = NULL;
 144         LocationVelocity *vel = NULL;
 145         LocationAddress *addr = NULL;
 146         LocationMethod method;
 147
 148         g_object_get(loc, "method", &method, NULL);
 149         g_debug("Get property>> method:%d", method);
 150
 151         if (LOCATION_ERROR_NONE == location_get_position (loc, &pos, &acc)) {
 152                 g_debug ("SYNC>> Current position> time: %d, lat: %f, long: %f, alt: %f, status: %d",
 153                         pos->timestamp, pos->latitude, pos->longitude, pos->altitude, pos->status);
 154                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
 155                         acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 156                 location_position_free(pos);
 157                 location_accuracy_free(acc);
 158         } else g_warning ("SYNC>> Current position> failed");
 159
 160         if (LOCATION_ERROR_NONE == location_get_velocity (loc, &vel, &acc)) {
 161                 g_debug ("SYNC>> Current velocity> time: %d, speed: %f, direction:%f, climb:%f",
 162                                 vel->timestamp, vel->speed, vel->direction, vel->climb);
 163                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
 164                                 acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 165                 location_velocity_free(vel);
 166                 location_accuracy_free(acc);
 167         } else g_warning ("SYNC>> Current velocity> failed");
 168
 169         if (LOCATION_ERROR_NONE == location_get_address(loc, &addr, &acc)) {
 170                 g_debug ("SYNC>> Current address> %s %s %s %s %s %s %s",
 171                                 addr->building_number, addr->street, addr->district, addr->city, addr->state, addr->postal_code, addr->country_code);
 172                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 173                 location_address_free(addr);
 174                 location_accuracy_free(acc);
 175         } else g_warning ("SYNC>> Current address> failed");
 176 }
 177
 178 static void
 179 cb_service_updated (GObject *self,
 180        guint type,
 181        gpointer data,
 182        gpointer accuracy,
 183        gpointer userdata)
 184 {
 185         LocationAccuracy *acc = (LocationAccuracy*) accuracy;
 186         switch (type) {
 187                 case POSITION_UPDATED: {
 188                         LocationPosition *pos = (LocationPosition*) data;
 189                         g_debug ("ASYNC>> Current position> time: %d, lat: %f, long: %f, alt: %f, status: %d",
 190                                 pos->timestamp, pos->latitude, pos->longitude, pos->altitude, pos->status);
 191                         g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
 192                                 acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 193                 }
 194                         break;
 195                 case VELOCITY_UPDATED: {
 196                         LocationVelocity *vel = (LocationVelocity*) data;
 197                         g_debug ("ASYNC>> Current velocity> time: %d, speed: %f, direction:%f, climb:%f",
 198                                         vel->timestamp, vel->speed, vel->direction, vel->climb);
 199                         g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
 200                                         acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 201                 }
 202                         break;
 203                 case SATELLITE_UPDATED: {
 204                         int idx = 0;
 205                         guint prn;
 206                         gboolean used;
 207                         guint elevation;
 208                         guint azimuth;
 209                         gint snr;
 210
 211                         LocationSatellite *sat = (LocationSatellite *)data;
 212                         g_debug ("ASYNC>> Current Satellite> time: %d, satellite in view = %d, satellite in used = %d", sat->timestamp, sat->num_of_sat_inview, sat->num_of_sat_used);
 213                         g_debug ("\tinview satellite information = ");
 214                         for (idx=0; idx<sat->num_of_sat_inview; idx++) {
 215                                 location_satellite_get_satellite_details(sat, idx, &prn, &used, &elevation, &azimuth, &snr);
 216                                 g_debug ("\t\t[%02d] used: %d, prn: %d, elevation: %d, azimuth: %d, snr: %d", idx, used, prn, elevation, azimuth, snr);
 217                         }
 218                 }
 219                         break;
 220
 221                 default:
 222                         g_warning ("ASYNC>> Undefined update type");
 223                         break;
 224         }
 225 }
 226
 227
 228 int main (int argc, char *argv[])
 229 {
 230         LocationObject *loc = NULL;
 231         int interval = 6;       //seconds
 232         location_init ();
 233
 234         loc  = location_new (LOCATION_METHOD_GPS);
 235         if(!loc)
 236                 return -1;
 237
 238         g_object_set(loc, "update-interval", interval, NULL);
 239
 240         g_signal_connect (loc, "service-enabled", G_CALLBACK(cb_service_enabled), loc);
 241         g_signal_connect (loc, "service-updated", G_CALLBACK(cb_service_updated), loc);
 242
 243         location_start(loc);
 244         loop = g_main_loop_new (NULL, TRUE);
 245         g_main_loop_run (loop);  // GMainLoop is needed for receiving signals.
 246
 247         // ...
 248         return 0;
 249 }
 250  * @endcode
 251  */
 252 int location_start (LocationObject *obj);
 253
 254 /**
 255  * @brief
 256  * Stop the location service by using given #LocationObject.
 257  * @remarks
 258  * After call this API, you can not recieve signals.
 259  * @pre
 260  * #location_init should be called before.\n
 261  * #location_start should be called before.
 262  * @post None.
 263  * @param [in]
 264  * obj - a #LocationObject created by #location_new
 265  * @return int
 266  * @retval 0                              Success
 267  *
 268  * Please refer #LocationError for more information.
 269  * @see location_start
 270  * @par Example
 271  * @code
 272 #include <location.h>
 273 static GMainLoop *loop = NULL;
 274
 275 int main (int argc, char *argv[])
 276 {
 277         LocationObject *loc = NULL;
 278         location_init ();
 279         loc  = location_new (LOCATION_METHOD_GPS);
 280         if(!loc)
 281                 return -1;
 282
 283         location_start(loc);
 284         loop = g_main_loop_new (NULL, TRUE);
 285         g_main_loop_run (loop);
 286
 287         // ....
 288
 289         location_stop (loc);
 290         // you can not receive signals anymore.
 291         return 0;
 292 }
 293  * @endcode
 294  */
 295 int location_stop (LocationObject *obj);
 296
 297 /**
 298  * @brief
 299  * Check wheither a method is available.
 300  * @remarks
 301  * @pre
 302  * #location_init should be called before.\n
 303  * @post None.
 304  * @param [in] method - a #LocationMethod
 305  * @return int
 306  * @retval True         Supported
 307  *         False        Not supported
 308  * @par Example
 309  #include <location.h>
 310 static GMainLoop *loop = NULL;
 311
 312 int main (int argc, char *argv[])
 313 {
 314         gboolean is_supported = FALSE;
 315
 316         // ....
 317
 318         is_supported = location_is_supported_method(LOCATION_METHOD_HYBRID);
 319         if(is_supported == TRUE)
 320                 g_printf("Hybrid Method is supported.\n");
 321         else
 322                 g_printf("Hybrid Method is not supported.\n");
 323
 324         return 0;
 325 }* @code
 326  * @endcode
 327  */
 328 gboolean location_is_supported_method(LocationMethod method);
 329
 330 /**
 331  * @brief
 332  * Check wheither GPS is turned on or off.
 333  * @remarks
 334  * @pre
 335  * #location_init should be called before.\n
 336  * @post None.
 337  * @param [in] method - a #LocationMethod
 338  * @return int
 339  * @retval True         Turned on
 340  *         False        Turned off
 341  * @par Example
 342  #include <location.h>
 343 static GMainLoop *loop = NULL;
 344
 345 int main (int argc, char *argv[])
 346 {
 347         gboolean is_enabled = FALSE;
 348
 349         // ....
 350
 351         is_enabled = location_is_enabled_gps(loc);
 352         if(is_enable == TRUE)
 353                 g_printf("GPS is turned on.\n");
 354         else
 355                 g_printf("GPS is turned off.\n");
 356
 357         return 0;
 358 }* @code
 359  * @endcode
 360  */
 361 gboolean location_is_enabled_gps(LocationObject *obj);
 362
 363 /**
 364  * @brief
 365  * Get current position information with estimate of the accuracy.
 366  * @remarks Out parameters are should be freed.
 367  * @pre
 368  * #location_init should be called before.\n
 369  * #location_start should be called before.
 370  * @post None.
 371  * @param [in]
 372  * obj - a #LocationObject created by #location_new
 373  * @param [out]
 374  * position - a new #LocationPosition
 375  * @param [out]
 376  * accuracy - a new #LocationAccuracy
 377  * @return int
 378  * @retval 0                              Success
 379  *
 380  * Please refer #LocationError for more information.
 381  * @see location_get_velocity
 382  * @par Example
 383  * @code
 384 #include <location.h>
 385 static GMainLoop *loop = NULL;
 386
 387 static void cb_service_enabled (GObject *self, guint status, gpointer userdata)
 388 {
 389         g_debug("cb_service_enabled: status(%d) userdata(0x%x)", status, (unsigned int)userdata);
 390
 391         LocationObject *loc = (LocationObject*)userdata;
 392         LocationAccuracy *acc = NULL;
 393         LocationPosition *pos = NULL;
 394
 395         // This function works properly after service is enabled.
 396         if (LOCATION_ERROR_NONE == location_get_position (loc, &pos, &acc)) {
 397                 g_debug ("SYNC>> Current position> time: %d, lat: %f, long: %f, alt: %f, status: %d",
 398                         pos->timestamp, pos->latitude, pos->longitude, pos->altitude, pos->status);
 399                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
 400                         acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 401                 location_position_free(pos);
 402                 location_accuracy_free(acc);
 403         } else g_warning ("SYNC>> Current position> failed");
 404 }
 405
 406 int main (int argc, char *argv[])
 407 {
 408         LocationObject *loc = NULL;
 409         gulong handler_id = 0;
 410
 411         location_init ();
 412         loop = g_main_loop_new (NULL, TRUE);
 413         loc  = location_new (LOCATION_METHOD_GPS);
 414         if(!loc){
 415                 g_debug("location_new failed");
 416                 return -1;
 417         }
 418
 419         handler_id = g_signal_connect (loc, "service-enabled", G_CALLBACK(cb_service_enabled), loc);
 420         location_start (loc);
 421         g_main_loop_run (loop);
 422
 423         g_signal_handler_disconnect(loc, handler_id);
 424         location_stop (loc);
 425         location_free (loc);
 426
 427         return 0;
 428 }
 429  * @endcode
 430  */
 431 int location_get_position (LocationObject *obj, LocationPosition **position, LocationAccuracy **accuracy);
 432
 433 /**
 434  * @brief
 435  * Get current position & velocity information with estimate of the accuracy.
 436  * @remarks Out parameters are should be freed.
 437  * @pre
 438  * #location_init should be called before.\n
 439  * #location_start should be called before.
 440  * @post None.
 441  * @param [in] obj - a #LocationObject created by #location_new
 442  * @param [out] position - a new #LocationPosition
 443  * @param [out] velocity - a new #LocationVelocity
 444  * @param [out] accuracy - a new #LocationAccuracy
 445  * @return int
 446  * @retval 0                              Success
 447  *
 448  * Please refer #LocationError for more information.
 449  * @see location_get_position
 450  * @par Example
 451  * @code
 452 #include <location.h>
 453 static GMainLoop *loop = NULL;
 454
 455 static void cb_service_enabled (GObject *self, guint status, gpointer userdata)
 456 {
 457         g_debug("cb_service_enabled: status(%d) userdata(0x%x)", status, (unsigned int)userdata);
 458
 459         LocationObject *loc = (LocationObject*)userdata;
 460
 461         LocationPosition *pos = NULL;
 462         LocationVelocity *vel = NULL;
 463         LocationAccuracy *acc = NULL;
 464
 465         // This function works properly after service is enabled.
 466         if (LOCATION_ERROR_NONE == location_get_position_ext (loc, &pos, &vel, &acc)) {
 467                 g_debug ("SYNC>> Current position> time: %d, lat: %f, long: %f, alt: %f, status: %d, speed: %f, direction: %f",
 468                         pos->timestamp, pos->latitude, pos->longitude, pos->altitude, pos->status, vel->speed, vel->direction);
 469                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
 470                         acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 471                 location_position_free(pos);
 472                 location_accuracy_free(acc);
 473         } else g_warning ("SYNC>> Current position_ext > failed");
 474 }
 475
 476 int main (int argc, char *argv[])
 477 {
 478         LocationObject *loc = NULL;
 479         gulong handler_id = 0;
 480
 481         location_init ();
 482         loop = g_main_loop_new (NULL, TRUE);
 483         loc  = location_new (LOCATION_METHOD_GPS);
 484         if(!loc){
 485                 g_debug("location_new failed");
 486                 return -1;
 487         }
 488
 489         handler_id = g_signal_connect (loc, "service-enabled", G_CALLBACK(cb_service_enabled), loc);
 490         location_start (loc);
 491         g_main_loop_run (loop);
 492
 493         g_signal_handler_disconnect(loc, handler_id);
 494         location_stop (loc);
 495         location_free (loc);
 496
 497         return 0;
 498 }
 499  * @endcode
 500  */
 501 int location_get_position_ext (LocationObject *obj, LocationPosition **position, LocationVelocity **velocity, LocationAccuracy **accuracy);
 502
 503 /**
 504  * @brief
 505  * Get last position information with estimate of the accuracy.
 506  * @remarks Out parameters are should be freed.
 507  * @pre #location_init should be called before.
 508  * @post None.
 509  * @param [in]
 510  * obj - a #LocationObject created by #location_new
 511  * @param [out] position - a new #LocationPosition
 512  * @param [out] accuracy - a new #LocationAccuracy
 513  * @return int
 514  * @retval 0                              Success
 515  *
 516  * Please refer #LocationError for more information.
 517  * @see location_get_position
 518  * @par Example
 519  * @code
 520 #include <location.h>
 521
 522 int main (int argc, char *argv[])
 523 {
 524         LocationObject *loc = NULL;
 525         int ret = 0;
 526         LocationPosition *last_pos = NULL;
 527         LocationAccuracy *last_acc = NULL;
 528
 529         location_init ();
 530         loc  = location_new (LOCATION_METHOD_GPS);
 531         if(!loc){
 532                 g_debug("location_new failed");
 533                 return -1;
 534         }
 535
 536         if (LOCATION_ERROR_NONE == location_get_last_position (loc, &last_pos, &last_acc)) {
 537                 g_debug ("SYNC>> Last position> time: %d, lat: %f, long: %f, alt: %f, status: %d",
 538                         last_pos->timestamp, last_pos->latitude, last_pos->longitude, last_pos->altitude, last_pos->status);
 539                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
 540                         last_acc->level, last_acc->horizontal_accuracy, last_acc->vertical_accuracy);
 541                 location_position_free(last_pos);
 542                 location_accuracy_free(last_acc);
 543         } else g_warning ("SYNC>> Last position> failed");
 544
 545         location_free (loc);
 546
 547         return 0;
 548 }
 549  * @endcode
 550  */
 551 int location_get_last_position (LocationObject *obj, LocationPosition **position, LocationAccuracy **accuracy);
 552
 553 /**
 554  * @brief
 555  * Get last position & velocity information with estimate of the accuracy.
 556  * @remarks Out parameters are should be freed.
 557  * @pre #location_init should be called before.
 558  * @post None.
 559  * @param [in] obj - a #LocationObject created by #location_new
 560  * @param [out] position - a new #LocationPosition
 561  * @param [out] velocity - a new #LocationVelocity
 562  * @param [out] accuracy - a new #LocationAccuracy
 563  * @return int
 564  * @retval 0                              Success
 565  *
 566  * Please refer #LocationError for more information.
 567  * @see location_get_position_ext
 568  * @par Example
 569  * @code
 570 #include <location.h>
 571
 572 int main (int argc, char *argv[])
 573 {
 574         LocationObject *loc = NULL;
 575         int ret = 0;
 576         LocationPosition *last_pos = NULL;
 577         LocationVelocity *last_vel = NULL;
 578         LocationAccuracy *last_acc = NULL;
 579
 580         location_init ();
 581         loc  = location_new (LOCATION_METHOD_GPS);
 582         if(!loc){
 583                 g_debug("location_new failed");
 584                 return -1;
 585         }
 586
 587         if (LOCATION_ERROR_NONE == location_get_last_position_ext (loc, &last_pos, &last_vel, &last_acc)) {
 588                 g_debug ("SYNC>> Last position> time: %d, lat: %f, long: %f, alt: %f, status: %d, speed: %f, direction: %f",
 589                         last_pos->timestamp, last_pos->latitude, last_pos->longitude, last_pos->altitude, last_pos->status, last_vel->speed, last_vel->direction);
 590                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
 591                         last_acc->level, last_acc->horizontal_accuracy, last_acc->vertical_accuracy);
 592                 location_position_free(last_pos);
 593                 location_velocity_free(last_vel);
 594                 location_accuracy_free(last_acc);
 595         } else g_warning ("SYNC>> Last position_ext > failed");
 596
 597         location_free (loc);
 598
 599         return 0;
 600 }
 601  * @endcode
 602  */
 603 int location_get_last_position_ext (LocationObject *obj, LocationPosition **position, LocationVelocity **velocity, LocationAccuracy **accuracy);
 604 /**
 605  * @brief
 606  * Get last satellite information.
 607  * @remarks This API is not implemented now. \n
 608  *   Out parameters are should be freed.
 609  * @pre
 610  * #location_init should be called before.
 611  * @post None.
 612  * @param [in]
 613  * obj - a #LocationObject created by #location_new
 614  * @param [out] satellite - a new #LocationSatellite
 615  * @return int
 616  * @retval 0                              Success
 617  * Please refer #LocationError for more information.
 618  * @see location_get_last_satellite
 619  * @par Example
 620  * @code
 621 #include <location.h>
 622
 623 int main (int argc, char *argv[])
 624 {
 625         LocationObject *loc = NULL;
 626         int ret = 0, idx = 0;
 627         LocationSatellite *sat = NULL;
 628         guint prn;
 629         gboolean used;
 630         guint elevation;
 631         guint azimuth;
 632         gint snr;
 633
 634         location_init ();
 635         loc  = location_new (LOCATION_METHOD_GPS);
 636         if(!loc){
 637                 g_debug("location_new failed");
 638                 return -1;
 639         }
 640
 641         if (LOCATION_ERROR_NONE == location_get_satellite (loc, &sat)) {
 642                 g_debug ("SYNC>> Current Sattelite> satellite in view = %d, satellite in used = %d", sat->num_of_sat_inview, sat->num_of_sat_used);
 643                 g_debug ("\tinview satellite information = ");
 644                 for (idx=0; idx<sat->num_of_sat_inview; idx++) {
 645                         location_satellite_get_satellite_details(sat, idx, &prn, &used, &elevation, &azimuth, &snr);
 646                         g_debug ("\t\t[%02d] used: %d, prn: %d, elevation: %d, azimuth: %d, snr: %d", idx, used, prn, elevation, azimuth, snr);
 647                 }
 648                 location_satellite_free (sat);
 649         } else g_warning ("SYNC>> Current satellite> failed");
 650
 651         location_free (loc);
 652
 653         return 0;
 654 }
 655  * @endcode
 656  */
 657 int location_get_satellite (LocationObject *obj, LocationSatellite **satellite);
 658
 659 /**
 660  * @brief
 661  * Get last satellite information.
 662  * @remarks This API is not implemented now. \n
 663  *   Out parameters are should be freed.
 664  * @pre
 665  * #location_init should be called before.
 666  * @post None.
 667  * @param [in]
 668  * obj - a #LocationObject created by #location_new
 669  * @param [out]
 670  * satellite - a new #LocationSatellite
 671  * @return int
 672  * @retval 0                              Success
 673  *
 674  * Please refer #LocationError for more information.
 675  * @par Example
 676  * @code
 677 #include <location.h>
 678
 679 int main (int argc, char *argv[])
 680 {
 681         LocationObject *loc = NULL;
 682         int ret = 0, idx = 0;
 683         LocationSatellite *last_sat = NULL;
 684         guint prn;
 685         gboolean used;
 686         guint elevation;
 687         guint azimuth;
 688         gint snr;
 689
 690         location_init ();
 691         loc  = location_new (LOCATION_METHOD_GPS);
 692         if(!loc){
 693                 g_debug("location_new failed");
 694                 return -1;
 695         }
 696
 697         if (LOCATION_ERROR_NONE == location_get_last_satellite (loc, &last_sat)) {
 698                 g_debug ("SYNC>> Last Sattelite> satellite in view = %d, satellite in used = %d", last_sat->num_of_sat_inview, last_sat->num_of_sat_used);
 699                 g_debug ("\tinview satellite information = ");
 700                 for (idx=0; idx<last_sat->num_of_sat_inview; idx++) {
 701                         location_satellite_get_satellite_details(last_sat, idx, &prn, &used, &elevation, &azimuth, &snr);
 702                         g_debug ("\t\t[%02d] used: %d, prn: %d, elevation: %d, azimuth: %d, snr: %d", idx, used, prn, elevation, azimuth, snr);
 703                 }
 704                 location_satellite_free (last_sat);
 705         } else g_warning ("SYNC>> Last satellite> failed");
 706
 707         location_free (loc);
 708
 709         return 0;
 710 }
 711  * @endcode
 712  */
 713 int location_get_last_satellite (LocationObject *obj, LocationSatellite **satellite);
 714
 715 /**
 716  * @brief
 717  * Get current velocity information with estimate of the accuracy.
 718  * @remarks Out parameters are should be freed.
 719  * @pre
 720  * #location_init should be called before.\n
 721  * #location_start should be called before.
 722  * @post None.
 723  * @param [in]
 724  * obj - a #LocationObject created by #location_new
 725  * @param [out]
 726  * velocity - a new #LocationVelocity
 727  * @param [out]
 728  * accuracy - a new #LocationAccuracy
 729  * @return int
 730  * @retval 0                              Success
 731  *
 732  * Please refer #LocationError for more information.
 733  * @see location_get_position
 734  * @par Example
 735  * @code
 736 #include <location.h>
 737 static GMainLoop *loop = NULL;
 738
 739 static void cb_service_enabled (GObject *self, guint status, gpointer userdata)
 740 {
 741         g_debug("cb_service_enabled: status(%d) userdata(0x%x)", status, (unsigned int)userdata);
 742
 743         LocationObject *loc = (LocationObject*)userdata;
 744         LocationAccuracy *acc = NULL;
 745         LocationVelocity *vel = NULL;
 746
 747         if (LOCATION_ERROR_NONE == location_get_velocity (loc, &vel, &acc)) {
 748                 g_debug ("SYNC>> Current velocity> time: %d, speed: %f, direction:%f, climb:%f",
 749                         vel->timestamp, vel->speed, vel->direction, vel->climb);
 750                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
 751                         acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 752                 location_velocity_free(vel);
 753                 location_accuracy_free(acc);
 754         } else g_warning ("SYNC>> Current velocity> failed");
 755 }
 756
 757 int main (int argc, char *argv[])
 758 {
 759         LocationObject *loc = NULL;
 760         gulong hander_id = 0;
 761         location_init ();
 762
 763         loop = g_main_loop_new (NULL, TRUE);
 764
 765         loc  = location_new (LOCATION_METHOD_GPS);
 766         if(!loc){
 767                 g_debug("location_new failed");
 768                 return -1;
 769         }
 770
 771         handler_id = g_signal_connect (loc, "service-enabled", G_CALLBACK(cb_service_enabled), loc);
 772         location_start (loc);
 773         g_main_loop_run (loop);
 774
 775         g_signal_handler_disconnect(loc, handler_id);
 776         location_stop (loc);
 777         location_free (loc);
 778
 779         return 0;
 780 }
 781
 782  * @endcode
 783  */
 784 int location_get_velocity (LocationObject *obj, LocationVelocity **velocity, LocationAccuracy **accuracy);
 785
 786 /**
 787  * @brief
 788  * Get last velocity information with estimate of the accuracy.
 789  * @remarks Out parameters are should be freed.
 790  * @pre
 791  * #location_init should be called before.
 792  * @post None.
 793  * @param [in]
 794  * obj - a #LocationObject created by #location_new
 795  * @param [out]
 796  * velocity - a new #LocationVelocity
 797  * @param [out]
 798  * accuracy - a new #LocationAccuracy
 799  * @return int
 800  * @retval 0                              Success
 801  *
 802  * Please refer #LocationError for more information.
 803  * @see location_get_position
 804  * @par Example
 805  * @code
 806 #include <location.h>
 807
 808 int main (int argc, char *argv[])
 809 {
 810         int ret = 0;
 811         LocationObject *loc = NULL;
 812         LocationVelocity *vel = NULL;
 813         LocationAccuracy *acc = NULL;
 814         gulong hander_id = 0;
 815
 816         location_init ();
 817
 818         loc  = location_new (LOCATION_METHOD_GPS);
 819         if(!loc){
 820                 g_debug("location_new failed");
 821                 return -1;
 822         }
 823
 824         ret = location_get_last_velocity (loc, &vel, &acc);
 825         if (ret == LOCATION_ERROR_NONE) {
 826                 g_debug ("SYNC>> Last velocity> time: %d, speed: %f, direction:%f, climb:%f",
 827                         vel->timestamp, vel->speed, vel->direction, vel->climb);
 828                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
 829                         acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 830                 location_velocity_free(vel);
 831                 location_accuracy_free(acc);
 832         }
 833
 834         location_free (loc);
 835         return 0;
 836 }
 837  * @endcode
 838  */
 839 int location_get_last_velocity (LocationObject *obj, LocationVelocity **velocity, LocationAccuracy **accuracy);
 840
 841 /**
 842  * @brief
 843  * Get the accessibility state of an application
 844  * @remarks None.
 845  * @pre
 846  * #location_init should be called before.\n
 847  * @post None.
 848  * @param [out]  state - a #LocationAccessState
 849  * @return int
 850  * @retval 0                              Success
 851  *
 852  * Please refer #LocationError for more information.
 853  */
 854 int location_get_accessibility_state (LocationAccessState *state);
 855
 856 /**
 857  * @brief
 858  * Send command to the server.
 859  * @pre
 860  * #location_init should be called before.\n
 861  * Calling application must have glib or ecore main loop.\n
 862  * Calling application must have an active data connection.
 863  * @post None.
 864  * @param [in]  cmd - a #char
 865  * @return int
 866  * @retval 0                              Success
 867  *
 868  * Please refer #LocationError for more information.
 869  */
 870 int location_send_command(const char *cmd);
 871
 872 /**
 873  * @brief
 874  * Set option of server.
 875  * @pre
 876  * #location_init should be called before.\n
 877  * Calling application must have glib or ecore main loop.\n
 878  * Calling application must have an active data connection.
 879  * @post None.
 880  * @param [in]  obj - a #LocationObject created by #location_new
 881  * @param [in]  option - a #char
 882  * @return int
 883  * @retval 0                              Success
 884  *
 885  * Please refer #LocationError for more information.
 886  */
 887 int location_set_option(LocationObject *obj, const char *option);
 888
 889 /**
 890  * @} @}
 891  */
 892
 893 G_END_DECLS
 894
 895 #endif /* __LOCATION_H__ */