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