include/maps_place_category.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_CATEGORY_H__
  18 #define __MAPS_PLACE_CATEGORY_H__
  19
  20 /**
  21  * @ingroup     CAPI_MAPS_PLACE_MODULE
  22  * @defgroup    CAPI_MAPS_PLACE_CATEGORY_MODULE Category
  23  *
  24  * @file maps_place_category.h
  25  * @brief This file contains the functions related to Place Category
  26  * information.
  27  *
  28  * @addtogroup CAPI_MAPS_PLACE_CATEGORY_MODULE
  29  * @{
  30  * @brief This provides APIs related to place Category information, used in
  31  * Place Discovery and Search.
  32  */
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /**
  39  * @brief       The Place Category handle
  40  * @details The handle of Place Category instance.
  41  * @remarks To release the handle use maps_place_category_destroy().
  42  * \n To clone the handle use maps_place_category_clone().
  43  * @since_tizen 2.4
  44  *
  45  * @see maps_place_category_destroy()
  46  * @see maps_place_category_clone()
  47  */
  48 typedef void *maps_place_category_h;
  49
  50 /*----------------------------------------------------------------------------*/
  51
  52 /**
  53  * @brief       Creates a new place category handle.
  54  * @details This function creates a new place category handle and allocates all
  55  * needed resources.
  56  * @since_tizen 2.4
  57  * @remarks @a category must be released using maps_place_category_destroy().
  58  * \n @a category may be cloned using maps_place_category_clone().
  59  *
  60  * @param[out]  category        A handle of a new place category on success
  61  * @return      0 on success, otherwise a negative error value
  62  * @retval      #MAPS_ERROR_NONE Successful
  63  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
  64  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
  65  *
  66  * @see maps_place_category_destroy()
  67  * @see maps_place_category_clone()
  68  */
  69 int maps_place_category_create(maps_place_category_h *category);
  70
  71
  72 /**
  73  * @brief       Clones the place category handle.
  74  * @details This function clones the place category handle @a origin and all its
  75  * resources.
  76  * @since_tizen 2.4
  77  * @remarks @a cloned must be released using maps_place_category_destroy().
  78  *
  79  * @param[in]   origin          The original place category handle
  80  * @param[out]  cloned          A cloned place category handle
  81  * @return      0 on success, otherwise a negative error value
  82  * @retval      #MAPS_ERROR_NONE Successful
  83  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
  84  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
  85  *
  86  * @see maps_place_category_destroy()
  87  */
  88 int maps_place_category_clone(const maps_place_category_h origin,
  89                               maps_place_category_h *cloned);
  90
  91
  92 /**
  93  * @brief       Destroys the place category handle and releases all its
  94  * resources.
  95  * @details This function destroys the place category handle and releases all
  96  * its resources.
  97  * @since_tizen 2.4
  98  *
  99  * @param[in]   category        The place category handle to destroy
 100  * @return      0 on success, otherwise a negative error value
 101  * @retval      #MAPS_ERROR_NONE Successful
 102  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 103  *
 104  * @see maps_place_category_clone()
 105  */
 106 int maps_place_category_destroy(maps_place_category_h category);
 107
 108
 109 /*----------------------------------------------------------------------------*/
 110
 111 /**
 112  * @brief       Sets the place category id.
 113  * @details This function sets the place category id.
 114  * @since_tizen 2.4
 115  *
 116  * @param[in]   category        The handle of place category
 117  * @param[in]   id              The place category id
 118  * @return      0 on success, otherwise a negative error value
 119  * @retval      #MAPS_ERROR_NONE Successful
 120  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 121  *
 122  * @pre @a category is created using maps_place_category_create().
 123  *
 124  * @see maps_place_category_create()
 125  * @see maps_place_category_get_id()
 126  */
 127 int maps_place_category_set_id(maps_place_category_h category,
 128                                const char *id);
 129
 130
 131 /**
 132  * @brief       Sets the place category name.
 133  * @details This function sets the place category name.
 134  * @since_tizen 2.4
 135  *
 136  * @param[in]   category        The handle of place category
 137  * @param[in]   name            The place category name
 138  * @return      0 on success, otherwise a negative error value
 139  * @retval      #MAPS_ERROR_NONE Successful
 140  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 141  *
 142  * @pre @a category is created using maps_place_category_create().
 143  *
 144  * @see maps_place_category_create()
 145  * @see maps_place_category_get_name()
 146  */
 147 int maps_place_category_set_name(maps_place_category_h category,
 148                                  const char *name);
 149
 150
 151 /**
 152  * @brief       Sets the place category URL.
 153  * @details This function sets the place category URL.
 154  * @since_tizen 2.4
 155  *
 156  * @param[in]   category        The handle of place category
 157  * @param[in]   url             The place category URL
 158  * @return      0 on success, otherwise a negative error value
 159  * @retval      #MAPS_ERROR_NONE Successful
 160  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 161  *
 162  * @pre @a category is created using maps_place_category_create().
 163  *
 164  * @see maps_place_category_create()
 165  * @see maps_place_category_get_url()
 166  */
 167 int maps_place_category_set_url(maps_place_category_h category,
 168                                 const char *url);
 169
 170
 171 /**
 172  * @brief       Gets the place category id.
 173  * @details This function gets the place category id.
 174  * @since_tizen 2.4
 175  * @remarks @a id must be released using free().
 176  *
 177  * @param[in]   category        The handle of place category
 178  * @param[out]  id              The place category id
 179  * @return      0 on success, otherwise a negative error value
 180  * @retval      #MAPS_ERROR_NONE Successful
 181  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 182  */
 183 int maps_place_category_get_id(const maps_place_category_h category,
 184                                char **id);
 185
 186 /**
 187  * @brief       Gets the place category name.
 188  * @details This function gets the place category name.
 189  * @since_tizen 2.4
 190  * @remarks @a name must be released using free().
 191  *
 192  * @param[in]   category        The handle of place category
 193  * @param[out]  name            The place category name
 194  * @return      0 on success, otherwise a negative error value
 195  * @retval      #MAPS_ERROR_NONE Successful
 196  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 197  */
 198 int maps_place_category_get_name(const maps_place_category_h category,
 199                                  char **name);
 200
 201 /**
 202  * @brief       Gets the place category URL.
 203  * @details This function gets the place category URL.
 204  * @since_tizen 2.4
 205  * @remarks @a url must be released using free().
 206  *
 207  * @param[in]   category        The handle of place category
 208  * @param[out]  url             The place category URL
 209  * @return      0 on success, otherwise a negative error value
 210  * @retval      #MAPS_ERROR_NONE Successful
 211  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 212  */
 213 int maps_place_category_get_url(const maps_place_category_h category,
 214                                 char **url);
 215
 216 #ifdef __cplusplus
 217 }
 218 #endif
 219 /**
 220  * @}
 221  */
 222 #endif                          /* __MAPS_PLACE_CATEGORY_H__ */