Tizen Native API
5.5
|
The IoTCon API provides functions for IoT connectivity.
Required Header
#include <iotcon.h>
Overview
The iotcon module provides various features based on IoTivity project.
The IoTivity project is sponsored by the Open Connectivity Foundation a group of industry leaders who will be developing a standard specification and certification program to address these challenges.
See http://iotivity.org and http://openconnectivity.org for more information.
Resource
A Resource is a component in a server that can be viewed and controlled by another client.
There are different resource types, for example a temperature sensor, a light controller etc.
Resource registration
Registering a resource requires a URI and handler to process requests.
The URI path should be rooted. IoTCon will construct the fully qualified URI by adding the URI authority to the provided URI path.
For example, given a service running on port 54321 in a device at IP address 192.168.1.1, if the application registers a resource with a URI path "/light/1",
the resulting fully qualified URI is "oic://192.168.1.1:54321/light/1", which uniquely identifies the resource's location.
Note : Only one resource can be registered at a given URI.
Example :
#include <iotcon.h> ... static void _request_handler(iotcon_resource_h resource, iotcon_request_h request, void *user_data) { int ret; iotcon_request_type_e type; iotcon_response_h response; iotcon_representation_h resp_repr; ret = iotcon_request_get_request_type(request, &type); if (IOTCON_ERROR_NONE != ret) return; if (IOTCON_REQUEST_GET == type) { ret = iotcon_response_create(request, &response); if (IOTCON_ERROR_NONE != ret) return; ret = iotcon_response_set_result(response, IOTCON_RESPONSE_OK); if (IOTCON_ERROR_NONE != ret) { iotcon_response_destroy(response); return; } ret = iotcon_representation_create(&resp_repr); if (IOTCON_ERROR_NONE != ret) { iotcon_response_destroy(response); return; } ret = iotcon_representation_set_uri_path(resp_repr, "/door/1"); if (IOTCON_ERROR_NONE != ret) { iotcon_representation_destroy(resp_repr); iotcon_response_destroy(response); return; } ret = iotcon_attributes_create(&attributes); if (IOTCON_ERROR_NONE != ret) { iotcon_representation_destroy(resp_repr); iotcon_response_destroy(response); return; } ret = iotcon_attributes_add_bool(resp_repr, "opened", true); if (IOTCON_ERROR_NONE != ret) { iotcon_attributes_destroy(attributes); iotcon_representation_destroy(resp_repr); iotcon_response_destroy(response); return; } ret = iotcon_response_set_representation(response, resp_repr); if (IOTCON_ERROR_NONE != ret) { iotcon_attributes_destroy(attributes); iotcon_representation_destroy(resp_repr); iotcon_response_destroy(response); return; } ret = iotcon_response_send(response); if (IOTCON_ERROR_NONE != ret) { iotcon_attributes_destroy(attributes); iotcon_representation_destroy(resp_repr); iotcon_response_destroy(response); return; } iotcon_attributes_destroy(attributes); iotcon_representation_destroy(resp_repr); iotcon_response_destroy(response); } } ... { int ret; uint8_t policies = (IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE); const char *uri_path = "/door/1"; const char *type = "org.tizen.door"; iotcon_resource_types_h resource_types; iotcon_resource_interfaces_h resource_ifaces; iotcon_resource_h resource = NULL; ret = iotcon_resource_types_create(&resource_types); if (IOTCON_ERROR_NONE != ret) return; ret = iotcon_resource_types_add(resource_types, type); if (IOTCON_ERROR_NONE != ret) { iotcon_resource_types_destroy(resource_types); return; } ret = iotcon_resource_interfaces_create(&resource_ifaces); if (IOTCON_ERROR_NONE != ret) iotcon_resource_types_destroy(resource_types); return; ret = iotcon_resource_interfaces_add(resource_ifaces, IOTCON_INTERFACE_DEFAULT); if (IOTCON_ERROR_NONE != ret) { iotcon_resource_interfaces_destroy(resource_ifaces); iotcon_resource_types_destroy(resource_types); return; } ret = iotcon_resource_create(uri_path, resource_types, resource_ifaces, policies, _request_handler, NULL, &resource); if (IOTCON_ERROR_NONE != ret) { iotcon_resource_interfaces_destroy(resource_ifaces); iotcon_resource_types_destroy(resource_types); return; } iotcon_resource_interfaces_destroy(resource_ifaces); iotcon_resource_types_destroy(resource_types); }
Finding a resource.
This operation returns all resources of given type on the network service.
This operation is sent via multicast to all services.
If you specify filter resource type in the query, only exact matches will be responded.
Example :
#include <iotcon.h> static void _on_response_get(iotcon_remote_resource_h resource, iotcon_error_e err, iotcon_request_type_e request_type, iotcon_response_h response, void *user_data) { // handle get from response } ... static bool _found_resource(iotcon_remote_resource_h resource, iotcon_error_e result, void *user_data) { int ret; char *resource_uri_path; char *resource_host; char *device_id; iotcon_query_h query; iotcon_resource_types_h resource_types; iotcon_resource_interfaces_h resource_interfaces; iotcon_remote_resource_h resource_clone = NULL; if (IOTCON_ERROR_NONE != result) return IOTCON_FUNC_STOP; ret = iotcon_remote_resource_get_uri_path(resource, &resource_uri_path); if (IOTCON_ERROR_NONE != ret) return IOTCON_FUNC_CONTINUE; ret = iotcon_remote_resource_get_device_id(resource, &device_id); if (IOTCON_ERROR_NONE != ret) return IOTCON_FUNC_CONTINUE; ret = iotcon_remote_resource_get_host_address(resource, &resource_host); if (IOTCON_ERROR_NONE != ret) return IOTCON_FUNC_CONTINUE; ret = iotcon_remote_resource_get_interfaces(resource, &resource_interfaces); if (IOTCON_ERROR_NONE != ret) return IOTCON_FUNC_CONTINUE; ret = iotcon_remote_resource_get_types(resource, &resource_types); if (IOTCON_ERROR_NONE != ret) return IOTCON_FUNC_CONTINUE; ret = iotcon_query_create(&query); if (IOTCON_ERROR_NONE != ret) return IOTCON_FUNC_CONTINUE; ret = iotcon_query_add(query, "key", "value"); if (IOTCON_ERROR_NONE != ret) return IOTCON_FUNC_CONTINUE; ret = iotcon_remote_resource_clone(resource, &resource_clone); if (IOTCON_ERROR_NONE != ret) { iotcon_query_destroy(query); return IOTCON_FUNC_CONTINUE; } ret = iotcon_remote_resource_get(resource_clone, query, _on_response_get, NULL); if (IOTCON_ERROR_NONE != ret) { iotcon_query_destroy(query); return IOTCON_FUNC_CONTINUE; } iotcon_query_destroy(query); return IOTCON_FUNC_CONTINUE; } ... { int ret; const char *type = "org.tizen.door"; ret = iotcon_find_resource(IOTCON_MULTICAST_ADDRESS, IOTCON_CONNECTIVITY_IPV4, type, false, _found_resource, NULL); if (IOTCON_ERROR_NONE != ret) return; }
Observing resource
This operation fetches and registers as an observer for the value of simple specific resource.
An observable resource can handle any number of observers.
If the server responds with a success code, the registration is considered successful.
Notifications from the server to the client may be confirmable or non-confirmable.
If the client returns a RST message, the observation registration should be dropped immediately.
If the client fails to acknowledge a number of confirmable requests, the server should assume that the client has abandoned the observation and drop the registration.
If the observed resource is removed, the server sends a NOTFOUND status to all observers.
If an observed resource fails to notify a client before the max-age of a resource value update, the client should attempt to re-register the observation.
Example (Server side) :
#include <iotcon.h> ... static iotcon_resource_h _door_handle; static iotcon_observers_h _observers; ... static void _request_handler(iotcon_request_h request, void *user_data) { int ret; int observe_id; iotcon_observe_type_e observe_type; ret = iotcon_request_get_observe_type(request, &observe_type); if (IOTCON_ERROR_NONE != ret) return; if (IOTCON_OBSERVE_REGISTER == observe_type) { int observe_id; ret = iotcon_request_get_observe_id(request, &observe_id); if (IOTCON_ERROR_NONE != ret) return; if (NULL == _observers) { ret = iotcon_observers_create(&_observers); if (IOTCON_ERROR_NONE != ret) return; } ret = iotcon_observers_add(_observers, observe_id); if (IOTCON_ERROR_NONE != ret) return; } else if (IOTCON_OBSERVE_DEREGISTER == observe_type) { int observe_id; if (NULL == _observers) return; ret = iotcon_request_get_observe_id(request, &observe_id); if (IOTCON_ERROR_NONE != ret) return; ret = iotcon_observers_remove(_observers, observe_id); if (IOTCON_ERROR_NONE != ret) return; } } ... { int ret; uint8_t policies = (IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE); const char *uri_path = "/door/1"; const char *type = "org.tizen.door"; iotcon_resource_types_h resource_types; iotcon_resource_interfaces_h resource_ifaces; ret = iotcon_resource_types_create(&resource_types); if (IOTCON_ERROR_NONE != ret) return; ret = iotcon_resource_types_add(resource_types, type); if (IOTCON_ERROR_NONE != ret) { iotcon_resource_types_destroy(resource_types); return; } ret = iotcon_resource_interfaces_create(&resource_ifaces); if (IOTCON_ERROR_NONE != ret) iotcon_resource_types_destroy(resource_types); return; ret = iotcon_resource_interfaces_add(resource_ifaces, IOTCON_INTERFACE_DEFAULT); if (IOTCON_ERROR_NONE != ret) { iotcon_resource_interfaces_destroy(resource_ifaces); iotcon_resource_types_destroy(resource_types); return; } ret = iotcon_resource_create(uri_path, resource_types, resource_ifaces, policies, _request_handler, NULL, &_door_handle); if (IOTCON_ERROR_NONE != ret) { iotcon_resource_interfaces_destroy(resource_ifaces); iotcon_resource_types_destroy(resource_types); return; } iotcon_resource_interfaces_destroy(resource_ifaces); iotcon_resource_types_destroy(resource_types); } ... { int ret; iotcon_representation_h repr; ret = iotcon_representation_create(&resp_repr); if (IOTCON_ERROR_NONE != ret) { return; } ret = iotcon_resource_notify(_door_handle, resp_repr, _observers, IOTCON_QOS_HIGH); if (IOTCON_ERROR_NONE != ret) { iotcon_representation_destroy(resp_repr); return; } iotcon_representation_destroy(resp_repr); }
Example (Client side) :
#include <iotcon.h> ... static iotcon_remote_resource_h _door_resource; ... static void _on_response_observe(iotcon_remote_resource_h resource, iotcon_error_e err, iotcon_request_type_e request_type, iotcon_response_h response, void *user_data) { } ... { int ret; ret = iotcon_remote_resource_observe_register(door_resource, IOTCON_OBSERVE_ACCEPT_OUT_OF_ORDER, NULL, _on_response_observe, NULL); if (IOTCON_ERROR_NONE != ret) return; }
Related Features
This API is related with the following features:
- http://tizen.org/feature/iot.ocf
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.
Functions | |
int | iotcon_initialize (const char *file_path) |
Initializes IoTCon. | |
int | iotcon_deinitialize (void) |
Deinitializes IoTCon. | |
int | iotcon_get_timeout (int *timeout_seconds) |
Gets the timeout seconds of asynchronous API. | |
int | iotcon_set_timeout (int timeout_seconds) |
Sets the timeout seconds of asynchronous APIs. | |
int | iotcon_polling_get_interval (int *interval) |
Gets the polling interval(milliseconds) of IoTCon. | |
int | iotcon_polling_set_interval (int interval) |
Sets the polling interval(milliseconds) of IoTCon. | |
int | iotcon_polling_invoke (void) |
Invokes a next message from a queue for receiving messages from others immediately. | |
int | iotcon_add_generated_pin_cb (iotcon_generated_pin_cb cb, void *user_data) |
Adds callback to show pin number which is generated automatically. | |
int | iotcon_remove_generated_pin_cb (iotcon_generated_pin_cb cb) |
Removes callback to show pin number which is generated automatically. | |
Typedefs | |
typedef void(* | iotcon_generated_pin_cb )(const char *pin, void *user_data) |
Specifies the type of function passed to iotcon_add_generated_pin_cb(). |
Typedef Documentation
typedef void(* iotcon_generated_pin_cb)(const char *pin, void *user_data) |
Specifies the type of function passed to iotcon_add_generated_pin_cb().
When a provisioning tool calls the function for registering this device, it is called, immediately.
- Since :
- 3.0
- Parameters:
-
[in] pin The pin number which is generated automatically [in] user_data The user data to pass to the function
- Precondition:
- The callback must be registered using iotcon_add_generated_pin_cb()
Enumeration Type Documentation
enum iotcon_error_e |
Enumeration for IoTCon error code.
- Since :
- 3.0
- Enumerator:
Function Documentation
int iotcon_add_generated_pin_cb | ( | iotcon_generated_pin_cb | cb, |
void * | user_data | ||
) |
Adds callback to show pin number which is generated automatically.
When a provisioning tool tries to register this device using random pin based
ownership transfer method, it makes pin number which is generated automatically be shown.
- Since :
- 3.0
- Parameters:
-
[in] cb The callback function to invoke [in] user_data The user data to pass to the function
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IOTCON_ERROR_NONE Successful IOTCON_ERROR_NOT_SUPPORTED Not supported IOTCON_ERROR_INVALID_PARAMETER Invalid parameter IOTCON_ERROR_ALREADY Already done IOTCON_ERROR_OUT_OF_MEMORY Out of memory
- Precondition:
- iotcon_initialize() should be called to initialize.
- Postcondition:
- When the device is registered by provisioning tool, iotcon_generated_pin_cb() will be called.
- See also:
- iotcon_remove_generated_pin_cb()
int iotcon_deinitialize | ( | void | ) |
Deinitializes IoTCon.
Frees the resources allocated to IoTCon.
- Since :
- 3.0
- Remarks:
- This function must be called if IoTCon API is no longer needed.
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IOTCON_ERROR_NONE Successful IOTCON_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- iotcon_initialize() should be called to initialize.
- See also:
- iotcon_initialize()
int iotcon_get_timeout | ( | int * | timeout_seconds | ) |
Gets the timeout seconds of asynchronous API.
This API get the timeout of iotcon_find_device_info(), iotcon_find_platform_info(), iotcon_find_resource(), iotcon_remote_resource_get(), iotcon_remote_resource_put(), iotcon_remote_resource_post() and iotcon_remote_resource_delete().
- Since :
- 3.0
- Parameters:
-
[out] timeout_seconds Seconds for timeout
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IOTCON_ERROR_NONE Successful IOTCON_ERROR_NOT_SUPPORTED Not supported IOTCON_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- iotcon_initialize() should be called to initialize.
- See also:
- iotcon_set_timeout()
int iotcon_initialize | ( | const char * | file_path | ) |
Initializes IoTCon.
Calls this function to start IoTCon.
- Since :
- 3.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/network.get
- Privilege:
- http://tizen.org/privilege/internet
- Remarks:
- The file_path point to a file for handling secure virtual resources. The file that is CBOR(Concise Binary Object Representation)-format must already exist in file_path. We recommend to use application-local file for file_path.
You must call iotcon_deinitialize() if IoTCon API is no longer needed.
- Parameters:
-
[in] file_path The path of SVR(Secure Virtual Resources) DB
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IOTCON_ERROR_NONE Successful IOTCON_ERROR_NOT_SUPPORTED Not supported IOTCON_ERROR_INVALID_PARAMETER Invalid parameter IOTCON_ERROR_PERMISSION_DENIED Permission denied
- See also:
- iotcon_deinitialize()
int iotcon_polling_get_interval | ( | int * | interval | ) |
Gets the polling interval(milliseconds) of IoTCon.
This API gets the polling interval of IoTCon. Default polling interval is 100 milliseconds.
- Since :
- 3.0
- Parameters:
-
[out] interval Milliseconds for polling interval
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IOTCON_ERROR_NONE Successful IOTCON_ERROR_NOT_SUPPORTED Not supported IOTCON_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- iotcon_initialize() should be called to initialize.
- See also:
- iotcon_set_timeout()
int iotcon_polling_invoke | ( | void | ) |
Invokes a next message from a queue for receiving messages from others immediately.
This API invokes a next message from a queue for receiving messages from others immediately.
After calling the API, it continues the polling with existing interval.
- Since :
- 3.0
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IOTCON_ERROR_NONE Successful IOTCON_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- iotcon_initialize() should be called to initialize.
int iotcon_polling_set_interval | ( | int | interval | ) |
Sets the polling interval(milliseconds) of IoTCon.
This API sets the polling interval of IoTCon. The closer to 0, the faster it operates. It is invoked immediately for changing the interval. Default polling interval is 100 milliseconds. If you want the faster operation, we recommend you set 10 milliseconds for polling interval.
- Since :
- 3.0
- Parameters:
-
[in] interval Milliseconds for polling interval (must be in range from 1 to 999)
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IOTCON_ERROR_NONE Successful IOTCON_ERROR_NOT_SUPPORTED Not supported IOTCON_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- iotcon_initialize() should be called to initialize.
- See also:
- iotcon_polling_get_interval()
Removes callback to show pin number which is generated automatically.
If this function is called, cb will be not called anymore.
For removing cb that is used at iotcon_add_generated_pin_cb() should be used.
- Since :
- 3.0
- Parameters:
-
[in] cb The callback function to invoke
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IOTCON_ERROR_NONE Successful IOTCON_ERROR_NOT_SUPPORTED Not supported IOTCON_ERROR_INVALID_PARAMETER Invalid parameter IOTCON_ERROR_NO_DATA No data available
- Precondition:
- iotcon_initialize() should be called to initialize.
- See also:
- iotcon_add_generated_pin_cb()
int iotcon_set_timeout | ( | int | timeout_seconds | ) |
Sets the timeout seconds of asynchronous APIs.
This API set the timeout of iotcon_find_device_info(), iotcon_find_platform_info(), iotcon_find_resource(), iotcon_remote_resource_get(), iotcon_remote_resource_put(), iotcon_remote_resource_post() and iotcon_remote_resource_delete().
Default timeout interval value is 30.
- Since :
- 3.0
- Parameters:
-
[in] timeout_seconds Seconds for timeout (must be in range from 1 to 3600)
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
IOTCON_ERROR_NONE Successful IOTCON_ERROR_NOT_SUPPORTED Not supported IOTCON_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- iotcon_initialize() should be called to initialize.
- See also:
- iotcon_get_timeout()