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 The sticker consumer handle.
  39  * @since_tizen 5.5
  40  */
  41 typedef struct sticker_consumer_s *sticker_consumer_h;
  42
  43 /**
  44  * @brief Called to retrieve all sticker data in the sticker database.
  45  * @details The sticker_consumer_data_foreach_all(), sticker_consumer_data_foreach_by_keyword(), sticker_consumer_data_foreach_by_group(),
  46  *          sticker_consumer_data_foreach_by_type() must be called to invoke this callback function, synchronously.
  47  * @since_tizen 5.5
  48  * @remarks @a data_handle should not be freed and can be used only in the callback.
  49  *          If you want to use it outside of the callback, you need to use a clone which can be obtained sticker_data_clone().
  50  * @param[in] data_handle The sticker data handle
  51  * @param[in] user_data The user data passed from the foreach function
  52  * @pre sticker_consumer_data_foreach_all() will invoke this callback.
  53  * @pre sticker_consumer_data_foreach_by_keyword() will invoke this callback.
  54  * @pre sticker_consumer_data_foreach_by_group() will invoke this callback.
  55  * @pre sticker_consumer_data_foreach_by_type() will invoke this callback.
  56  * @see sticker_consumer_data_foreach_all()
  57  * @see sticker_consumer_data_foreach_by_keyword()
  58  * @see sticker_consumer_data_foreach_by_group()
  59  * @see sticker_consumer_data_foreach_by_type()
  60  */
  61 typedef void (*sticker_consumer_data_foreach_cb)(sticker_data_h data_handle, void *user_data);
  62
  63 /**
  64  * @brief Called to retrieve all group names in the sticker database.
  65  * @details The sticker_consumer_group_list_foreach_all() must be called to invoke this callback function, synchronously.
  66  * @since_tizen 5.5
  67  * @remarks @a group should not be freed and can be used only in the callback.
  68  * @param[in] group The group name of the sticker
  69  * @param[in] user_data The user data passed from the foreach function
  70  * @pre sticker_consumer_group_list_foreach_all() will invoke this callback.
  71  * @see sticker_consumer_group_list_foreach_all()
  72  */
  73 typedef void (*sticker_consumer_group_list_foreach_cb)(const char *group, void *user_data);
  74
  75 /**
  76  * @brief Called to retrieve all keywords in the sticker database.
  77  * @details The sticker_consumer_keyword_list_foreach_all() must be called to invoke this callback function, synchronously.
  78  * @since_tizen 5.5
  79  * @remarks @a keyword should not be freed and can be used only in the callback.
  80  * @param[in] keyword The keyword of the sticker
  81  * @param[in] user_data The user data passed from the foreach function
  82  * @pre sticker_consumer_keyword_list_foreach_all() will invoke this callback.
  83  * @see sticker_consumer_keyword_list_foreach_all()
  84  */
  85 typedef void (*sticker_consumer_keyword_list_foreach_cb)(const char *keyword, void *user_data);
  86
  87 /**
  88  * @brief Creates a sticker consumer handle.
  89  * @since_tizen 5.5
  90  * @privlevel public
  91  * @privilege %http://tizen.org/privilege/mediastorage
  92  * @remarks If the function succeeds, @a consumer_handle must be released with sticker_consumer_destroy().
  93  * @param[out] consumer_handle The sticker consumer handle
  94  * @return 0 on success, otherwise a negative error value
  95  * @retval #STICKER_ERROR_NONE Successful
  96  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
  97  * @retval #STICKER_ERROR_PERMISSION_DENIED Permission denied
  98  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
  99  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 100  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 101  * @see sticker_consumer_destroy()
 102  */
 103 int sticker_consumer_create(sticker_consumer_h *consumer_handle);
 104
 105 /**
 106  * @brief Destroys a sticker consumer handle.
 107  * @since_tizen 5.5
 108  * @param[in] consumer_handle The sticker consumer handle
 109  * @return 0 on success, otherwise a negative error value
 110  * @retval #STICKER_ERROR_NONE Successful
 111  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 112  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 113  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 114  * @see sticker_consumer_create()
 115  */
 116 int sticker_consumer_destroy(sticker_consumer_h consumer_handle);
 117
 118 /**
 119  * @brief Retrieves all sticker data in the sticker database.
 120  * @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.
 121  * @since_tizen 5.5
 122  * @remarks It is not an error if @a result is smaller than @a count.
 123  * @param[in] consumer_handle The sticker consumer handle
 124  * @param[in] offset The start position (Starting from zero)
 125  * @param[in] count The number of stickers to be retrieved with respect to the offset
 126  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 127  * @param[in] callback The callback function to invoke
 128  * @param[in] user_data The user data to be passed to the callback function
 129  * @return 0 on success, otherwise a negative error value
 130  * @retval #STICKER_ERROR_NONE Successful
 131  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 132  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 133  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 134  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 135  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 136  * @see sticker_consumer_data_foreach_cb()
 137  */
 138 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);
 139
 140 /**
 141  * @brief Retrieves all sticker data in the sticker database using keyword.
 142  * @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.
 143  * @since_tizen 5.5
 144  * @remarks It is not an error if @a result is smaller than @a count.
 145  * @param[in] consumer_handle The sticker consumer handle
 146  * @param[in] offset The start position (Starting from zero)
 147  * @param[in] count The number of stickers to be retrieved with respect to the offset
 148  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 149  * @param[in] keyword The keyword of the sticker for getting sticker data
 150  * @param[in] callback The callback function to invoke
 151  * @param[in] user_data The user data to be passed to the callback function
 152  * @return 0 on success, otherwise a negative error value
 153  * @retval #STICKER_ERROR_NONE Successful
 154  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 155  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 156  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 157  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 158  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 159  * @see sticker_consumer_data_foreach_cb()
 160  */
 161 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);
 162
 163 /**
 164  * @brief Retrieves all sticker data in the sticker database using group name.
 165  * @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.
 166  * @since_tizen 5.5
 167  * @remarks It is not an error if @a result is smaller than @a count.
 168  * @param[in] consumer_handle The sticker consumer handle
 169  * @param[in] offset The start position (Starting from zero)
 170  * @param[in] count The number of stickers to be retrieved with respect to the offset
 171  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 172  * @param[in] group The group name of the sticker for getting sticker data
 173  * @param[in] callback The callback function to invoke
 174  * @param[in] user_data The user data to be passed to the callback function
 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_OUT_OF_MEMORY Out of memory
 180  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 181  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 182  * @see sticker_consumer_data_foreach_cb()
 183  */
 184 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);
 185
 186 /**
 187  * @brief Retrieves all sticker data in the sticker database using URI type.
 188  * @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.
 189  * @since_tizen 5.5
 190  * @remarks It is not an error if @a result is smaller than @a count.
 191  * @param[in] consumer_handle The sticker consumer handle
 192  * @param[in] offset The start position (Starting from zero)
 193  * @param[in] count The number of stickers to be retrieved with respect to the offset
 194  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 195  * @param[in] type The URI type of the sticker for getting sticker data
 196  * @param[in] callback The callback function to invoke
 197  * @param[in] user_data The user data to be passed to the callback function
 198  * @return 0 on success, otherwise a negative error value
 199  * @retval #STICKER_ERROR_NONE Successful
 200  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 201  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 202  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 203  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 204  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 205  * @see sticker_consumer_data_foreach_cb()
 206  */
 207 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);
 208
 209 /**
 210  * @brief Retrieves all group name in the sticker database.
 211  * @since_tizen 5.5
 212  * @param[in] consumer_handle The sticker consumer handle
 213  * @param[in] callback The callback function to invoke
 214  * @param[in] user_data The user data to be passed to the callback function
 215  * @return 0 on success, otherwise a negative error value
 216  * @retval #STICKER_ERROR_NONE Successful
 217  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 218  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 219  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 220  * @post This function invokes sticker_consumer_group_list_foreach_cb() repeatedly for getting data.
 221  * @see sticker_consumer_group_list_foreach_cb()
 222  */
 223 int sticker_consumer_group_list_foreach_all(sticker_consumer_h consumer_handle, sticker_consumer_group_list_foreach_cb callback, void *user_data);
 224
 225 /**
 226  * @brief Retrieves all keyword in the sticker database.
 227  * @since_tizen 5.5
 228  * @param[in] consumer_handle The sticker consumer handle
 229  * @param[in] callback The callback function to invoke
 230  * @param[in] user_data The user data to be passed to the callback function
 231  * @return 0 on success, otherwise a negative error value
 232  * @retval #STICKER_ERROR_NONE Successful
 233  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 234  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 235  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 236  * @post This function invokes sticker_consumer_keyword_list_foreach_cb() repeatedly for getting data.
 237  * @see sticker_consumer_keyword_list_foreach_cb()
 238  */
 239 int sticker_consumer_keyword_list_foreach_all(sticker_consumer_h consumer_handle, sticker_consumer_keyword_list_foreach_cb callback, void *user_data);
 240
 241 /**
 242  * @brief Retrieves all sticker data in the sticker database using display type.
 243  * @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.
 244  * @since_tizen 5.5
 245  * @remarks It is not an error if @a result is smaller than @a count.
 246  * @param[in] consumer_handle The sticker consumer handle
 247  * @param[in] offset The start position (Starting from zero)
 248  * @param[in] count The number of stickers to be retrieved with respect to the offset
 249  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 250  * @param[in] type The display type of the sticker for getting sticker data
 251  * @param[in] callback The callback function to invoke
 252  * @param[in] user_data The user data to be passed to the callback function
 253  * @return 0 on success, otherwise a negative error value
 254  * @retval #STICKER_ERROR_NONE Successful
 255  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 256  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 257  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 258  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 259  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 260  * @see sticker_consumer_data_foreach_cb()
 261  */
 262 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);
 263
 264 /**
 265  * @brief Retrieves all group name in the sticker database using display type.
 266  * @since_tizen 5.5
 267  * @param[in] consumer_handle The sticker consumer handle
 268  * @param[in] type The display type of the sticker for getting sticker data
 269  * @param[in] callback The callback function to invoke
 270  * @param[in] user_data The user data to be passed to the callback function
 271  * @return 0 on success, otherwise a negative error value
 272  * @retval #STICKER_ERROR_NONE Successful
 273  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 274  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 275  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 276  * @post This function invokes sticker_consumer_group_list_foreach_cb() repeatedly for getting data.
 277  * @see sticker_consumer_group_list_foreach_cb()
 278  */
 279 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);
 280
 281 /**
 282  * @brief Add history to recently used stickers list
 283  * @since_tizen 5.5
 284  * @param[in] consumer_handle The sticker consumer handle
 285  * @param[in] data_handle The sticker data handle
 286  * @return 0 on success, otherwise a negative error value
 287  * @retval #STICKER_ERROR_NONE Successful
 288  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 289  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 290  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 291  * @see sticker_consumer_get_recent_list()
 292  */
 293 int sticker_consumer_add_recent_data(sticker_consumer_h consumer_handle, sticker_data_h data_handle);
 294
 295 /**
 296  * @brief Gets recently used stickers list.
 297  * @details The most recently used stickers are delivered in order.
 298  * @since_tizen 5.5
 299  * @remarks It is not an error if @a result is smaller than @a count.
 300  * @param[in] consumer_handle The sticker consumer handle
 301  * @param[in] count The number of stickers that you want to receive.
 302  *            If -1, the number of stickers is not restricted
 303  * @param[out] result The number of stickers received (zero indicates that no data was found)
 304  * @param[in] callback The callback function to invoke
 305  * @param[in] user_data The user data to be passed to the callback function
 306  * @return 0 on success, otherwise a negative error value
 307  * @retval #STICKER_ERROR_NONE Successful
 308  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 309  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 310  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 311  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 312  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 313  * @see sticker_consumer_data_foreach_cb()
 314  * @see sticker_consumer_add_recent_data()
 315  */
 316 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);
 317
 318 /**
 319  * @}
 320  */
 321
 322 #ifdef __cplusplus
 323 }
 324 #endif
 325
 326 #endif /* __TIZEN_UIX_STICKER_CONSUMER_H__ */