doc/iotcon_doc.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
  17 #ifndef __TIZEN_NETWORK_IOTCON_DOC_H__
  18 #define __TIZEN_NETWORK_IOTCON_DOC_H__
  19
  20 /**
  21  * @ingroup CAPI_NETWORK_FRAMEWORK
  22  * @defgroup CAPI_IOT_CONNECTIVITY_MODULE Iotcon
  23  *
  24  * @brief The Iotcon API provides functions for IoT connectivity
  25  *
  26  * @section CAPI_IOT_CONNECTIVITY_MODULE_HEADER Required Header
  27  * \#include <iotcon.h>
  28  *
  29  * @section CAPI_IOT_CONNECTIVITY_MODULE_OVERVIEW Overview
  30  * The Iotcon API provides to register resources, discover resources and access them via
  31  * RESTful API.\n\n
  32  *
  33  * @subsection CAPI_IOT_CONNECTIVITY_MODULE_RESOURCE Resource
  34  * A Resource is a component in a server that can be viewed and conrolled by another client.\n
  35  * There are different resource types, for example a temperature sensor, a light controller etc.\n\n
  36  *
  37  * @subsection CAPI_IOT_CONNECTIVITY_MODULE_RESOURCE_REGISTRATION Resource registration
  38  * Registering a resource requires a URI and handler to process requests.\n
  39  * The URI path should be rooted. Iotcon will construct the fully qualified URI by adding
  40  * the URI authority to the provided URI path.\n
  41  * For example, given a service running on port 54321 in a device at IP address 192.168.1.1,
  42  * if the application registers a resource with a URI path "/light/1",\n
  43  * the resulting fully qualified URI is "oic://192.168.1.1:54321/light/1",
  44  * which uniquely identifies the resource's location.\n
  45  * Note : Only one resource can be registered at a given URI.
  46  *
  47  * Example :
  48  * @code
  49 #include <iotcon.h>
  50 ...
  51 static void _request_handler(iotcon_resource_h resource, iotcon_request_h request, void *user_data)
  52 {
  53         int ret;
  54         iotcon_request_type_e type;
  55         iotcon_response_h response;
  56         iotcon_representation_h resp_repr;
  57
  58         ret = iotcon_request_get_request_type(request, &type);
  59         if (IOTCON_ERROR_NONE != ret)
  60                 return;
  61
  62         if (IOTCON_REQUEST_GET == type) {
  63                 ret = iotcon_response_create(request, &response);
  64                 if (IOTCON_ERROR_NONE != ret)
  65                         return;
  66
  67                 ret = iotcon_response_set_result(response, IOTCON_RESPONSE_OK);
  68                 if (IOTCON_ERROR_NONE != ret) {
  69                         iotcon_response_destroy(response);
  70                         return;
  71                 }
  72
  73                 ret = iotcon_representation_create(&resp_repr);
  74                 if (IOTCON_ERROR_NONE != ret) {
  75                         iotcon_response_destroy(response);
  76                         return;
  77                 }
  78
  79                 ret = iotcon_representation_set_uri_path(resp_repr, "/door/1");
  80                 if (IOTCON_ERROR_NONE != ret) {
  81                         iotcon_representation_destroy(resp_repr);
  82                         iotcon_response_destroy(response);
  83                         return;
  84                 }
  85
  86                 ret = iotcon_state_create(&state);
  87                 if (IOTCON_ERROR_NONE != ret) {
  88                         iotcon_representation_destroy(resp_repr);
  89                         iotcon_response_destroy(response);
  90                         return;
  91                 }
  92
  93                 ret = iotcon_state_set_bool(resp_repr, "opened", true);
  94                 if (IOTCON_ERROR_NONE != ret) {
  95                         iotcon_state_destroy(state);
  96                         iotcon_representation_destroy(resp_repr);
  97                         iotcon_response_destroy(response);
  98                         return;
  99                 }
 100
 101                 ret = iotcon_response_set_representation(response, IOTCON_INTERFACE_DEFAULT, resp_repr);
 102                 if (IOTCON_ERROR_NONE != ret) {
 103                         iotcon_state_destroy(state);
 104                         iotcon_representation_destroy(resp_repr);
 105                         iotcon_response_destroy(response);
 106                         return;
 107                 }
 108
 109                 ret = iotcon_response_send(response);
 110                 if (IOTCON_ERROR_NONE != ret) {
 111                         iotcon_state_destroy(state);
 112                         iotcon_representation_destroy(resp_repr);
 113                         iotcon_response_destroy(response);
 114                         return;
 115                 }
 116
 117                 iotcon_state_destroy(state);
 118                 iotcon_representation_destroy(resp_repr);
 119                 iotcon_response_destroy(response);
 120         }
 121 }
 122 ...
 123 {
 124         int ret;
 125         int interfaces = IOTCON_INTERFACE_DEFAULT;
 126         int properties = (IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE);
 127         const char *uri_path = "/door/1";
 128         const char *type = "org.tizen.door";
 129         iotcon_resource_types_h resource_types;
 130         iotcon_resource_h resource = NULL;
 131
 132         ret = iotcon_resource_types_create(&resource_types);
 133         if (IOTCON_ERROR_NONE != ret)
 134                 return;
 135
 136         ret = iotcon_resource_types_add(resource_types, type);
 137         if (IOTCON_ERROR_NONE != ret) {
 138                 iotcon_resource_types_destroy(resource_types);
 139                 return;
 140         }
 141
 142         ret = iotcon_resource_create(uri_path, resource_types,
 143                         interfaces, properties, _request_handler, NULL, &resource);
 144         if (IOTCON_ERROR_NONE != ret) {
 145                 iotcon_resource_types_destroy(resource_types);
 146                 return;
 147         }
 148
 149         iotcon_resource_types_destroy(resource_types);
 150 }
 151  * @endcode
 152  *
 153  * @subsection CAPI_IOT_CONNECTIVITY_MODULE_FINDING_RESOURCE Finding a resource.
 154  * This operation returns all resources of given type on the network service.\n
 155  * This operation is sent via multicast to all services.\n
 156  * If you specify filter resource type in the query, only exact matches will be responded.
 157  *
 158  * Example :
 159  * @code
 160 #include <iotcon.h>
 161 static void _on_response_get(iotcon_remote_resource_h resource, iotcon_error_e err,
 162                 iotcon_request_type_e request_type, iotcon_response_h response, void *user_data)
 163 {
 164         // handle get from response
 165 }
 166 ...
 167 static void _found_resource(iotcon_remote_resource_h resource, iotcon_error_e result,
 168                 void *user_data)
 169 {
 170         int ret;
 171         int resource_interfaces;
 172         char *resource_uri_path;
 173         char *resource_host;
 174         char *device_id;
 175         iotcon_query_h query;
 176         iotcon_resource_types_h resource_types;
 177         iotcon_remote_resource_h resource_clone = NULL;
 178
 179         if (IOTCON_ERROR_NONE != result)
 180                 return;
 181
 182         ret = iotcon_remote_resource_get_uri_path(resource, &resource_uri_path);
 183         if (IOTCON_ERROR_NONE != ret)
 184                 return;
 185
 186         ret = iotcon_remote_resource_get_device_id(resource, &device_id);
 187         if (IOTCON_ERROR_NONE != ret)
 188                 return;
 189
 190         ret = iotcon_remote_resource_get_host_address(resource, &resource_host);
 191         if (IOTCON_ERROR_NONE != ret)
 192                 return;
 193
 194         ret = iotcon_remote_resource_get_interfaces(resource, &resource_interfaces);
 195         if (IOTCON_ERROR_NONE != ret)
 196                 return;
 197
 198         ret = iotcon_remote_resource_get_types(resource, &resource_types);
 199         if (IOTCON_ERROR_NONE != ret)
 200                 return;
 201
 202         ret = iotcon_query_create(&query);
 203         if (IOTCON_ERROR_NONE != ret)
 204                 return;
 205
 206         ret = iotcon_query_add(query, "key", "value");
 207         if (IOTCON_ERROR_NONE != ret)
 208                 return;
 209
 210         ret = iotcon_remote_resource_clone(resource, &resource_clone);
 211         if (IOTCON_ERROR_NONE != ret) {
 212                 iotcon_query_destroy(query);
 213                 return;
 214         }
 215
 216         ret = iotcon_remote_resource_get(resource_clone, query, _on_response_get, NULL);
 217         if (IOTCON_ERROR_NONE != ret) {
 218                 iotcon_query_destroy(query);
 219                 return;
 220         }
 221
 222         iotcon_query_destroy(query);
 223 }
 224 ...
 225 {
 226         int ret;
 227         const char *type = "org.tizen.door";
 228
 229         ret = iotcon_find_resource(IOTCON_MULTICAST_ADDRESS, IOTCON_CONNECTIVITY_IPV4, type,
 230                         _found_resource, NULL);
 231         if (IOTCON_ERROR_NONE != ret)
 232                 return;
 233 }
 234  * @endcode
 235  *
 236  * @subsection CAPI_IOT_CONNECTIVITY_MODULE_OBSERVING_RESOURCE Observing resource
 237  * This operation fetches and registers as an observer for the value of simple specific resource.\n
 238  * An observable resource can handle any number of observers.\n
 239  * If the server responds with a success code, the registration is considered successful.\n
 240  * Notifications from the server to the client may be confirmable or non-confirmable.\n
 241  * If the client returns a RST message, the observation registration should be dropped immediately.\n
 242  * If the client fails to acknowledge a number of confirmable requests,
 243  * the server should assume that the client has abandoned the observation and drop the registration.\n
 244  * If the observed resource is removed, the server sends a NOTFOUND status to all observers.\n
 245  * If an observed resource fails to notify a client before the max-age of a resource value update,
 246  * the client should attempt to re-register the observation.\n
 247  *
 248  * Example (Server side) :
 249  * @code
 250 #include <iotcon.h>
 251 ...
 252 static iotcon_resource_h _door_handle;
 253 static iotcon_observers_h _observers;
 254 ...
 255 static void _request_handler(iotcon_request_h request, void *user_data)
 256 {
 257         int ret;
 258         int observe_id;
 259         iotcon_observe_type_e observe_type;
 260
 261         ret = iotcon_request_get_observe_type(request, &observe_type);
 262         if (IOTCON_ERROR_NONE != ret)
 263                 return;
 264
 265         if (IOTCON_OBSERVE_REGISTER == observe_type) {
 266                 int observe_id;
 267                 ret = iotcon_request_get_observe_id(request, &observe_id);
 268                 if (IOTCON_ERROR_NONE != ret)
 269                         return;
 270
 271                 if (NULL == _observers) {
 272                         ret = iotcon_observers_create(&_observers);
 273                         if (IOTCON_ERROR_NONE != ret)
 274                                 return;
 275                 }
 276                 ret = iotcon_observers_add(_observers, observe_id);
 277                 if (IOTCON_ERROR_NONE != ret)
 278                         return;
 279         } else if (IOTCON_OBSERVE_DEREGISTER == observe_type) {
 280                 int observe_id;
 281
 282                 if (NULL == _observers)
 283                         return;
 284
 285                 ret = iotcon_request_get_observe_id(request, &observe_id);
 286                 if (IOTCON_ERROR_NONE != ret)
 287                         return;
 288
 289                 ret = iotcon_observers_remove(_observers, observe_id);
 290                 if (IOTCON_ERROR_NONE != ret)
 291                         return;
 292         }
 293 }
 294 ...
 295 {
 296         int ret;
 297         int interfaces = IOTCON_INTERFACE_DEFAULT;
 298         int properties = (IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE);
 299         const char *uri_path = "/door/1";
 300         const char *type = "org.tizen.door";
 301         iotcon_resource_types_h resource_types;
 302
 303         ret = iotcon_resource_types_create(&resource_types);
 304         if (IOTCON_ERROR_NONE != ret)
 305                 return;
 306
 307         ret = iotcon_resource_types_add(resource_types, type);
 308         if (IOTCON_ERROR_NONE != ret) {
 309                 iotcon_resource_types_destroy(resource_types);
 310                 return;
 311         }
 312
 313         ret = iotcon_resource_create(uri_path, resource_types,
 314                         interfaces, properties, _request_handler, NULL, &_door_handle);
 315         if (IOTCON_ERROR_NONE != ret) {
 316                 iotcon_resource_types_destroy(resource_types);
 317                 return;
 318         }
 319
 320         iotcon_resource_types_destroy(resource_types);
 321 }
 322 ...
 323 {
 324         int ret;
 325         iotcon_representation_h repr;
 326
 327         ret = iotcon_representation_create(&resp_repr);
 328         if (IOTCON_ERROR_NONE != ret) {
 329                 return;
 330         }
 331
 332         ret = iotcon_resource_notify(_door_handle, resp_repr, _observers);
 333         if (IOTCON_ERROR_NONE != ret) {
 334                 iotcon_representation_destroy(resp_repr);
 335                 return;
 336         }
 337
 338         iotcon_representation_destroy(resp_repr);
 339 }
 340  * @endcode
 341  *
 342  * Example (Client side) :
 343  * @code
 344 #include <iotcon.h>
 345 ...
 346 static iotcon_remote_resource_h _door_resource;
 347 ...
 348 static void _on_response_observe(iotcon_remote_resource_h resource, iotcon_error_e err,
 349                 iotcon_request_type_e request_type, iotcon_response_h response, void *user_data)
 350 {
 351 }
 352 ...
 353 {
 354         int ret;
 355         ret = iotcon_remote_resource_observe_register(door_resource, IOTCON_OBSERVE_ACCEPT_OUT_OF_ORDER, NULL,
 356                         _on_resopnse_observe, NULL);
 357         if (IOTCON_ERROR_NONE != ret)
 358                 return;
 359 }
 360  * @endcode
 361  *
 362  */
 363
 364 #endif /* __TIZEN_NETWORK_IOTCON_DOC_H__ */