2 * Copyright (c) 2018 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef __TIZEN_UIX_STICKER_CONSUMER_H__
18 #define __TIZEN_UIX_STICKER_CONSUMER_H__
20 #include <sticker_error.h>
21 #include <sticker_data.h>
28 * @file sticker_consumer.h
29 * @brief This file contains sticker consumer's APIs.
33 * @addtogroup CAPI_UIX_STICKER_CONSUMER_MODULE
38 * @brief The sticker consumer handle.
41 typedef struct sticker_consumer_s *sticker_consumer_h;
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.
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()
61 typedef void (*sticker_consumer_data_foreach_cb)(sticker_data_h data_handle, void *user_data);
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.
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()
73 typedef void (*sticker_consumer_group_list_foreach_cb)(const char *group, void *user_data);
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.
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()
85 typedef void (*sticker_consumer_keyword_list_foreach_cb)(const char *keyword, void *user_data);
88 * @brief Creates a sticker consumer handle.
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 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
101 * @see sticker_consumer_destroy()
103 int sticker_consumer_create(sticker_consumer_h *consumer_handle);
106 * @brief Destroys a sticker consumer handle.
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_INVALID_PARAMETER Invalid parameter
112 * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
113 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
114 * @see sticker_consumer_create()
116 int sticker_consumer_destroy(sticker_consumer_h consumer_handle);
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.
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_INVALID_PARAMETER Invalid parameter
132 * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
133 * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
134 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
135 * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
136 * @see sticker_consumer_data_foreach_cb()
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);
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.
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_INVALID_PARAMETER Invalid parameter
155 * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
156 * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
157 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
158 * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
159 * @see sticker_consumer_data_foreach_cb()
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);
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.
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_INVALID_PARAMETER Invalid parameter
178 * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
179 * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
180 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
181 * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
182 * @see sticker_consumer_data_foreach_cb()
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);
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.
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_INVALID_PARAMETER Invalid parameter
201 * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
202 * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
203 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
204 * @post This function invokes sticker_consumer_data_foreach_cb() repeatedly for getting data.
205 * @see sticker_consumer_data_foreach_cb()
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);
210 * @brief Retrieves all group name in the sticker database.
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_INVALID_PARAMETER Invalid parameter
218 * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
219 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
220 * @post This function invokes sticker_consumer_group_list_foreach_cb() repeatedly for getting data.
221 * @see sticker_consumer_group_list_foreach_cb()
223 int sticker_consumer_group_list_foreach_all(sticker_consumer_h consumer_handle, sticker_consumer_group_list_foreach_cb callback, void *user_data);
226 * @brief Retrieves all keyword in the sticker database.
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_INVALID_PARAMETER Invalid parameter
234 * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
235 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
236 * @post This function invokes sticker_consumer_keyword_list_foreach_cb() repeatedly for getting data.
237 * @see sticker_consumer_keyword_list_foreach_cb()
239 int sticker_consumer_keyword_list_foreach_all(sticker_consumer_h consumer_handle, sticker_consumer_keyword_list_foreach_cb callback, void *user_data);
249 #endif /* __TIZEN_UIX_STICKER_CONSUMER_H__ */