2 * Copyright (c) 2019 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_DATA_H__
18 #define __TIZEN_UIX_STICKER_DATA_H__
20 #include <sticker_error.h>
27 * @file sticker_data.h
28 * @brief This file contains sticker data APIs and related enumeration.
32 * @addtogroup CAPI_UIX_STICKER_DATA_MODULE
37 * @brief Enumeration for sticker URI type.
42 STICKER_DATA_URI_LOCAL_PATH = 1, /**< Local path URI */
43 STICKER_DATA_URI_WEB_RESOURCE, /**< Web resource URI */
44 } sticker_data_uri_type_e;
47 * @brief Enumeration for sticker display type.
52 STICKER_DATA_DISP_EMOJI = 1, /**< Emoji type */
54 * @brief Wallpaper type
55 * @details The stickers of the wallpaper type are intended to be used by
56 * a wallpaper application and usually have larger size.
58 STICKER_DATA_DISP_WALLPAPER,
59 } sticker_data_display_type_e;
62 * @brief The sticker data handle.
65 typedef struct sticker_data_s *sticker_data_h;
68 * @brief Called to retrieve the keyword of the sticker.
69 * @details The sticker_data_foreach_keyword() must be called to invoke this callback function, synchronously.
71 * @remarks @a keyword should not be freed and can be used only in the callback.
72 * @param[in] keyword The sticker keyword
73 * @param[in] user_data The user data passed from the foreach function
74 * @pre sticker_data_foreach_keyword() will invoke this callback.
75 * @see sticker_data_foreach_keyword()
77 typedef void (*sticker_data_keyword_foreach_cb)(const char *keyword, void *user_data);
80 * @brief Creates a sticker data handle.
82 * @remarks If the function succeeds, @a data_handle must be released with sticker_data_destroy().
83 * @param[out] data_handle The sticker data handle
84 * @return 0 on success, otherwise a negative error value
85 * @retval #STICKER_ERROR_NONE Successful
86 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
87 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
88 * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
89 * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
90 * @see sticker_data_destroy()
92 int sticker_data_create(sticker_data_h *data_handle);
95 * @brief Destroys a sticker data handle.
97 * @param[in] data_handle The sticker data handle
98 * @return 0 on success, otherwise a negative error value
99 * @retval #STICKER_ERROR_NONE Successful
100 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
101 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
102 * @see sticker_data_create()
104 int sticker_data_destroy(sticker_data_h data_handle);
107 * @brief Clones a sticker data handle.
109 * @remarks If the function succeeds, @a target_handle must be released with sticker_data_destroy().
110 * @param[in] origin_handle The sticker data handle
111 * @param[out] target_handle The sticker data handle to be cloned
112 * @return 0 on success, otherwise a negative error value
113 * @retval #STICKER_ERROR_NONE Successful
114 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
115 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
116 * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
117 * @see sticker_data_destroy()
119 int sticker_data_clone(sticker_data_h origin_handle, sticker_data_h *target_handle);
122 * @brief Gets the name of the sticker provider application from sticker data handle.
124 * @remarks @a app_id must be released using free().
125 * @param[in] data_handle The sticker data handle
126 * @param[out] app_id The name of the application that provides sticker information
127 * @return 0 on success, otherwise a negative error value
128 * @retval #STICKER_ERROR_NONE Successful
129 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
130 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
131 * @retval #STICKER_ERROR_NO_DATA No data available
133 int sticker_data_get_app_id(sticker_data_h data_handle, char **app_id);
136 * @brief Sets the URI and URI type of the sticker.
137 * @details @a uri must be a relative path like '/res/smile.png' when the type of URI is local path.
139 * @remarks @a uri must have a non-null value and must be an existing file. If not, the error as invalid parameter will be returned.
140 * @param[in] data_handle The sticker data handle
141 * @param[in] type The URI type to be saved
142 * @param[in] uri The URI to be saved
143 * @return 0 on success, otherwise a negative error value
144 * @retval #STICKER_ERROR_NONE Successful
145 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
146 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
147 * @see sticker_data_get_uri()
149 int sticker_data_set_uri(sticker_data_h data_handle, sticker_data_uri_type_e type, const char *uri);
152 * @brief Gets the URI and URI type from sticker data handle.
154 * @remarks @a uri must be released using free().
155 * @param[in] data_handle The sticker data handle
156 * @param[out] type The URI type
157 * @param[out] uri The URI
158 * @return 0 on success, otherwise a negative error value
159 * @retval #STICKER_ERROR_NONE Successful
160 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
161 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
162 * @retval #STICKER_ERROR_NO_DATA No data available
163 * @see sticker_data_set_uri()
165 int sticker_data_get_uri(sticker_data_h data_handle, sticker_data_uri_type_e *type, char **uri);
168 * @brief Retrieves all keywords of the sticker using callback function.
170 * @param[in] data_handle The sticker data handle
171 * @param[in] callback The callback function to invoke
172 * @param[in] user_data The user data to be passed to the callback function
173 * @return 0 on success, otherwise a negative error value
174 * @retval #STICKER_ERROR_NONE Successful
175 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
176 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
177 * @retval #STICKER_ERROR_NO_DATA No data available
178 * @post This function invokes sticker_data_keyword_foreach_cb() repeatedly for getting keywords.
179 * @see sticker_data_keyword_foreach_cb()
180 * @see sticker_data_add_keyword()
181 * @see sticker_data_remove_keyword()
183 int sticker_data_foreach_keyword(sticker_data_h data_handle, sticker_data_keyword_foreach_cb callback, void *user_data);
186 * @brief Adds a keyword of the sticker to the list.
188 * @remarks @a keyword must have a non-null value and can not have duplicate value. If not, the error as invalid parameter will be returned.
189 * @param[in] data_handle The sticker data handle
190 * @param[in] keyword The keyword to be saved
191 * @return 0 on success, otherwise a negative error value
192 * @retval #STICKER_ERROR_NONE Successful
193 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
194 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
195 * @see sticker_data_keyword_foreach_cb()
196 * @see sticker_data_foreach_keyword()
197 * @see sticker_data_remove_keyword()
199 int sticker_data_add_keyword(sticker_data_h data_handle, const char *keyword);
202 * @brief Removes a keyword of the sticker from the list.
204 * @remarks @a keyword must exist value in the list. If not, the error as invalid parameter will be returned.
205 * @param[in] data_handle The sticker data handle
206 * @param[in] keyword The keyword to be removed
207 * @return 0 on success, otherwise a negative error value
208 * @retval #STICKER_ERROR_NONE Successful
209 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
210 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
211 * @see sticker_data_keyword_foreach_cb()
212 * @see sticker_data_foreach_keyword()
213 * @see sticker_data_add_keyword()
215 int sticker_data_remove_keyword(sticker_data_h data_handle, const char *keyword);
218 * @brief Sets the group name of the sticker.
220 * @remarks @a group must have a non-null value. If not, the error as invalid parameter will be returned.
221 * @param[in] data_handle The sticker data handle
222 * @param[in] group The group name to be saved
223 * @return 0 on success, otherwise a negative error value
224 * @retval #STICKER_ERROR_NONE Successful
225 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
226 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
227 * @see sticker_data_get_group()
229 int sticker_data_set_group_name(sticker_data_h data_handle, const char *group);
232 * @brief Gets the group name from sticker data handle.
234 * @remarks @a group must be released using free().
235 * @param[in] data_handle The sticker data handle
236 * @param[out] group The group name
237 * @return 0 on success, otherwise a negative error value
238 * @retval #STICKER_ERROR_NONE Successful
239 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
240 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
241 * @retval #STICKER_ERROR_NO_DATA No data available
242 * @see sticker_data_set_group()
244 int sticker_data_get_group_name(sticker_data_h data_handle, char **group);
247 * @brief Sets the thumbnail local path of the sticker.
248 * @details @a thumbnail must be a relative path like '/res/smile_thumbnail.png'.
250 * @remarks @a thumbnail must have a non-null value and must be an existing file. If not, the error as invalid parameter will be returned.
251 * @param[in] data_handle The sticker data handle
252 * @param[in] thumbnail The thumbnail path to be saved
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 * @see sticker_data_get_thumbnail()
259 int sticker_data_set_thumbnail(sticker_data_h data_handle, const char *thumbnail);
262 * @brief Gets the thumbnail local path from sticker data handle.
263 * @details If the thumbnail is empty, the result will be an empty string.
265 * @remarks @a thumbnail must be released using free().
266 * @param[in] data_handle The sticker data handle
267 * @param[out] thumbnail The thumbnail path
268 * @return 0 on success, otherwise a negative error value
269 * @retval #STICKER_ERROR_NONE Successful
270 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
271 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
272 * @see sticker_data_set_thumbnail()
274 int sticker_data_get_thumbnail(sticker_data_h data_handle, char **thumbnail);
277 * @brief Sets the description of the sticker.
279 * @remarks @a description must have a non-null value. If not, the error as invalid parameter will be returned.
280 * @param[in] data_handle The sticker data handle
281 * @param[in] description The description to be saved
282 * @return 0 on success, otherwise a negative error value
283 * @retval #STICKER_ERROR_NONE Successful
284 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
285 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
286 * @see sticker_data_get_description()
288 int sticker_data_set_description(sticker_data_h data_handle, const char *description);
291 * @brief Gets the description from sticker data handle.
292 * @details If the description is empty, the result will be an empty string.
294 * @remarks @a description must be released using free().
295 * @param[in] data_handle The sticker data handle
296 * @param[out] description The description of the sticker
297 * @return 0 on success, otherwise a negative error value
298 * @retval #STICKER_ERROR_NONE Successful
299 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
300 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
301 * @see sticker_data_set_description()
303 int sticker_data_get_description(sticker_data_h data_handle, char **description);
306 * @brief Gets the last updated date from sticker data handle.
307 * @details The format of @a date is YYYY-MM-DD HH:MM:SS.
309 * @remarks @a date must be released using free().
310 * @param[in] data_handle The sticker data handle
311 * @param[out] date The last updated date
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_NO_DATA No data available
318 int sticker_data_get_date(sticker_data_h data_handle, char **date);
321 * @brief Sets the display type of the sticker.
323 * @param[in] data_handle The sticker data handle
324 * @param[in] type The display type to be saved
325 * @return 0 on success, otherwise a negative error value
326 * @retval #STICKER_ERROR_NONE Successful
327 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
328 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
329 * @see sticker_data_get_display_type()
331 int sticker_data_set_display_type(sticker_data_h data_handle, sticker_data_display_type_e type);
334 * @brief Gets the display type from sticker data handle.
335 * @details If the display type is empty, the result will be a zero.
337 * @param[in] data_handle The sticker data handle
338 * @param[out] type The display type of the sticker
339 * @return 0 on success, otherwise a negative error value
340 * @retval #STICKER_ERROR_NONE Successful
341 * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
342 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
343 * @see sticker_data_set_display_type()
345 int sticker_data_get_display_type(sticker_data_h data_handle, sticker_data_display_type_e *type);
355 #endif /* __TIZEN_UIX_STICKER_DATA_H__ */