include/sticker_consumer.h

   1 /*
   2  * Copyright (c) 2018 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_CONSUMER_H__
  18 #define __TIZEN_UIX_STICKER_CONSUMER_H__
  19
  20 #include <sticker_error.h>
  21 #include <sticker_data.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * @file sticker_consumer.h
  29  * @brief This file contains sticker consumer's APIs.
  30  */
  31
  32 /**
  33  * @addtogroup CAPI_UIX_STICKER_CONSUMER_MODULE
  34  * @{
  35  */
  36
  37 /**
  38  * @brief Enumeration for event type.
  39  *
  40  * @since_tizen 5.5
  41  */
  42 typedef enum {
  43     STICKER_CONSUMER_EVENT_TYPE_INSERT, /**< A sticker data has been added */
  44     STICKER_CONSUMER_EVENT_TYPE_DELETE, /**< A sticker data has been removed */
  45     STICKER_CONSUMER_EVENT_TYPE_UPDATE, /**< A sticker data has been updated */
  46 } sticker_consumer_event_type_e;
  47
  48 /**
  49  * @brief The sticker consumer handle.
  50  * @since_tizen 5.5
  51  */
  52 typedef struct sticker_consumer_s *sticker_consumer_h;
  53
  54 /**
  55  * @brief Called to retrieve all sticker data in the sticker database.
  56  * @details The sticker_consumer_data_foreach_all(), sticker_consumer_data_foreach_by_keyword(), sticker_consumer_data_foreach_by_group(),
  57  *          sticker_consumer_data_foreach_by_type() must be called to invoke this callback function, synchronously.
  58  * @since_tizen 5.5
  59  * @remarks @a data_handle should not be freed and can be used only in the callback.
  60  *          If you want to use it outside of the callback, you need to use a clone which can be obtained sticker_data_clone().
  61  * @param[in] data_handle The sticker data handle
  62  * @param[in] user_data The user data passed from the foreach function
  63  * @pre sticker_consumer_data_foreach_all() will invoke this callback.
  64  * @pre sticker_consumer_data_foreach_by_keyword() will invoke this callback.
  65  * @pre sticker_consumer_data_foreach_by_group() will invoke this callback.
  66  * @pre sticker_consumer_data_foreach_by_type() will invoke this callback.
  67  * @see sticker_consumer_data_foreach_all()
  68  * @see sticker_consumer_data_foreach_by_keyword()
  69  * @see sticker_consumer_data_foreach_by_group()
  70  * @see sticker_consumer_data_foreach_by_type()
  71  */
  72 typedef void (*sticker_consumer_data_foreach_cb)(sticker_data_h data_handle, void *user_data);
  73
  74 /**
  75  * @brief Called to retrieve all group names in the sticker database.
  76  * @details The sticker_consumer_group_list_foreach_all() must be called to invoke this callback function, synchronously.
  77  * @since_tizen 5.5
  78  * @remarks @a group should not be freed and can be used only in the callback.
  79  * @param[in] group The group name of the sticker
  80  * @param[in] user_data The user data passed from the foreach function
  81  * @pre sticker_consumer_group_list_foreach_all() will invoke this callback.
  82  * @see sticker_consumer_group_list_foreach_all()
  83  */
  84 typedef void (*sticker_consumer_group_list_foreach_cb)(const char *group, void *user_data);
  85
  86 /**
  87  * @brief Called to retrieve all keywords in the sticker database.
  88  * @details The sticker_consumer_keyword_list_foreach_all() must be called to invoke this callback function, synchronously.
  89  * @since_tizen 5.5
  90  * @remarks @a keyword should not be freed and can be used only in the callback.
  91  * @param[in] keyword The keyword of the sticker
  92  * @param[in] user_data The user data passed from the foreach function
  93  * @pre sticker_consumer_keyword_list_foreach_all() will invoke this callback.
  94  * @see sticker_consumer_keyword_list_foreach_all()
  95  */
  96 typedef void (*sticker_consumer_keyword_list_foreach_cb)(const char *keyword, void *user_data);
  97
  98 /**
  99  * @brief Called when the stickers are inserted, deleted, or updated.
 100  * @since_tizen 5.5
 101  * @remarks @a data_handle should not be freed and can be used only in the callback.
 102  *          If you want to use it outside of the callback, you need to use a clone which can be obtained sticker_data_clone().
 103  *          When the @a event_type is #STICKER_CONSUMER_EVENT_TYPE_DELETE, sticker data can be obtained using @a data_handle,
 104  *          but the files have been already deleted.
 105  * @param[in] event_type The event type
 106  * @param[in] data_handle The sticker data handle
 107  * @param[in] user_data The user data passed from sticker_consumer_set_event_cb()
 108  * @pre The callback can be registered using sticker_consumer_set_event_cb()
 109  * @see sticker_consumer_set_event_cb()
 110  * @see sticker_consumer_unset_event_cb()
 111  */
 112 typedef void (*sticker_consumer_event_cb)(sticker_consumer_event_type_e event_type, sticker_data_h data_handle, void *user_data);
 113
 114 /**
 115  * @brief Called to retrieve group images in the sticker database.
 116  * @details The sticker_consumer_group_image_list_foreach_all() must be called to invoke this callback function, synchronously.
 117  * @since_tizen 6.5
 118  * @remarks @a group and @a uri should not be freed and can be used only in the callback.
 119  * @param[in] group The group name of the stickers
 120  * @param[in] type The URI type of the sticker group image URI
 121  * @param[in] uri The URI of the sticker group image
 122  * @param[in] user_data The user data passed from the foreach function
 123  * @pre sticker_consumer_group_image_list_foreach_all() will invoke this callback.
 124  * @see sticker_consumer_group_image_list_foreach_all()
 125  */
 126 typedef void (*sticker_consumer_group_image_list_foreach_cb)(const char *group, sticker_data_uri_type_e type, const char *uri, void *user_data);
 127
 128 /**
 129  * @brief Creates a sticker consumer handle.
 130  * @since_tizen 5.5
 131  * @privlevel public
 132  * @privilege %http://tizen.org/privilege/mediastorage
 133  * @remarks If the function succeeds, @a consumer_handle must be released with sticker_consumer_destroy().
 134  * @param[out] consumer_handle The sticker consumer handle
 135  * @return 0 on success, otherwise a negative error value
 136  * @retval #STICKER_ERROR_NONE Successful
 137  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 138  * @retval #STICKER_ERROR_PERMISSION_DENIED Permission denied
 139  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 140  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 141  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 142  * @see sticker_consumer_destroy()
 143  */
 144 int sticker_consumer_create(sticker_consumer_h *consumer_handle);
 145
 146 /**
 147  * @brief Destroys a sticker consumer handle.
 148  * @since_tizen 5.5
 149  * @param[in] consumer_handle The sticker consumer handle
 150  * @return 0 on success, otherwise a negative error value
 151  * @retval #STICKER_ERROR_NONE Successful
 152  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 153  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 154  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 155  * @see sticker_consumer_create()
 156  */
 157 int sticker_consumer_destroy(sticker_consumer_h consumer_handle);
 158
 159 /**
 160  * @brief Retrieves all sticker data in the sticker database.
 161  * @details If you set the @a offset as @c 10 and @a count as @c 10, then only retrieved data from @c 10 to @c 19 will be invoked.
 162  * @since_tizen 5.5
 163  * @remarks It is not an error if @a result is smaller than @a count.
 164  * @param[in] consumer_handle The sticker consumer handle
 165  * @param[in] offset The start position (Starting from zero)
 166  * @param[in] count The number of stickers to be retrieved with respect to the offset
 167  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 168  * @param[in] callback The callback function to invoke
 169  * @param[in] user_data The user data to be passed to the callback function
 170  * @return 0 on success, otherwise a negative error value
 171  * @retval #STICKER_ERROR_NONE Successful
 172  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 173  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 174  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 175  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 176  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 177  * @see sticker_consumer_data_foreach_cb()
 178  */
 179 int sticker_consumer_data_foreach_all(sticker_consumer_h consumer_handle, int offset, int count, int *result, sticker_consumer_data_foreach_cb callback, void *user_data);
 180
 181 /**
 182  * @brief Retrieves all sticker data in the sticker database using keyword.
 183  * @details If you set the @a offset as @c 10 and @a count as @c 10, then only retrieved data from @c 10 to @c 19 will be invoked.
 184  * @since_tizen 5.5
 185  * @remarks It is not an error if @a result is smaller than @a count.
 186  * @param[in] consumer_handle The sticker consumer handle
 187  * @param[in] offset The start position (Starting from zero)
 188  * @param[in] count The number of stickers to be retrieved with respect to the offset
 189  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 190  * @param[in] keyword The keyword of the sticker for getting sticker data
 191  * @param[in] callback The callback function to invoke
 192  * @param[in] user_data The user data to be passed to the callback function
 193  * @return 0 on success, otherwise a negative error value
 194  * @retval #STICKER_ERROR_NONE Successful
 195  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 196  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 197  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 198  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 199  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 200  * @see sticker_consumer_data_foreach_cb()
 201  */
 202 int sticker_consumer_data_foreach_by_keyword(sticker_consumer_h consumer_handle, int offset, int count, int *result, const char *keyword, sticker_consumer_data_foreach_cb callback, void *user_data);
 203
 204 /**
 205  * @brief Retrieves all sticker data in the sticker database using group name.
 206  * @details If you set the @a offset as @c 10 and @a count as @c 10, then only retrieved data from @c 10 to @c 19 will be invoked.
 207  * @since_tizen 5.5
 208  * @remarks It is not an error if @a result is smaller than @a count.
 209  * @param[in] consumer_handle The sticker consumer handle
 210  * @param[in] offset The start position (Starting from zero)
 211  * @param[in] count The number of stickers to be retrieved with respect to the offset
 212  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 213  * @param[in] group The group name of the sticker for getting sticker data
 214  * @param[in] callback The callback function to invoke
 215  * @param[in] user_data The user data to be passed to the callback function
 216  * @return 0 on success, otherwise a negative error value
 217  * @retval #STICKER_ERROR_NONE Successful
 218  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 219  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 220  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 221  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 222  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 223  * @see sticker_consumer_data_foreach_cb()
 224  */
 225 int sticker_consumer_data_foreach_by_group(sticker_consumer_h consumer_handle, int offset, int count, int *result, const char *group, sticker_consumer_data_foreach_cb callback, void *user_data);
 226
 227 /**
 228  * @brief Retrieves all sticker data in the sticker database using URI type.
 229  * @details If you set the @a offset as @c 10 and @a count as @c 10, then only retrieved data from @c 10 to @c 19 will be invoked.
 230  * @since_tizen 5.5
 231  * @remarks It is not an error if @a result is smaller than @a count.
 232  * @param[in] consumer_handle The sticker consumer handle
 233  * @param[in] offset The start position (Starting from zero)
 234  * @param[in] count The number of stickers to be retrieved with respect to the offset
 235  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 236  * @param[in] type The URI type of the sticker for getting sticker data
 237  * @param[in] callback The callback function to invoke
 238  * @param[in] user_data The user data to be passed to the callback function
 239  * @return 0 on success, otherwise a negative error value
 240  * @retval #STICKER_ERROR_NONE Successful
 241  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 242  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 243  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 244  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 245  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 246  * @see sticker_consumer_data_foreach_cb()
 247  */
 248 int sticker_consumer_data_foreach_by_type(sticker_consumer_h consumer_handle, int offset, int count, int *result, sticker_data_uri_type_e type, sticker_consumer_data_foreach_cb callback, void *user_data);
 249
 250 /**
 251  * @brief Retrieves all group name in the sticker database.
 252  * @since_tizen 5.5
 253  * @param[in] consumer_handle The sticker consumer handle
 254  * @param[in] callback The callback function to invoke
 255  * @param[in] user_data The user data to be passed to the callback function
 256  * @return 0 on success, otherwise a negative error value
 257  * @retval #STICKER_ERROR_NONE Successful
 258  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 259  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 260  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 261  * @post This function invokes sticker_consumer_group_list_foreach_cb() repeatedly for getting data.
 262  * @see sticker_consumer_group_list_foreach_cb()
 263  */
 264 int sticker_consumer_group_list_foreach_all(sticker_consumer_h consumer_handle, sticker_consumer_group_list_foreach_cb callback, void *user_data);
 265
 266 /**
 267  * @brief Retrieves all keyword in the sticker database.
 268  * @since_tizen 5.5
 269  * @param[in] consumer_handle The sticker consumer handle
 270  * @param[in] callback The callback function to invoke
 271  * @param[in] user_data The user data to be passed to the callback function
 272  * @return 0 on success, otherwise a negative error value
 273  * @retval #STICKER_ERROR_NONE Successful
 274  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 275  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 276  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 277  * @post This function invokes sticker_consumer_keyword_list_foreach_cb() repeatedly for getting data.
 278  * @see sticker_consumer_keyword_list_foreach_cb()
 279  */
 280 int sticker_consumer_keyword_list_foreach_all(sticker_consumer_h consumer_handle, sticker_consumer_keyword_list_foreach_cb callback, void *user_data);
 281
 282 /**
 283  * @brief Retrieves all sticker data in the sticker database using display type.
 284  * @details If you set the @a offset as @c 10 and @a count as @c 10, then only retrieved data from @c 10 to @c 19 will be invoked.
 285  * @since_tizen 5.5
 286  * @remarks It is not an error if @a result is smaller than @a count.
 287  * @param[in] consumer_handle The sticker consumer handle
 288  * @param[in] offset The start position (Starting from zero)
 289  * @param[in] count The number of stickers to be retrieved with respect to the offset
 290  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 291  * @param[in] type The display type of the sticker for getting sticker data
 292  * @param[in] callback The callback function to invoke
 293  * @param[in] user_data The user data to be passed to the callback function
 294  * @return 0 on success, otherwise a negative error value
 295  * @retval #STICKER_ERROR_NONE Successful
 296  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 297  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 298  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 299  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 300  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 301  * @see sticker_consumer_data_foreach_cb()
 302  */
 303 int sticker_consumer_data_foreach_by_display_type(sticker_consumer_h consumer_handle, int offset, int count, int *result, sticker_data_display_type_e type, sticker_consumer_data_foreach_cb callback, void *user_data);
 304
 305 /**
 306  * @brief Retrieves all group names assigned to stickers with a matching display @a type.
 307  * @since_tizen 5.5
 308  * @param[in] consumer_handle The sticker consumer handle
 309  * @param[in] type The display type of the sticker for getting sticker data
 310  * @param[in] callback The callback function to invoke
 311  * @param[in] user_data The user data to be passed to the callback function
 312  * @return 0 on success, otherwise a negative error value
 313  * @retval #STICKER_ERROR_NONE Successful
 314  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 315  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 316  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 317  * @post This function invokes sticker_consumer_group_list_foreach_cb() repeatedly for getting data.
 318  * @see sticker_consumer_group_list_foreach_cb()
 319  */
 320 int sticker_consumer_group_list_foreach_by_display_type(sticker_consumer_h consumer_handle, sticker_data_display_type_e type, sticker_consumer_group_list_foreach_cb callback, void *user_data);
 321
 322 /**
 323  * @brief Adds entry to recently used stickers list.
 324  * @since_tizen 5.5
 325  * @param[in] consumer_handle The sticker consumer handle
 326  * @param[in] data_handle The sticker data handle
 327  * @return 0 on success, otherwise a negative error value
 328  * @retval #STICKER_ERROR_NONE Successful
 329  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 330  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 331  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 332  * @see sticker_consumer_get_recent_data_list()
 333  */
 334 int sticker_consumer_add_recent_data(sticker_consumer_h consumer_handle, sticker_data_h data_handle);
 335
 336 /**
 337  * @brief Gets recently used stickers list.
 338  * @details The most recently used stickers are delivered in order.
 339  * @since_tizen 5.5
 340  * @remarks It is not an error if @a result is smaller than @a count.
 341  * @param[in] consumer_handle The sticker consumer handle
 342  * @param[in] count The number of stickers that you want to receive.
 343  *            If -1, the number of stickers is not restricted
 344  * @param[out] result The number of stickers received (zero indicates that no data was found)
 345  * @param[in] callback The callback function to invoke
 346  * @param[in] user_data The user data to be passed to the callback function
 347  * @return 0 on success, otherwise a negative error value
 348  * @retval #STICKER_ERROR_NONE Successful
 349  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 350  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 351  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 352  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 353  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 354  * @see sticker_consumer_data_foreach_cb()
 355  * @see sticker_consumer_add_recent_data()
 356  */
 357 int sticker_consumer_get_recent_data_list(sticker_consumer_h consumer_handle, int count, int *result, sticker_consumer_data_foreach_cb callback, void *user_data);
 358
 359 /**
 360  * @brief Registers a callback function to be invoked when the stickers are inserted, deleted, or updated.
 361  * @since_tizen 5.5
 362  * @param[in] consumer_handle The sticker consumer handle
 363  * @param[in] callback The callback function to invoke
 364  * @param[in] user_data The user data to be passed to the callback function
 365  * @return 0 on success, otherwise a negative error value
 366  * @retval #STICKER_ERROR_NONE Successful
 367  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 368  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 369  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 370  * @see sticker_consumer_event_cb()
 371  * @see sticker_consumer_unset_event_cb()
 372  */
 373 int sticker_consumer_set_event_cb(sticker_consumer_h consumer_handle, sticker_consumer_event_cb callback, void *user_data);
 374
 375 /**
 376  * @brief Unregisters a callback function.
 377  * @since_tizen 5.5
 378  * @param[in] consumer_handle The sticker consumer handle
 379  * @return 0 on success, otherwise a negative error value
 380  * @retval #STICKER_ERROR_NONE Successful
 381  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 382  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 383  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 384  * @see sticker_consumer_event_cb()
 385  * @see sticker_consumer_set_event_cb()
 386  */
 387 int sticker_consumer_unset_event_cb(sticker_consumer_h consumer_handle);
 388
 389 /**
 390  * @brief Retrieves images of all sticker groups in the database.
 391  * @since_tizen 6.5
 392  * @param[in] consumer_handle The sticker consumer handle
 393  * @param[in] callback The callback function to invoke
 394  * @param[in] user_data The user data to be passed to the callback function
 395  * @return 0 on success, otherwise a negative error value
 396  * @retval #STICKER_ERROR_NONE Successful
 397  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 398  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 399  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 400  * @post This function invokes sticker_consumer_group_image_list_foreach_cb() repeatedly for getting data.
 401  * @see sticker_consumer_group_image_list_foreach_cb()
 402  */
 403 int sticker_consumer_group_image_list_foreach_all(sticker_consumer_h consumer_handle, sticker_consumer_group_image_list_foreach_cb callback, void *user_data);
 404
 405 /**
 406  * @}
 407  */
 408
 409 #ifdef __cplusplus
 410 }
 411 #endif
 412
 413 #endif /* __TIZEN_UIX_STICKER_CONSUMER_H__ */