2 * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef __TIZEN_NETWORK_IOTCON_DOC_H__
18 #define __TIZEN_NETWORK_IOTCON_DOC_H__
21 * @ingroup CAPI_NETWORK_FRAMEWORK
22 * @defgroup CAPI_IOT_CONNECTIVITY_MODULE Iotcon
24 * @brief The Iotcon API provides functions for IoT connectivity
26 * @section CAPI_IOT_CONNECTIVITY_MODULE_HEADER Required Header
27 * \#include <iotcon.h>
29 * @section CAPI_IOT_CONNECTIVITY_MODULE_OVERVIEW Overview
30 * The Iotcon API provides to register resources, discover resources and access them via
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
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.
51 static void _request_handler(iotcon_resource_h resource, iotcon_request_h request, void *user_data)
54 iotcon_request_type_e type;
55 iotcon_response_h response;
56 iotcon_representation_h resp_repr;
58 ret = iotcon_request_get_request_type(request, &type);
59 if (IOTCON_ERROR_NONE != ret)
62 if (IOTCON_REQUEST_GET == type) {
63 ret = iotcon_response_create(request, &response);
64 if (IOTCON_ERROR_NONE != ret)
67 ret = iotcon_response_set_result(response, IOTCON_RESPONSE_OK);
68 if (IOTCON_ERROR_NONE != ret) {
69 iotcon_response_destroy(response);
73 ret = iotcon_representation_create(&resp_repr);
74 if (IOTCON_ERROR_NONE != ret) {
75 iotcon_response_destroy(response);
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);
86 ret = iotcon_state_create(&state);
87 if (IOTCON_ERROR_NONE != ret) {
88 iotcon_representation_destroy(resp_repr);
89 iotcon_response_destroy(response);
93 ret = iotcon_state_add_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);
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);
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);
117 iotcon_state_destroy(state);
118 iotcon_representation_destroy(resp_repr);
119 iotcon_response_destroy(response);
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;
132 ret = iotcon_resource_types_create(&resource_types);
133 if (IOTCON_ERROR_NONE != ret)
136 ret = iotcon_resource_types_add(resource_types, type);
137 if (IOTCON_ERROR_NONE != ret) {
138 iotcon_resource_types_destroy(resource_types);
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);
149 iotcon_resource_types_destroy(resource_types);
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.
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)
164 // handle get from response
167 static void _found_resource(iotcon_remote_resource_h resource, iotcon_error_e result,
171 int resource_interfaces;
172 char *resource_uri_path;
175 iotcon_query_h query;
176 iotcon_resource_types_h resource_types;
177 iotcon_remote_resource_h resource_clone = NULL;
179 if (IOTCON_ERROR_NONE != result)
182 ret = iotcon_remote_resource_get_uri_path(resource, &resource_uri_path);
183 if (IOTCON_ERROR_NONE != ret)
186 ret = iotcon_remote_resource_get_device_id(resource, &device_id);
187 if (IOTCON_ERROR_NONE != ret)
190 ret = iotcon_remote_resource_get_host_address(resource, &resource_host);
191 if (IOTCON_ERROR_NONE != ret)
194 ret = iotcon_remote_resource_get_interfaces(resource, &resource_interfaces);
195 if (IOTCON_ERROR_NONE != ret)
198 ret = iotcon_remote_resource_get_types(resource, &resource_types);
199 if (IOTCON_ERROR_NONE != ret)
202 ret = iotcon_query_create(&query);
203 if (IOTCON_ERROR_NONE != ret)
206 ret = iotcon_query_add(query, "key", "value");
207 if (IOTCON_ERROR_NONE != ret)
210 ret = iotcon_remote_resource_clone(resource, &resource_clone);
211 if (IOTCON_ERROR_NONE != ret) {
212 iotcon_query_destroy(query);
216 ret = iotcon_remote_resource_get(resource_clone, query, _on_response_get, NULL);
217 if (IOTCON_ERROR_NONE != ret) {
218 iotcon_query_destroy(query);
222 iotcon_query_destroy(query);
227 const char *type = "org.tizen.door";
229 ret = iotcon_find_resource(IOTCON_MULTICAST_ADDRESS, IOTCON_CONNECTIVITY_IPV4, type,
230 _found_resource, NULL);
231 if (IOTCON_ERROR_NONE != ret)
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
248 * Example (Server side) :
252 static iotcon_resource_h _door_handle;
253 static iotcon_observers_h _observers;
255 static void _request_handler(iotcon_request_h request, void *user_data)
259 iotcon_observe_type_e observe_type;
261 ret = iotcon_request_get_observe_type(request, &observe_type);
262 if (IOTCON_ERROR_NONE != ret)
265 if (IOTCON_OBSERVE_REGISTER == observe_type) {
267 ret = iotcon_request_get_observe_id(request, &observe_id);
268 if (IOTCON_ERROR_NONE != ret)
271 if (NULL == _observers) {
272 ret = iotcon_observers_create(&_observers);
273 if (IOTCON_ERROR_NONE != ret)
276 ret = iotcon_observers_add(_observers, observe_id);
277 if (IOTCON_ERROR_NONE != ret)
279 } else if (IOTCON_OBSERVE_DEREGISTER == observe_type) {
282 if (NULL == _observers)
285 ret = iotcon_request_get_observe_id(request, &observe_id);
286 if (IOTCON_ERROR_NONE != ret)
289 ret = iotcon_observers_remove(_observers, observe_id);
290 if (IOTCON_ERROR_NONE != 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;
303 ret = iotcon_resource_types_create(&resource_types);
304 if (IOTCON_ERROR_NONE != ret)
307 ret = iotcon_resource_types_add(resource_types, type);
308 if (IOTCON_ERROR_NONE != ret) {
309 iotcon_resource_types_destroy(resource_types);
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);
320 iotcon_resource_types_destroy(resource_types);
325 iotcon_representation_h repr;
327 ret = iotcon_representation_create(&resp_repr);
328 if (IOTCON_ERROR_NONE != ret) {
332 ret = iotcon_resource_notify(_door_handle, resp_repr, _observers);
333 if (IOTCON_ERROR_NONE != ret) {
334 iotcon_representation_destroy(resp_repr);
338 iotcon_representation_destroy(resp_repr);
342 * Example (Client side) :
346 static iotcon_remote_resource_h _door_resource;
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)
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)
364 #endif /* __TIZEN_NETWORK_IOTCON_DOC_H__ */