Tizen(Headless) Native API  6.5
Functions | Typedefs
IoTCon
Network

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]pinThe pin number which is generated automatically
[in]user_dataThe 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]cbThe callback function to invoke
[in]user_dataThe user data to pass to the function
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter
IOTCON_ERROR_ALREADYAlready done
IOTCON_ERROR_OUT_OF_MEMORYOut 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_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot 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_secondsSeconds for timeout
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid 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_pathThe path of SVR(Secure Virtual Resources) DB
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter
IOTCON_ERROR_PERMISSION_DENIEDPermission 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]intervalMilliseconds for polling interval
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid 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_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot 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]intervalMilliseconds for polling interval (must be in range from 1 to 999)
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid 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]cbThe callback function to invoke
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter
IOTCON_ERROR_NO_DATANo 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_secondsSeconds for timeout (must be in range from 1 to 3600)
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
iotcon_initialize() should be called to initialize.
See also:
iotcon_get_timeout()