location/location.h

   1 /*
   2  * libslp-location
   3  *
   4  * Copyright (c) 2010-2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Youngae Kang <youngae.kang@samsung.com>, Yunhan Kim <yhan.kim@samsung.com>,
   7  *          Genie Kim <daejins.kim@samsung.com>, Minjune Kim <sena06.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/location-types.h>
  29 #include <location/location-position.h>
  30 #include <location/location-velocity.h>
  31 #include <location/location-accuracy.h>
  32 #include <location/location-address.h>
  33 #include <location/location-boundary.h>
  34 #include <location/location-satellite.h>
  35 #include <location/location-poi-info.h>
  36
  37 G_BEGIN_DECLS
  38
  39 /**
  40  * @file location.h
  41  * @brief This file contains the Location API and related structure and enumeration.
  42  */
  43 /**
  44  * @defgroup LocationFW LocationFW
  45  * @brief This is a Locatoin Framework for providing location based services.
  46  * @addtogroup LocationFW
  47  * @{
  48  * @defgroup LocationAPI Location API
  49  * @brief This sub module provides the Location API.
  50  * @addtogroup LocationAPI
  51  * @{
  52  */
  53
  54 /**
  55  * @brief
  56  * Initialize location sub module.
  57  * @remarks None.
  58  * This API should be called before any other Location APIs.
  59  * @pre None.
  60  * @post None.
  61  * @return int
  62  * @retval 0                              Success
  63  *
  64  * Please refer #LocationError for more information.
  65  * @see None.
  66  * @par Example
  67  * @code
  68 #include <location.h>
  69 int main (int argc, char *argv[])
  70 {
  71     location_init();
  72     // Now you can use any other Location APIs.
  73     return 0;
  74 }
  75  * @endcode
  76  */
  77 int location_init (void);
  78
  79 /**
  80  * @brief
  81  * Create a new #LocationObject by using given #LocationMethod.
  82  * @remarks
  83  * Returned object is necessary for other APIs.
  84  * @pre
  85  * #location_init should be called before.
  86  * @post None.
  87  * @param [in]
  88  * method - Location method to be used.
  89  * @return a new #LocationObject
  90  * @retval NULL              if error occured
  91  * @see location_free
  92  * @par Example
  93  * @code
  94 #include <location.h>
  95 int main (int argc, char *argv[])
  96 {
  97         LocationObject *loc = NULL;
  98         location_init ();
  99
 100         loc  = location_new (LOCATION_METHOD_GPS);
 101         if(!loc)
 102                 return -1;
 103         // You can use new location object now.
 104         return 0;
 105 }
 106  * @endcode
 107  */
 108 LocationObject *location_new (LocationMethod method);
 109
 110 /**
 111  * @brief
 112  * Free memory of given #LocationObject.
 113  * @remarks None.
 114  * @pre
 115  * #location_init should be called before.
 116  * @post None.
 117  * @param [in]
 118  * obj - a #LocationObject created by #location_new.
 119  * @return int
 120  * @retval 0                              Success.
 121  *
 122  * Please refer #LocationError for more information.
 123  * @see location_new
 124  * @par Example
 125  * @code
 126 #include <location.h>
 127 int main (int argc, char *argv[])
 128 {
 129         LocationObject *loc = NULL;
 130         location_init ();
 131         loc  = location_new (LOCATION_METHOD_GPS);
 132         if(!loc)
 133                 return -1;
 134
 135         location_free (loc);
 136         // You can not use location object anymore.
 137         return 0;
 138 }
 139  * @endcode
 140  */
 141 int location_free (LocationObject *obj);
 142
 143 /**
 144  * @brief
 145  * Start the location service by using given #LocationObject.
 146  * @remarks
 147  * If you want to recieve signals, you should use this API.
 148  * @pre
 149  * #location_init should be called before.
 150  * @post None.
 151  * @param [in]
 152  * obj - a #LocationObject created by #location_new
 153  * @return int
 154  * @retval 0                              Success.
 155  *
 156  * Please refer #LocationError for more information.
 157  * @see location_stop
 158  * @par Example
 159  * @code
 160 #include <location.h>
 161 static GMainLoop *loop = NULL;
 162
 163 int main (int argc, char *argv[])
 164 {
 165         LocationObject *loc = NULL;
 166         int interval = 6;       //seconds
 167         location_init ();
 168
 169         loc  = location_new (LOCATION_METHOD_GPS);
 170         if(!loc)
 171                 return -1;
 172
 173         g_object_set(loc, "update-interval", interval, NULL);
 174
 175         location_start(loc);
 176         loop = g_main_loop_new (NULL, TRUE);
 177         g_main_loop_run (loop);  // GMainLoop is needed for receiving signals.
 178
 179         // ...
 180         return 0;
 181 }
 182  * @endcode
 183  */
 184 int location_start (LocationObject *obj);
 185
 186 /**
 187  * @brief
 188  * Stop the location service by using given #LocationObject.
 189  * @remarks
 190  * After call this API, you can not recieve signals.
 191  * @pre
 192  * #location_init should be called before.\n
 193  * #location_start should be called before.
 194  * @post None.
 195  * @param [in]
 196  * obj - a #LocationObject created by #location_new
 197  * @return int
 198  * @retval 0                              Success
 199  *
 200  * Please refer #LocationError for more information.
 201  * @see location_start
 202  * @par Example
 203  * @code
 204 #include <location.h>
 205 static GMainLoop *loop = NULL;
 206
 207 int main (int argc, char *argv[])
 208 {
 209         LocationObject *loc = NULL;
 210         location_init ();
 211         loc  = location_new (LOCATION_METHOD_GPS);
 212         if(!loc)
 213                 return -1;
 214
 215         location_start(loc);
 216         loop = g_main_loop_new (NULL, TRUE);
 217         g_main_loop_run (loop);
 218
 219         // ....
 220
 221         location_stop (loc);
 222         // you can not receive signals anymore.
 223         return 0;
 224 }
 225  * @endcode
 226  */
 227 int location_stop (LocationObject *obj);
 228
 229 /**
 230  * @brief
 231  * Check wheither a method is available.
 232  * @remarks
 233  * @pre
 234  * #location_init should be called before.\n
 235  * @post None.
 236  * @param [in] method - a #LocationMethod
 237  * @return int
 238  * @retval True         Supported
 239  *         False        Not supported
 240  * @par Example
 241  #include <location.h>
 242 static GMainLoop *loop = NULL;
 243
 244 int main (int argc, char *argv[])
 245 {
 246         gboolean is_supported = FALSE;
 247
 248         // ....
 249
 250         is_supported = location_is_supported_method(LOCATION_METHOD_HYBRID);
 251         if(is_supported == TRUE)
 252                 g_printf("Hybrid Method is supported.\n");
 253         else
 254                 g_printf("Hybrid Method is not supported.\n");
 255
 256         return 0;
 257 }* @code
 258  * @endcode
 259  */
 260 gboolean location_is_supported_method(LocationMethod method);
 261
 262 /**
 263  * @brief
 264  * Check wheither GPS is turned on or off.
 265  * @remarks
 266  * @pre
 267  * #location_init should be called before.\n
 268  * @post None.
 269  * @param [in] method - a #LocationMethod
 270  * @return int
 271  * @retval True         Turned on
 272  *         False        Turned off
 273  * @par Example
 274  #include <location.h>
 275 static GMainLoop *loop = NULL;
 276
 277 int main (int argc, char *argv[])
 278 {
 279         gboolean is_enabled = FALSE;
 280
 281         // ....
 282
 283         is_enabled = location_is_enabled_gps(loc);
 284         if(is_enable == TRUE)
 285                 g_printf("GPS is turned on.\n");
 286         else
 287                 g_printf("GPS is turned off.\n");
 288
 289         return 0;
 290 }* @code
 291  * @endcode
 292  */
 293 gboolean location_is_enabled_gps(LocationObject *obj);
 294
 295 /**
 296  * @brief
 297  * Get current position information with estimate of the accuracy.
 298  * @remarks Out parameters are should be freed.
 299  * @pre
 300  * #location_init should be called before.\n
 301  * #location_start should be called before.
 302  * @post None.
 303  * @param [in]
 304  * obj - a #LocationObject created by #location_new
 305  * @param [out]
 306  * position - a new #LocationPosition
 307  * @param [out]
 308  * accuracy - a new #LocationAccuracy
 309  * @return int
 310  * @retval 0                              Success
 311  *
 312  * Please refer #LocationError for more information.
 313  * @see location_get_velocity
 314  * @par Example
 315  * @code
 316 #include <location.h>
 317 static GMainLoop *loop = NULL;
 318
 319 static void cb_service_enabled (GObject *self, guint status, gpointer userdata)
 320 {
 321         g_debug("cb_service_enabled: status(%d) userdata(0x%x)", status, (unsigned int)userdata);
 322
 323         LocationObject *loc = (LocationObject*)userdata;
 324         LocationAccuracy *acc = NULL;
 325         LocationPosition *pos = NULL;
 326
 327         // This function works properly after service is enabled.
 328         if (LOCATION_ERROR_NONE == location_get_position (loc, &pos, &acc)) {
 329                 g_debug ("SYNC>> Current position> time: %d, lat: %f, long: %f, alt: %f, status: %d",
 330                         pos->timestamp, pos->latitude, pos->longitude, pos->altitude, pos->status);
 331                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
 332                         acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 333                 location_position_free(pos);
 334                 location_accuracy_free(acc);
 335         } else g_warning ("SYNC>> Current position> failed");
 336 }
 337
 338 int main (int argc, char *argv[])
 339 {
 340         LocationObject *loc = NULL;
 341         gulong handler_id = 0;
 342
 343         location_init ();
 344         loop = g_main_loop_new (NULL, TRUE);
 345         loc  = location_new (LOCATION_METHOD_GPS);
 346         if(!loc){
 347                 g_debug("location_new failed");
 348                 return -1;
 349         }
 350
 351         handler_id = g_signal_connect (loc, "service-enabled", G_CALLBACK(cb_service_enabled), loc);
 352         location_start (loc);
 353         g_main_loop_run (loop);
 354
 355         g_signal_handler_disconnect(loc, handler_id);
 356         location_stop (loc);
 357         location_free (loc);
 358
 359         return 0;
 360 }
 361  * @endcode
 362  */
 363 int location_get_position (LocationObject *obj, LocationPosition **position,    LocationAccuracy **accuracy);
 364
 365 /**
 366  * @brief
 367  * Get last known position information with estimate of the accuracy.
 368  * @remarks None.
 369  * @pre
 370  * #location_init should be called before.
 371  * @post None.
 372  * @param [in]
 373  * obj - a #LocationObject created by #location_new
 374  * @param [in]
 375  * last_position - a #LocationLastPosition
 376  * @return int
 377  * @retval 0                              Success
 378  *
 379  * @par Example
 380  * @code
 381 #include <location.h>
 382
 383 int main (int argc, char *argv[])
 384 {
 385         LocationObject *loc = NULL;
 386         LocationLastPosition last_pos;
 387         location_init ();
 388         loc  = location_new (LOCATION_METHOD_GPS);
 389         if (!loc) {
 390                 g_debug("location_new failed");
 391                 return -1;
 392         }
 393
 394         location_get_last_known_position(loc, &last_pos);
 395         g_debug ("Last known position > lat: %f, long: %f, acc: %f", last_pos.latitude, last_pos.longitude, last_pos.accuracy);
 396
 397         location_free (loc);
 398         return 0;
 399 }
 400  * @endcode
 401  */
 402 int location_get_last_known_position (LocationObject *obj, LocationLastPosition *last_position);
 403
 404
 405 /**
 406  * @brief
 407  * Get current position information with estimate of the accuracy by using given address information.
 408  * @remarks Out parameters are should be freed.
 409  * @pre
 410  * #location_init should be called before.\n
 411  * Calling application must have an active data connection.
 412  * @post None.
 413  * @param [in]
 414  * obj - a #LocationObject created by #location_new
 415  * @param [in]
 416  * address - a #LocationAddress
 417  * @param [out]
 418  * position - a new #LocationPosition
 419  * @param [out]
 420  * accuracy - a new #LocationAccuracy
 421  * @return int
 422  * @retval 0                              Success.
 423  *
 424  * Please refer #LocationError for more information.
 425  * @see
 426  * location_get_position_from_address_async\n
 427  * @par Example
 428  * @code
 429 #include <location.h>
 430
 431 int main (int argc, char *argv[])
 432 {
 433         LocationObject *loc = NULL;
 434         int ret = LOCATION_ERROR_NONE;
 435
 436         location_init ();
 437         loc  = location_new (LOCATION_METHOD_GPS);
 438         if(!loc){
 439                 g_debug("location_new failed");
 440                 return -1;
 441         }
 442
 443         LocationPosition *pos = NULL;
 444         LocationAccuracy *acc = NULL;
 445         LocationAddress *addr = NULL;
 446
 447         addr = location_address_new ("1", "Post Street", NULL, "san jose", "ca", NULL, "95113");
 448         if (LOCATION_ERROR_NONE == location_get_position_from_address(loc, addr, &pos, &acc)) {
 449                 g_debug ("SYNC>> position from address> time: %d, lat: %f, long: %f, alt: %f, status: %d",
 450                         pos->timestamp, pos->latitude, pos->longitude, pos->altitude, pos->status);
 451                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
 452                         acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 453                 location_position_free (pos);
 454                 location_accuracy_free (acc);
 455         } else g_warning ("SYNC>> position from address> failed");
 456         location_address_free (addr);
 457
 458         location_free (loc);
 459         return 0;
 460 }
 461  * @endcode
 462  */
 463 int location_get_position_from_address (LocationObject *obj, const LocationAddress *address, LocationPosition **position, LocationAccuracy **accuracy);
 464
 465 /**
 466  * @brief
 467  * Get current position information asynchronously with estimate of the accuracy by using given address information.
 468  * @remarks None.
 469  * @pre
 470  * #location_init should be called before.\n
 471  * Calling application must have glib or ecore main loop.\n
 472  * Calling application must have an active data connection.
 473  * @post None.
 474  * @param [in]
 475  * obj - a #LocationObject created by #location_new
 476  * @param [in]
 477  * address - a #LocationAddress
 478  * @param [in]
 479  * callback - A pointer of function which will be called after position is gained or when an error occurs.
 480  * @param [in]
 481  * userdata - data to pass to function
 482  * @return int
 483  * @retval 0                              Success.
 484  *
 485  * Please refer #LocationError for more information.
 486  * @see
 487  * location_get_position_from_address\n
 488  * @par Example
 489  * @code
 490 #include <location.h>
 491
 492 static void
 493 cb_position_from_address (LocationError error, LocationPosition *pos, LocationAccuracy *acc, gpointer userdata)
 494 {
 495         g_debug ("ASYNC>> location_get_position_from_address_async> time: %d, lat: %f, long: %f, alt: %f, status: %d",
 496                         pos->timestamp, pos->latitude, pos->longitude, pos->altitude, pos->status);
 497         g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 498 }
 499
 500 void get_position_from_address(LocationObject* loc)
 501 {
 502         LocationAddress *addr = location_address_new ("1", "Post Street", NULL, "san jose", "ca", NULL, "95113");
 503         //Calling application must have an active data connection before using this function.
 504         if (LOCATION_ERROR_NONE == location_get_position_from_address_async(loc, addr, cb_position_from_address, loc))
 505                 g_debug("location_get_position_from_address_async() success");
 506         else g_warning ("location_get_position_from_address_async() failed");
 507         location_address_free (addr);
 508 }
 509  * @endcode
 510  */
 511 int location_get_position_from_address_async (LocationObject *obj, const LocationAddress *address, LocationPositionCB callback, gpointer userdata);
 512
 513 /**
 514  * @brief
 515  * Get current position information with estimate of the accuracy by using given free-formed address string.
 516  * @remarks Out parameters are should be freed.
 517  * @pre
 518  * #location_init should be called before.\n
 519  * Calling application must have an active data connection.
 520  * @post None.
 521  * @param [in]
 522  * obj - a #LocationObject created by #location_new
 523  * @param [in]
 524  * address - Free-formed address string to be used
 525  * @param [out]
 526  * position - a new #LocationPosition
 527  * @param [out]
 528  * accuracy - a new #LocationAccuracy
 529  * @return int
 530  * @retval 0                              Success
 531  *
 532  * Please refer #LocationError for more information.
 533  * @see
 534  * location_get_position_from_freeformed_address_async\n
 535  * @par Example
 536  * @code
 537 #include <location.h>
 538
 539 int main (int argc, char *argv[])
 540 {
 541         LocationObject *loc = NULL;
 542         int ret = LOCATION_ERROR_NONE;
 543
 544         location_init ();
 545         loc  = location_new (LOCATION_METHOD_GPS);
 546         if(!loc){
 547                 g_debug("location_new failed");
 548                 return -1;
 549         }
 550
 551         LocationPosition *pos = NULL;
 552         LocationAccuracy *acc = NULL;
 553         char* addr_str = g_strdup("4 N 2nd Street 95113");
 554         //Calling application must have an active data connection before using this function.
 555         if (LOCATION_ERROR_NONE == location_get_position_from_freeformed_address(loc, addr_str, &pos, &acc)) {
 556                 g_debug ("SYNC>> position from freeformed address> time: %d, lat: %f, long: %f, alt: %f, status: %d",
 557                         pos->timestamp, pos->latitude, pos->longitude, pos->altitude, pos->status);
 558                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 559                 location_position_free (pos);
 560                 location_accuracy_free (acc);
 561         } else g_warning ("SYNC>> position from freeformed address> failed");
 562         g_free(addr_str);
 563
 564
 565         location_free (loc);
 566         return 0;
 567 }
 568  * @endcode
 569  */
 570 int location_get_position_from_freeformed_address (LocationObject *obj, const gchar *address, LocationPosition **position, LocationAccuracy **accuracy);
 571
 572 /**
 573  * @brief
 574  * Get current position information asynchronously with estimate of the accuracy by using given free-formed address string.
 575  * @remarks None.
 576  * @pre
 577  * #location_init should be called before.\n
 578  * Calling application must have glib or ecore main loop.\n
 579  * Calling application must have an active data connection.
 580  * @post None.
 581  * @param [in]
 582  * obj - a #LocationObject created by #location_new
 583  * @param [in]
 584  * address - Free-formed address string to be used
 585  * @param [in]
 586  * callback - A pointer of function which will be called after position is gained or when an error occurs.
 587  * @param [in]
 588  * userdata - data to pass to function
 589  * @return int
 590  * @retval 0                              Success
 591  *
 592  * Please refer #LocationError for more information.
 593  * @see
 594  * location_get_position_from_freeformed_address\n
 595  * @par Example
 596  * @code
 597 #include <location.h>
 598
 599 static void
 600 cb_position_from_freeformed_address (LocationError error, LocationPosition *pos, LocationAccuracy *acc, gpointer userdata)
 601 {
 602         g_debug ("ASYNC>> location_get_position_from_freeformed_address_async> time: %d, lat: %f, long: %f, alt: %f, status: %d",
 603                         pos->timestamp, pos->latitude, pos->longitude, pos->altitude, pos->status);
 604         g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 605 }
 606
 607 void get_position_from_address(LocationObject* loc)
 608 {
 609         gchar *addr_str = g_strdup("4 N 2nd Street 95113");
 610         //Calling application must have an active data connection before using this function.
 611         if (LOCATION_ERROR_NONE == location_get_position_from_freeformed_address_async(loc, addr_str, cb_position_from_freeformed_address, loc))
 612                 g_debug("location_get_position_from_freeformed_address_async() success");
 613         else g_warning ("location_get_position_from_freeformed_address_async() failed");
 614         g_free(addr_str);
 615
 616 }
 617  * @endcode
 618  */
 619 int location_get_position_from_freeformed_address_async (LocationObject *obj, const gchar *address, LocationPositionCB callback,        gpointer userdata);
 620
 621 /**
 622  * @brief
 623  * Get current velocity information with estimate of the accuracy.
 624  * @remarks Out parameters are should be freed.
 625  * @pre
 626  * #location_init should be called before.\n
 627  * #location_start should be called before.
 628  * @post None.
 629  * @param [in]
 630  * obj - a #LocationObject created by #location_new
 631  * @param [out]
 632  * velocity - a new #LocationVelocity
 633  * @param [out]
 634  * accuracy - a new #LocationAccuracy
 635  * @return int
 636  * @retval 0                              Success
 637  *
 638  * Please refer #LocationError for more information.
 639  * @see location_get_position
 640  * @par Example
 641  * @code
 642 #include <location.h>
 643 static GMainLoop *loop = NULL;
 644
 645 static void cb_service_enabled (GObject *self, guint status, gpointer userdata)
 646 {
 647         g_debug("cb_service_enabled: status(%d) userdata(0x%x)", status, (unsigned int)userdata);
 648
 649         LocationObject *loc = (LocationObject*)userdata;
 650         LocationAccuracy *acc = NULL;
 651         LocationVelocity *vel = NULL;
 652
 653         if (LOCATION_ERROR_NONE == location_get_velocity (loc, &vel, &acc)) {
 654                 g_debug ("SYNC>> Current velocity> time: %d, speed: %f, direction:%f, climb:%f",
 655                         vel->timestamp, vel->speed, vel->direction, vel->climb);
 656                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
 657                         acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 658                 location_velocity_free(vel);
 659                 location_accuracy_free(acc);
 660         } else g_warning ("SYNC>> Current velocity> failed");
 661 }
 662
 663 int main (int argc, char *argv[])
 664 {
 665         LocationObject *loc = NULL;
 666         gulong hander_id = 0;
 667         location_init ();
 668
 669         loop = g_main_loop_new (NULL, TRUE);
 670
 671         loc  = location_new (LOCATION_METHOD_GPS);
 672         if(!loc){
 673                 g_debug("location_new failed");
 674                 return -1;
 675         }
 676
 677         handler_id = g_signal_connect (loc, "service-enabled", G_CALLBACK(cb_service_enabled), loc);
 678         location_start (loc);
 679         g_main_loop_run (loop);
 680
 681         g_signal_handler_disconnect(loc, handler_id);
 682         location_stop (loc);
 683         location_free (loc);
 684
 685         return 0;
 686 }
 687
 688  * @endcode
 689  */
 690 int location_get_velocity (LocationObject *obj, LocationVelocity **velocity, LocationAccuracy **accuracy);
 691
 692 /**
 693  * @brief
 694  * Get current address information with estimate of the accuracy by using current position.
 695  * @remarks Out parameters are should be freed.
 696  * @pre
 697  * #location_init should be called before.\n
 698  * #location_start should be called before.\n
 699  * Calling application must have an active data connection.
 700  * @post None.
 701  * @param [in]
 702  * obj - a #LocationObject created by #location_new
 703  * @param [out]
 704  * address - a new #LocationAddress
 705  * @param [out]
 706  * accuracy - a new #LocationAccuracy
 707  * @return int
 708  * @retval 0                              Success
 709  *
 710  * Please refer #LocationError for more information.
 711  * @see
 712  * location_get_address_async\n
 713  * @par Example
 714  * @code
 715 #include <location.h>
 716 static GMainLoop *loop = NULL;
 717
 718 static void cb_service_enabled (GObject *self, guint status, gpointer userdata)
 719 {
 720         g_debug("cb_service_enabled: status(%d) userdata(0x%x)", status, (unsigned int)userdata);
 721
 722         LocationAddress *addr = NULL;
 723         LocationAccuracy *acc = NULL;
 724         LocationObject *loc = (LocationObject*)userdata;
 725
 726         // This function works properly after service is enabled.
 727         //Calling application must have an active data connection before using this function.
 728         if (LOCATION_ERROR_NONE == location_get_address(loc, &addr, &acc)) {
 729                 g_debug ("SYNC>> Current address> %s %s %s %s %s %s %s",
 730                         addr->building_number, addr->street, addr->district, addr->city, addr->state, addr->postal_code, addr->country_code);
 731                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 732                 location_address_free(addr);
 733                 location_accuracy_free(acc);
 734         } else g_warning ("SYNC>> Current address> failed");
 735 }
 736
 737 int main (int argc, char *argv[])
 738 {
 739         LocationObject *loc = NULL;
 740         gulong handler_id = 0;
 741         int ret = LOCATION_ERROR_NONE;
 742
 743         location_init ();
 744
 745         loop = g_main_loop_new (NULL, TRUE);
 746
 747         loc  = location_new (LOCATION_METHOD_GPS);
 748         if(!loc){
 749                 g_debug("location_new failed");
 750                 return -1;
 751         }
 752
 753         handler_id = g_signal_connect (loc, "service-enabled", G_CALLBACK(cb_service_enabled), loc);
 754         location_start (loc);
 755         g_main_loop_run (loop);
 756
 757         g_signal_handler_disconnect(loc, handler_id);
 758         location_stop (loc);
 759         location_free (loc);
 760
 761         return 0;
 762 }
 763  * @endcode
 764  */
 765 int location_get_address (LocationObject *obj, LocationAddress **address, LocationAccuracy **accuracy);
 766
 767 /**
 768  * @brief
 769  * Get current address information asynchronously with estimate of the accuracy by using current position.
 770  * @remarks None.
 771  * @pre
 772  * #location_init should be called before.\n
 773  * #location_start should be called before.\n
 774  * Calling application must have glib or ecore main loop.\n
 775  * Calling application must have an active data connection.
 776  * @post None.
 777  * @param [in]
 778  * obj - a #LocationObject created by #location_new
 779  * @param [in]
 780  * callback - A pointer of function which will be called after address is gained or when an error occurs.
 781  * @param [in]
 782  * userdata - data to pass to function
 783  * @return int
 784  * @retval 0                              Success
 785  *
 786  * Please refer #LocationError for more information.
 787  * @see
 788  * location_get_address\n
 789  * @par Example
 790  * @code
 791 #include <location.h>
 792 static GMainLoop *loop = NULL;
 793
 794 static void
 795 cb_address (LocationError error, LocationAddress *addr, LocationAccuracy *acc, gpointer userdata)
 796 {
 797         g_debug ("ASYNC>> location_get_address_async> %s %s %s %s %s %s %s",
 798                         addr->building_number, addr->street, addr->district, addr->city, addr->state, addr->postal_code, addr->country_code);
 799         g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 800 }
 801
 802 static void cb_service_enabled (GObject *self, guint status, gpointer userdata)
 803 {
 804         g_debug("cb_service_enabled: status(%d) userdata(0x%x)", status, (unsigned int)userdata);
 805
 806         LocationObject *loc = (LocationObject*)userdata;
 807         // This function works properly after service is enabled.
 808         //Calling application must have an active data connection before using this function.
 809         if (LOCATION_ERROR_NONE == location_get_address_async(loc, cb_address, loc))
 810                 g_debug("location_get_address_async() success");
 811         else g_warning ("location_get_address_async() failed");
 812 }
 813
 814
 815 int main (int argc, char *argv[])
 816 {
 817         LocationObject *loc = NULL;
 818         gulong handler_id = 0;
 819         int ret = LOCATION_ERROR_NONE;
 820
 821         location_init ();
 822
 823         loop = g_main_loop_new (NULL, TRUE);
 824
 825         loc  = location_new (LOCATION_METHOD_GPS);
 826         if(!loc){
 827                 g_debug("location_new failed");
 828                 return -1;
 829         }
 830
 831         handler_id = g_signal_connect (loc, "service-enabled", G_CALLBACK(cb_service_enabled), loc);
 832         location_start (loc);
 833         g_main_loop_run (loop);
 834
 835         g_signal_handler_disconnect(loc, handler_id);
 836         location_stop (loc);
 837         location_free (loc);
 838
 839         return 0;
 840 }
 841  * @endcode
 842  */
 843 int location_get_address_async (LocationObject *obj, LocationAddressCB callback, gpointer userdata);
 844
 845 /**
 846  * @brief
 847  * Get current address information with estimate of the accuracy by using given position information.
 848  * @remarks Out parameters are should be freed.
 849  * @pre
 850  * #location_init should be called before.\n
 851  * Calling application must have an active data connection.
 852  * @post None.
 853  * @param [in]
 854  * obj - a #LocationObject created by #location_new
 855  * @param [in]
 856  * position - a #LocationPosition
 857  * @param [out]
 858  * address - a new #LocationAddress
 859  * @param [out]
 860  * accuracy - a new #LocationAccuracy
 861  * @return int
 862  * @retval 0                              Success
 863  *
 864  * Please refer #LocationError for more information.
 865  * @see
 866  * location_get_address_from_position_async\n
 867  * @par Example
 868  * @code
 869 #include <location.h>
 870 static GMainLoop *loop = NULL;
 871
 872 int
 873 main (int argc, char *argv[])
 874 {
 875         LocationObject *loc = NULL;
 876         int ret = LOCATION_ERROR_NONE;
 877
 878         location_init ();
 879
 880         loop = g_main_loop_new (NULL, TRUE);
 881
 882         loc  = location_new (LOCATION_METHOD_GPS);
 883         if(!loc){
 884                 g_debug("location_new failed");
 885                 return -1;
 886         }
 887
 888         LocationPosition *pos = NULL;
 889         LocationAccuracy *acc = NULL;
 890         LocationAddress *addr = NULL;
 891
 892         //Calling application must have an active data connection before using this function.
 893         pos = location_position_new (0, 37.257809, 127.056383, 0, LOCATION_STATUS_2D_FIX);
 894         if (LOCATION_ERROR_NONE == location_get_address_from_position(loc, pos, &addr, &acc)) {
 895                 g_debug ("SYNC>> address from position> %s %s %s %s %s %s %s",
 896                         addr->building_number, addr->street, addr->district, addr->city, addr->state, addr->postal_code, addr->country_code);
 897                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 898                 location_address_free(addr);
 899                 location_accuracy_free(acc);
 900         } else g_warning ("SYNC>> address from position> failed");
 901         location_position_free (pos);
 902 }
 903  * @endcode
 904  */
 905 int location_get_address_from_position (LocationObject *obj, const LocationPosition *position, LocationAddress **address, LocationAccuracy **accuracy);
 906
 907 /**
 908  * @brief
 909  * Get current address information asynchronously with estimate of the accuracy by using given position information.
 910  * @remarks None.
 911  * @pre
 912  * #location_init should be called before.\n
 913  * Calling application must have glib or ecore main loop.\n
 914  * Calling application must have an active data connection.
 915  * @post None.
 916  * @param [in]
 917  * obj - a #LocationObject created by #location_new
 918  * @param [in]
 919  * position - a #LocationPosition
 920  * @param [in]
 921  * callback - A pointer of function which will be called after address is gained or when an error occurs.
 922  * @param [in]
 923  * userdata - data to pass to function
 924  * @return int
 925  * @retval 0                              Success
 926  *
 927  * Please refer #LocationError for more information.
 928  * @see
 929  * location_get_address_from_position\n
 930  * @par Example
 931  * @code
 932 #include <location.h>
 933 static GMainLoop *loop = NULL;
 934
 935 static void
 936 cb_address_from_position (LocationError error, LocationAddress *addr, LocationAccuracy *acc, gpointer userdata)
 937 {
 938         g_debug ("ASYNC>> location_get_address_from_position_async> %s %s %s %s %s %s %s",
 939                         addr->building_number, addr->street, addr->district, addr->city, addr->state, addr->postal_code, addr->country_code);
 940         g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 941 }
 942
 943 void get_address_from_position(LocationObject* loc)
 944 {
 945         LocationPosition *pos = location_position_new (0, 37.257809, 127.056383, 0, LOCATION_STATUS_2D_FIX);
 946         //Calling application must have an active data connection before using this function.
 947         if (LOCATION_ERROR_NONE == location_get_address_from_position_async(loc, pos, cb_address_from_position, loc))
 948                 g_debug("location_get_address_from_position_async() success");
 949         else g_warning ("location_get_address_from_position_async() failed");
 950         location_position_free (pos);
 951 }
 952  * @endcode
 953  */
 954 int location_get_address_from_position_async (LocationObject *obj, const LocationPosition *position,    LocationAddressCB callback, gpointer userdata);
 955
 956 /**
 957  * @brief
 958  * Get information of point of interests by using current position within a given radius.
 959  * @remarks Out parameters are should be freed.
 960  * \n This functions is not implemneted yet.
 961  * @pre
 962  * #location_init should be called before.\n
 963  * #location_start should be called before.\n
 964  * Calling application must have an active data connection.
 965  * @post None.
 966  * @param [in]  obj - a #LocationObject created by #location_new
 967  * @param [in]  radius - radius of a circle
 968  * @param [in]  keyword - keyword for POI
 969  * @param [out] poi_info - a new #LocationPOIInfo
 970  * @return int
 971  * @retval 0                              Success
 972  *
 973  * Please refer #LocationError for more information.
 974  */
 975 int location_get_poi (LocationObject *obj, gdouble radius, const gchar *keyword, LocationPOIInfo **poi_info);
 976
 977 /**
 978  * @brief
 979  * Get information of point of interests asynchronously by using current position within a given radius.
 980  * @remarks This functions is not implemneted yet.
 981  * @pre
 982  * #location_init should be called before.\n
 983  * #location_start should be called before.\n
 984  * Calling application must have glib or ecore main loop.\n
 985  * Calling application must have an active data connection.
 986  * @post None.
 987  * @param [in]  obj - a #LocationObject created by #location_new
 988  * @param [in]  radius - radius of a circle
 989  * @param [in]  callback - function to call
 990  * @param [in]  userdata - data to pass to function
 991  * @return int
 992  * @retval 0                              Success
 993  *
 994  * Please refer #LocationError for more information.
 995  */
 996 int location_get_poi_async (LocationObject *obj, gdouble radius, const gchar *keyword, LocationPOICB callback, gpointer userdata);
 997
 998 /**
 999  * @brief
1000  * Get information of point of interests by using given address within a given radius.
1001  * @remarks Out parameters are should be freed.
1002  * \n This functions is not implemneted yet.
1003  * @pre
1004  * #location_init should be called before.\n
1005  * Calling application must have an active data connection.
1006  * @post None.
1007  * @param [in]  obj - a #LocationObject created by #location_new
1008  * @param [in]  address - a #LocationAddress
1009  * @param [in]  radius - radius of a circle
1010  * @param [in]  keyword - keyword for POI
1011  * @param [out] poi_info - a new #LocationPOIInfo
1012  * @return int
1013  * @retval 0                              Success
1014  *
1015  * Please refer #LocationError for more information.
1016  */
1017 int location_get_poi_from_address(LocationObject *obj, const LocationAddress *address, gdouble radius, const gchar *keyword,    LocationPOIInfo **poi_info);
1018
1019 /**
1020  * @brief
1021  * Get information of point of interests asynchronously by using given address within a given radius.
1022  * @remarks This functions is not implemneted yet.
1023  * @pre
1024  * #location_init should be called before.\n
1025  * Calling application must have glib or ecore main loop.\n
1026  * Calling application must have an active data connection.
1027  * @post None.
1028  * @param [in]  obj - a #LocationObject created by #location_new
1029  * @param [in]  address - a #LocationAddress
1030  * @param [in]  radius - radius of a circle
1031  * @param [in]  callback - function to call
1032  * @param [in]  userdata - data to pass to function
1033  * @return int
1034  * @retval 0                              Success
1035  *
1036  * Please refer #LocationError for more information.
1037  */
1038 int location_get_poi_from_address_async (LocationObject *obj, const LocationAddress *address, gdouble radius, const gchar *keyword, LocationPOICB callback, gpointer userdata);
1039
1040 /**
1041  * @brief
1042  * Get information of point of interests by using given position within a given radius.
1043  * @remarks Out parameters are should be freed.
1044  * \n This functions is not implemneted yet.
1045  * @pre
1046  * #location_init should be called before.\n
1047  * Calling application must have an active data connection.
1048  * @post None.
1049  * @param [in]  obj - a #LocationObject created by #location_new
1050  * @param [in]  position - a #LocationPosition
1051  * @param [in]  radius - radius of a circle
1052  * @param [in]  keyword - keyword for POI
1053  * @param [out] poi_info - a new #LocationPOIInfo
1054  * @return int
1055  * @retval 0                              Success
1056  *
1057  * Please refer #LocationError for more information.
1058  */
1059 int location_get_poi_from_position(LocationObject *obj, const LocationPosition *position, gdouble radius,       const gchar *keyword, LocationPOIInfo **poi_info);
1060
1061 /**
1062  * @brief
1063  * Get information of point of interests asynchronously by using given position within a given radius.
1064  * @remarks This functions is not implemneted yet.
1065  * @pre
1066  * #location_init should be called before.\n
1067  * Calling application must have glib or ecore main loop.\n
1068  * Calling application must have an active data connection.
1069  * @post None.
1070  * @param [in]  obj - a #LocationObject created by #location_new
1071  * @param [in]  position - a #LocationPosition
1072  * @param [in]  radius - radius of a circle
1073  * @param [in]  callback - function to call
1074  * @param [in]  userdata - data to pass to function
1075  * @return int
1076  * @retval 0                              Success
1077  *
1078  * Please refer #LocationError for more information.
1079  */
1080 int location_get_poi_from_position_async (LocationObject *obj, const LocationPosition *position, gdouble radius,        const gchar*keyword, LocationPOICB callback, gpointer userdata);
1081
1082 /**
1083  * @brief
1084  * Send command to the server.
1085  * @remarks This functions is not implemneted yet.
1086  * @pre
1087  * #location_init should be called before.\n
1088  * Calling application must have glib or ecore main loop.\n
1089  * Calling application must have an active data connection.
1090  * @post None.
1091  * @param [in]  cmd - a #char
1092  * @return int
1093  * @retval 0                              Success
1094  *
1095  * Please refer #LocationError for more information.
1096  */
1097 int location_send_command(const char *cmd);
1098
1099 /**
1100  * @} @}
1101  */
1102
1103 G_END_DECLS
1104
1105 #endif /* __LOCATION_H__ */