lib/include/iotcon-lite-resource.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_SERVER_LITE_RESOURCE_H__
  17 #define __IOT_CONNECTIVITY_MANAGER_SERVER_LITE_RESOURCE_H__
  18
  19 #include <iotcon-types.h>
  20
  21 /**
  22  * @file iotcon-lite-resource.h
  23  */
  24
  25 /**
  26  * @ingroup CAPI_IOT_CONNECTIVITY_SERVER_MODULE
  27  * @defgroup CAPI_IOT_CONNECTIVITY_SERVER_LITE_RESOURCE_MODULE Lite Resource
  28  *
  29  * @brief Iotcon Lite Resource provides API to encapsulate resources.
  30  *
  31  * @section CAPI_IOT_CONNECTIVITY_SERVER_LITE_RESOURCE_MODULE_HEADER Required Header
  32  *  \#include <iotcon.h>
  33  *
  34  * @section CAPI_IOT_CONNECTIVITY_SERVER_LITE_RESOURCE_MODULE_OVERVIEW Overview
  35  * This API provides that the users manages resources without request handler.
  36  * When client request by CRUD functions, internal default request handler will be invoked.
  37  * The default request handler will create response and send to client automatically.
  38  * When updated state by iotcon_lite_update_state(), changes will notify to observers.
  39  *
  40  * Example :
  41  * @code
  42 #include <iotcon.h>
  43 ...
  44 static iotcon_lite_resource_h _resource;
  45
  46 static void _create_light_resource()
  47 {
  48         int ret;
  49         iotcon_lite_resource_h resource = NULL;
  50         iotcon_resource_types_h resource_types = NULL;
  51         iotcon_state_h state = NULL;
  52
  53         ret = iotcon_resource_types_create(&resource_types);
  54         if (IOTCON_ERROR_NONE != ret)
  55                 return;
  56
  57         ret = iotcon_resource_types_add(resource_types, "org.tizen.light");
  58         if (IOTCON_ERROR_NONE != ret) {
  59                 iotcon_resource_types_destroy(resource_types);
  60                 return;
  61         }
  62
  63         ret = iotcon_state_create(&state);
  64         if (IOTCON_ERROR_NONE != ret) {
  65                 iotcon_resource_types_destroy(resource_types);
  66                 return;
  67         }
  68
  69         ret = iotcon_state_add_bool(state, "power", true);
  70         if (IOTCON_ERROR_NONE != ret) {
  71                 iotcon_state_destroy(state);
  72                 iotcon_resource_types_destroy(resource_types);
  73                 return;
  74         }
  75
  76         ret = iotcon_state_add_int(state, "brightness", 75);
  77         if (IOTCON_ERROR_NONE != ret) {
  78                 iotcon_state_destroy(state);
  79                 iotcon_resource_types_destroy(resource_types);
  80                 return;
  81         }
  82
  83         ret = iotcon_lite_resource_create("/light/1", resource_types,
  84                         IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE, state, &resource);
  85         if (IOTCON_ERROR_NONE != ret) {
  86                 iotcon_state_destroy(state);
  87                 iotcon_resource_types_destroy(resource_types);
  88                 return;
  89         }
  90
  91         iotcon_state_destroy(state);
  92         iotcon_resource_types_destroy(resource_types);
  93
  94         _resource = resource;
  95 }
  96
  97 static void _update_brightness(int brightness)
  98 {
  99         int ret;
 100         iotcon_state_h state = NULL;
 101         iotcon_state_h state_clone = NULL;
 102
 103         ret = iotcon_lite_resource_get_state(_resource, &state);
 104         if (IOTCON_ERROR_NONE != ret)
 105                 return;
 106
 107         ret = iotcon_state_clone(state, &state_clone);
 108         if (IOTCON_ERROR_NONE != ret)
 109                 return;
 110
 111         ret = iotcon_state_add_int(state_clone, "brightness", brightness);
 112         if (IOTCON_ERROR_NONE != ret) {
 113                 iotcon_state_destroy(state_clone);
 114                 return;
 115         }
 116
 117         ret = iotcon_lite_resource_update_state(_resource, state_clone);
 118         if (IOTCON_ERROR_NONE != ret) {
 119                 iotcon_state_destroy(state_clone);
 120                 return;
 121         }
 122
 123         iotcon_state_destroy(state_clone);
 124 }
 125
 126  * @endcode
 127  *
 128  * @{
 129  */
 130
 131 /**
 132  * @brief Creates a lite resource handle and registers the resource in server
 133  * @details Registers a resource specified by @a uri_path, @a res_types, @a state which have
 134  * @a properties in Iotcon server.\n
 135  * When client requests some operations, it send a response to client, automatically.\n
 136  *
 137  * @since_tizen 3.0
 138  * @privlevel public
 139  * @privilege %http://tizen.org/privilege/internet
 140  *
 141  * @remarks @a uri_path length must be less than or equal 36.\n
 142  * You must destroy @a resource_handle by calling iotcon_lite_resource_destroy()
 143  * if @a remote_handle is no longer needed.
 144  *
 145  * @param[in] uri_path The URI path of the resource.
 146  * @param[in] res_types The list of type of the resource.
 147  * @param[in] properties The property of the resource.
 148  * @param[in] state The state handle to set.
 149  * @param[out] resource_handle The handle of the resource
 150  *
 151  * @return 0 on success, otherwise a negative error value.
 152  * @retval #IOTCON_ERROR_NONE  Successful
 153  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 154  * @retval #IOTCON_ERROR_IOTIVITY  Iotivity errors
 155  * @retval #IOTCON_ERROR_DBUS  Dbus errors
 156  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
 157  * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied
 158  *
 159  * @post When the resource receive CRUD request, iotcon_request_handler_cb() will be called.
 160  *
 161  * @see iotcon_lite_resource_destroy()
 162  */
 163 int iotcon_lite_resource_create(const char *uri_path,
 164                 iotcon_resource_types_h res_types,
 165                 int properties,
 166                 iotcon_state_h state,
 167                 iotcon_lite_resource_h *resource_handle);
 168
 169 /**
 170  * @brief Destroys the resource and releases its data.
 171  *
 172  * @since_tizen 3.0
 173  * @privlevel public
 174  * @privilege %http://tizen.org/privilege/internet
 175  *
 176  * @remarks When a normal variable is used, there are only dbus error and permission\n
 177  * denied error. If the errors of this API are not handled, then you must check\n
 178  * whether dbus is running and an application have the privileges for the API.
 179  *
 180  * @param[in] resource The handle of the lite resource to be unregistered
 181  *
 182  * @return 0 on success, otherwise a negative error value.
 183  * @retval #IOTCON_ERROR_NONE  Successful
 184  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 185  * @retval #IOTCON_ERROR_DBUS  Dbus error
 186  * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied
 187  *
 188  * @see iotcon_lite_resource_create()
 189  */
 190 int iotcon_lite_resource_destroy(iotcon_lite_resource_h resource);
 191
 192 /**
 193  * @brief Updates state into the lite resource handle
 194  *
 195  * @since_tizen 3.0
 196  *
 197  * @param[in] resource The handle of the lite resource
 198  * @param[in] state The state handle to update
 199  *
 200  * @return 0 on success, otherwise a negative error value.
 201  * @retval #IOTCON_ERROR_NONE  Successful
 202  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 203  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
 204  *
 205  * @see iotcon_lite_resource_get_state()
 206  */
 207 int iotcon_lite_resource_update_state(iotcon_lite_resource_h resource,
 208                 iotcon_state_h state);
 209
 210 /**
 211  * @brief Gets state from the lite resource handle
 212  *
 213  * @since_tizen 3.0
 214  *
 215  * @remarks @a state must not be released using iotcon_state_destroy().
 216  *
 217  * @param[in] resource The handle of the lite resource
 218  * @param[out] state The state handle of the lite resource
 219  *
 220  * @return 0 on success, otherwise a negative error value.
 221  * @retval #IOTCON_ERROR_NONE  Successful
 222  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 223  *
 224  * @see iotcon_lite_resource_update_state()
 225  */
 226 int iotcon_lite_resource_get_state(iotcon_lite_resource_h resource,
 227                 iotcon_state_h *state);
 228
 229 /**
 230  * @}
 231  */
 232
 233 #endif /* __IOT_CONNECTIVITY_MANAGER_SERVER_LITE_RESOURCE_H__ */