2 * Copyright (c) 2013-2015 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 _MINICTRL_HANDLER_H_
18 #define _MINICTRL_HANDLER_H_
21 #include "minicontrol-error.h"
22 #include "minicontrol-type.h"
29 * @file minicontrol-handler.h
30 * @brief This minicontrol handler library used to manage handler created with a minicontrol window
34 * @addtogroup MINICONTROL_HANDLER_MODULE
39 * @brief minicontrol category : "UNKNOWN" is treated as "CLOCK"
41 #define MINICONTROL_HDL_CATEGORY_UNKNOWN "UNKNOWN"
43 * @brief minicontrol category : CLOCK
45 #define MINICONTROL_HDL_CATEGORY_CLOCK "CLOCK"
47 * @brief minicontrol category : NOTIFICATION
49 #define MINICONTROL_HDL_CATEGORY_NOTIFICATION "NOTIFICATION"
51 * @brief minicontrol category : DASHBOARD
53 #define MINICONTROL_HDL_CATEGORY_DASHBOARD "DASHBOARD"
56 * @brief minicontrol operation : NONE(do nothing)
58 #define MINICONTROL_HDL_OPERATION_NONE "NONE"
60 * @brief minicontrol operation : add a minicontrol
62 #define MINICONTROL_HDL_OPERATION_ADD "ADD"
64 * @brief minicontrol operation : show a minicontrol
66 #define MINICONTROL_HDL_OPERATION_SHOW "SHOW"
68 * @brief minicontrol operation : remove a minicontrol
70 #define MINICONTROL_HDL_OPERATION_REMOVE "REMOVE"
72 * @brief minicontrol operation : reload(rearrange) a minicontrol on the viewer
74 #define MINICONTROL_HDL_OPERATION_RELOAD "RELOAD"
77 * @brief minicontrol priority : LV1(TOP)
79 #define MINICONTROL_HDL_PRIORITY_LV1 "LV1"
81 * @brief minicontrol priority : LV2
83 #define MINICONTROL_HDL_PRIORITY_LV2 "LV2"
85 * @brief minicontrol priority : LV3(BOTTOM)
87 #define MINICONTROL_HDL_PRIORITY_LV3 "LV3"
90 * @addtogroup MINICONTROL_HANDLER_MODULE
95 * @brief Creates a minicontrol handle.
97 * @remarks The @a minicontrol handler must be released with minicontrol_handler_destroy() by you.
98 * @param [out] handler A minicontrol handle to be newly created on success
99 * @return 0 on success, otherwise a negative error value.
100 * @retval #MINICONTROL_ERROR_NONE Successful
101 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
102 * @retval #MINICONTROL_ERROR_OUT_OF_MEMORY Out of memory
103 * @see minicontrol_handler_destroy()
105 minicontrol_error_e minicontrol_handler_create(minicontrol_h *handler);
108 * @brief Destroys the minicontrol handler and releases all its resources.
110 * @param [in] handler The minicontrol handler
111 * @return MINICONTROL_ERROR_NONE on success, otherwise a negative error value.
112 * @retval #MINICONTROL_ERROR_NONE Successful
113 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
114 * @retval #MINICONTROL_ERROR_OUT_OF_MEMORY Out of memory
115 * @see minicontrol_handler_create()
117 minicontrol_error_e minicontrol_handler_destroy(minicontrol_h handler);
120 * @brief clone a minicontrol handler
122 * @param [in] handler The minicontrol handler
123 * @param [in] handler_new The cloned minicontrol handler
124 * @return MINICONTROL_ERROR_NONE on success, otherwise a negative error value.
125 * @retval #MINICONTROL_ERROR_NONE Successful
126 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
127 * @retval #MINICONTROL_ERROR_OUT_OF_MEMORY Out of memory
128 * @see minicontrol_handler_create()
130 minicontrol_error_e minicontrol_handler_clone(minicontrol_h handler, minicontrol_h *handler_new);
133 * @brief Sets the service name
135 * @remarks service name should be unique.
136 * @param [in] handler The minicontrol handle
137 * @param [in] name the service name
138 * If the @a name is NULL, it clears the previous value.
139 * @return 0 on success, otherwise a negative error value.
140 * @retval #MINICONTROL_ERROR_NONE Successful
141 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
142 * @see minicontrol_handler_get_service_name()
144 minicontrol_error_e minicontrol_handler_set_service_name(minicontrol_h handler, const char *name);
147 * @brief Gets the service name
149 * @remarks The @a name must be released with free() by you.
150 * @param [in] handler The minicontrol handle
151 * @param [out] name The service name
152 * @return 0 on success, otherwise a negative error value.
153 * @retval #MINICONTROL_ERROR_NONE Successful
154 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
155 * @retval #MINICONTROL_ERROR_OUT_OF_MEMORY Out of memory
156 * @see minicontrol_handler_set_service_name()
158 minicontrol_error_e minicontrol_handler_get_service_name(minicontrol_h handler, char **name);
161 * @brief Sets the category
163 * @param [in] handler The minicontrol handle
164 * @param [in] category the category
165 * If the @a category is NULL, it clears the previous value.
166 * @return 0 on success, otherwise a negative error value.
167 * @retval #MINICONTROL_ERROR_NONE Successful
168 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
169 * @see minicontrol_handler_set_category()
170 * @see MINICONTROL_HDL_CATEGORY_UNKNOWN
171 * @see MINICONTROL_HDL_CATEGORY_CLOCK
172 * @see MINICONTROL_HDL_CATEGORY_NOTIFICATION
174 minicontrol_error_e minicontrol_handler_set_category(minicontrol_h handler, const char *category);
177 * @brief Gets the category
179 * @remarks The @a category must be released with free() by you.
180 * @param [in] handler The minicontrol handle
181 * @param [out] category The category
182 * @return 0 on success, otherwise a negative error value.
183 * @retval #MINICONTROL_ERROR_NONE Successful
184 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
185 * @see minicontrol_handler_set_service_name()
186 * @see MINICONTROL_HDL_CATEGORY_UNKNOWN
187 * @see MINICONTROL_HDL_CATEGORY_CLOCK
188 * @see MINICONTROL_HDL_CATEGORY_NOTIFICATION
190 minicontrol_error_e minicontrol_handler_get_category(minicontrol_h handler, char **category);
193 * @brief Sets the operation
195 * @param [in] handler The minicontrol handle
196 * @param [in] operation the operation
197 * If the @a operation is NULL, it clears the previous value.
198 * @return 0 on success, otherwise a negative error value.
199 * @retval #MINICONTROL_ERROR_NONE Successful
200 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
201 * @see minicontrol_handler_get_operation()
202 * @see MINICONTROL_HDL_OPERATION_NONE
203 * @see MINICONTROL_HDL_OPERATION_ADD
204 * @see MINICONTROL_HDL_OPERATION_REMOVE
205 * @see MINICONTROL_HDL_OPERATION_RELOAD
207 minicontrol_error_e minicontrol_handler_set_operation(minicontrol_h handler, const char *operation);
210 * @brief Gets the operation
212 * @remarks The @a operation must be released with free() by you.
213 * @param [in] handler The minicontrol handle
214 * @param [out] operation The operation
215 * @return 0 on success, otherwise a negative error value.
216 * @retval #MINICONTROL_ERROR_NONE Successful
217 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
218 * @see minicontrol_handler_set_operation()
220 minicontrol_error_e minicontrol_handler_get_operation(minicontrol_h handler, char **operation);
223 * @brief Sets the operation
225 * @param [in] handler The minicontrol handle
226 * @param [in] priority the priority
227 * If the @a priority is NULL, it clears the previous value.
228 * @return 0 on success, otherwise a negative error value.
229 * @retval #MINICONTROL_ERROR_NONE Successful
230 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
231 * @see minicontrol_handler_get_priority()
232 * @see MINICONTROL_HDL_PRIORITY_LV1
233 * @see MINICONTROL_HDL_PRIORITY_LV1
234 * @see MINICONTROL_HDL_PRIORITY_LV1
236 minicontrol_error_e minicontrol_handler_set_priority(minicontrol_h handler, const char *priority);
239 * @brief Gets the priority
241 * @remarks The @a priority must be released with free() by you.
242 * @param [in] handler The minicontrol handle
243 * @param [out] priority The priority
244 * @return 0 on success, otherwise a negative error value.
245 * @retval #MINICONTROL_ERROR_NONE Successful
246 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
247 * @see MINICONTROL_HDL_PRIORITY_LV1
248 * @see MINICONTROL_HDL_PRIORITY_LV1
249 * @see MINICONTROL_HDL_PRIORITY_LV1
250 * @see minicontrol_handler_set_priority()
252 minicontrol_error_e minicontrol_handler_get_priority(minicontrol_h handler, char **priority);
255 * @brief Sets the timestamp
257 * @param [in] handler The minicontrol handle
258 * @param [in] timestamp the timestamp
259 * If the @a timestamp is NULL, it clears the previous value.
260 * @return 0 on success, otherwise a negative error value.
261 * @retval #MINICONTROL_ERROR_NONE Successful
262 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
263 * @see minicontrol_handler_get_timestamp()
265 minicontrol_error_e minicontrol_handler_set_timestamp(minicontrol_h handler, time_t timestamp);
268 * @brief Gets the timestamp
270 * @param [in] handler The minicontrol handle
271 * @param [out] timestamp The timestamp
272 * @return 0 on success, otherwise a negative error value.
273 * @retval #MINICONTROL_ERROR_NONE Successful
274 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
275 * @retval #MINICONTROL_ERROR_OUT_OF_MEMORY Out of memory
276 * @see minicontrol_handler_set_timestamp()
278 minicontrol_error_e minicontrol_handler_get_timestamp(minicontrol_h handler, time_t *timestamp);
281 * @brief Gets the pid which create the minicontrol
283 * @param [in] handler The minicontrol handle
284 * @param [out] pid The pid
285 * @return 0 on success, otherwise a negative error value.
286 * @retval #MINICONTROL_ERROR_NONE Successful
287 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
289 minicontrol_error_e minicontrol_handler_get_pid(minicontrol_h handler, int *pid);
292 * @brief Gets the state which create the minicontrol
294 * @param [in] handler The minicontrol handle
295 * @param [out] state The state
296 * @return 0 on success, otherwise a negative error value.
297 * @retval #MINICONTROL_ERROR_NONE Successful
298 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
300 minicontrol_error_e minicontrol_handler_state_get(minicontrol_h handler, int *state);
303 * @brief Adds the extra data to the handler.
305 * @remarks The function replaces any existing value for the given key.
306 * @remarks The function returns #MINICONTROL_ERROR_INVALID_PARAMETER if key or value is zero-length string.
307 * @remarks The function returns #MINICONTROL_ERROR_INVALID_PARAMETER if the application tries to use same key with system-defined key
308 * @param [in] handler The minicontrol handle
309 * @param [in] key The name of the extra data
310 * @param [in] value The value associated with given key
311 * @return 0 on success, otherwise a negative error value.
312 * @retval #MINICONTROL_ERROR_NONE Successful
313 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
314 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Not available key
315 * @see minicontrol_handler_get_data()
316 * @see minicontrol_handler_remove_data()
318 minicontrol_error_e minicontrol_handler_add_data(minicontrol_h handler, const char *key, const char *value);
321 * @brief Gets the extra data from the handler.
323 * @remarks The @a value must be released with free() by you.
324 * @remarks The function returns #MINICONTROL_ERROR_INVALID_PARAMETER if the value is array data type.
325 * @param [in] handler The minicontrol handle
326 * @param [int] key The name of the extra data
327 * @param [out] value The value associated with given key
328 * @return 0 on success, otherwise a negative error value.
329 * @retval #MINICONTROL_ERROR_NONE Successful
330 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
331 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Specified key not found
332 * @retval #MINICONTROL_ERROR_OUT_OF_MEMORY Out of memory
333 * @see minicontrol_handler_add_data()
334 * @see minicontrol_handler_remove_data()
336 minicontrol_error_e minicontrol_handler_get_data(minicontrol_h handler, const char *key, char **value);
339 * @brief Removes the extra data from the handler.
341 * @param [in] handler The minicontrol handle
342 * @param [in] key The name of the extra data
343 * @return 0 on success, otherwise a negative error value.
344 * @retval #MINICONTROL_ERROR_NONE Successful
345 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Invalid parameter
346 * @retval #MINICONTROL_ERROR_INVALID_PARAMETER Specified key not found
347 * @see minicontrol_handler_add_data()
348 * @see minicontrol_handler_get_data()
350 minicontrol_error_e minicontrol_handler_remove_data(minicontrol_h handler, const char *key);
359 #endif /* _MINICTRL_HANDLER_H_ */