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()

See also:: iotcon_add_generated_pin_cb(); iotcon_remove_generated_pin_cb()

Enumeration Type Documentation

enum iotcon_error_e

Enumeration for IoTCon error code.

Since :: 3.0

Enumerator:

IOTCON_ERROR_NONE	Successful
IOTCON_ERROR_IO_ERROR	I/O error
IOTCON_ERROR_OUT_OF_MEMORY	Out of memory
IOTCON_ERROR_PERMISSION_DENIED	Permission denied
IOTCON_ERROR_NOT_SUPPORTED	Not supported
IOTCON_ERROR_INVALID_PARAMETER	Invalid parameter
IOTCON_ERROR_NO_DATA	No data available
IOTCON_ERROR_TIMEOUT	Time out
IOTCON_ERROR_IOTIVITY	IoTivity errors
IOTCON_ERROR_REPRESENTATION	Representation errors
IOTCON_ERROR_INVALID_TYPE	Invalid type
IOTCON_ERROR_ALREADY	Already
IOTCON_ERROR_SYSTEM	System errors

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()

int iotcon_remove_generated_pin_cb ( iotcon_generated_pin_cb cb )

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()

Required Header

Overview

Resource

Resource registration

Finding a resource.

Observing resource

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation