include/minicontrol-handler.h

   1 /*
   2  * Copyright (c)  2013-2015 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   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
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 #ifndef _MINICTRL_HANDLER_H_
  18 #define _MINICTRL_HANDLER_H_
  19
  20 #include <Evas.h>
  21 #include "minicontrol-error.h"
  22 #include "minicontrol-type.h"
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29  * @file minicontrol-handler.h
  30  * @brief This minicontrol handler library used to manage handler created with a minicontrol window
  31  */
  32
  33 /**
  34  * @addtogroup MINICONTROL_HANDLER_MODULE
  35  * @{
  36  */
  37
  38 /**
  39  * @brief       minicontrol category : "UNKNOWN" is treated as "CLOCK"
  40  */
  41 #define MINICONTROL_HDL_CATEGORY_UNKNOWN "UNKNOWN"
  42 /**
  43  * @brief       minicontrol category : CLOCK
  44  */
  45 #define MINICONTROL_HDL_CATEGORY_CLOCK "CLOCK"
  46 /**
  47  * @brief       minicontrol category : NOTIFICATION
  48  */
  49 #define MINICONTROL_HDL_CATEGORY_NOTIFICATION "NOTIFICATION"
  50 /**
  51  * @brief       minicontrol category : DASHBOARD
  52  */
  53 #define MINICONTROL_HDL_CATEGORY_DASHBOARD "DASHBOARD"
  54
  55 /**
  56  * @brief       minicontrol operation : NONE(do nothing)
  57  */
  58 #define MINICONTROL_HDL_OPERATION_NONE "NONE"
  59 /**
  60  * @brief       minicontrol operation : add a minicontrol
  61  */
  62 #define MINICONTROL_HDL_OPERATION_ADD "ADD"
  63  /**
  64  * @brief       minicontrol operation : show a minicontrol
  65  */
  66 #define MINICONTROL_HDL_OPERATION_SHOW "SHOW"
  67 /**
  68  * @brief       minicontrol operation : remove a minicontrol
  69  */
  70 #define MINICONTROL_HDL_OPERATION_REMOVE "REMOVE"
  71 /**
  72  * @brief       minicontrol operation : reload(rearrange) a minicontrol on the viewer
  73  */
  74 #define MINICONTROL_HDL_OPERATION_RELOAD "RELOAD"
  75
  76 /**
  77  * @brief       minicontrol priority : LV1(TOP)
  78  */
  79 #define MINICONTROL_HDL_PRIORITY_LV1 "LV1"
  80 /**
  81  * @brief       minicontrol priority : LV2
  82  */
  83 #define MINICONTROL_HDL_PRIORITY_LV2 "LV2"
  84 /**
  85  * @brief       minicontrol priority : LV3(BOTTOM)
  86  */
  87 #define MINICONTROL_HDL_PRIORITY_LV3 "LV3"
  88
  89 /**
  90  * @addtogroup MINICONTROL_HANDLER_MODULE
  91  * @{
  92  */
  93
  94 /**
  95  * @brief Creates a minicontrol handle.
  96  *
  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()
 104  */
 105 minicontrol_error_e minicontrol_handler_create(minicontrol_h *handler);
 106
 107 /**
 108  * @brief Destroys the minicontrol handler and releases all its resources.
 109  *
 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()
 116  */
 117 minicontrol_error_e minicontrol_handler_destroy(minicontrol_h handler);
 118
 119 /**
 120  * @brief clone a minicontrol handler
 121  *
 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()
 129  */
 130 minicontrol_error_e minicontrol_handler_clone(minicontrol_h handler, minicontrol_h *handler_new);
 131
 132 /**
 133  * @brief Sets the service name
 134  *
 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()
 143  */
 144 minicontrol_error_e minicontrol_handler_set_service_name(minicontrol_h handler, const char *name);
 145
 146 /**
 147  * @brief Gets the service name
 148  *
 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()
 157  */
 158 minicontrol_error_e minicontrol_handler_get_service_name(minicontrol_h handler, char **name);
 159
 160 /**
 161  * @brief Sets the category
 162  *
 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
 173  */
 174 minicontrol_error_e minicontrol_handler_set_category(minicontrol_h handler, const char *category);
 175
 176 /**
 177  * @brief Gets the category
 178  *
 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
 189  */
 190 minicontrol_error_e minicontrol_handler_get_category(minicontrol_h handler, char **category);
 191
 192 /**
 193  * @brief Sets the operation
 194  *
 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
 206  */
 207 minicontrol_error_e minicontrol_handler_set_operation(minicontrol_h handler, const char *operation);
 208
 209 /**
 210  * @brief Gets the operation
 211  *
 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()
 219  */
 220 minicontrol_error_e minicontrol_handler_get_operation(minicontrol_h handler, char **operation);
 221
 222 /**
 223  * @brief Sets the operation
 224  *
 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
 235  */
 236 minicontrol_error_e minicontrol_handler_set_priority(minicontrol_h handler, const char *priority);
 237
 238 /**
 239  * @brief Gets the priority
 240  *
 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()
 251  */
 252 minicontrol_error_e minicontrol_handler_get_priority(minicontrol_h handler, char **priority);
 253
 254 /**
 255  * @brief Sets the timestamp
 256  *
 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()
 264  */
 265 minicontrol_error_e minicontrol_handler_set_timestamp(minicontrol_h handler, time_t timestamp);
 266
 267 /**
 268  * @brief Gets the timestamp
 269  *
 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()
 277  */
 278 minicontrol_error_e minicontrol_handler_get_timestamp(minicontrol_h handler, time_t *timestamp);
 279
 280 /**
 281  * @brief Gets the pid which create the minicontrol
 282  *
 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
 288  */
 289 minicontrol_error_e minicontrol_handler_get_pid(minicontrol_h handler, int *pid);
 290
 291 /**
 292  * @brief Gets the state which create the minicontrol
 293  *
 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
 299  */
 300 minicontrol_error_e minicontrol_handler_state_get(minicontrol_h handler, int *state);
 301
 302 /**
 303  * @brief Adds the extra data to the handler.
 304  *
 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()
 317  */
 318 minicontrol_error_e minicontrol_handler_add_data(minicontrol_h handler, const char *key, const char *value);
 319
 320 /**
 321  * @brief Gets the extra data from the handler.
 322  *
 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()
 335  */
 336 minicontrol_error_e minicontrol_handler_get_data(minicontrol_h handler, const char *key, char **value);
 337
 338 /**
 339  * @brief Removes the extra data from the handler.
 340  *
 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()
 349  */
 350 minicontrol_error_e minicontrol_handler_remove_data(minicontrol_h handler, const char *key);
 351
 352 /**
 353  * @}
 354  */
 355
 356 #ifdef __cplusplus
 357 }
 358 #endif
 359 #endif /* _MINICTRL_HANDLER_H_ */