include/rrs_control_data.h

   1 /*
   2  * Copyright (c) 2016 Samsung Electronics Co., Ltd.
   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
  18 #ifndef _RRS_CONTROL_DATA_H_
  19 #define _RRS_CONTROL_DATA_H_
  20
  21 #include "rrs_main.h"
  22
  23 /**
  24  * @ingroup     CAPI_RRS_CLIENT
  25  * @defgroup    CAPI_RRS_CONTROL_DATA_MODULE Control data
  26  *
  27  * @file rrs_control_data.h
  28  * @brief This file contains the RRS Control Data API
  29  * @addtogroup CAPI_RRS_CONTROL_DATA_MODULE
  30  * @{
  31  * @brief This provides APIs related to control data handling
  32  */
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38
  39 /**
  40  * @brief       Handle of control data.
  41  * @details The handle to generate control data for controlling remote resource.
  42  * @since_tizen 3.0
  43  *
  44  * @remarks To release the handle use rrs_control_data_destroy().
  45  *
  46  * @see rrs_control_data_destroy()
  47  */
  48 typedef void * rrs_control_data_h;
  49
  50
  51 /**
  52  * @brief       Creates an instance of structured control data.
  53  * @details This function creates an instance of structured control data and issues a new handle for it.
  54  * @since_tizen 3.0
  55  *
  56  * @remarks @a data handle must be released using rrs_control_data_destroy().
  57  *
  58  * @param[in]   type            Resource type
  59  * @param[out]  data            The handle of newly created data instance
  60  * @return      0 on success, otherwise a negative error value
  61  * @retval      #RRS_ERROR_NONE Successful
  62  * @retval      #RRS_ERROR_INVALID_PARAMETER Invalid parameter
  63  * @retval      #RRS_ERROR_INVALID_TYPE Invalid type
  64  * @retval      #RRS_ERROR_OUT_OF_MEMORY Out of memory
  65  *
  66  * @see rrs_control_data_destroy()
  67  * @see rrs_control_data_clone()
  68  * @see rrs_resource_e
  69  */
  70 int rrs_control_data_create(const rrs_resource_e type,
  71                 rrs_control_data_h *data);
  72
  73
  74 /**
  75  * @brief       Destroys the data handle.
  76  * @details This function releases the data handle.
  77  * @since_tizen 3.0
  78  *
  79  * @param[in]   data            The data handle to destroy
  80  * @return      0 on success, otherwise a negative error value
  81  * @retval      #RRS_ERROR_NONE Successful
  82  * @retval      #RRS_ERROR_INVALID_PARAMETER Invalid parameter
  83  *
  84  * @pre @a data handle is created with rrs_control_data_create() functions.
  85  *
  86  * @see rrs_control_data_create()
  87  * @see rrs_control_data_clone()
  88  */
  89 int rrs_control_data_destroy(rrs_control_data_h data);
  90
  91
  92 /**
  93  * @brief       Clones the data handle.
  94  * @details This function clones the structured data handle @a origin.
  95  * @since_tizen 3.0
  96  *
  97  * @remarks @a cloned must be released using rrs_control_data_destroy().
  98  *
  99  * @param[in]   origin          The original data handle
 100  * @param[out]  cloned          A cloned data handle
 101  * @return      0 on success, otherwise a negative error data
 102  * @retval      #RRS_ERROR_NONE Successful
 103  * @retval      #RRS_ERROR_INVALID_PARAMETER Invalid parameter
 104  * @retval      #RRS_ERROR_OUT_OF_MEMORY Out of memory
 105  *
 106  * @see rrs_control_data_create()
 107  * @see rrs_control_data_destroy()
 108  */
 109 int rrs_control_data_clone(const rrs_control_data_h origin,
 110                 rrs_control_data_h *cloned);
 111
 112
 113 /**
 114  * @brief       Sets boolean field value.
 115  * @details This function sets the boolean field value.
 116  * @since_tizen 3.0
 117  *
 118  * @param[in]   data            The data handle
 119  * @param[in]   name            The name of the field
 120  * @param[in]   value           The value of the field
 121  * @return      0 on success, otherwise a negative error value
 122  * @retval      #RRS_ERROR_NONE Successful
 123  * @retval      #RRS_ERROR_INVALID_PARAMETER Invalid parameter
 124  *
 125  * @pre @a data handle is created with rrs_control_data_create() functions.
 126  *
 127  * @see rrs_control_data_create()
 128  * @see rrs_resource_send_control()
 129  */
 130 int rrs_control_data_set_bool(rrs_control_data_h data,
 131                 const char *name,
 132                 const bool value);
 133
 134
 135 /**
 136  * @brief       Sets integer field value.
 137  * @details This function sets the integer field value.
 138  * @since_tizen 3.0
 139  *
 140  * @param[in]   data            The data handle
 141  * @param[in]   name            The name of the field
 142  * @param[in]   value           The value of the field
 143  * @return      0 on success, otherwise a negative error value
 144  * @retval      #RRS_ERROR_NONE Successful
 145  * @retval      #RRS_ERROR_INVALID_PARAMETER Invalid parameter
 146  *
 147  * @pre @a data handle is created with rrs_control_data_create() functions.
 148  *
 149  * @see rrs_control_data_create()
 150  * @see rrs_resource_send_control()
 151  */
 152 int rrs_control_data_set_int(rrs_control_data_h data,
 153                 const char *name,
 154                 const int value);
 155
 156
 157 /**
 158  * @brief       Sets floating point field value.
 159  * @details This function sets the floating point field value.
 160  * @since_tizen 3.0
 161  *
 162  * @param[in]   data            The data handle
 163  * @param[in]   name            The name of the field
 164  * @param[in]   value           The value of the field
 165  * @return      0 on success, otherwise a negative error value
 166  * @retval      #RRS_ERROR_NONE Successful
 167  * @retval      #RRS_ERROR_INVALID_PARAMETER Invalid parameter
 168  *
 169  * @pre @a data handle is created with rrs_control_data_create() functions.
 170  *
 171  * @see rrs_control_data_create()
 172  * @see rrs_resource_send_control()
 173  */
 174 int rrs_control_data_set_double(rrs_control_data_h data,
 175                 const char *name,
 176                 const double value);
 177
 178
 179 /**
 180  * @brief       Sets string field value.
 181  * @details This function sets the string field value.
 182  * @since_tizen 3.0
 183  *
 184  * @param[in]   data            The data handle
 185  * @param[in]   name            The name of the field
 186  * @param[in]   value           The value of the field
 187  * @return      0 on success, otherwise a negative error value
 188  * @retval      #RRS_ERROR_NONE Successful
 189  * @retval      #RRS_ERROR_INVALID_PARAMETER Invalid parameter
 190  *
 191  * @pre @a data handle is created with rrs_control_data_create() functions.
 192  *
 193  * @see rrs_control_data_create()
 194  * @see rrs_resource_send_control()
 195  */
 196 int rrs_control_data_set_string(rrs_control_data_h data,
 197                 const char *name,
 198                 const char *value);
 199
 200
 201 /**
 202  * @brief       Gets boolean field value.
 203  * @details This function gets the boolean field value.
 204  * @since_tizen 3.0
 205  *
 206  * @param[in]   data            The data handle
 207  * @param[in]   name            The name of the field
 208  * @param[out]  value           The pointer to bool in which to store the
 209  * value of the field
 210  * @return      0 on success, otherwise a negative error value
 211  * @retval      #RRS_ERROR_NONE Successful
 212  * @retval      #RRS_ERROR_INVALID_PARAMETER Invalid parameter
 213  *
 214  * @pre @a data handle is created with rrs_control_data_create() functions.
 215  *
 216  * @see rrs_control_data_create()
 217  * @see rrs_resource_monitor_control()
 218  */
 219 int rrs_control_data_get_bool(const rrs_control_data_h data,
 220                 const char *name,
 221                 bool *value);
 222
 223
 224 /**
 225  * @brief       Gets integer field value.
 226  * @details This function gets the integer field value.
 227  * @since_tizen 3.0
 228  *
 229  * @param[in]   data            The data handle
 230  * @param[in]   name            The name of the field
 231  * @param[out]  value           The pointer to int in which to store the
 232  * value of the field
 233  * @return      0 on success, otherwise a negative error value
 234  * @retval      #RRS_ERROR_NONE Successful
 235  * @retval      #RRS_ERROR_INVALID_PARAMETER Invalid parameter
 236  *
 237  * @pre @a data handle is created with rrs_control_data_create() functions.
 238  *
 239  * @see rrs_control_data_create()
 240  * @see rrs_resource_monitor_control()
 241  */
 242 int rrs_control_data_get_int(const rrs_control_data_h data,
 243                 const char *name,
 244                 int *value);
 245
 246
 247 /**
 248  * @brief       Gets floating point field value.
 249  * @details This function gets the floating point field value.
 250  * @since_tizen 3.0
 251  *
 252  * @param[in]   data            The data handle
 253  * @param[in]   name            The name of the field
 254  * @param[out]  value           The pointer to double in which to store the
 255  * value of the field
 256  * @return      0 on success, otherwise a negative error value
 257  * @retval      #RRS_ERROR_NONE Successful
 258  * @retval      #RRS_ERROR_INVALID_PARAMETER Invalid parameter
 259  *
 260  * @pre @a data handle is created with rrs_control_data_create() functions.
 261  *
 262  * @see rrs_control_data_create()
 263  * @see rrs_resource_monitor_control()
 264  */
 265 int rrs_control_data_get_double(const rrs_control_data_h data,
 266                 const char *name,
 267                 double *value);
 268
 269
 270 /**
 271  * @brief       Gets string field value.
 272  * @details This function gets the sting field value.
 273  * @since_tizen 3.0
 274  *
 275  * @remarks Release the value @a value using free().
 276  *
 277  * @param[in]   data            The data handle
 278  * @param[in]   name            The name of the field
 279  * @param[out]  value           The pointer to char * in which to store the
 280  * value of the field
 281  * @return      0 on success, otherwise a negative error value
 282  * @retval      #RRS_ERROR_NONE Successful
 283  * @retval      #RRS_ERROR_INVALID_PARAMETER Invalid parameter
 284  *
 285  * @pre @a data handle is created with rrs_control_data_create() functions.
 286  *
 287  * @see rrs_control_data_create()
 288  * @see rrs_resource_monitor_control()
 289  */
 290 int rrs_control_data_get_string(const rrs_control_data_h data,
 291                 const char *name,
 292                 char **value);
 293
 294
 295 #ifdef __cplusplus
 296 }
 297 #endif
 298 /**
 299  * @}
 300  */
 301 #endif  /* _RRS_CONTROL_DATA_H_ */