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 The sticker data handle.
50 typedef struct sticker_data_s *sticker_data_h;
53 * @brief Called to retrieve the keyword of the sticker.
54 * @details The sticker_data_foreach_keyword() must be called to invoke this callback function, synchronously.
56 * @remarks @a keyword should not be freed and can be used only in the callback.
57 * @param[in] keyword The sticker keyword
58 * @param[in] user_data The user data passed from the foreach function
59 * @pre sticker_data_foreach_keyword() will invoke this callback.
60 * @see sticker_data_foreach_keyword()
62 typedef void (*sticker_data_keyword_foreach_cb)(const char *keyword, void *user_data);
65 * @brief Creates a sticker data handle.
67 * @remarks If the function succeeds, @a data_handle must be released with sticker_data_destroy().
68 * @param[out] data_handle The sticker data handle
69 * @return 0 on success, otherwise a negative error value
70 * @retval #STICKER_ERROR_NONE Successful
71 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
72 * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
73 * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
74 * @see sticker_data_destroy()
76 int sticker_data_create(sticker_data_h *data_handle);
79 * @brief Destroys a sticker data handle.
81 * @param[in] data_handle The sticker data handle
82 * @return 0 on success, otherwise a negative error value
83 * @retval #STICKER_ERROR_NONE Successful
84 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
85 * @see sticker_data_create()
87 int sticker_data_destroy(sticker_data_h data_handle);
90 * @brief Clones a sticker data handle.
92 * @remarks If the function succeeds, @a target_handle must be released with sticker_data_destroy().
93 * @param[in] origin_handle The sticker data handle
94 * @param[out] target_handle The sticker data handle to be cloned
95 * @return 0 on success, otherwise a negative error value
96 * @retval #STICKER_ERROR_NONE Successful
97 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
98 * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
99 * @see sticker_data_destroy()
101 int sticker_data_clone(sticker_data_h origin_handle, sticker_data_h *target_handle);
104 * @brief Gets the name of the sticker provider application from sticker data handle.
106 * @remarks @a app_id must be released using free().
107 * @param[in] data_handle The sticker data handle
108 * @param[out] app_id The name of the application that provides sticker information
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
114 int sticker_data_get_app_id(sticker_data_h data_handle, char **app_id);
117 * @brief Sets the URI and URI type of the sticker.
118 * @details @a uri must be a relative path like '/res/smile.png' when the type of URI is local path.
120 * @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.
121 * @param[in] data_handle The sticker data handle
122 * @param[in] type The URI type to be saved
123 * @param[in] uri The URI to be saved
124 * @return 0 on success, otherwise a negative error value
125 * @retval #STICKER_ERROR_NONE Successful
126 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
127 * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
128 * @see sticker_data_get_uri()
130 int sticker_data_set_uri(sticker_data_h data_handle, sticker_data_uri_type_e type, const char *uri);
133 * @brief Gets the URI and URI type from sticker data handle.
135 * @remarks @a uri must be released using free().
136 * @param[in] data_handle The sticker data handle
137 * @param[out] type The URI type
138 * @param[out] uri The URI
139 * @return 0 on success, otherwise a negative error value
140 * @retval #STICKER_ERROR_NONE Successful
141 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
142 * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
143 * @see sticker_data_set_uri()
145 int sticker_data_get_uri(sticker_data_h data_handle, sticker_data_uri_type_e *type, char **uri);
148 * @brief Retrieves all keywords of the sticker using callback function.
150 * @param[in] data_handle The sticker data handle
151 * @param[in] callback The callback function to invoke
152 * @param[in] user_data The user data to be passed to the callback function
153 * @return 0 on success, otherwise a negative error value
154 * @retval #STICKER_ERROR_NONE Successful
155 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
156 * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
157 * @post This function invokes sticker_data_keyword_foreach_cb() repeatedly for getting keywords.
158 * @see sticker_data_keyword_foreach_cb()
159 * @see sticker_data_add_keyword()
160 * @see sticker_data_remove_keyword()
162 int sticker_data_foreach_keyword(sticker_data_h data_handle, sticker_data_keyword_foreach_cb callback, void *user_data);
165 * @brief Adds a keyword of the sticker to the list.
167 * @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.
168 * @param[in] data_handle The sticker data handle
169 * @param[in] keyword The keyword to be saved
170 * @return 0 on success, otherwise a negative error value
171 * @retval #STICKER_ERROR_NONE Successful
172 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
173 * @see sticker_data_keyword_foreach_cb()
174 * @see sticker_data_foreach_keyword()
175 * @see sticker_data_remove_keyword()
177 int sticker_data_add_keyword(sticker_data_h data_handle, const char *keyword);
180 * @brief Removes a keyword of the sticker from the list.
182 * @remarks @a keyword must exist value in the list. If not, the error as invalid parameter will be returned.
183 * @param[in] data_handle The sticker data handle
184 * @param[in] keyword The keyword to be removed
185 * @return 0 on success, otherwise a negative error value
186 * @retval #STICKER_ERROR_NONE Successful
187 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
188 * @see sticker_data_keyword_foreach_cb()
189 * @see sticker_data_foreach_keyword()
190 * @see sticker_data_add_keyword()
192 int sticker_data_remove_keyword(sticker_data_h data_handle, const char *keyword);
195 * @brief Sets the group name of the sticker.
197 * @remarks @a group must have a non-null value. If not, the error as invalid parameter will be returned.
198 * @param[in] data_handle The sticker data handle
199 * @param[in] group The group name to be saved
200 * @return 0 on success, otherwise a negative error value
201 * @retval #STICKER_ERROR_NONE Successful
202 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
203 * @see sticker_data_get_group()
205 int sticker_data_set_group_name(sticker_data_h data_handle, const char *group);
208 * @brief Gets the group name from sticker data handle.
210 * @remarks @a group must be released using free().
211 * @param[in] data_handle The sticker data handle
212 * @param[out] group The group name
213 * @return 0 on success, otherwise a negative error value
214 * @retval #STICKER_ERROR_NONE Successful
215 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
216 * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
217 * @see sticker_data_set_group()
219 int sticker_data_get_group_name(sticker_data_h data_handle, char **group);
222 * @brief Sets the thumbnail local path of the sticker.
223 * @details @a thumbnail must be a relative path like '/res/smile_thumbnail.png'.
225 * @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.
226 * @param[in] data_handle The sticker data handle
227 * @param[in] thumbnail The thumbnail path to be saved
228 * @return 0 on success, otherwise a negative error value
229 * @retval #STICKER_ERROR_NONE Successful
230 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
231 * @see sticker_data_get_thumbnail()
233 int sticker_data_set_thumbnail(sticker_data_h data_handle, const char *thumbnail);
236 * @brief Gets the thumbnail local path from sticker data handle.
237 * @details If the thumbnail is empty, the result will be an empty string.
239 * @remarks @a thumbnail must be released using free().
240 * @param[in] data_handle The sticker data handle
241 * @param[out] thumbnail The thumbnail path
242 * @return 0 on success, otherwise a negative error value
243 * @retval #STICKER_ERROR_NONE Successful
244 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
245 * @see sticker_data_set_thumbnail()
247 int sticker_data_get_thumbnail(sticker_data_h data_handle, char **thumbnail);
250 * @brief Sets the description of the sticker.
252 * @remarks @a description must have a non-null value. If not, the error as invalid parameter will be returned.
253 * @param[in] data_handle The sticker data handle
254 * @param[in] description The description to be saved
255 * @return 0 on success, otherwise a negative error value
256 * @retval #STICKER_ERROR_NONE Successful
257 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
258 * @see sticker_data_get_description()
260 int sticker_data_set_description(sticker_data_h data_handle, const char *description);
263 * @brief Gets the description from sticker data handle.
264 * @details If the description is empty, the result will be an empty string.
266 * @remarks @a description must be released using free().
267 * @param[in] data_handle The sticker data handle
268 * @param[out] description The description of the sticker
269 * @return 0 on success, otherwise a negative error value
270 * @retval #STICKER_ERROR_NONE Successful
271 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
272 * @see sticker_data_set_description()
274 int sticker_data_get_description(sticker_data_h data_handle, char **description);
277 * @brief Gets the last updated date from sticker data handle.
278 * @details The format of @a date is YYYY-MM-DD HH:MM:SS.
280 * @remarks @a date must be released using free().
281 * @param[in] data_handle The sticker data handle
282 * @param[out] date The last updated date
283 * @return 0 on success, otherwise a negative error value
284 * @retval #STICKER_ERROR_NONE Successful
285 * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
286 * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
288 int sticker_data_get_date(sticker_data_h data_handle, char **date);
298 #endif /* __TIZEN_UIX_STICKER_DATA_H__ */