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_INVALID_PARAMETER Invalid parameter
  97  * @retval #STICKER_ERROR_PERMISSION_DENIED Permission denied
  98  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
  99  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 100  * @see sticker_consumer_destroy()
 101  */
 102 int sticker_consumer_create(sticker_consumer_h *consumer_handle);
 103
 104 /**
 105  * @brief Destroys a sticker consumer handle.
 106  * @since_tizen 5.5
 107  * @param[in] consumer_handle The sticker consumer handle
 108  * @return 0 on success, otherwise a negative error value
 109  * @retval #STICKER_ERROR_NONE Successful
 110  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 111  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 112  * @see sticker_consumer_create()
 113  */
 114 int sticker_consumer_destroy(sticker_consumer_h consumer_handle);
 115
 116 /**
 117  * @brief Retrieves all sticker data in the sticker database.
 118  * @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.
 119  * @since_tizen 5.5
 120  * @remarks It is not an error if @a result is smaller than @a count.
 121  * @param[in] consumer_handle The sticker consumer handle
 122  * @param[in] offset The start position (Starting from zero)
 123  * @param[in] count The number of stickers to be retrieved with respect to the offset
 124  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 125  * @param[in] callback The callback function to invoke
 126  * @param[in] user_data The user data to be passed to the callback function
 127  * @return 0 on success, otherwise a negative error value
 128  * @retval #STICKER_ERROR_NONE Successful
 129  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 130  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 131  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 132  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 133  * @see sticker_consumer_data_foreach_cb()
 134  */
 135 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);
 136
 137 /**
 138  * @brief Retrieves all sticker data in the sticker database using keyword.
 139  * @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.
 140  * @since_tizen 5.5
 141  * @remarks It is not an error if @a result is smaller than @a count.
 142  * @param[in] consumer_handle The sticker consumer handle
 143  * @param[in] offset The start position (Starting from zero)
 144  * @param[in] count The number of stickers to be retrieved with respect to the offset
 145  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 146  * @param[in] keyword The keyword of the sticker for getting sticker data
 147  * @param[in] callback The callback function to invoke
 148  * @param[in] user_data The user data to be passed to the callback function
 149  * @return 0 on success, otherwise a negative error value
 150  * @retval #STICKER_ERROR_NONE Successful
 151  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 152  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 153  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 154  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 155  * @see sticker_consumer_data_foreach_cb()
 156  */
 157 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);
 158
 159 /**
 160  * @brief Retrieves all sticker data in the sticker database using group name.
 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] group The group name of the sticker for getting sticker data
 169  * @param[in] callback The callback function to invoke
 170  * @param[in] user_data The user data to be passed to the callback function
 171  * @return 0 on success, otherwise a negative error value
 172  * @retval #STICKER_ERROR_NONE Successful
 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_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);
 180
 181 /**
 182  * @brief Retrieves all sticker data in the sticker database using URI type.
 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] type The URI type 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_INVALID_PARAMETER Invalid parameter
 196  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 197  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 198  * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
 199  * @see sticker_consumer_data_foreach_cb()
 200  */
 201 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);
 202
 203 /**
 204  * @brief Retrieves all group name in the sticker database.
 205  * @since_tizen 5.5
 206  * @param[in] consumer_handle The sticker consumer handle
 207  * @param[in] callback The callback function to invoke
 208  * @param[in] user_data The user data to be passed to the callback function
 209  * @return 0 on success, otherwise a negative error value
 210  * @retval #STICKER_ERROR_NONE Successful
 211  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 212  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 213  * @post This function invokes sticker_consumer_group_list_foreach_cb() repeatedly for getting data.
 214  * @see sticker_consumer_group_list_foreach_cb()
 215  */
 216 int sticker_consumer_group_list_foreach_all(sticker_consumer_h consumer_handle, sticker_consumer_group_list_foreach_cb callback, void *user_data);
 217
 218 /**
 219  * @brief Retrieves all keyword in the sticker database.
 220  * @since_tizen 5.5
 221  * @param[in] consumer_handle The sticker consumer handle
 222  * @param[in] callback The callback function to invoke
 223  * @param[in] user_data The user data to be passed to the callback function
 224  * @return 0 on success, otherwise a negative error value
 225  * @retval #STICKER_ERROR_NONE Successful
 226  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 227  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 228  * @post This function invokes sticker_consumer_keyword_list_foreach_cb() repeatedly for getting data.
 229  * @see sticker_consumer_keyword_list_foreach_cb()
 230  */
 231 int sticker_consumer_keyword_list_foreach_all(sticker_consumer_h consumer_handle, sticker_consumer_keyword_list_foreach_cb callback, void *user_data);
 232
 233 /**
 234  * @}
 235  */
 236
 237 #ifdef __cplusplus
 238 }
 239 #endif
 240
 241 #endif /* __TIZEN_UIX_STICKER_CONSUMER_H__ */