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