include/maps_place_plugin.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_PLUGIN_H__
  18 #define __MAPS_PLACE_PLUGIN_H__
  19
  20 #include <maps_place.h>
  21 #include <maps_extra_types.h>
  22
  23 /**
  24  * @ingroup     CAPI_MAPS_PLUGIN_MODULE
  25  * @defgroup    CAPI_MAPS_PLUGIN_PLACE_MODULE Places
  26  */
  27
  28 /**
  29  * @ingroup     CAPI_MAPS_PLUGIN_PLACE_MODULE
  30  * @defgroup    CAPI_MAPS_PLUGIN_PLACE_DATA_MODULE Place
  31  *
  32  * @file maps_place_plugin.h
  33  * @brief This file contains the functions related to Place
  34  * information, needed in plug-in development.
  35  *
  36  * @addtogroup CAPI_MAPS_PLUGIN_PLACE_DATA_MODULE
  37  * @{
  38  * @brief This provides APIs related to Place information, used in
  39  * Place Discovery and Search, needed in plug-in development.
  40  */
  41
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45
  46 /**
  47  * @brief       Creates a new place handle.
  48  * @details This function creates a new place handle and allocates all needed
  49  * resources.
  50  * @since_tizen 2.4
  51  * @remarks @a place must be released using maps_place_destroy().
  52  * \n @a place may be cloned using maps_place_clone().
  53  *
  54  * @param[in]   place           A handle of a new place on success
  55  * @return      0 on success, otherwise a negative error value
  56  * @retval      #MAPS_ERROR_NONE Successful
  57  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
  58  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
  59  *
  60  * @see maps_place_destroy()
  61  * @see maps_place_clone()
  62  */
  63 int maps_place_create(maps_place_h *place);
  64
  65 /**
  66  * @brief       Sets the place id.
  67  * @details This function sets the place id.
  68  * @since_tizen 2.4
  69  *
  70  * @param[in]   place           The handle to place
  71  * @param[in]   id              The place id
  72  * @return      0 on success, otherwise a negative error value
  73  * @retval      #MAPS_ERROR_NONE Successful
  74  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
  75  *
  76  * @pre @a place is created using maps_place_create().
  77  *
  78  * @see maps_place_create()
  79  * @see maps_place_get_related_link()
  80  */
  81 int maps_place_set_id(maps_place_h place, const char *id);
  82
  83 /**
  84  * @brief       Sets the place name.
  85  * @details This function sets the place name.
  86  * @since_tizen 2.4
  87  *
  88  * @param[in]   place           The handle to place
  89  * @param[in]   name            The place name
  90  * @return      0 on success, otherwise a negative error value
  91  * @retval      #MAPS_ERROR_NONE Successful
  92  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
  93  *
  94  * @pre @a place is created using maps_place_create().
  95  *
  96  * @see maps_place_create()
  97  * @see maps_place_get_name()
  98  */
  99 int maps_place_set_name(maps_place_h place, const char *name);
 100
 101 /**
 102  * @brief       Sets the place location.
 103  * @details This function sets the place location.
 104  * @since_tizen 2.4
 105  *
 106  * @param[in]   place           The handle to place
 107  * @param[in]   location        The place location
 108  * @return      0 on success, otherwise a negative error value
 109  * @retval      #MAPS_ERROR_NONE Successful
 110  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 111  *
 112  * @pre @a place is created using maps_place_create().
 113  *
 114  * @see maps_place_create()
 115  * @see maps_place_get_location()
 116  */
 117 int maps_place_set_location(maps_place_h place,
 118                             const maps_coordinates_h location);
 119
 120 /**
 121  * @brief       Sets the place distance from the center of the location.
 122  * @details This function sets the place distance from the center of the
 123  * location.
 124  * @since_tizen 2.4
 125  *
 126  * @param[in]   place           The handle to place
 127  * @param[in]   distance        The place distance in meters
 128  * @return      0 on success, otherwise a negative error value
 129  * @retval      #MAPS_ERROR_NONE Successful
 130  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 131  *
 132  * @pre @a place is created using maps_place_create().
 133  *
 134  * @see maps_place_create()
 135  * @see maps_place_get_distance()
 136  */
 137 int maps_place_set_distance(maps_place_h place, const int distance);
 138
 139 /**
 140  * @brief       Sets the place address.
 141  * @details This function sets the place address.
 142  * @since_tizen 2.4
 143  *
 144  * @param[in]   place           The handle to place
 145  * @param[in]   address         The place address
 146  * @return      0 on success, otherwise a negative error value
 147  * @retval      #MAPS_ERROR_NONE Successful
 148  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 149  *
 150  * @pre @a place is created using maps_place_create().
 151  *
 152  * @see maps_place_create()
 153  * @see maps_place_get_address()
 154  */
 155 int maps_place_set_address(maps_place_h place, const maps_address_h address);
 156
 157 /**
 158  * @brief       Sets the place categories.
 159  * @details This function sets the place categories.
 160  * @since_tizen 2.4
 161  *
 162  * @param[in]   place           The handle to place
 163  * @param[in]   categories      The place category list
 164  * @return      0 on success, otherwise a negative error value
 165  * @retval      #MAPS_ERROR_NONE Successful
 166  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 167  *
 168  * @pre @a place is created using maps_place_create().
 169  *
 170  * @see maps_place_create()
 171  * @see maps_place_foreach_category()
 172  */
 173 int maps_place_set_categories(maps_place_h place,
 174                                 const maps_item_list_h categories);
 175
 176 /**
 177  * @brief       Sets the place view URI.
 178  * @details This function sets the place URI.
 179  * @since_tizen 2.4
 180  *
 181  * @param[in]   place           The handle to place
 182  * @param[in]   uri             The place view uri
 183  * @return      0 on success, otherwise a negative error value
 184  * @retval      #MAPS_ERROR_NONE Successful
 185  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 186  *
 187  * @pre @a place is created using maps_place_create().
 188  *
 189  * @see maps_place_create()
 190  * @see maps_place_get_uri()
 191  */
 192 int maps_place_set_uri(maps_place_h place, const char *uri);
 193
 194 /**
 195  * @brief       Sets the place attributes.
 196  * @details This function sets the place attributes.
 197  * @since_tizen 2.4
 198  *
 199  * @param[in]   place           The handle to place
 200  * @param[in]   attributes      The place attribute list
 201  * @return      0 on success, otherwise a negative error value
 202  * @retval      #MAPS_ERROR_NONE Successful
 203  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 204  *
 205  * @pre @a place is created using maps_place_create().
 206  *
 207  * @see maps_place_create()
 208  * @see maps_place_foreach_attribute()
 209  */
 210 int maps_place_set_attributes(maps_place_h place,
 211                               const maps_item_list_h attributes);
 212
 213 /**
 214  * @brief       Sets the place contacts.
 215  * @details This function sets the place contacts.
 216  * @since_tizen 2.4
 217  *
 218  * @param[in]   place           The handle to place
 219  * @param[in]   contacts        The place contact list
 220  * @return      0 on success, otherwise a negative error value
 221  * @retval      #MAPS_ERROR_NONE Successful
 222  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 223  *
 224  * @pre @a place is created using maps_place_create().
 225  *
 226  * @see maps_place_create()
 227  * @see maps_place_foreach_contact()
 228  */
 229 int maps_place_set_contacts(maps_place_h place,
 230                             const maps_item_list_h contacts);
 231
 232 /**
 233  * @brief       Sets the place editorials.
 234  * @details This function sets the place editorials.
 235  * @since_tizen 2.4
 236  *
 237  * @param[in]   place           The handle to place
 238  * @param[in]   editorials      The place editorial list
 239  * @return      0 on success, otherwise a negative error value
 240  * @retval      #MAPS_ERROR_NONE Successful
 241  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 242  *
 243  * @pre @a place is created using maps_place_create().
 244  *
 245  * @see maps_place_create()
 246  * @see maps_place_foreach_editorial()
 247  */
 248 int maps_place_set_editorials(maps_place_h place,
 249                               const maps_item_list_h editorials);
 250
 251 /**
 252  * @brief       Sets the place images.
 253  * @details This function sets the place images.
 254  * @since_tizen 2.4
 255  *
 256  * @param[in]   place           The handle to place
 257  * @param[in]   images          The place image list
 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  * @pre @a place is created using maps_place_create().
 263  *
 264  * @see maps_place_create()
 265  * @see maps_place_foreach_image()
 266  */
 267 int maps_place_set_images(maps_place_h place, const maps_item_list_h images);
 268
 269 /**
 270  * @brief       Sets the place review.
 271  * @details This function sets the place reviews.
 272  * @since_tizen 2.4
 273  *
 274  * @param[in]   place           The handle to place
 275  * @param[in]   reviews         The place review list
 276  * @return      0 on success, otherwise a negative error value
 277  * @retval      #MAPS_ERROR_NONE Successful
 278  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 279  *
 280  * @pre @a place is created using maps_place_create().
 281  *
 282  * @see maps_place_create()
 283  * @see maps_place_foreach_review()
 284  */
 285 int maps_place_set_reviews(maps_place_h place,
 286                            const maps_item_list_h reviews);
 287
 288 /**
 289  * @brief       Sets the place properties.
 290  * @details This function sets the place properties.
 291  * @since_tizen 2.4
 292  *
 293  * @param[in]   place           The handle to place
 294  * @param[in]   properties      The place properties list
 295  * @return      0 on success, otherwise a negative error value
 296  * @retval      #MAPS_ERROR_NONE Successful
 297  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 298  *
 299  * @pre @a place is created using maps_place_create().
 300  *
 301  * @see maps_place_create()
 302  * @see maps_place_foreach_property()
 303  */
 304 int maps_place_set_properties(maps_place_h place,
 305                               const maps_item_hashtable_h properties);
 306
 307 /**
 308  * @brief       Sets the place rating.
 309  * @details This function sets the place rating.
 310  * @since_tizen 2.4
 311  *
 312  * @param[in]   place           The handle to place image
 313  * @param[in]   rating          The place rating
 314  * @return      0 on success, otherwise a negative error value
 315  * @retval      #MAPS_ERROR_NONE Successful
 316  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 317  *
 318  * @pre @a place is created using maps_place_create().
 319  *
 320  * @see maps_place_create()
 321  * @see maps_place_get_rating()
 322  */
 323 int maps_place_set_rating(maps_place_h place,
 324                           const maps_place_rating_h rating);
 325
 326 /**
 327  * @brief       Sets the place supplier link.
 328  * @details This function sets the place supplier link.
 329  * @since_tizen 2.4
 330  *
 331  * @param[in]   place           The handle to place image
 332  * @param[in]   supplier        The place supplier link
 333  * @return      0 on success, otherwise a negative error value
 334  * @retval      #MAPS_ERROR_NONE Successful
 335  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 336  *
 337  * @pre @a place is created using maps_place_create().
 338  *
 339  * @see maps_place_create()
 340  * @see maps_place_get_supplier_link()
 341  */
 342 int maps_place_set_supplier_link(maps_place_h place,
 343                                  const maps_place_link_object_h supplier);
 344
 345 /**
 346  * @brief       Sets the place related link.
 347  * @details This function sets the place related link.
 348  * @since_tizen 2.4
 349  *
 350  * @param[in]   place           The handle to place image
 351  * @param[in]   related         The place related link
 352  * @return      0 on success, otherwise a negative error value
 353  * @retval      #MAPS_ERROR_NONE Successful
 354  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 355  *
 356  * @pre @a place is created using maps_place_create().
 357  *
 358  * @see maps_place_create()
 359  * @see maps_place_get_related_link()
 360  */
 361 int maps_place_set_related_link(maps_place_h place,
 362                                 const maps_place_link_object_h related);
 363
 364 #ifdef __cplusplus
 365 }
 366 #endif
 367 /**
 368  * @}
 369  */
 370 #endif                          /* __MAPS_PLACE_PLUGIN_H__ */