include/maps_place.h

   1 /*
   2  * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __MAPS_PLACE_H__
  18 #define __MAPS_PLACE_H__
  19
  20 #include <tizen_type.h>
  21 #include <maps_address.h>
  22 #include <maps_place_category.h>
  23 #include <maps_place_attribute.h>
  24 #include <maps_place_contact.h>
  25 #include <maps_place_editorial.h>
  26 #include <maps_place_link_object.h>
  27 #include <maps_place_image.h>
  28 #include <maps_place_review.h>
  29 #include <maps_place_rating.h>
  30 #include <maps_coordinates.h>
  31
  32 /**
  33  * @ingroup     CAPI_MAPS_PLACE_MODULE
  34  * @defgroup    CAPI_MAPS_PLACE_DATA_MODULE Place
  35  *
  36  * @file maps_place.h
  37  * @brief This file contains the functions related to Place information.
  38  *
  39  * @addtogroup CAPI_MAPS_PLACE_DATA_MODULE
  40  * @{
  41  * @brief This provides APIs related to Place information, used in Place
  42  * Discovery and Search.
  43  */
  44
  45 #ifdef __cplusplus
  46 extern "C" {
  47 #endif
  48
  49 /**
  50  * @brief       The Place handle
  51  * @details The handle of Place instance.
  52  * @remarks To release the handle use maps_place_destroy().
  53  * \n To clone the handle use maps_place_clone().
  54  * @since_tizen 2.4
  55  *
  56  * @see maps_place_destroy()
  57  * @see maps_place_clone()
  58  */
  59 typedef void *maps_place_h;
  60
  61 /*----------------------------------------------------------------------------*/
  62
  63 /**
  64  * @brief       Called when requesting the list of Place Properties.
  65  * @details This callback is invoked while iterating through the list of Place
  66  * Properties.
  67  * @since_tizen 2.4
  68  * @remarks @a key and @a value must be released using free() and corresponding
  69  * release method for property value correspondingly.
  70  *
  71  * @param[in]   index           The current index of property
  72  * @param[in]   total           The total amount of properties
  73  * @param[in]   key             The key of property
  74  * @param[in]   value           The value of property
  75  * @param[in]   uesr_data       The user data passed from
  76  * maps_place_foreach_property()
  77  * @return      @c true to continue with the next iteration of the loop, \n @c
  78  * false to break out of the loop
  79  *
  80  * @pre maps_place_foreach_property() will invoke this callback.
  81  *
  82  * @see maps_place_foreach_property()
  83  */
  84 typedef bool(*maps_place_properties_cb) (int index, int total, char *key,
  85                                          void *value, void *user_data);
  86
  87 /**
  88  * @brief       Called when requesting the list of Place Categories.
  89  * @details This callback is invoked while iterating through the list of Place
  90  * Categories.
  91  * @since_tizen 2.4
  92  * @remarks @a category is valid only in this function and must be released
  93  * using maps_place_category_destroy().
  94  * \n To use @a category outside this function, clone it with
  95  * maps_place_category_clone().
  96  *
  97  * @param[in]   index           The current index of category
  98  * @param[in]   total           The total amount of categories
  99  * @param[in]   category        The place category handle
 100  * @param[in]   uesr_data       The user data passed from
 101  * maps_place_foreach_category()
 102  * @return      @c true to continue with the next iteration of the loop, \n @c
 103  * false to break out of the loop
 104  *
 105  * @pre maps_place_foreach_category() will invoke this callback.
 106  *
 107  * @see maps_place_foreach_category()
 108  * @see #maps_place_category_h
 109  */
 110 typedef bool(*maps_place_categories_cb) (int index, int total,
 111                                          maps_place_category_h category,
 112                                          void *user_data);
 113
 114 /**
 115  * @brief       Called when requesting the list of Place Attributes.
 116  * @details This callback is invoked while iterating through the list of Place
 117  * Attributes.
 118  * @since_tizen 2.4
 119  * @remarks @a attribute is valid only in this function and must be released
 120  * using maps_place_attribute_destroy().
 121  * \n To use @a attribute outside this function, clone it with
 122  * maps_place_attribute_clone().
 123  *
 124  * @param[in]   index           The current index of attribute
 125  * @param[in]   total           The total amount of attributes
 126  * @param[in]   attribute       The place attribute handle
 127  * @param[in]   uesr_data       The user data passed from the
 128  * maps_place_foreach_attribute()
 129  * @return      @c true to continue with the next iteration of the loop, \n @c
 130  * false to break out of the loop
 131  *
 132  * @pre maps_place_foreach_attribute() will invoke this callback.
 133  *
 134  * @see maps_place_foreach_attribute()
 135  * @see #maps_place_attribute_h
 136  */
 137 typedef bool(*maps_place_attributes_cb) (int index, int total,
 138                                          maps_place_attribute_h attribute,
 139                                          void *user_data);
 140
 141 /**
 142  * @brief       Called when requesting the list of Place Contacts.
 143  * @details This callback is invoked while iterating through the list of Place
 144  * Contacts.
 145  * @since_tizen 2.4
 146  * @remarks @a contact is valid only in this function and must be released using
 147  * maps_place_contact_destroy().
 148  * \n To use @a contact outside this function, clone it with
 149  * maps_place_contact_clone().
 150  *
 151  * @param[in]   index           The current index of contact
 152  * @param[in]   total           The total amount of contacts
 153  * @param[in]   contact         The place contact handle
 154  * @param[in]   uesr_data       The user data passed from the
 155  * maps_place_foreach_contact()
 156  * @return      @c true to continue with the next iteration of the loop, \n @c
 157  * false to break out of the loop
 158  *
 159  * @pre maps_place_foreach_contact() will invoke this callback.
 160  *
 161  * @see maps_place_foreach_contact()
 162  * @see #maps_place_contact_h
 163  */
 164 typedef bool(*maps_place_contacts_cb) (int index, int total,
 165                                        maps_place_contact_h contact,
 166                                        void *user_data);
 167
 168 /**
 169  * @brief       Called when requesting the list of Place Editorial.
 170  * @details This callback is invoked while iterating through the list of Place
 171  * Editorials.
 172  * @since_tizen 2.4
 173  * @remarks @a editorial is valid only in this function and must be released
 174  * using maps_place_editorial_destroy().
 175  * \n To use @a editorial outside this function, clone it with
 176  * maps_place_editorial_clone().
 177  *
 178  * @param[in]   index           The current index of editorial
 179  * @param[in]   total           The total amount of editorials
 180  * @param[in]   editorial       The place editorial handle
 181  * @param[in]   uesr_data       The user data passed from the
 182  * maps_place_foreach_editorial()
 183  * @return      @c true to continue with the next iteration of the loop, \n @c
 184  * false to break out of the loop
 185  *
 186  * @pre maps_place_foreach_editorial() will invoke this callback.
 187  *
 188  * @see maps_place_foreach_editorial()
 189  * @see #maps_place_editorial_h
 190  */
 191
 192 typedef bool(*maps_place_editorials_cb) (int index, int total,
 193                                          maps_place_editorial_h editorial,
 194                                          void *user_data);
 195 /**
 196  * @brief       Called when requesting the list of Place Image.
 197  * @details This callback is invoked while iterating through the list of Place
 198  * Images.
 199  * @since_tizen 2.4
 200  * @remarks @a image is valid only in this function and must be released using
 201  * maps_place_image_destroy().
 202  * \n To use @a image outside this function, clone it with
 203  * maps_place_image_clone().
 204  *
 205  * @param[in]   index           The current index of image
 206  * @param[in]   total           The total amount of images
 207  * @param[in]   image           The place image handle
 208  * @param[in]   uesr_data       The user data passed from the
 209  * maps_place_foreach_image()
 210  * @return      @c true to continue with the next iteration of the loop, \n @c
 211  * false to break out of the loop
 212  *
 213  * @pre maps_place_foreach_image() will invoke this callback.
 214  *
 215  * @see maps_place_foreach_image()
 216  * @see #maps_place_image_h
 217  */
 218 typedef bool(*maps_place_images_cb) (int index, int total,
 219                                      maps_place_image_h image,
 220                                      void *user_data);
 221
 222 /**
 223  * @brief       Called when requesting the list of Place Review.
 224  * @details This callback is invoked while iterating through the list of Place
 225  * Reviews.
 226  * @since_tizen 2.4
 227  * @remarks @a review is valid only in this function and must be released using
 228  * maps_place_review_destroy().
 229  * \n To use @a review outside this function, clone it with
 230  * maps_place_review_clone().
 231  *
 232  * @param[in]   index           The current index of review
 233  * @param[in]   total           The total amount of reviews
 234  * @param[in]   review          The place review handle
 235  * @param[in]   uesr_data       The user data passed from the
 236  * maps_place_foreach_review()
 237  * @return      @c true to continue with the next iteration of the loop, \n @c
 238  * false to break out of the loop
 239  *
 240  * @pre maps_place_foreach_review() will invoke this callback.
 241  *
 242  * @see maps_place_foreach_review()
 243  * @see #maps_place_image_h
 244  */
 245 typedef bool(*maps_place_reviews_cb) (int index, int total,
 246                                       maps_place_review_h review,
 247                                       void *user_data);
 248
 249 /*----------------------------------------------------------------------------*/
 250
 251 /**
 252  * @brief       Destroys the place handle and releases all its resources.
 253  * @details This function destroys the place handle and releases all its
 254  * resources.
 255  * @since_tizen 2.4
 256  *
 257  * @param[in]   place           The place handle to destroy
 258  * @return      0 on success, otherwise a negative error value
 259  * @retval      #MAPS_ERROR_NONE Successful
 260  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 261  *
 262  * @see maps_place_clone()
 263  */
 264 int maps_place_destroy(maps_place_h place);
 265
 266 /**
 267  * @brief       Clones the place handle.
 268  * @details This function clones the place handle @a origin and all its
 269  * resources.
 270  * @since_tizen 2.4
 271  * @remarks @a cloned must be released using maps_place_destroy().
 272  *
 273  * @param[in]   origin  The original place handle
 274  * @param[out]  cloned  A cloned place handle
 275  * @return      0 on success, otherwise a negative error value
 276  * @retval      #MAPS_ERROR_NONE Successful
 277  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 278  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 279  *
 280  * @see maps_place_destroy()
 281  */
 282 int maps_place_clone(const maps_place_h origin, maps_place_h *cloned);
 283
 284 /*----------------------------------------------------------------------------*/
 285
 286 /**
 287  * @brief       Gets the place id.
 288  * @details This function gets the place id.
 289  * @since_tizen 2.4
 290  * @remarks @a id must be released using free().
 291  *
 292  * @param[in]   place           The place handle
 293  * @param[out]  id              The place id
 294  * @return      0 on success, otherwise a negative error value
 295  * @retval      #MAPS_ERROR_NONE Successful
 296  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 297  */
 298 int maps_place_get_id(const maps_place_h place, char **id);
 299
 300 /**
 301  * @brief       Gets the place name.
 302  * @details This function gets the place name.
 303  * @since_tizen 2.4
 304  * @remarks @a name must be released using free().
 305  *
 306  * @param[in]   place           The place handle
 307  * @param[out]  name            The place name
 308  * @return      0 on success, otherwise a negative error value
 309  * @retval      #MAPS_ERROR_NONE Successful
 310  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 311  */
 312 int maps_place_get_name(const maps_place_h place, char **name);
 313
 314 /**
 315  * @brief       Gets the place view URI.
 316  * @details This function gets the place view URI.
 317  * @since_tizen 2.4
 318  * @remarks @a uri must be released using free().
 319  *
 320  * @param[in]   place           The place handle
 321  * @param[out]  uri             The place view URI
 322  * @return      0 on success, otherwise a negative error value
 323  * @retval      #MAPS_ERROR_NONE Successful
 324  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 325  */
 326 int maps_place_get_uri(const maps_place_h place, char **uri);
 327
 328 /**
 329  * @brief       Gets the place location.
 330  * @details This function gets the place location.
 331  * @since_tizen 2.4
 332  * @remarks @a location must be released using maps_coordinates_destroy().
 333  *
 334  * @param[in]   place                   The place handle
 335  * @param[out]  location                The place location
 336  * @return      0 on success, otherwise a negative error value
 337  * @retval      #MAPS_ERROR_NONE Successful
 338  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 339  */
 340 int maps_place_get_location(const maps_place_h place,
 341                             maps_coordinates_h *location);
 342
 343 /**
 344  * @brief       Gets the place distance from the center of the location.
 345  * @details This function gets the place distance from the center of the
 346  * location.
 347  * @since_tizen 2.4
 348  *
 349  * @param[in]   place                   The place handle
 350  * @param[out]  distance                The place distance in meters
 351  * @return      0 on success, otherwise a negative error value
 352  * @retval      #MAPS_ERROR_NONE Successful
 353  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 354  */
 355 int maps_place_get_distance(const maps_place_h place, int *distance);
 356
 357 /**
 358  * @brief       Gets the place address.
 359  * @details This function gets the place address.
 360  * @since_tizen 2.4
 361  * @remarks @a address must be released using maps_address_destroy().
 362  *
 363  * @param[in]   place                   The place handle
 364  * @param[out]  address                 The place address
 365  * @return      0 on success, otherwise a negative error value
 366  * @retval      #MAPS_ERROR_NONE Successful
 367  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 368  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 369  */
 370 int maps_place_get_address(const maps_place_h place,
 371                            maps_address_h *address);
 372
 373 /**
 374  * @brief       Gets the place rating.
 375  * @details This function gets the place rating.
 376  * @since_tizen 2.4
 377  * @remarks @a rating must be released using maps_place_rating_destroy().
 378  *
 379  * @param[in]   place           The place handle
 380  * @param[out]  rating          The place rating handle
 381  * @return      0 on success, otherwise a negative error value
 382  * @retval      #MAPS_ERROR_NONE Successful
 383  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 384  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 385  */
 386 int maps_place_get_rating(const maps_place_h place,
 387                           maps_place_rating_h *rating);
 388
 389 /**
 390  * @brief       Retrieves all properties.
 391  * @details This function retrieves all place properties.
 392  * @since_tizen 2.4
 393  * @remarks The properties will be delivered via maps_place_properties_cb().
 394  *
 395  * @param[in]   place           The place handle
 396  * @param[in]   callback        The callback function to invoke
 397  * @param[in]   user_data       The user data to be passed to the callback
 398  * function
 399  * @return      0 on success, otherwise a negative error value
 400  * @retval      #MAPS_ERROR_NONE Successful
 401  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 402  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 403  *
 404  * @post This function invokes maps_place_properties_cb() repeatedly to retrieve
 405  * each property.
 406  *
 407  * @see maps_place_properties_cb()
 408  */
 409 int maps_place_foreach_property(const maps_place_h place,
 410                                 maps_place_properties_cb callback,
 411                                 void *user_data);
 412
 413 /**
 414  * @brief       Retrieves all categories
 415  * @details This function retrieves all place categories.
 416  * @since_tizen 2.4
 417  * @remarks The categories will be delivered via maps_place_categories_cb().
 418  *
 419  * @param[in]   place           The place handle
 420  * @param[in]   callback        The callback function to invoke
 421  * @param[in]   user_data       The user data to be passed to the callback
 422  * function
 423  * @return      0 on success, otherwise a negative error value
 424  * @retval      #MAPS_ERROR_NONE Successful
 425  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 426  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 427  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 428  *
 429  * @post This function invokes maps_place_categories_cb() repeatedly to retrieve
 430  * each category.
 431  *
 432  * @see maps_place_categories_cb()
 433  */
 434 int maps_place_foreach_category(const maps_place_h place,
 435                                 maps_place_categories_cb callback,
 436                                 void *user_data);
 437
 438 /**
 439  * @brief       Retrieves all attributes.
 440  * @details This function retrieves all place attributes.
 441  * @since_tizen 2.4
 442  * @remarks The attributes will be delivered via maps_place_attributes_cb().
 443  *
 444  * @param[in]   place           The place handle
 445  * @param[in]   callback        The callback function to invoke
 446  * @param[in]   user_data       The user data to be passed to the callback
 447  * function
 448  * @return      0 on success, otherwise a negative error value
 449  * @retval      #MAPS_ERROR_NONE Successful
 450  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 451  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 452  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 453  *
 454  * @post This function invokes maps_place_attributes_cb() repeatedly to retrieve
 455  * each attribute.
 456  *
 457  * @see maps_place_attributes_cb()
 458  */
 459 int maps_place_foreach_attribute(const maps_place_h place,
 460                                  maps_place_attributes_cb callback,
 461                                  void *user_data);
 462
 463 /**
 464  * @brief       Retrieves all contacts.
 465  * @details This function retrieves all place contacts.
 466  * @since_tizen 2.4
 467  * @remarks The contacts will be delivered via maps_place_contacts_cb().
 468  *
 469  * @param[in]   place           The place handle
 470  * @param[in]   callback        The callback function to invoke
 471  * @param[in]   user_data       The user data to be passed to the callback
 472  * function
 473  * @return      0 on success, otherwise a negative error value
 474  * @retval      #MAPS_ERROR_NONE Successful
 475  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 476  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 477  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 478  *
 479  * @post This function invokes maps_place_contacts_cb() repeatedly to retrieve
 480  * each contact.
 481  *
 482  * @see maps_place_contacts_cb()
 483  */
 484 int maps_place_foreach_contact(const maps_place_h place,
 485                                maps_place_contacts_cb callback,
 486                                void *user_data);
 487
 488 /**
 489  * @brief       Retrieves all editorials.
 490  * @details This function retrieves all place editorials.
 491  * @since_tizen 2.4
 492  * @remarks The editorials will be delivered via maps_place_editorials_cb().
 493  *
 494  * @param[in]   place           The place handle
 495  * @param[in]   callback        The callback function to invoke
 496  * @param[in]   user_data       The user data to be passed to the callback
 497  * function
 498  * @return      0 on success, otherwise a negative error value
 499  * @retval      #MAPS_ERROR_NONE Successful
 500  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 501  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 502  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 503  *
 504  * @post This function invokes maps_place_editorials_cb() repeatedly to retrieve
 505  * each editorial.
 506  *
 507  * @see maps_place_editorials_cb()
 508  */
 509 int maps_place_foreach_editorial(const maps_place_h place,
 510                                  maps_place_editorials_cb callback,
 511                                  void *user_data);
 512
 513 /**
 514  * @brief       Retrieves all images.
 515  * @details This function retrieves all place images.
 516  * @since_tizen 2.4
 517  * @remarks The images will be delivered via maps_place_images_cb().
 518  *
 519  * @param[in]   place           The place handle
 520  * @param[in]   callback        The callback function to invoke
 521  * @param[in]   user_data       The user data to be passed to the callback
 522  * function
 523  * @return      0 on success, otherwise a negative error value
 524  * @retval      #MAPS_ERROR_NONE Successful
 525  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 526  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 527  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 528  *
 529  * @post This function invokes maps_place_images_cb() repeatedly to retrieve
 530  * each image.
 531  *
 532  * @see maps_place_images_cb()
 533  */
 534 int maps_place_foreach_image(const maps_place_h place,
 535                              maps_place_images_cb callback, void *user_data);
 536
 537 /**
 538  * @brief       Retrieves all reviews.
 539  * @details This function retrieves all place reviews.
 540  * @since_tizen 2.4
 541  * @remarks The reviews will be delivered via maps_place_reviews_cb().
 542  *
 543  * @param[in]   place           The place handle
 544  * @param[in]   callback        The callback function to invoke
 545  * @param[in]   user_data       The user data to be passed to the callback
 546  * function
 547  * @return      0 on success, otherwise a negative error value
 548  * @retval      #MAPS_ERROR_NONE Successful
 549  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 550  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 551  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 552  *
 553  * @post This function invokes maps_place_reviews_cb() repeatedly to retrieve
 554  * each review.
 555  *
 556  * @see maps_place_reviews_cb()
 557  */
 558 int maps_place_foreach_review(const maps_place_h place,
 559                               maps_place_reviews_cb callback,
 560                               void *user_data);
 561
 562 /**
 563  * @brief       Gets the place supplier link.
 564  * @details This function gets the place supplier link.
 565  * @since_tizen 2.4
 566  * @remarks @a supplier must be released using maps_place_link_object_destroy().
 567  *
 568  * @param[in]   place                   The place handle image
 569  * @param[out]  supplier        The place supplier link
 570  * @return      0 on success, otherwise a negative error value
 571  * @retval      #MAPS_ERROR_NONE Successful
 572  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 573  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 574  */
 575 int maps_place_get_supplier_link(const maps_place_image_h place,
 576                                  maps_place_link_object_h *supplier);
 577
 578 /**
 579  * @brief       Gets the place related link.
 580  * @details This function gets the place related link.
 581  * @since_tizen 2.4
 582  * @remarks @a related must be released using maps_place_link_object_destroy().
 583  *
 584  * @param[in]   place           The place handle image
 585  * @param[out]  related The place related link
 586  * @return      0 on success, otherwise a negative error value
 587  * @retval      #MAPS_ERROR_NONE Successful
 588  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 589  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 590  */
 591 int maps_place_get_related_link(const maps_place_image_h place,
 592                                 maps_place_link_object_h *related);
 593
 594 #ifdef __cplusplus
 595 }
 596 #endif
 597 /**
 598  * @}
 599  */
 600 #endif                          /* __MAPS_PLACE_H__ */