location/map-service/location-map-service.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_MAP_SERVICE_H__
  24 #define __LOCATION_MAP_SERVICE_H__
  25
  26
  27 #include <glib.h>
  28 #include <location-types.h>
  29 #include <location-poi.h>
  30 #include <location-route.h>
  31 #include <location-pref.h>
  32 #include <location-landmark.h>
  33
  34 G_BEGIN_DECLS
  35
  36 /**
  37  * @file location-map-service.h
  38  * @brief This file contains the Location API and related structure and enumeration.
  39  */
  40 /**
  41  * @addtogroup LocationFW
  42  * @{
  43  * @defgroup LocationMapService Location Map Service API
  44  * @brief This sub module provides the Location Map Service API.
  45  * @addtogroup LocationMapService
  46  * @{
  47  */
  48
  49 /**
  50  * @brief
  51  * Get current position information with estimate of the accuracy by using given address information.
  52  * @remarks Out parameters are should be freed.
  53  * @pre
  54  * #location_init should be called before.\n
  55  * Calling application must have an active data connection.
  56  * @post None.
  57  * @param [in]
  58  * obj - a #LocationObject created by #location_new
  59  * @param [in]
  60  * address - a #LocationAddress
  61  * @param [out]
  62  * position_list - a list of #LocationPosition
  63  * @param [out]
  64  * accuracy_list - a list of #LocationAccuracy
  65  * @return int
  66  * @retval 0                              Success.
  67  *
  68  * Please refer #LocationError for more information.
  69  * @see
  70  * location_get_position_from_address_async\n
  71  * @par Example
  72  * @code
  73 #include <location.h>
  74 #include <location-map-service.h>
  75
  76 static void PrintPos (gpointer data, gpointer user_data)
  77 {
  78        LocationPosition *pos = (LocationPosition *)data;
  79
  80        if (pos) {
  81            g_debug("time: [%d], latitude: [%f], longitude: [%f], altitude: [%f]\n", pos->timestamp, pos->latitude, pos->longitude, pos->altitude);
  82            location_position_free (pos);
  83       }
  84 }
  85
  86 static void PrintAcc (gpointer data, gpointer user_data)
  87 {
  88        LocationAccuracy *acc = (LocationAccuracy *)data;
  89
  90        if (acc) {
  91               g_debug("level: [%d], horizontal_accuracy: [%f], vertical_accuracy: [%f]\n", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
  92               location_accuracy_free (acc);
  93        }
  94
  95 }
  96
  97 static void PrintPos (gpointer data, gpointer user_data)
  98 {
  99         LocationPosition *pos = (LocationPosition *)data;
 100
 101         if (pos) {
 102                 g_debug("time: [%d], latitude: [%f], longitude: [%f], altitude: [%f]\n", pos->timestamp, pos->latitude, pos->longitude, pos->altitude);
 103                 location_position_free (pos);
 104         }
 105 }
 106
 107 static void PrintAcc (gpointer data, gpointer user_data)
 108 {
 109         LocationAccuracy *acc = (LocationAccuracy *)data;
 110
 111         if (acc) {
 112                 g_debug("level: [%d], horizontal_accuracy: [%f], vertical_accuracy: [%f]\n", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 113                 location_accuracy_free (acc);
 114         }
 115 }
 116
 117 int main (int argc, char *argv[])
 118 {
 119         LocationObject *loc = NULL;
 120         int ret = LOCATION_ERROR_NONE;
 121
 122         location_init ();
 123         loc  = location_new (LOCATION_METHOD_GPS);
 124         if(!loc){
 125                 g_debug("location_new failed");
 126                 return -1;
 127         }
 128
 129         GList *pos_list = NULL;
 130         GList *acc_list = NULL;
 131         LocationAddress *addr = NULL;
 132
 133         addr = location_address_new ("1", "Post Street", NULL, "san jose", "ca", NULL, "95113");
 134         if (LOCATION_ERROR_NONE == location_get_position_from_address(loc, addr, &pos_list, &acc_list)) {
 135
 136         } else g_warning ("SYNC>> position from address> failed");
 137         location_address_free (addr);
 138         g_list_foreach (pos_list, PrintPos, NULL);
 139         g_list_foreach (acc_list, PrintAcc, NULL);
 140         g_list_free (pos_list);
 141         g_list_free (acc_list);
 142         location_free (loc);
 143         return 0;
 144 }
 145  * @endcode
 146  */
 147 int location_get_position_from_address (LocationObject *obj, const LocationAddress *address, GList **position_list, GList **accuracy_list);
 148
 149 /**
 150  * @brief
 151  * Get current position information asynchronously with estimate of the accuracy by using given address information.
 152  * @remarks None.
 153  * @pre
 154  * #location_init should be called before.\n
 155  * Calling application must have glib or ecore main loop.\n
 156  * Calling application must have an active data connection.
 157  * @post None.
 158  * @param [in]
 159  * obj - a #LocationObject created by #location_new
 160  * @param [in]
 161  * address - a #LocationAddress
 162  * @param [in]
 163  * callback - A pointer of function which will be called after position is gained or when an error occurs.
 164  * @param [in]
 165  * userdata - data to pass to function
 166  * @return int
 167  * @retval 0                              Success.
 168  *
 169  * Please refer #LocationError for more information.
 170  * @see
 171  * location_get_position_from_address\n
 172  * @par Example
 173  * @code
 174 #include <location.h>
 175 #include <location-map-service.h>
 176
 177 static void PrintPos (gpointer data, gpointer user_data)
 178 {
 179         LocationPosition *pos = (LocationPosition *)data;
 180
 181         if (pos) {
 182                 g_debug("time: [%d], latitude: [%f], longitude: [%f], altitude: [%f]\n", pos->timestamp, pos->latitude, pos->longitude, pos->altitude);
 183         }
 184 }
 185
 186 static void PrintAcc (gpointer data, gpointer user_data)
 187 {
 188         LocationAccuracy *acc = (LocationAccuracy *)data;
 189
 190         if (acc) {
 191                 g_debug("level: [%d], horizontal_accuracy: [%f], vertical_accuracy: [%f]\n", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 192         }
 193 }
 194 static void
 195 cb_position_from_address (LocationError error, GList *position_list, GList *accuracy_list, gpointer userdata)
 196 {
 197         if (position_list && accuracy_list) {
 198                 g_list_foreach (position_list, PrintPos);
 199                 g_list_foreach (accuracy_list, PrintAcc);
 200         }
 201 }
 202
 203 void get_position_from_address(LocationObject* loc)
 204 {
 205         LocationAddress *addr = location_address_new ("1", "Post Street", NULL, "san jose", "ca", NULL, "95113");
 206         //Calling application must have an active data connection before using this function.
 207         if (LOCATION_ERROR_NONE == location_get_position_from_address_async(loc, addr, cb_position_from_address, loc))
 208                 g_debug("location_get_position_from_address_async() success");
 209         else g_warning ("location_get_position_from_address_async() failed");
 210         location_address_free (addr);
 211 }
 212  * @endcode
 213  */
 214 int location_get_position_from_address_async (LocationObject *obj, const LocationAddress *address, LocationPositionCB callback, gpointer userdata);
 215
 216 /**
 217  * @brief
 218  * Get current position information with estimate of the accuracy by using given free-formed address string.
 219  * @remarks Out parameters are should be freed.
 220  * @pre
 221  * #location_init should be called before.\n
 222  * Calling application must have an active data connection.
 223  * @post None.
 224  * @param [in]
 225  * obj - a #LocationObject created by #location_new
 226  * @param [in]
 227  * address - Free-formed address string to be used
 228  * @param [out]
 229  * position_list - a list of #LocationPosition
 230  * @param [out]
 231  * accuracy_list - a list of #LocationAccuracy
 232  * @return int
 233  * @retval 0                              Success
 234  *
 235  * Please refer #LocationError for more information.
 236  * @see
 237  * location_get_position_from_freeformed_address_async\n
 238  * @par Example
 239  * @code
 240 #include <location.h>
 241 #include <location-map-service.h>
 242
 243 static void PrintPos (gpointer data, gpointer user_data)
 244 {
 245         LocationPosition *pos = (LocationPosition *)data;
 246
 247         if (pos) {
 248                 g_debug("time: [%d], latitude: [%f], longitude: [%f], altitude: [%f]\n", pos->timestamp, pos->latitude, pos->longitude, pos->altitude);
 249                 location_position_free (pos);
 250         }
 251 }
 252
 253 static void PrintAcc (gpointer data, gpointer user_data)
 254 {
 255         LocationAccuracy *acc = (LocationAccuracy *)data;
 256
 257         if (acc) {
 258                 g_debug("level: [%d], horizontal_accuracy: [%f], vertical_accuracy: [%f]\n", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 259                 location_accuracy_free (acc);
 260         }
 261 }
 262
 263 static void PrintPos (gpointer data, gpointer user_data)
 264 {
 265         LocationPosition *pos = (LocationPosition *)data;
 266
 267         if (pos) {
 268                 g_debug("time: [%d], latitude: [%f], longitude: [%f], altitude: [%f]\n", pos->timestamp, pos->latitude, pos->longitude, pos->altitude);
 269                 location_position_free (pos);
 270         }
 271 }
 272
 273 static void PrintAcc (gpointer data, gpointer user_data)
 274 {
 275         LocationAccuracy *acc = (LocationAccuracy *)data;
 276
 277         if (acc) {
 278                 g_debug("level: [%d], horizontal_accuracy: [%f], vertical_accuracy: [%f]\n", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 279                 location_accuracy_free (acc);
 280         }
 281 }
 282
 283 int main (int argc, char *argv[])
 284 {
 285         LocationObject *loc = NULL;
 286         int ret = LOCATION_ERROR_NONE;
 287
 288         location_init ();
 289         loc  = location_new (LOCATION_METHOD_GPS);
 290         if(!loc){
 291                 g_debug("location_new failed");
 292                 return -1;
 293         }
 294
 295         GList *pos_list = NULL;
 296         GList *acc_list = NULL;
 297         char* addr_str = g_strdup("4 N 2nd Street 95113");
 298
 299         //Calling application must have an active data connection before using this function.
 300         if (LOCATION_ERROR_NONE == location_get_position_from_freeformed_address(loc, addr_str, &pos_list, &acc_list)) {
 301                 g_list_foreach (pos_list, PrintPos, NULL);
 302                 g_list_foreach (acc_list, PrintAcc, NULL);
 303                 g_list_free (pos_list);
 304                 g_list_free (acc_list);
 305         } else g_warning ("SYNC>> position from freeformed address> failed");
 306         g_free(addr_str);
 307
 308         location_free (loc);
 309         return 0;
 310 }
 311  * @endcode
 312  */
 313 int location_get_position_from_freeformed_address (LocationObject *obj, const gchar *address, GList **position_list, GList **accuracy_list);
 314
 315 /**
 316  * @brief
 317  * Get current position information asynchronously with estimate of the accuracy by using given free-formed address string.
 318  * @remarks None.
 319  * @pre
 320  * #location_init should be called before.\n
 321  * Calling application must have glib or ecore main loop.\n
 322  * Calling application must have an active data connection.
 323  * @post None.
 324  * @param [in]
 325  * obj - a #LocationObject created by #location_new
 326  * @param [in]
 327  * address - Free-formed address string to be used
 328  * @param [in]
 329  * callback - A pointer of function which will be called after position is gained or when an error occurs.
 330  * @param [in]
 331  * userdata - data to pass to function
 332  * @return int
 333  * @retval 0                              Success
 334  *
 335  * Please refer #LocationError for more information.
 336  * @see
 337  * location_get_position_from_freeformed_address\n
 338  * @par Example
 339  * @code
 340 #include <location.h>
 341 #include <location-map-service.h>
 342
 343 static void PrintPos (gpointer data, gpointer user_data)
 344 {
 345         LocationPosition *pos = (LocationPosition *)data;
 346
 347         if (pos) {
 348                 g_debug("time: [%d], latitude: [%f], longitude: [%f], altitude: [%f]\n", pos->timestamp, pos->latitude, pos->longitude, pos->altitude);
 349         }
 350 }
 351
 352 static void PrintAcc (gpointer data, gpointer user_data)
 353 {
 354         LocationAccuracy *acc = (LocationAccuracy *)data;
 355
 356         if (acc) {
 357                 g_debug("level: [%d], horizontal_accuracy: [%f], vertical_accuracy: [%f]\n", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 358         }
 359 }
 360
 361 static void
 362 cb_position_from_freeformed_address (LocationError error, GList *position_list, GList *accuracy_list, gpointer userdata)
 363 {
 364         if (position_list && accuracy_list) {
 365                 g_list_foreach (position_list, PrintPos);
 366                 g_list_foreach (accuracy_list, PrintAcc);
 367         }
 368 }
 369
 370 void get_position_from_address(LocationObject* loc)
 371 {
 372         gchar *addr_str = g_strdup("4 N 2nd Street 95113");
 373         //Calling application must have an active data connection before using this function.
 374         if (LOCATION_ERROR_NONE == location_get_position_from_freeformed_address_async(loc, addr_str, cb_position_from_freeformed_address, loc))
 375                 g_debug("location_get_position_from_freeformed_address_async() success");
 376         else g_warning ("location_get_position_from_freeformed_address_async() failed");
 377         g_free(addr_str);
 378
 379 }
 380  * @endcode
 381  */
 382 int location_get_position_from_freeformed_address_async (LocationObject *obj, const gchar *address, LocationPositionCB callback,        gpointer userdata);
 383
 384 /**
 385  * @brief
 386  * Get current address information with estimate of the accuracy by using current position.
 387  * @remarks Out parameters are should be freed.
 388  * @pre
 389  * #location_init should be called before.\n
 390  * #location_start should be called before.\n
 391  * Calling application must have an active data connection.
 392  * @post None.
 393  * @param [in]
 394  * obj - a #LocationObject created by #location_new
 395  * @param [out]
 396  * address - a new #LocationAddress
 397  * @param [out]
 398  * accuracy - a new #LocationAccuracy
 399  * @return int
 400  * @retval 0                              Success
 401  *
 402  * Please refer #LocationError for more information.
 403  * @see
 404  * location_get_address_async\n
 405  * @par Example
 406  * @code
 407 #include <location.h>
 408 #include <location-map-service.h>
 409 static GMainLoop *loop = NULL;
 410
 411 static void cb_service_enabled (GObject *self, guint status, gpointer userdata)
 412 {
 413         g_debug("cb_service_enabled: status(%d) userdata(0x%x)", status, (unsigned int)userdata);
 414
 415         LocationAddress *addr = NULL;
 416         LocationAccuracy *acc = NULL;
 417         LocationObject *loc = (LocationObject*)userdata;
 418
 419         // This function works properly after service is enabled.
 420         //Calling application must have an active data connection before using this function.
 421         if (LOCATION_ERROR_NONE == location_get_address(loc, &addr, &acc)) {
 422                 g_debug ("SYNC>> Current address> %s %s %s %s %s %s %s",
 423                         addr->building_number, addr->street, addr->district, addr->city, addr->state, addr->postal_code, addr->country_code);
 424                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 425                 location_address_free(addr);
 426                 location_accuracy_free(acc);
 427         } else g_warning ("SYNC>> Current address> failed");
 428 }
 429
 430 int main (int argc, char *argv[])
 431 {
 432         LocationObject *loc = NULL;
 433         gulong handler_id = 0;
 434         int ret = LOCATION_ERROR_NONE;
 435
 436         location_init ();
 437
 438         loop = g_main_loop_new (NULL, TRUE);
 439
 440         loc  = location_new (LOCATION_METHOD_GPS);
 441         if(!loc){
 442                 g_debug("location_new failed");
 443                 return -1;
 444         }
 445
 446         handler_id = g_signal_connect (loc, "service-enabled", G_CALLBACK(cb_service_enabled), loc);
 447         location_start (loc);
 448         g_main_loop_run (loop);
 449
 450         g_signal_handler_disconnect(loc, handler_id);
 451         location_stop (loc);
 452         location_free (loc);
 453
 454         return 0;
 455 }
 456  * @endcode
 457  */
 458 int location_get_address (LocationObject *obj, LocationAddress **address, LocationAccuracy **accuracy);
 459
 460 /**
 461  * @brief
 462  * Get current address information asynchronously with estimate of the accuracy by using current position.
 463  * @remarks None.
 464  * @pre
 465  * #location_init should be called before.\n
 466  * #location_start should be called before.\n
 467  * Calling application must have glib or ecore main loop.\n
 468  * Calling application must have an active data connection.
 469  * @post None.
 470  * @param [in]
 471  * obj - a #LocationObject created by #location_new
 472  * @param [in]
 473  * callback - A pointer of function which will be called after address is gained or when an error occurs.
 474  * @param [in]
 475  * userdata - data to pass to function
 476  * @return int
 477  * @retval 0                              Success
 478  *
 479  * Please refer #LocationError for more information.
 480  * @see
 481  * location_get_address\n
 482  * @par Example
 483  * @code
 484 #include <location.h>
 485 #include <location-map-service.h>
 486 static GMainLoop *loop = NULL;
 487
 488 static void
 489 cb_address (LocationError error, LocationAddress *addr, LocationAccuracy *acc, gpointer userdata)
 490 {
 491         g_debug ("ASYNC>> location_get_address_async> %s %s %s %s %s %s %s",
 492                         addr->building_number, addr->street, addr->district, addr->city, addr->state, addr->postal_code, addr->country_code);
 493         g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 494 }
 495
 496 static void cb_service_enabled (GObject *self, guint status, gpointer userdata)
 497 {
 498         g_debug("cb_service_enabled: status(%d) userdata(0x%x)", status, (unsigned int)userdata);
 499
 500         LocationObject *loc = (LocationObject*)userdata;
 501         // This function works properly after service is enabled.
 502         //Calling application must have an active data connection before using this function.
 503         if (LOCATION_ERROR_NONE == location_get_address_async(loc, cb_address, loc))
 504                 g_debug("location_get_address_async() success");
 505         else g_warning ("location_get_address_async() failed");
 506 }
 507
 508
 509 int main (int argc, char *argv[])
 510 {
 511         LocationObject *loc = NULL;
 512         gulong handler_id = 0;
 513         int ret = LOCATION_ERROR_NONE;
 514
 515         location_init ();
 516
 517         loop = g_main_loop_new (NULL, TRUE);
 518
 519         loc  = location_new (LOCATION_METHOD_GPS);
 520         if(!loc){
 521                 g_debug("location_new failed");
 522                 return -1;
 523         }
 524
 525         handler_id = g_signal_connect (loc, "service-enabled", G_CALLBACK(cb_service_enabled), loc);
 526         location_start (loc);
 527         g_main_loop_run (loop);
 528
 529         g_signal_handler_disconnect(loc, handler_id);
 530         location_stop (loc);
 531         location_free (loc);
 532
 533         return 0;
 534 }
 535  * @endcode
 536  */
 537 int location_get_address_async (LocationObject *obj, LocationAddressCB callback, gpointer userdata);
 538
 539 /**
 540  * @brief
 541  * Get current address information with estimate of the accuracy by using given position information.
 542  * @remarks Out parameters are should be freed.
 543  * @pre
 544  * #location_init should be called before.\n
 545  * Calling application must have an active data connection.
 546  * @post None.
 547  * @param [in]
 548  * obj - a #LocationObject created by #location_new
 549  * @param [in]
 550  * position - a #LocationPosition
 551  * @param [out]
 552  * address - a new #LocationAddress
 553  * @param [out]
 554  * accuracy - a new #LocationAccuracy
 555  * @return int
 556  * @retval 0                              Success
 557  *
 558  * Please refer #LocationError for more information.
 559  * @see
 560  * location_get_address_from_position_async\n
 561  * @par Example
 562  * @code
 563 #include <location.h>
 564 #include <location-map-service.h>
 565 static GMainLoop *loop = NULL;
 566
 567 int
 568 main (int argc, char *argv[])
 569 {
 570         LocationObject *loc = NULL;
 571         int ret = LOCATION_ERROR_NONE;
 572
 573         location_init ();
 574
 575         loop = g_main_loop_new (NULL, TRUE);
 576
 577         loc  = location_new (LOCATION_METHOD_GPS);
 578         if(!loc){
 579                 g_debug("location_new failed");
 580                 return -1;
 581         }
 582
 583         LocationPosition *pos = NULL;
 584         LocationAccuracy *acc = NULL;
 585         LocationAddress *addr = NULL;
 586
 587         //Calling application must have an active data connection before using this function.
 588         pos = location_position_new (0, 37.257809, 127.056383, 0, LOCATION_STATUS_2D_FIX);
 589         if (LOCATION_ERROR_NONE == location_get_address_from_position(loc, pos, &addr, &acc)) {
 590                 g_debug ("SYNC>> address from position> %s %s %s %s %s %s %s",
 591                         addr->building_number, addr->street, addr->district, addr->city, addr->state, addr->postal_code, addr->country_code);
 592                 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 593                 location_address_free(addr);
 594                 location_accuracy_free(acc);
 595         } else g_warning ("SYNC>> address from position> failed");
 596         location_position_free (pos);
 597 }
 598  * @endcode
 599  */
 600 int location_get_address_from_position (LocationObject *obj, const LocationPosition *position, LocationAddress **address, LocationAccuracy **accuracy);
 601
 602 /**
 603  * @brief
 604  * Get current address information asynchronously with estimate of the accuracy by using given position information.
 605  * @remarks None.
 606  * @pre
 607  * #location_init should be called before.\n
 608  * Calling application must have glib or ecore main loop.\n
 609  * Calling application must have an active data connection.
 610  * @post None.
 611  * @param [in]
 612  * obj - a #LocationObject created by #location_new
 613  * @param [in]
 614  * position - a #LocationPosition
 615  * @param [in]
 616  * callback - A pointer of function which will be called after address is gained or when an error occurs.
 617  * @param [in]
 618  * userdata - data to pass to function
 619  * @return int
 620  * @retval 0                              Success
 621  *
 622  * Please refer #LocationError for more information.
 623  * @see
 624  * location_get_address_from_position\n
 625  * @par Example
 626  * @code
 627 #include <location.h>
 628 #include <location-map-service.h>
 629 static GMainLoop *loop = NULL;
 630
 631 static void
 632 cb_address_from_position (LocationError error, LocationAddress *addr, LocationAccuracy *acc, gpointer userdata)
 633 {
 634         g_debug ("ASYNC>> location_get_address_from_position_async> %s %s %s %s %s %s %s",
 635                         addr->building_number, addr->street, addr->district, addr->city, addr->state, addr->postal_code, addr->country_code);
 636         g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
 637 }
 638
 639 void get_address_from_position(LocationObject* loc)
 640 {
 641         LocationPosition *pos = location_position_new (0, 37.257809, 127.056383, 0, LOCATION_STATUS_2D_FIX);
 642         //Calling application must have an active data connection before using this function.
 643         if (LOCATION_ERROR_NONE == location_get_address_from_position_async(loc, pos, cb_address_from_position, loc))
 644                 g_debug("location_get_address_from_position_async() success");
 645         else g_warning ("location_get_address_from_position_async() failed");
 646         location_position_free (pos);
 647 }
 648  * @endcode
 649  */
 650 int location_get_address_from_position_async (LocationObject *obj, const LocationPosition *position,    LocationAddressCB callback, gpointer userdata);
 651
 652 /**
 653  * @brief Request a search service from service provider.
 654  * @remarks refer #LocationLandmark
 655  * @pre #location_init should be called before.\n
 656  *      #location_poi_pref_new should be set before.
 657  * @post None.
 658  * @param [in] obj - a #LocationObject created by #location_new
 659  * @param [in] filter - a #LocaitonPOIFilter created by #location_poi_filter_new
 660  * @param [in] position - a #LocationPosition
 661  * @param [in] pref - a #LocationPOIPreference created by #location_poi_pref_new
 662  * @param [in] cb - #LocationPOICB
 663  * @param [in] user_data - data to pass to function
 664  * @param [out] req_id - a guint
 665  * @return int
 666  * @retval 0                              Success
 667  * Please refer #LocationError for more information.
 668  * @par Example
 669  * @code
 670 #include <location.h>
 671 #include <location-map-service.h>
 672
 673 static GMainLoop *loop = NULL;
 674
 675 void PrintLandmarkCb (gpointer data, gpointer user_data)
 676 {
 677         g_return_if_fail (data);
 678
 679         LocationLandmark *landmark = (LocationLandmark *)data;
 680
 681         g_debug ("id[%d], Priority[%d], Name:[%s], Author[%s], Phone[%s], Category[%s]\n", location_landmark_get_id (landmark),
 682                                   location_landmark_get_priority(landmark),
 683                                   location_landmark_get_name(landmark),
 684                                   location_landmark_get_author(landmark),
 685                                   location_landmark_get_phone_number(landmark),
 686                                   location_landmark_get_category(landmark));
 687 }
 688
 689 static void poi_cb(LocationError error, guint req_id, GList * landmark_list, gchar * error_code, gchar * error_msg, gpointer userdata)
 690 {
 691         if (error != LOCATION_ERROR_NONE || landmark_list == NULL) {
 692                 g_debug ("Fail to get poi. Error[%d], ErrCode[%s], ErrMsg[%s]", error, error_code, error_msg);
 693                 return;
 694         }
 695         g_list_foreach (landmark_list, PrintLandmarkCb, NULL);
 696 }
 697
 698 void search_poi(LocationObject* loc)
 699 {
 700         int ret = 0;
 701         guint req_id = 0;
 702         LocationPosition *pos = location_position_new (0, 37.257809, 127.056383, 0, LOCATION_STATUS_2D_FIX);
 703         LocationPOIFilter *filter = location_poi_filter_new();
 704         LocationPOIPreference *pref = location_poi_pref_new();
 705
 706         location_poi_filter_set(filter, "CATEGORY", "restaurant");
 707
 708         location_poi_pref_set_max_result(pref, 5);
 709         location_poi_pref_set_sort_by(pref, "name");
 710         location_poi_pref_set_sort_order(pref, LOCATION_POI_PREF_SO_ASC);
 711
 712         ret = location_search_poi (loc, filter, pos, pref, poi_cb, loc, &req_id);
 713         if (ret != LOCATION_ERROR_NONE) {
 714                 g_debug("Fail to get poi. Error[%d]", ret);
 715         }
 716
 717         location_poi_filter_free(filter);
 718         location_poi_pref_free(pref);
 719         location_position_free(pos);
 720
 721 }
 722  * @endcode
 723  */
 724 int location_search_poi (LocationObject *obj, const LocationPOIFilter * filter, const LocationPosition *position, const LocationPOIPreference * pref, LocationPOICB cb, gpointer user_data, guint * req_id);
 725
 726 /**
 727  * @brief Request a search service with area filter from service provider.
 728  * @remarks refer #LocationLandmark
 729  * @pre #location_init should be called before.\n
 730  *      #location_poi_pref_new should be set before.
 731  * @post None.
 732  * @param [in] obj - a #LocationObject created by #location_new
 733  * @param [in] filter - a #LocaitonPOIFilter created by #location_poi_filter_new
 734  * @param [in] boundary - a #LocationBoundary
 735  * @param [in] pref - a #LocationPOIPreference created by #location_poi_pref_new
 736  * @param [in] cb - #LocationPOICB
 737  * @param [in] user_data - data to pass to function
 738  * @param [out] req_id - a guint
 739  * @return int
 740  * @retval 0                              Success
 741  * Please refer #LocationError for more information.
 742  * @par Example
 743  * @code
 744 #include <location.h>
 745 #include <location-map-service.h>
 746
 747 static GMainLoop *loop = NULL;
 748
 749 void PrintLandmarkCb (gpointer data, gpointer user_data)
 750 {
 751         g_return_if_fail (data);
 752
 753         LocationLandmark *landmark = (LocationLandmark *)data;
 754
 755         g_debug ("id[%d], Priority[%d], Name:[%s], Author[%s], Phone[%s], Category[%s]\n", location_landmark_get_id (landmark),
 756                                   location_landmark_get_priority(landmark),
 757                                   location_landmark_get_name(landmark),
 758                                   location_landmark_get_author(landmark),
 759                                   location_landmark_get_phone_number(landmark),
 760                                   location_landmark_get_category(landmark));
 761 }
 762
 763 static void poi_cb(LocationError error, guint req_id, GList * landmark_list, gchar * error_code, gchar * error_msg, gpointer userdata)
 764 {
 765         if (error != LOCATION_ERROR_NONE || landmark_list == NULL) {
 766                 g_debug ("Fail to get poi. Error[%d], ErrCode[%s], ErrMsg[%s]", error, error_code, error_msg);
 767                 return;
 768         }
 769         g_list_foreach (landmark_list, PrintLandmarkCb, NULL);
 770 }
 771
 772 void search_poi(LocationObject* loc)
 773 {
 774         int ret = 0;
 775         guint req_id = 0;
 776
 777         LocationPosition* rb = location_position_new (0, 37.300, -121.86, 0, LOCATION_STATUS_2D_FIX);
 778         LocationPosition* lt = location_position_new (0, 37.360, -121.92, 0, LOCATION_STATUS_2D_FIX);
 779         LocationBoundary *bbox = location_boundary_new_for_rect (lt, rb);
 780         LocationPOIFilter *filter = location_poi_filter_new();
 781         LocationPOIPreference *pref = location_poi_pref_new();
 782
 783         location_poi_filter_set(filter, "CATEGORY", "restaurant");
 784
 785         location_poi_pref_set_max_result(pref, 5);
 786         location_poi_pref_set_sort_by(pref, "name");
 787         location_poi_pref_set_sort_order(pref, LOCATION_POI_PREF_SO_ASC);
 788
 789         ret = location_search_poi_by_area (loc, filter, bbox, pref, poi_cb, loc, &req_id);
 790         if (ret != LOCATION_ERROR_NONE) {
 791                 g_debug("Fail to get poi. Error[%d]", ret);
 792         }
 793
 794         location_poi_filter_free(filter);
 795         location_poi_pref_free(pref);
 796         location_boundary_free (bbox);
 797 }
 798  * @endcode
 799  */
 800 int location_search_poi_by_area (LocationObject *obj, const LocationPOIFilter * filter, const LocationBoundary * boundary, const LocationPOIPreference * pref, LocationPOICB cb, gpointer user_data, guint * req_id);
 801
 802 /**
 803  * @brief Request a search service with address filter from service provider.
 804  * @remarks refer #LocationLandmark
 805  * @pre #location_init should be called before.\n
 806  *      #location_poi_pref_new should be set before.
 807  * @post None.
 808  * @param [in] obj - a #LocationObject created by #location_new
 809  * @param [in] filter - a #LocaitonPOIFilter created by #location_poi_filter_new
 810  * @param [in] address - a #LocationAddress
 811  * @param [in] pref - a #LocationPOIPreference created by #location_poi_pref_new
 812  * @param [in] cb - #LocationPOICB
 813  * @param [in] user_data - data to pass to function
 814  * @param [out] req_id - a guint
 815  * @return int
 816  * @retval 0                              Success
 817  * Please refer #LocationError for more information.
 818  * @par Example
 819  * @code
 820 #include <location.h>
 821 #include <location-map-service.h>
 822
 823 static GMainLoop *loop = NULL;
 824
 825 void PrintLandmarkCb (gpointer data, gpointer user_data)
 826 {
 827         g_return_if_fail (data);
 828
 829         LocationLandmark *landmark = (LocationLandmark *)data;
 830
 831         g_debug ("id[%d], Priority[%d], Name:[%s], Author[%s], Phone[%s], Category[%s]\n", location_landmark_get_id (landmark),
 832                                   location_landmark_get_priority(landmark),
 833                                   location_landmark_get_name(landmark),
 834                                   location_landmark_get_author(landmark),
 835                                   location_landmark_get_phone_number(landmark),
 836                                   location_landmark_get_category(landmark));
 837 }
 838
 839 static void poi_cb(LocationError error, guint req_id, GList * landmark_list, gchar * error_code, gchar * error_msg, gpointer userdata)
 840 {
 841         if (error != LOCATION_ERROR_NONE || landmark_list == NULL) {
 842                 g_debug ("Fail to get poi. Error[%d], ErrCode[%s], ErrMsg[%s]", error, error_code, error_msg);
 843                 return;
 844         }
 845         g_list_foreach (landmark_list, PrintLandmarkCb, NULL);
 846 }
 847
 848 void search_poi(LocationObject* loc)
 849 {
 850         int ret = 0;
 851         guint req_id = 0;
 852
 853         LocationAddress *addr = location_address_new ("1", "Post Street", NULL, "san jose", "ca", NULL, "95113");
 854         LocationPOIFilter *filter = location_poi_filter_new();
 855         LocationPOIPreference *pref = location_poi_pref_new();
 856
 857         location_poi_filter_set(filter, "CATEGORY", "restaurant");
 858
 859         location_poi_pref_set_max_result(pref, 5);
 860         location_poi_pref_set_sort_by(pref, "name");
 861         location_poi_pref_set_sort_order(pref, LOCATION_POI_PREF_SO_ASC);
 862
 863         ret = location_search_poi_by_address (loc, filter, addr, pref, poi_cb, loc, &req_id);
 864         if (ret != LOCATION_ERROR_NONE) {
 865                 g_debug("Fail to get poi. Error[%d]", ret);
 866         }
 867
 868         location_poi_filter_free(filter);
 869         location_poi_pref_free(pref);
 870         location_address_free (addr);
 871 }
 872  * @endcode
 873  */
 874 int location_search_poi_by_address (LocationObject *obj, const LocationPOIFilter * filter, const LocationAddress * addr, const LocationPOIPreference * pref, LocationPOICB cb, gpointer user_data, guint * req_id);
 875
 876 /**
 877  * @brief Request a search service with area filter from service provider.
 878  * @remarks refer #LocationLandmark
 879  * @pre #location_init should be called before.\n
 880  *      #location_poi_pref_new should be set before.
 881  * @post None.
 882  * @param [in] obj - a #LocationObject created by #location_new
 883  * @param [in] filter - a #LocaitonPOIFilter created by #location_poi_filter_new
 884  * @param [in] address - a freeformed address
 885  * @param [in] pref - a #LocationPOIPreference created by #location_poi_pref_new
 886  * @param [in] cb - #LocationPOICB
 887  * @param [in] user_data - data to pass to function
 888  * @param [out] req_id - a guint
 889  * @return int
 890  * @retval 0                              Success
 891  * Please refer #LocationError for more information.
 892  * @par Example
 893  * @code
 894 #include <location.h>
 895 #include <location-map-service.h>
 896
 897 static GMainLoop *loop = NULL;
 898
 899 void PrintLandmarkCb (gpointer data, gpointer user_data)
 900 {
 901         g_return_if_fail (data);
 902
 903         LocationLandmark *landmark = (LocationLandmark *)data;
 904
 905         g_debug ("id[%d], Priority[%d], Name:[%s], Author[%s], Phone[%s], Category[%s]\n", location_landmark_get_id (landmark),
 906                                   location_landmark_get_priority(landmark),
 907                                   location_landmark_get_name(landmark),
 908                                   location_landmark_get_author(landmark),
 909                                   location_landmark_get_phone_number(landmark),
 910                                   location_landmark_get_category(landmark));
 911 }
 912
 913 static void poi_cb(LocationError error, guint req_id, GList * landmark_list, gchar * error_code, gchar * error_msg, gpointer userdata)
 914 {
 915         if (error != LOCATION_ERROR_NONE || landmark_list == NULL) {
 916                 g_debug ("Fail to get poi. Error[%d], ErrCode[%s], ErrMsg[%s]", error, error_code, error_msg);
 917                 return;
 918         }
 919         g_list_foreach (landmark_list, PrintLandmarkCb, NULL);
 920 }
 921
 922 void search_poi(LocationObject* loc)
 923 {
 924         int ret = 0;
 925         guint req_id = 0;
 926
 927         gchar *addr = g_strdup("4 N 2nd Street 95113");
 928         LocationPOIFilter *filter = location_poi_filter_new();
 929         LocationPOIPreference *pref = location_poi_pref_new();
 930
 931         location_poi_filter_set(filter, "CATEGORY", "restaurant");
 932
 933         location_poi_pref_set_max_result(pref, 5);
 934         location_poi_pref_set_sort_by(pref, "name");
 935         location_poi_pref_set_sort_order(pref, LOCATION_POI_PREF_SO_ASC);
 936
 937         ret = location_search_poi_by_freeformed_address (loc, filter, addr, pref, poi_cb, loc, &req_id);
 938         if (ret != LOCATION_ERROR_NONE) {
 939                 g_debug("Fail to get poi. Error[%d]", ret);
 940         }
 941
 942         location_poi_filter_free(filter);
 943         location_poi_pref_free(pref);
 944         g_free (addr);
 945 }
 946  * @endcode
 947  */
 948 int location_search_poi_by_freeformed_address (LocationObject *obj, const LocationPOIFilter * filter, const gchar * address, const LocationPOIPreference * pref, LocationPOICB cb, gpointer user_data, guint * req_id);
 949
 950 /**
 951  * @brief Cancel the previous poi search.
 952  * @remarks refer #LocationLandmark
 953  * @pre #location_search_poi should be called before.
 954  * @post None.
 955  * @param [in] obj - a #LocationObject created by #location_new
 956  * @param [in] req_id - a poi request id returned by location_search_poi
 957  * @return int
 958  * @retval 0                              Success
 959  * Please refer #LocationError for more information.
 960  * @par Example
 961  * @code
 962 #include <location.h>
 963 #include <location-map-service.h>
 964
 965 static GMainLoop *loop = NULL;
 966
 967 void PrintLandmarkCb (gpointer data, gpointer user_data)
 968 {
 969         g_return_if_fail (data);
 970
 971         LocationLandmark *landmark = (LocationLandmark *)data;
 972
 973         g_debug ("id[%d], Priority[%d], Name:[%s], Author[%s], Phone[%s], Category[%s]\n", location_landmark_get_id (landmark),
 974                                   location_landmark_get_priority(landmark),
 975                                   location_landmark_get_name(landmark),
 976                                   location_landmark_get_author(landmark),
 977                                   location_landmark_get_phone_number(landmark),
 978                                   location_landmark_get_category(landmark));
 979 }
 980
 981 static void poi_cb(LocationError error, guint req_id, GList * landmark_list, gchar * error_code, gchar * error_msg, gpointer userdata)
 982 {
 983         if (error != LOCATION_ERROR_NONE || landmark_list == NULL) {
 984                 g_debug ("Fail to get poi. Error[%d], ErrCode[%s], ErrMsg[%s]", error, error_code, error_msg);
 985                 return;
 986         }
 987         g_list_foreach (landmark_list, PrintLandmarkCb, NULL);
 988 }
 989
 990 void search_poi(LocationObject* loc)
 991 {
 992         int ret = 0;
 993         guint req_id = 0;
 994
 995         gchar *addr = g_strdup("4 N 2nd Street 95113");
 996         LocationPOIFilter *filter = location_poi_filter_new();
 997         LocationPOIPreference *pref = location_poi_pref_new();
 998
 999         location_poi_filter_set(filter, "CATEGORY", "restaurant");
1000
1001         location_poi_pref_set_max_result(pref, 5);
1002         location_poi_pref_set_sort_by(pref, "name");
1003         location_poi_pref_set_sort_order(pref, LOCATION_POI_PREF_SO_ASC);
1004
1005         ret = location_search_poi (loc, filter, addr, pref, poi_cb, loc, &req_id);
1006         if (ret != LOCATION_ERROR_NONE) {
1007                 g_debug("Fail to get poi. Error[%d]", ret);
1008         }
1009
1010         ret = location_cancel_poi_request (loc, req_id);
1011         if (ret != LOCATION_ERROR_NONE) {
1012                 g_debug("Fail to cancel poi request. Err[%d]", ret);
1013         }
1014
1015         location_poi_filter_free(filter);
1016         location_poi_pref_free(pref);
1017         g_free (addr);
1018 }
1019  * @endcode
1020  */
1021 int location_cancel_poi_request (LocationObject *obj, guint req_id);
1022
1023 /**
1024  * @brief Request a route service from service provider.
1025  * @remarks refer #LocationRoute, #LocationRouteSegment and #LocationRouteStep
1026  * @pre #location_new should be called before.
1027  * @post None.
1028  * @param [in] obj - a #LocationObject created by #location_new
1029  * @param [in] origin - a #LocationPosition
1030  * @param [in] destination - a #LocationPosition
1031  * @param [in] waypoint - a list of #LocationPosition
1032  * const LocationRoutePreference * pref, LocationRouteCB cb, gpointer user_data, guint * req_id);
1033  * @param [in] pref - a #LocationRoutePreference created by #location_route_pref_new
1034  * @param [in] cb - a #LocationRouteCB
1035  * @param [in] user_data - a gpointer
1036  * @param [out] req_id - a guint
1037  * @return int
1038  * @retval 0                              Success
1039  * Please refer #LocationError for more information.
1040  * @par Example
1041  * @code
1042 #include <location.h>
1043 #include <location-map-service.h>
1044
1045 static void free_waypoint (gpointer data)
1046 {
1047         LocationPosition *pos = (LocationPosition *)data;
1048
1049         if (pos) location_position_free(pos);
1050 }
1051
1052 static void __print_route_step (gpointer data, gpointer user_data)
1053 {
1054         g_printf("+++Step begin\n");
1055         LocationRouteStep *step = (LocationRouteStep *)data;
1056
1057         const LocationPosition *start = location_route_step_get_start_point(step);
1058         gdouble start_lat = 0;
1059         gdouble start_lon = 0;
1060         if (start) {
1061                 start_lat = start->latitude;
1062                 start_lon = start->longitude;
1063         } else {
1064                 g_printf("Step start position NULL\n");
1065         }
1066         const LocationPosition *end = location_route_step_get_end_point(step);
1067         gdouble end_lat = 0;
1068         gdouble end_lon = 0;
1069         if (end) {
1070                 end_lat = end->latitude;
1071                 end_lon = end->longitude;
1072         } else {
1073                 g_printf("Step end postion NULL\n");
1074         }
1075         const gchar *inst = location_route_step_get_instruction(step);
1076
1077         g_printf("Step: start(%f/%f), end(%f/%f), instruction(%s)\n", start_lat, start_lon, end_lat, end_lon, inst);
1078
1079         g_printf("---Step end\n");
1080 }
1081
1082 static void print_route_segment (gpointer data, gpointer user_data)
1083 {
1084         g_printf("++Segment begin\n");
1085         LocationRouteSegment *seg = (LocationRouteSegment *)data;
1086         gdouble seg_dist = location_route_segment_get_distance(seg);
1087         glong seg_duration = location_route_segment_get_duration(seg);
1088         const LocationPosition *start = location_route_segment_get_start_point(seg);
1089         gdouble start_lat = 0;
1090         gdouble start_lon = 0;
1091         if (start) {
1092                 start_lat = start->latitude;
1093                 start_lon = start->longitude;
1094         } else {
1095                 g_printf("Segment start postion NULL\n");
1096         }
1097         const LocationPosition *end = location_route_segment_get_end_point(seg);
1098         gdouble end_lat = 0;
1099         gdouble end_lon = 0;
1100         if (end) {
1101                 end_lat = end->latitude;
1102                 end_lon = end->longitude;
1103         } else {
1104                 g_printf("Segment end postion NULL\n");
1105         }
1106         g_printf("Segment info: Distance[%f], Duration[%ld], start(%f/%f), end(%f/%f)\n", seg_dist, seg_duration,
1107                         start_lat, start_lon, end_lat, end_lon);
1108
1109         GList *step_list = location_route_segment_get_route_step(seg);
1110         GList *tmp_list = (GList *)step_list;
1111         if (tmp_list) {
1112                 g_list_foreach(tmp_list, print_route_step, NULL);
1113         }
1114         g_printf("--Segment end\n");
1115 }
1116
1117
1118 static void print_route_list (gpointer data, gpointer user_data)
1119 {
1120         g_printf("+Route begin\n");
1121         LocationRoute *route = (LocationRoute *)data;
1122
1123         const LocationPosition *start = location_route_get_origin(route);
1124         gdouble start_lat = 0;
1125         gdouble start_lon = 0;
1126         if (start) {
1127                 start_lat = start->latitude;
1128                 start_lon = start->longitude;
1129         } else {
1130                 g_printf("Route start position NULL\n");
1131         }
1132         const LocationPosition *end = location_route_get_destination(route);
1133         gdouble end_lat = 0;
1134         gdouble end_lon = 0;
1135         if (end) {
1136                 end_lat = end->latitude;
1137                 end_lon = end->longitude;
1138         } else {
1139                 g_printf("Route end position NULL\n");
1140         }
1141         g_printf("Route: start(%f/%f), end(%f/%f)\n", start_lat, start_lon, end_lat, end_lon);
1142
1143         gdouble distance = location_route_get_total_distance(route);
1144         const gchar *dis_unit = location_route_get_distance_unit(route);
1145         glong duration = location_route_get_total_duration(route);
1146         const LocationBoundary *bound = location_route_get_bounding_box(route);
1147         if (bound && bound->type == LOCATION_BOUNDARY_RECT) {
1148                 g_printf("RECT left top[%f-%f], right bottom[%f-%f]\n", bound->rect.left_top->latitude, bound->rect.left_top->longitude,
1149                         bound->rect.right_bottom->latitude, bound->rect.right_bottom->longitude);
1150         } else {
1151                 g_printf("route boundary not exist, or not RECT\n");
1152         }
1153         g_printf ("Distance[%f], Distance unit[%s], Duration[%ld]\n", distance, dis_unit, duration);
1154
1155         GList *seg_list = location_route_get_route_segment(route);
1156         if (seg_list) {
1157                 g_list_foreach(seg_list, print_route_segment, NULL);
1158         }
1159
1160         g_printf("-Route end\n");
1161 }
1162
1163 static void cb_route(LocationError error, guint req_id, GList * route_list, gchar * error_code, gchar * error_msg, gpointer userdata)
1164 {
1165         if (error != LOCATION_ERROR_NONE) {
1166                 g_printf("Failed :%d\n", error);
1167                 return;
1168         }
1169
1170         g_printf("Success, poi_list[0x%x] user_data[0x%x] req_id[%d]\n", (unsigned int)route_list, (unsigned int)userdata, req_id);
1171         g_list_foreach (route_list, print_route_list, NULL);
1172
1173         if (error_code && error_msg) {
1174                 g_printf("cb_route: error_code[%s], error_msg[%s]\n", error_code, error_msg);
1175         }
1176 }
1177
1178 int request_route(LocationObject *loc)
1179 {
1180         int ret = 0;
1181         LocationPosition *origin = location_position_new(0, 37.564263, 126.974676, 0, LOCATION_STATUS_2D_FIX);  // Seoul city hall
1182         LocationPosition *destination = location_position_new(0, 37.557120, 126.992410, 0, LOCATION_STATUS_2D_FIX);     // NamSan
1183
1184         GList *waypoint = NULL;
1185         LocationPosition *via_pos = location_position_new(0, 37.560950, 126.986240, 0, LOCATION_STATUS_2D_FIX); // Wangsimli
1186         waypoint = g_list_append (waypoint, (gpointer)via_pos);
1187
1188         LocationRoutePreference *pref = location_route_pref_new();
1189         gchar *type = g_strdup("FASTEST");
1190         location_route_pref_set_route_type(pref, type);
1191
1192         ret = location_request_route(loc, origin, destination, waypoint, pref, cb_route, NULL, &req_id);
1193         if (ret != LOCATION_ERROR_NONE) {
1194                         g_printf("Fail to search route by address. Error[%d]\n", ret);
1195         } else {
1196                         g_printf("Search Route successfully, req_id %d\n", req_id);
1197         }
1198
1199         g_free(type);
1200         g_list_free_full (waypoint, free_waypoint);
1201         location_position_free(origin);
1202         location_position_free(destination);
1203         location_route_pref_free(pref);
1204
1205         return ret;
1206  }
1207  * @endcode
1208  */
1209 int location_request_route (LocationObject *obj, LocationPosition *origin, LocationPosition *destination, GList *waypoint, const LocationRoutePreference * pref, LocationRouteCB cb, gpointer user_data, guint * req_id);
1210
1211 /**
1212  * @brief Cancel the previous route request.
1213  * @remarks None
1214  * @pre #location_request_route should be called before.
1215  * @post None.
1216  * @param [in] obj - a #LocationObject created by #location_new
1217  * @param [in] req_id - a route request id returned by location_search_route
1218  * @return int
1219  * @retval 0                              Success
1220  * Please refer #LocationError for more information.
1221  * @par Example
1222  * @code
1223 #include <location.h>
1224 #include <location-map-service.h>
1225
1226 int cancel_route_request (LocationObject *loc, guint req_id)
1227 {
1228         g_printf("cancel_route_request\n");
1229
1230         int ret = LOCATION_ERROR_NONE;
1231
1232         ret = location_cancel_route_request(loc, req_id);
1233         if (ret != LOCATION_ERROR_NONE) {
1234                 g_printf("Fail to cancel route request. Error[%d]\n", ret);
1235         }
1236         else {
1237                 g_printf("location_cancel_route_request, req_id %d\n", req_id);
1238         }
1239 }
1240  * @endcode
1241  */
1242 int location_cancel_route_request (LocationObject *obj, guint req_id);
1243
1244 /**
1245  * @brief Check wheither a map service is available on a service provider
1246  * @remarks None
1247  * @pre #location_new should be called before.
1248  * @post None.
1249  * @param [in] obj - a #LocationObject created by #location_new
1250  * @param [in] type - a #LocationMapService
1251  * @return gboolean
1252  * @retval TRUE if supported
1253  * @par Example
1254  * @code
1255 #include <location.h>
1256 #include <location-map-service.h>
1257
1258 int check_map_service (LocationObject *loc)
1259 {
1260         g_printf("check_map_service\n");
1261
1262         gboolean is_supported = FALSE;
1263
1264         is_supported = location_is_supported_map_provider_capability(loc, MAP_SERVICE_ROUTE_REQUEST_FEATURE_TO_AVOID);
1265         if (is_supported == TRUE) {
1266                 g_printf("Map Service(MAP_SERVICE_ROUTE_REQUEST_FEATURE_TO_AVOID) is supported.\n");
1267         }
1268         else {
1269                 g_printf("Map Service(MAP_SERVICE_ROUTE_REQUEST_FEATURE_TO_AVOID) is not supported.\n");
1270         }
1271 }
1272  * @endcode
1273  */
1274 gboolean location_is_supported_map_provider_capability (LocationObject *obj, LocationMapServiceType type);
1275
1276 /**
1277  * @brief Get Map service key on a service provider
1278  * @remarks None
1279  * @pre #location_new should be called before.
1280  * @post None.
1281  * @param [in] obj - a #LocationObject created by #location_new
1282  * @param [in] type - a #LocationMapService
1283  * @return GList
1284  * @retval a list of keys
1285  * @par Example
1286  * @code
1287 #include <location.h>
1288 #include <location-map-service.h>
1289
1290 static void _print_keys(gpointer data)
1291 {
1292         g_return_if_fail(data);
1293         gchar *key = (gchar *)data;
1294
1295         g_printf("Key[%s] is available now\n", key);
1296 }
1297
1298 int get_map_service_key (LocationObject *loc)
1299 {
1300         g_printf("check_map_service\n");
1301
1302         GList *keys = NULL;
1303
1304         keys = location_get_map_provider_capability_key(loc, MAP_SERVICE_ROUTE_REQUEST_FEATURE_TO_AVOID);
1305         if (keys) {
1306                 g_list_foreach (keys, _print_keys, NULL);
1307                 g_list_free_full (keys, g_free);
1308         }
1309         else {
1310                 g_printf("Map Service(MAP_SERVICE_ROUTE_REQUEST_FEATURE_TO_AVOID) doesnot have keys. Need to check wheither its service is supported.\n");
1311         }
1312 }
1313  * @endcode
1314  */
1315 int location_get_map_provider_capability_key (LocationObject *obj, LocationMapServiceType type, GList **key);
1316
1317 /**
1318  * @brief Get Map service Preference on a service provider
1319  * @remarks None
1320  * @pre #location_new should be called before.
1321  * @post None.
1322  * @param [in] obj - a #LocationObject created by #location_new
1323  * @return #LocationPreference
1324  * @retval a preference
1325  * @par Example
1326  * @code
1327 #include <location.h>
1328 #include <location-map-service.h>
1329         int get_map_service_pref (LocationObject loc)
1330         {
1331                 if (!loc) return -1;
1332
1333                 LocationPreference *svc_pref = location_get_map_service_pref (loc);
1334                 if (!svc_pref) return -1;
1335
1336                 gchar *name = location_pref_get_provider_name (svc_pref);
1337                 gchar *unit = location_pref_get_distance_unit (svc_pref);
1338                 gchar *language = location_pref_get_language (svc_pref);
1339
1340                 g_printf("provider [%s]: distance unit [%s], languange [%s]\n", name, unit, language);
1341
1342                 return 0;
1343         }
1344
1345  * @endcode
1346  */
1347 LocationPreference *location_get_map_service_pref (LocationObject *obj);
1348
1349 /**
1350  * @brief Set Map service preference on a service provider
1351  * @remarks None
1352  * @pre #location_new should be called before.
1353  * @post None.
1354  * @param [in] obj - a #LocationObject created by #location_new
1355  * @param [in] pref = a #LocationPreference
1356  * @return gboolean
1357  * @retval TRUE if success
1358  * @par Example
1359  * @code
1360 #include <location.h>
1361 #include <location-map-service.h>
1362
1363 int set_map_service_pref (LocationObject *loc)
1364 {
1365         if (!loc) return -1;
1366
1367         LocationPreference *svc_pref = location_pref_new();
1368         location_pref_set_language (svc_pref, "en");
1369         location_pref_set_distance_unit (svc_pref, "MI");
1370
1371         gboolean ret = location_set_map_service_pref (loc, svc_pref);
1372         if (!ret) {
1373                 location_pref_pref (svc_pref);
1374                 return -1;
1375         }
1376         location_pref_pref (svc_pref);
1377         return 0;
1378 }
1379  * @endcode
1380  */
1381 gboolean location_set_map_service_pref (LocationObject *obj, LocationPreference *pref);
1382
1383 /**
1384  * @} @}
1385  */
1386
1387 G_END_DECLS
1388
1389 #endif /* __LOCATION_MAP_SERVICE_H__ */