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, /**< Insert event type */
44 STICKER_CONSUMER_EVENT_TYPE_DELETE, /**< Delete event type */
45 STICKER_CONSUMER_EVENT_TYPE_UPDATE, /**< Update event type */
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 unable to access file because it has been deleted.
105 * @param[in] event_type The event type of sticker
106 * @param[in] data_handle The sticker data handle
107 * @param[in] user_data The user data passed from sticker_consumer_set_event_callback()
108 * @pre The callback can be registered using sticker_consumer_set_event_callback()
109 * @see sticker_consumer_set_event_callback()
110 * @see sticker_consumer_unset_event_callback()
112 typedef void (*sticker_consumer_event_cb)(sticker_consumer_event_type_e event_type, sticker_data_h data_handle, void *user_data);
115 * @brief Creates a sticker consumer handle.
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()
130 int sticker_consumer_create(sticker_consumer_h *consumer_handle);
133 * @brief Destroys a sticker consumer handle.
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()
143 int sticker_consumer_destroy(sticker_consumer_h consumer_handle);
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.
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()
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);
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.
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()
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);
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.
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()
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);
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.
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()
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);
237 * @brief Retrieves all group name in the sticker database.
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()
250 int sticker_consumer_group_list_foreach_all(sticker_consumer_h consumer_handle, sticker_consumer_group_list_foreach_cb callback, void *user_data);
253 * @brief Retrieves all keyword in the sticker database.
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()
266 int sticker_consumer_keyword_list_foreach_all(sticker_consumer_h consumer_handle, sticker_consumer_keyword_list_foreach_cb callback, void *user_data);
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.
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()
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);
292 * @brief Retrieves all group name in the sticker database using display type.
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()
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);
309 * @brief Add history to recently used stickers list
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_list()
320 int sticker_consumer_add_recent_data(sticker_consumer_h consumer_handle, sticker_data_h data_handle);
323 * @brief Gets recently used stickers list.
324 * @details The most recently used stickers are delivered in order.
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()
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);
346 * @brief Registers a callback function to be invoked when the stickers are inserted, deleted, or updated.
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_callback()
359 int sticker_consumer_set_event_callback(sticker_consumer_h consumer_handle, sticker_consumer_event_cb callback, void *user_data);
362 * @brief Unregisters a callback function.
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_callback()
373 int sticker_consumer_unset_event_callback(sticker_consumer_h consumer_handle);
383 #endif /* __TIZEN_UIX_STICKER_CONSUMER_H__ */