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 Creates a sticker consumer handle.
 116  * @since_tizen 5.5
 117  * @privlevel public
 118  * @privilege %http://tizen.org/privilege/mediastorage
 119  * @remarks If the function succeeds, @a consumer_handle must be released with sticker_consumer_destroy().
 120  * @param[out] consumer_handle The sticker consumer handle
 121  * @return 0 on success, otherwise a negative error value
 122  * @retval #STICKER_ERROR_NONE Successful
 123  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 124  * @retval #STICKER_ERROR_PERMISSION_DENIED Permission denied
 125  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 126  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 127  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 128  * @see sticker_consumer_destroy()
 129  */
 130 int sticker_consumer_create(sticker_consumer_h *consumer_handle);
 131
 132 /**
 133  * @brief Destroys a sticker consumer handle.
 134  * @since_tizen 5.5
 135  * @param[in] consumer_handle The sticker consumer handle
 136  * @return 0 on success, otherwise a negative error value
 137  * @retval #STICKER_ERROR_NONE Successful
 138  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 139  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 140  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 141  * @see sticker_consumer_create()
 142  */
 143 int sticker_consumer_destroy(sticker_consumer_h consumer_handle);
 144
 145 /**
 146  * @brief Retrieves all sticker data in the sticker database.
 147  * @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.
 148  * @since_tizen 5.5
 149  * @remarks It is not an error if @a result is smaller than @a count.
 150  * @param[in] consumer_handle The sticker consumer handle
 151  * @param[in] offset The start position (Starting from zero)
 152  * @param[in] count The number of stickers to be retrieved with respect to the offset
 153  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 154  * @param[in] callback The callback function to invoke
 155  * @param[in] user_data The user data to be passed to the callback function
 156  * @return 0 on success, otherwise a negative error value
 157  * @retval #STICKER_ERROR_NONE Successful
 158  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 159  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 160  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 161  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 162  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 163  * @see sticker_consumer_data_foreach_cb()
 164  */
 165 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);
 166
 167 /**
 168  * @brief Retrieves all sticker data in the sticker database using keyword.
 169  * @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.
 170  * @since_tizen 5.5
 171  * @remarks It is not an error if @a result is smaller than @a count.
 172  * @param[in] consumer_handle The sticker consumer handle
 173  * @param[in] offset The start position (Starting from zero)
 174  * @param[in] count The number of stickers to be retrieved with respect to the offset
 175  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 176  * @param[in] keyword The keyword of the sticker for getting sticker data
 177  * @param[in] callback The callback function to invoke
 178  * @param[in] user_data The user data to be passed to the callback function
 179  * @return 0 on success, otherwise a negative error value
 180  * @retval #STICKER_ERROR_NONE Successful
 181  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 182  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 183  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 184  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 185  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 186  * @see sticker_consumer_data_foreach_cb()
 187  */
 188 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);
 189
 190 /**
 191  * @brief Retrieves all sticker data in the sticker database using group name.
 192  * @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.
 193  * @since_tizen 5.5
 194  * @remarks It is not an error if @a result is smaller than @a count.
 195  * @param[in] consumer_handle The sticker consumer handle
 196  * @param[in] offset The start position (Starting from zero)
 197  * @param[in] count The number of stickers to be retrieved with respect to the offset
 198  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 199  * @param[in] group The group name of the sticker for getting sticker data
 200  * @param[in] callback The callback function to invoke
 201  * @param[in] user_data The user data to be passed to the callback function
 202  * @return 0 on success, otherwise a negative error value
 203  * @retval #STICKER_ERROR_NONE Successful
 204  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 205  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 206  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 207  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 208  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 209  * @see sticker_consumer_data_foreach_cb()
 210  */
 211 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);
 212
 213 /**
 214  * @brief Retrieves all sticker data in the sticker database using URI type.
 215  * @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.
 216  * @since_tizen 5.5
 217  * @remarks It is not an error if @a result is smaller than @a count.
 218  * @param[in] consumer_handle The sticker consumer handle
 219  * @param[in] offset The start position (Starting from zero)
 220  * @param[in] count The number of stickers to be retrieved with respect to the offset
 221  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 222  * @param[in] type The URI type of the sticker for getting sticker data
 223  * @param[in] callback The callback function to invoke
 224  * @param[in] user_data The user data to be passed to the callback function
 225  * @return 0 on success, otherwise a negative error value
 226  * @retval #STICKER_ERROR_NONE Successful
 227  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 228  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 229  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 230  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 231  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 232  * @see sticker_consumer_data_foreach_cb()
 233  */
 234 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);
 235
 236 /**
 237  * @brief Retrieves all group name in the sticker database.
 238  * @since_tizen 5.5
 239  * @param[in] consumer_handle The sticker consumer handle
 240  * @param[in] callback The callback function to invoke
 241  * @param[in] user_data The user data to be passed to the callback function
 242  * @return 0 on success, otherwise a negative error value
 243  * @retval #STICKER_ERROR_NONE Successful
 244  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 245  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 246  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 247  * @post This function invokes sticker_consumer_group_list_foreach_cb() repeatedly for getting data.
 248  * @see sticker_consumer_group_list_foreach_cb()
 249  */
 250 int sticker_consumer_group_list_foreach_all(sticker_consumer_h consumer_handle, sticker_consumer_group_list_foreach_cb callback, void *user_data);
 251
 252 /**
 253  * @brief Retrieves all keyword in the sticker database.
 254  * @since_tizen 5.5
 255  * @param[in] consumer_handle The sticker consumer handle
 256  * @param[in] callback The callback function to invoke
 257  * @param[in] user_data The user data to be passed to the callback function
 258  * @return 0 on success, otherwise a negative error value
 259  * @retval #STICKER_ERROR_NONE Successful
 260  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 261  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 262  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 263  * @post This function invokes sticker_consumer_keyword_list_foreach_cb() repeatedly for getting data.
 264  * @see sticker_consumer_keyword_list_foreach_cb()
 265  */
 266 int sticker_consumer_keyword_list_foreach_all(sticker_consumer_h consumer_handle, sticker_consumer_keyword_list_foreach_cb callback, void *user_data);
 267
 268 /**
 269  * @brief Retrieves all sticker data in the sticker database using display type.
 270  * @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.
 271  * @since_tizen 5.5
 272  * @remarks It is not an error if @a result is smaller than @a count.
 273  * @param[in] consumer_handle The sticker consumer handle
 274  * @param[in] offset The start position (Starting from zero)
 275  * @param[in] count The number of stickers to be retrieved with respect to the offset
 276  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 277  * @param[in] type The display type of the sticker for getting sticker data
 278  * @param[in] callback The callback function to invoke
 279  * @param[in] user_data The user data to be passed to the callback function
 280  * @return 0 on success, otherwise a negative error value
 281  * @retval #STICKER_ERROR_NONE Successful
 282  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 283  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 284  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 285  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 286  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 287  * @see sticker_consumer_data_foreach_cb()
 288  */
 289 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);
 290
 291 /**
 292  * @brief Retrieves all group names assigned to stickers with a matching display @a type.
 293  * @since_tizen 5.5
 294  * @param[in] consumer_handle The sticker consumer handle
 295  * @param[in] type The display type of the sticker for getting sticker data
 296  * @param[in] callback The callback function to invoke
 297  * @param[in] user_data The user data to be passed to the callback function
 298  * @return 0 on success, otherwise a negative error value
 299  * @retval #STICKER_ERROR_NONE Successful
 300  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 301  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 302  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 303  * @post This function invokes sticker_consumer_group_list_foreach_cb() repeatedly for getting data.
 304  * @see sticker_consumer_group_list_foreach_cb()
 305  */
 306 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);
 307
 308 /**
 309  * @brief Adds entry to recently used stickers list.
 310  * @since_tizen 5.5
 311  * @param[in] consumer_handle The sticker consumer handle
 312  * @param[in] data_handle The sticker data handle
 313  * @return 0 on success, otherwise a negative error value
 314  * @retval #STICKER_ERROR_NONE Successful
 315  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 316  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 317  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 318  * @see sticker_consumer_get_recent_data_list()
 319  */
 320 int sticker_consumer_add_recent_data(sticker_consumer_h consumer_handle, sticker_data_h data_handle);
 321
 322 /**
 323  * @brief Gets recently used stickers list.
 324  * @details The most recently used stickers are delivered in order.
 325  * @since_tizen 5.5
 326  * @remarks It is not an error if @a result is smaller than @a count.
 327  * @param[in] consumer_handle The sticker consumer handle
 328  * @param[in] count The number of stickers that you want to receive.
 329  *            If -1, the number of stickers is not restricted
 330  * @param[out] result The number of stickers received (zero indicates that no data was found)
 331  * @param[in] callback The callback function to invoke
 332  * @param[in] user_data The user data to be passed to the callback function
 333  * @return 0 on success, otherwise a negative error value
 334  * @retval #STICKER_ERROR_NONE Successful
 335  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 336  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 337  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 338  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 339  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 340  * @see sticker_consumer_data_foreach_cb()
 341  * @see sticker_consumer_add_recent_data()
 342  */
 343 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);
 344
 345 /**
 346  * @brief Registers a callback function to be invoked when the stickers are inserted, deleted, or updated.
 347  * @since_tizen 5.5
 348  * @param[in] consumer_handle The sticker consumer handle
 349  * @param[in] callback The callback function to invoke
 350  * @param[in] user_data The user data to be passed to the callback function
 351  * @return 0 on success, otherwise a negative error value
 352  * @retval #STICKER_ERROR_NONE Successful
 353  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 354  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 355  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 356  * @see sticker_consumer_event_cb()
 357  * @see sticker_consumer_unset_event_cb()
 358  */
 359 int sticker_consumer_set_event_cb(sticker_consumer_h consumer_handle, sticker_consumer_event_cb callback, void *user_data);
 360
 361 /**
 362  * @brief Unregisters a callback function.
 363  * @since_tizen 5.5
 364  * @param[in] consumer_handle The sticker consumer handle
 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_set_event_cb()
 372  */
 373 int sticker_consumer_unset_event_cb(sticker_consumer_h consumer_handle);
 374
 375 /**
 376  * @}
 377  */
 378
 379 #ifdef __cplusplus
 380 }
 381 #endif
 382
 383 #endif /* __TIZEN_UIX_STICKER_CONSUMER_H__ */