lib/include/iotcon-representation.h

   1 /*
   2  * Copyright (c) 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 #ifndef __IOT_CONNECTIVITY_MANAGER_STRUCT_REPRESENTATION_H__
  17 #define __IOT_CONNECTIVITY_MANAGER_STRUCT_REPRESENTATION_H__
  18
  19 #include <iotcon-types.h>
  20
  21 /**
  22  * @file iotcon-representation.h
  23  */
  24
  25 /**
  26  * @ingroup CAPI_IOT_CONNECTIVITY_COMMON_MODULE
  27  * @defgroup CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_MODULE Representation
  28  *
  29  * @brief Iotcon Representation provides API to manage representation
  30  *
  31  * @section CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_MODULE_HEADER Required Header
  32  *  \#include <iotcon.h>
  33  *
  34  * @section CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_MODULE_OVERVIEW Overview
  35  * The Iotcon Representation API provides data type of resp_repr handling.\n
  36  * A resp_repr is a payload of a request or a response.\n
  37  * It has uri_path, interface, list of resource types and its attributes.\n
  38  * Attributes have capabilties to store and retrieve integer, boolean, double, string, list, null,
  39  * resp_repr.\n
  40  * A list is a container that includes number of datas of same type.\n
  41  * It has capabilties to store and retrieve integer, boolean, double, string, list, null, resp_repr.
  42  *
  43  * Example :
  44  *@code
  45 #include <iotcon.h>
  46 ...
  47 {
  48         int ret;
  49         iotcon_representation_h repr;
  50         iotcon_resource_types_h types;
  51         iotcon_list_h bright_step_list;
  52
  53         ret = iotcon_representation_create(&resp_repr);
  54         if (IOTCON_ERROR_NONE != ret) {
  55                 return;
  56         }
  57
  58         ret = iotcon_representation_set_uri_path(resp_repr, "/a/light");
  59         if (IOTCON_ERROR_NONE != ret) {
  60                 iotcon_representation_destroy(resp_repr);
  61                 return;
  62         }
  63
  64         ret = iotcon_resource_types_create(&types);
  65         if (IOTCON_ERROR_NONE != ret) {
  66                 iotcon_representation_destroy(resp_repr);
  67                 return;
  68         }
  69
  70         ret = iotcon_resource_types_add(types, "core.light");
  71         if (IOTCON_ERROR_NONE != ret) {
  72                 iotcon_resource_types_destroy(types);
  73                 iotcon_representation_destroy(resp_repr);
  74                 return;
  75         }
  76
  77         ret = iotcon_representation_set_resource_types(resp_repr, types);
  78         if (IOTCON_ERROR_NONE != ret) {
  79                 iotcon_resource_types_destroy(types);
  80                 iotcon_representation_destroy(resp_repr);
  81                 return;
  82         }
  83
  84         ret = iotcon_representation_set_resource_interfaces(resp_repr, IOTCON_INTERFACE_LINK);
  85         if (IOTCON_ERROR_NONE != ret) {
  86                 iotcon_resource_types_destroy(types);
  87                 iotcon_representation_destroy(resp_repr);
  88                 return;
  89         }
  90
  91         ret = iotcon_state_add_str(resp_repr, "type", "lamp");
  92         if (IOTCON_ERROR_NONE != ret) {
  93                 iotcon_resource_types_destroy(types);
  94                 iotcon_representation_destroy(resp_repr);
  95                 return;
  96         }
  97
  98         ret = iotcon_state_add_str(resp_repr, "where", "desk");
  99         if (IOTCON_ERROR_NONE != ret) {
 100                 iotcon_resource_types_destroy(types);
 101                 iotcon_representation_destroy(resp_repr);
 102                 return;
 103         }
 104
 105         ret = iotcon_state_add_double(resp_repr, "default_bright", 200.0);
 106         if (IOTCON_ERROR_NONE != ret) {
 107                 iotcon_resource_types_destroy(types);
 108                 iotcon_representation_destroy(resp_repr);
 109                 return;
 110         }
 111
 112         ret = iotcon_state_add_str(resp_repr, "unit", "lux");
 113         if (IOTCON_ERROR_NONE != ret) {
 114                 iotcon_resource_types_destroy(types);
 115                 iotcon_representation_destroy(resp_repr);
 116                 return;
 117         }
 118
 119         ret = iotcon_state_add_bool(resp_repr, "bright_step", true);
 120         if (IOTCON_ERROR_NONE != ret) {
 121                 iotcon_resource_types_destroy(types);
 122                 iotcon_representation_destroy(resp_repr);
 123                 return;
 124         }
 125
 126         ret = iotcon_list_create(IOTCON_TYPE_DOUBLE, &bright_step_list);
 127         if (IOTCON_ERROR_NONE != ret) {
 128                 iotcon_resource_types_destroy(types);
 129                 iotcon_representation_destroy(resp_repr);
 130                 return;
 131         }
 132
 133         ret = iotcon_list_add_double(bright_step_list, 100.0, -1);
 134         if (IOTCON_ERROR_NONE != ret) {
 135                 iotcon_list_destroy(bright_step_list);
 136                 iotcon_resource_types_destroy(types);
 137                 iotcon_representation_destroy(resp_repr);
 138                 return;
 139         }
 140
 141         ret = iotcon_list_add_double(bright_step_list, 200.0, -1);
 142         if (IOTCON_ERROR_NONE != ret) {
 143                 iotcon_list_destroy(bright_step_list);
 144                 iotcon_resource_types_destroy(types);
 145                 iotcon_representation_destroy(resp_repr);
 146                 return;
 147         }
 148
 149         ret = iotcon_list_add_double(bright_step_list, 300.0, -1);
 150         if (IOTCON_ERROR_NONE != ret) {
 151                 iotcon_list_destroy(bright_step_list);
 152                 iotcon_resource_types_destroy(types);
 153                 iotcon_representation_destroy(resp_repr);
 154                 return;
 155         }
 156
 157         ret = iotcon_list_add_double(bright_step_list, 400.0, -1);
 158         if (IOTCON_ERROR_NONE != ret) {
 159                 iotcon_list_destroy(bright_step_list);
 160                 iotcon_resource_types_destroy(types);
 161                 iotcon_representation_destroy(resp_repr);
 162                 return;
 163         }
 164
 165         ret = iotcon_list_add_double(bright_step_list, 500.0, -1);
 166         if (IOTCON_ERROR_NONE != ret) {
 167                 iotcon_list_destroy(bright_step_list);
 168                 iotcon_resource_types_destroy(types);
 169                 iotcon_representation_destroy(resp_repr);
 170                 return;
 171         }
 172
 173         ret = iotcon_state_add_list(resp_repr, "bright_step_list", bright_step_list);
 174         if (IOTCON_ERROR_NONE != ret) {
 175                 iotcon_list_destroy(bright_step_list);
 176                 iotcon_resource_types_destroy(types);
 177                 iotcon_representation_destroy(resp_repr);
 178                 return;
 179         }
 180
 181         iotcon_list_destroy(bright_step_list);
 182         iotcon_resource_types_destroy(types);
 183         iotcon_representation_destroy(resp_repr);
 184 }
 185  * @endcode
 186  * @{
 187  */
 188
 189 /**
 190  * @brief Creates a new representation handle.
 191  *
 192  * @since_tizen 3.0
 193  *
 194  * @remarks You must destroy @a repr by calling iotcon_representation_destroy()
 195  * if @a repr is no longer needed.
 196  *
 197  * @param[out] repr A newly allocated representation handle
 198  *
 199  * @return 0 on success, otherwise a negative error value.
 200  * @retval #IOTCON_ERROR_NONE  Successful
 201  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
 202  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 203  *
 204  * @see iotcon_representation_destroy()
 205  */
 206 int iotcon_representation_create(iotcon_representation_h *repr);
 207
 208 /**
 209  * @brief Destroys a representation.
 210  * @details Releases a @a representation and its internal data.
 211  *
 212  * @since_tizen 3.0
 213  *
 214  * @param[in] repr The representation handle to free
 215  *
 216  * @return void
 217  *
 218  * @see iotcon_representation_create()
 219  */
 220 void iotcon_representation_destroy(iotcon_representation_h repr);
 221
 222 /**
 223  * @brief Clones from the source representation.
 224  * @details Makes a deep copy of a source representation.
 225  *
 226  * @since_tizen 3.0
 227  *
 228  * @remarks You must destroy @a dest by calling iotcon_representation_destroy()
 229  * if @a dest is no longer needed.
 230  *
 231  * @param[in] src Source of representation to be copied
 232  * @param[out] dest Clone of a source representation
 233  *
 234  * @return Clone of a source representation, otherwise NULL on failure
 235  * @retval iotcon_representation_h Success
 236  * @retval NULL Failure
 237  */
 238 int iotcon_representation_clone(const iotcon_representation_h src,
 239                 iotcon_representation_h *dest);
 240
 241 /**
 242  * @brief Appends resource type name.
 243  *
 244  * @since_tizen 3.0
 245  * @remarks Stored string is replaced with @a uri_path. If @a uri_path is NULL, stored string
 246  * is set by NULL.
 247  *
 248  * @param[in] repr The handle to the Representation
 249  * @param[in] uri_path The URI of resource
 250  *
 251  * @return 0 on success, otherwise a negative error value.
 252  * @retval #IOTCON_ERROR_NONE  Successful
 253  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
 254  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 255  */
 256 int iotcon_representation_set_uri_path(iotcon_representation_h repr,
 257                 const char *uri_path);
 258
 259 /**
 260  * @brief Gets an URI path from the representation.
 261  *
 262  * @since_tizen 3.0
 263  *
 264  * @remarks @a uri_path must not be released using free().
 265  *
 266  * @param[in] repr The representation handle
 267  * @param[out] uri_path The URI path to get
 268  *
 269  * @return 0 on success, otherwise a negative error value.
 270  * @retval #IOTCON_ERROR_NONE  Successful
 271  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 272  */
 273 int iotcon_representation_get_uri_path(iotcon_representation_h repr, char **uri_path);
 274
 275 /**
 276  * @brief Sets resource type list to the Representation.
 277  *
 278  * @since_tizen 3.0
 279  * @remarks Stored list is replaced with @a types. If @a types is NULL, stored list is set
 280  * by NULL.
 281  * @param[in] repr The handle to the Representation
 282  * @param[in] types The resource type list
 283  *
 284  * @return 0 on success, otherwise a negative error value.
 285  * @retval #IOTCON_ERROR_NONE  Successful
 286  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 287  */
 288 int iotcon_representation_set_resource_types(iotcon_representation_h repr,
 289                 iotcon_resource_types_h types);
 290
 291 /**
 292  * @brief Gets list of resource type from the representation.
 293  *
 294  * @since_tizen 3.0
 295  *
 296  * @remarks @a types must not be released using iotcon_resource_types_destroy().
 297  *
 298  * @param[in] repr The representation handle
 299  * @param[out] types The list of resource types to get
 300  *
 301  * @return 0 on success, otherwise a negative error value.
 302  * @retval #IOTCON_ERROR_NONE  Successful
 303  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 304  */
 305 int iotcon_representation_get_resource_types(iotcon_representation_h repr,
 306                 iotcon_resource_types_h *types);
 307
 308 /**
 309  * @brief Sets interfaces to the representation.
 310  * @details If you set new interfaces, current interfaces value will be replaced with @a ifaces.\n
 311  * @a ifaces can be consist of multiple interface like
 312  * IOTCON_INTERFACE_LINK | IOTCON_INTERFACE_BATCH.
 313  *
 314  * @since_tizen 3.0
 315  *
 316  * @param[in] repr The representation handle
 317  * @param[in] ifaces The interfaces to set
 318  *
 319  * @return 0 on success, otherwise a negative error value.
 320  * @retval #IOTCON_ERROR_NONE  Successful
 321  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 322  */
 323 int iotcon_representation_set_resource_interfaces(iotcon_representation_h repr,
 324                 int ifaces);
 325
 326 /**
 327  * @brief Gets resource interfaces from the representation.
 328  *
 329  * @since_tizen 3.0
 330  *
 331  * @param[in] repr The representation handle
 332  * @param[out] ifaces The interfaces to get
 333  *
 334  * @return Interfaces to get. Interfaces may contain multiple interfaces.
 335  * @retval #IOTCON_INTERFACE_NONE  Not set
 336  * @retval Bitwise OR value which consists of iotcon_interface_e items
 337  */
 338 int iotcon_representation_get_resource_interfaces(iotcon_representation_h repr,
 339                 int *ifaces);
 340
 341 /**
 342  * @brief Sets a new state handle into the representation.
 343  *
 344  * @since_tizen 3.0
 345  *
 346  * @param[in] repr The representation handle
 347  * @param[in] state The state handle to set newly
 348  *
 349  * @return 0 on success, otherwise a negative error value.
 350  * @retval #IOTCON_ERROR_NONE  Successful
 351  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
 352  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 353  */
 354 int iotcon_representation_set_state(iotcon_representation_h repr, iotcon_state_h state);
 355
 356 /**
 357  * @brief Gets a state handle in the representation.
 358  *
 359  * @since_tizen 3.0
 360  *
 361  * @param[in] repr The representation handle
 362  * @param[in] state The state handle to get
 363  *
 364  * @return 0 on success, otherwise a negative error value.
 365  * @retval #IOTCON_ERROR_NONE  Successful
 366  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 367  */
 368 int iotcon_representation_get_state(iotcon_representation_h repr, iotcon_state_h *state);
 369
 370 /**
 371  * @brief Deletes state handle in the representation.
 372  *
 373  * @since_tizen 3.0
 374  *
 375  * @param[in] repr The representation handle
 376  *
 377  * @return 0 on success, otherwise a negative error value.
 378  * @retval #IOTCON_ERROR_NONE  Successful
 379  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 380  */
 381 int iotcon_representation_del_state(iotcon_representation_h repr);
 382
 383 /**
 384  * @brief Appends a new child representation on to the end of the parent representation
 385  * @details Duplicated child representation is allowed to append.
 386  *
 387  * @since_tizen 3.0
 388  *
 389  * @param[in] parent The parent representation handle
 390  * @param[in] child The child representation handle
 391  *
 392  * @return 0 on success, otherwise a negative error value.
 393  * @retval #IOTCON_ERROR_NONE  Successful
 394  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 395  */
 396 int iotcon_representation_append_child(iotcon_representation_h parent,
 397                 iotcon_representation_h child);
 398
 399 /**
 400  * @brief Removes a child representation from parent representation without freeing.
 401  *
 402  * @since_tizen 3.0
 403  *
 404  * @param[in] parent The parent representation handle
 405  * @param[in] child The child representation handle
 406  *
 407  * @return 0 on success, otherwise a negative error value.
 408  * @retval #IOTCON_ERROR_NONE  Successful
 409  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 410  */
 411 int iotcon_representation_remove_child(iotcon_representation_h parent,
 412                 iotcon_representation_h child);
 413
 414 /**
 415  * @brief Specifies the type of function passed to iotcon_representation_foreach_children()
 416  *
 417  * @since_tizen 3.0
 418  *
 419  * @param[in] child The child representation handle
 420  * @param[in] user_data The user data to pass to the function
 421  *
 422  * @return true to continue with the next iteration of the loop,
 423  * otherwise false to break out of the loop. #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP
 424  * are more friendly values for the return.
 425  *
 426  * @pre iotcon_representation_foreach_children() will invoke this callback function.
 427  *
 428  * @see iotcon_representation_foreach_children()
 429  *
 430  */
 431 typedef bool (*iotcon_children_cb)(iotcon_representation_h child, void *user_data);
 432
 433 /**
 434  * @brief Calls a function for each children representation of parent.
 435  * @details iotcon_children_cb() will be called for each child.
 436  *
 437  * @since_tizen 3.0
 438  *
 439  * @param[in] parent The parent representation handle
 440  * @param[in] cb The callback function to invoke
 441  * @param[in] user_data The user data to pass to the function
 442  *
 443  * @return 0 on success, otherwise a negative error value.
 444  * @retval #IOTCON_ERROR_NONE  Successful
 445  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 446  *
 447  * @post iotcon_children_cb() will be called for each child.
 448  *
 449  * @see iotcon_children_cb()
 450  */
 451 int iotcon_representation_foreach_children(iotcon_representation_h parent,
 452                 iotcon_children_cb cb, void *user_data);
 453
 454 /**
 455  * @brief Gets the number of children representation in the parent representation
 456  *
 457  * @since_tizen 3.0
 458  *
 459  * @param[in] parent The parent representation handle
 460  * @param[out] count The number of children representation
 461  *
 462  * @return 0 on success, otherwise a negative error value.
 463  * @retval #IOTCON_ERROR_NONE  Successful
 464  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 465  */
 466 int iotcon_representation_get_children_count(iotcon_representation_h parent,
 467                 unsigned int *count);
 468
 469 /**
 470  * @brief Gets the child representation at the given position.
 471  * @details Iterates over the parent until it reaches the @a pos-1 position.
 472  *
 473  * @since_tizen 3.0
 474  *
 475  * @remarks @a child must not be released using iotcon_representation_destroy().
 476  *
 477  * @param[in] parent The parent representation handle
 478  * @param[in] pos The position of the child representation
 479  * @param[out] child The handle to the child representation
 480  *
 481  * @return 0 on success, otherwise a negative error value.
 482  * @retval #IOTCON_ERROR_NONE  Successful
 483  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 484  * @retval #IOTCON_ERROR_NO_DATA  No data available
 485  */
 486 int iotcon_representation_get_nth_child(iotcon_representation_h parent, int pos,
 487                 iotcon_representation_h *child);
 488
 489 /**
 490  * @}
 491  */
 492
 493 #endif /* __IOT_CONNECTIVITY_MANAGER_STRUCT_REPRESENTATION_H__ */