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 Enumeration for event type.
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;
49 * @brief The sticker consumer handle.
52 typedef struct sticker_consumer_s *sticker_consumer_h;
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.
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()
72 typedef void (*sticker_consumer_data_foreach_cb)(sticker_data_h data_handle, void *user_data);
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.
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()
84 typedef void (*sticker_consumer_group_list_foreach_cb)(const char *group, void *user_data);
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.
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()
96 typedef void (*sticker_consumer_keyword_list_foreach_cb)(const char *keyword, void *user_data);
99 * @brief Called when the stickers are inserted, deleted, or updated.
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()
112 typedef void (*sticker_consumer_event_cb)(sticker_consumer_event_type_e event_type, sticker_data_h data_handle, void *user_data);
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.
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()
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);
129 * @brief Creates a sticker consumer handle.
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()
144 int sticker_consumer_create(sticker_consumer_h *consumer_handle);
147 * @brief Destroys a sticker consumer handle.
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()
157 int sticker_consumer_destroy(sticker_consumer_h consumer_handle);
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.
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()
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);
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.
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()
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);
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.
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()
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);
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.
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()
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);
251 * @brief Retrieves all group name in the sticker database.
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()
264 int sticker_consumer_group_list_foreach_all(sticker_consumer_h consumer_handle, sticker_consumer_group_list_foreach_cb callback, void *user_data);
267 * @brief Retrieves all keyword in the sticker database.
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()
280 int sticker_consumer_keyword_list_foreach_all(sticker_consumer_h consumer_handle, sticker_consumer_keyword_list_foreach_cb callback, void *user_data);
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.
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()
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);
306 * @brief Retrieves all group names assigned to stickers with a matching display @a type.
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()
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);
323 * @brief Adds entry to recently used stickers list.
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()
334 int sticker_consumer_add_recent_data(sticker_consumer_h consumer_handle, sticker_data_h data_handle);
337 * @brief Gets recently used stickers list.
338 * @details The most recently used stickers are delivered in order.
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()
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);
360 * @brief Registers a callback function to be invoked when the stickers are inserted, deleted, or updated.
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()
373 int sticker_consumer_set_event_cb(sticker_consumer_h consumer_handle, sticker_consumer_event_cb callback, void *user_data);
376 * @brief Unregisters a callback function.
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()
387 int sticker_consumer_unset_event_cb(sticker_consumer_h consumer_handle);
390 * @brief Retrieves images of all sticker groups in the database.
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()
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);
413 #endif /* __TIZEN_UIX_STICKER_CONSUMER_H__ */