include/sticker_data.h

   1 /*
   2  * Copyright (c) 2019 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 __TIZEN_UIX_STICKER_DATA_H__
  18 #define __TIZEN_UIX_STICKER_DATA_H__
  19
  20 #include <sticker_error.h>
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /**
  27  * @file sticker_data.h
  28  * @brief This file contains sticker data APIs and related enumeration.
  29  */
  30
  31 /**
  32  * @addtogroup CAPI_UIX_STICKER_DATA_MODULE
  33  * @{
  34  */
  35
  36 /**
  37  * @brief Enumeration for sticker URI type.
  38  *
  39  * @since_tizen 5.5
  40  */
  41 typedef enum {
  42     STICKER_DATA_URI_LOCAL_PATH = 1, /**< Local path URI */
  43     STICKER_DATA_URI_WEB_RESOURCE, /**< Web resource URI */
  44 } sticker_data_uri_type_e;
  45
  46 /**
  47  * @brief Enumeration for sticker display type.
  48  *
  49  * @since_tizen 5.5
  50  */
  51 typedef enum {
  52     STICKER_DATA_DISP_EMOJI = 1, /**< Emoji type */
  53     /**
  54      * @brief Wallpaper type
  55      * @details The stickers of the wallpaper type are intended to be used by
  56      * a wallpaper application and usually have larger size.
  57      */
  58     STICKER_DATA_DISP_WALLPAPER,
  59 } sticker_data_display_type_e;
  60
  61 /**
  62  * @brief The sticker data handle.
  63  * @since_tizen 5.5
  64  */
  65 typedef struct sticker_data_s *sticker_data_h;
  66
  67 /**
  68  * @brief Called to retrieve the keyword of the sticker.
  69  * @details The sticker_data_foreach_keyword() must be called to invoke this callback function, synchronously.
  70  * @since_tizen 5.5
  71  * @remarks @a keyword should not be freed and can be used only in the callback.
  72  * @param[in] keyword The sticker keyword
  73  * @param[in] user_data The user data passed from the foreach function
  74  * @pre sticker_data_foreach_keyword() will invoke this callback.
  75  * @see sticker_data_foreach_keyword()
  76  */
  77 typedef void (*sticker_data_keyword_foreach_cb)(const char *keyword, void *user_data);
  78
  79 /**
  80  * @brief Creates a sticker data handle.
  81  * @since_tizen 5.5
  82  * @remarks If the function succeeds, @a data_handle must be released with sticker_data_destroy().
  83  * @param[out] data_handle The sticker data handle
  84  * @return 0 on success, otherwise a negative error value
  85  * @retval #STICKER_ERROR_NONE Successful
  86  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
  87  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
  88  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
  89  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
  90  * @see sticker_data_destroy()
  91  */
  92 int sticker_data_create(sticker_data_h *data_handle);
  93
  94 /**
  95  * @brief Destroys a sticker data handle.
  96  * @since_tizen 5.5
  97  * @param[in] data_handle The sticker data handle
  98  * @return 0 on success, otherwise a negative error value
  99  * @retval #STICKER_ERROR_NONE Successful
 100  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 101  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 102  * @see sticker_data_create()
 103  */
 104 int sticker_data_destroy(sticker_data_h data_handle);
 105
 106 /**
 107  * @brief Clones a sticker data handle.
 108  * @since_tizen 5.5
 109  * @remarks If the function succeeds, @a target_handle must be released with sticker_data_destroy().
 110  * @param[in] origin_handle The sticker data handle
 111  * @param[out] target_handle The sticker data handle to be cloned
 112  * @return 0 on success, otherwise a negative error value
 113  * @retval #STICKER_ERROR_NONE Successful
 114  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 115  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 116  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 117  * @see sticker_data_destroy()
 118  */
 119 int sticker_data_clone(sticker_data_h origin_handle, sticker_data_h *target_handle);
 120
 121 /**
 122  * @brief Gets the sticker data handle for the given URI.
 123  * @since_tizen 5.5
 124  * @remarks If the function succeeds, @a data_handle must be released with sticker_data_destroy().
 125  * @param[in] uri The URI of the sticker data handle
 126  * @param[out] data_handle The sticker data handle for the given sticker URI
 127  * @return 0 on success, otherwise a negative error value
 128  * @retval #STICKER_ERROR_NONE Successful
 129  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 130  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 131  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 132  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 133  * @retval #STICKER_ERROR_NO_SUCH_FILE A sticker with given @a uri does not exist
 134  * @see sticker_data_destroy()
 135  */
 136 int sticker_data_get_handle(const char* uri, sticker_data_h *data_handle);
 137
 138 /**
 139  * @brief Gets the name of the sticker provider application from sticker data handle.
 140  * @since_tizen 5.5
 141  * @remarks @a app_id must be released using free().
 142  * @param[in] data_handle The sticker data handle
 143  * @param[out] app_id The name of the application that provides sticker information
 144  * @return 0 on success, otherwise a negative error value
 145  * @retval #STICKER_ERROR_NONE Successful
 146  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 147  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 148  * @retval #STICKER_ERROR_NO_DATA No data available
 149  */
 150 int sticker_data_get_app_id(sticker_data_h data_handle, char **app_id);
 151
 152 /**
 153  * @brief Sets the URI and URI type of the sticker.
 154  * @details @a uri must be a relative path like '/res/smile.png' when the type of URI is local path.
 155  * @since_tizen 5.5
 156  * @remarks @a uri must have a non-null value and must be an existing file. If not, the error as invalid parameter will be returned.
 157  * @param[in] data_handle The sticker data handle
 158  * @param[in] type The URI type to be saved
 159  * @param[in] uri The URI to be saved
 160  * @return 0 on success, otherwise a negative error value
 161  * @retval #STICKER_ERROR_NONE Successful
 162  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 163  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 164  * @see sticker_data_get_uri()
 165  */
 166 int sticker_data_set_uri(sticker_data_h data_handle, sticker_data_uri_type_e type, const char *uri);
 167
 168 /**
 169  * @brief Gets the URI and URI type from sticker data handle.
 170  * @since_tizen 5.5
 171  * @remarks @a uri must be released using free().
 172  * @param[in] data_handle The sticker data handle
 173  * @param[out] type The URI type
 174  * @param[out] uri The URI
 175  * @return 0 on success, otherwise a negative error value
 176  * @retval #STICKER_ERROR_NONE Successful
 177  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 178  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 179  * @retval #STICKER_ERROR_NO_DATA No data available
 180  * @see sticker_data_set_uri()
 181  */
 182 int sticker_data_get_uri(sticker_data_h data_handle, sticker_data_uri_type_e *type, char **uri);
 183
 184 /**
 185  * @brief Retrieves all keywords of the sticker using callback function.
 186  * @since_tizen 5.5
 187  * @param[in] data_handle The sticker data handle
 188  * @param[in] callback The callback function to invoke
 189  * @param[in] user_data The user data to be passed to the callback function
 190  * @return 0 on success, otherwise a negative error value
 191  * @retval #STICKER_ERROR_NONE Successful
 192  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 193  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 194  * @retval #STICKER_ERROR_NO_DATA No data available
 195  * @post This function invokes sticker_data_keyword_foreach_cb() repeatedly for getting keywords.
 196  * @see sticker_data_keyword_foreach_cb()
 197  * @see sticker_data_add_keyword()
 198  * @see sticker_data_remove_keyword()
 199  */
 200 int sticker_data_foreach_keyword(sticker_data_h data_handle, sticker_data_keyword_foreach_cb callback, void *user_data);
 201
 202 /**
 203  * @brief Adds a keyword of the sticker to the list.
 204  * @since_tizen 5.5
 205  * @remarks @a keyword must have a non-null value and can not have duplicate value. If not, the error as invalid parameter will be returned.
 206  * @param[in] data_handle The sticker data handle
 207  * @param[in] keyword The keyword to be saved
 208  * @return 0 on success, otherwise a negative error value
 209  * @retval #STICKER_ERROR_NONE Successful
 210  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 211  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 212  * @see sticker_data_keyword_foreach_cb()
 213  * @see sticker_data_foreach_keyword()
 214  * @see sticker_data_remove_keyword()
 215  */
 216 int sticker_data_add_keyword(sticker_data_h data_handle, const char *keyword);
 217
 218 /**
 219  * @brief Removes a keyword of the sticker from the list.
 220  * @since_tizen 5.5
 221  * @remarks @a keyword must exist value in the list. If not, the error as invalid parameter will be returned.
 222  * @param[in] data_handle The sticker data handle
 223  * @param[in] keyword The keyword to be removed
 224  * @return 0 on success, otherwise a negative error value
 225  * @retval #STICKER_ERROR_NONE Successful
 226  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 227  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 228  * @see sticker_data_keyword_foreach_cb()
 229  * @see sticker_data_foreach_keyword()
 230  * @see sticker_data_add_keyword()
 231  */
 232 int sticker_data_remove_keyword(sticker_data_h data_handle, const char *keyword);
 233
 234 /**
 235  * @brief Sets the group name of the sticker.
 236  * @since_tizen 5.5
 237  * @remarks @a group must have a non-null value. If not, the error as invalid parameter will be returned.
 238  * @param[in] data_handle The sticker data handle
 239  * @param[in] group The group name to be saved
 240  * @return 0 on success, otherwise a negative error value
 241  * @retval #STICKER_ERROR_NONE Successful
 242  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 243  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 244  * @see sticker_data_get_group_name()
 245  */
 246 int sticker_data_set_group_name(sticker_data_h data_handle, const char *group);
 247
 248 /**
 249  * @brief Gets the group name from sticker data handle.
 250  * @since_tizen 5.5
 251  * @remarks @a group must be released using free().
 252  * @param[in] data_handle The sticker data handle
 253  * @param[out] group The group name
 254  * @return 0 on success, otherwise a negative error value
 255  * @retval #STICKER_ERROR_NONE Successful
 256  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 257  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 258  * @retval #STICKER_ERROR_NO_DATA No data available
 259  * @see sticker_data_set_group_name()
 260  */
 261 int sticker_data_get_group_name(sticker_data_h data_handle, char **group);
 262
 263 /**
 264  * @brief Sets the thumbnail local path of the sticker.
 265  * @details @a thumbnail must be a relative path like '/res/smile_thumbnail.png'.
 266  * @since_tizen 5.5
 267  * @remarks @a thumbnail must have a non-null value and must be an existing file. If not, the error as invalid parameter will be returned.
 268  * @param[in] data_handle The sticker data handle
 269  * @param[in] thumbnail The thumbnail path to be saved
 270  * @return 0 on success, otherwise a negative error value
 271  * @retval #STICKER_ERROR_NONE Successful
 272  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 273  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 274  * @see sticker_data_get_thumbnail()
 275  */
 276 int sticker_data_set_thumbnail(sticker_data_h data_handle, const char *thumbnail);
 277
 278 /**
 279  * @brief Gets the thumbnail local path from sticker data handle.
 280  * @details If the thumbnail is empty, the result will be an empty string.
 281  * @since_tizen 5.5
 282  * @remarks @a thumbnail must be released using free().
 283  * @param[in] data_handle The sticker data handle
 284  * @param[out] thumbnail The thumbnail path
 285  * @return 0 on success, otherwise a negative error value
 286  * @retval #STICKER_ERROR_NONE Successful
 287  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 288  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 289  * @see sticker_data_set_thumbnail()
 290  */
 291 int sticker_data_get_thumbnail(sticker_data_h data_handle, char **thumbnail);
 292
 293 /**
 294  * @brief Sets the description of the sticker.
 295  * @since_tizen 5.5
 296  * @remarks @a description must have a non-null value. If not, the error as invalid parameter will be returned.
 297  * @param[in] data_handle The sticker data handle
 298  * @param[in] description The description to be saved
 299  * @return 0 on success, otherwise a negative error value
 300  * @retval #STICKER_ERROR_NONE Successful
 301  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 302  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 303  * @see sticker_data_get_description()
 304  */
 305 int sticker_data_set_description(sticker_data_h data_handle, const char *description);
 306
 307 /**
 308  * @brief Gets the description from sticker data handle.
 309  * @details If the description is empty, the result will be an empty string.
 310  * @since_tizen 5.5
 311  * @remarks @a description must be released using free().
 312  * @param[in] data_handle The sticker data handle
 313  * @param[out] description The description of the sticker
 314  * @return 0 on success, otherwise a negative error value
 315  * @retval #STICKER_ERROR_NONE Successful
 316  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 317  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 318  * @see sticker_data_set_description()
 319  */
 320 int sticker_data_get_description(sticker_data_h data_handle, char **description);
 321
 322 /**
 323  * @brief Gets the last updated date from sticker data handle.
 324  * @details The format of @a date is YYYY-MM-DD HH:MM:SS.
 325  * @since_tizen 5.5
 326  * @remarks @a date must be released using free().
 327  * @param[in] data_handle The sticker data handle
 328  * @param[out] date The last updated date
 329  * @return 0 on success, otherwise a negative error value
 330  * @retval #STICKER_ERROR_NONE Successful
 331  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 332  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 333  * @retval #STICKER_ERROR_NO_DATA No data available
 334  */
 335 int sticker_data_get_date(sticker_data_h data_handle, char **date);
 336
 337 /**
 338  * @brief Sets the display type of the sticker.
 339  * @since_tizen 5.5
 340  * @param[in] data_handle The sticker data handle
 341  * @param[in] type The display type to be saved
 342  * @return 0 on success, otherwise a negative error value
 343  * @retval #STICKER_ERROR_NONE Successful
 344  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 345  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 346  * @see sticker_data_get_display_type()
 347  */
 348 int sticker_data_set_display_type(sticker_data_h data_handle, sticker_data_display_type_e type);
 349
 350 /**
 351  * @brief Gets the display type from sticker data handle.
 352  * @details If the display type is empty, the result will be a zero.
 353  * @since_tizen 5.5
 354  * @param[in] data_handle The sticker data handle
 355  * @param[out] type The display type of the sticker
 356  * @return 0 on success, otherwise a negative error value
 357  * @retval #STICKER_ERROR_NONE Successful
 358  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 359  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 360  * @see sticker_data_set_display_type()
 361  */
 362 int sticker_data_get_display_type(sticker_data_h data_handle, sticker_data_display_type_e *type);
 363
 364 /**
 365  * @}
 366  */
 367
 368 #ifdef __cplusplus
 369 }
 370 #endif
 371
 372 #endif /* __TIZEN_UIX_STICKER_DATA_H__ */