Tizen(Headless) Native API  6.5

IoTCon Resource provides API to manage resource.

Required Header

#include <iotcon.h>

Overview

The IoTCon Resource API provides methods for managing handle and resource information. Example :

#include <iotcon.h>

static iotcon_resource_h _resource_room;

static void _room_request_handler(iotcon_resource_h resource, iotcon_request_h request, void *user_data)
{
    // handle request
    ...
}

static void _door_request_handler(iotcon_resource_h resource, iotcon_request_h request, void *user_data)
{
    // handle request
    ...
}

static void _create_resource()
{
    int ret;
    uint8_t policies;
    iotcon_resource_interfaces_h resource_ifaces = NULL;
    iotcon_resource_types_h resource_types = NULL;
    iotcon_resource_h resource_door = NULL;

    // 1. create room resource
    policies = IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE;

    ret = iotcon_resource_types_create(&resource_types);
    if (IOTCON_ERROR_NONE != ret)
        return;

    ret = iotcon_resource_types_add(resource_types, "org.tizen.room");
    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_interfaces_add(resource_ifaces, IOTCON_INTERFACE_LINK);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_resource_interfaces_destroy(resource_ifaces);
        iotcon_resource_types_destroy(resource_types);
        return;
    }

    ret = iotcon_resource_interfaces_add(resource_ifaces, IOTCON_INTERFACE_BATCH);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_resource_interfaces_destroy(resource_ifaces);
        iotcon_resource_types_destroy(resource_types);
        return;
    }

    ret = iotcon_resource_create("/room/1", resource_types, resource_ifaces,
            policies, _room_request_handler, NULL, &_resource_room);
    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);

    // 2. create door resource
    policies = IOTCON_RESOURCE_OBSERVABLE;

    ret = iotcon_resource_types_create(&resource_types);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_resource_destroy(_resource_room);
        _resource_room = NULL;
        return;
    }

    ret = iotcon_resource_types_add(resource_types, "org.tizen.door");
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_resource_types_destroy(resource_types);
        iotcon_resource_destroy(_resource_room);
        _resource_room = NULL;
        return;
    }

    ret = iotcon_resource_interfaces_create(&resource_ifaces);
    if (IOTCON_ERROR_NONE != ret)
        iotcon_resource_types_destroy(resource_types);
        iotcon_resource_destroy(_resource_room);
        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);
        iotcon_resource_destroy(_resource_room);
        return;
    }

    ret = iotcon_resource_create("/door/1", resource_types, resource_ifaces,
            policies, _door_request_handler, NULL, &resource_door);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_resource_interfaces_destroy(resource_ifaces);
        iotcon_resource_types_destroy(resource_types);
        iotcon_resource_destroy(_resource_room);
        _resource_room = NULL;
        return;
    }
    iotcon_resource_interfaces_destroy(resource_ifaces);
    iotcon_resource_types_destroy(resource_types);

    // 3. bind door resource to room resource
    ret = iotcon_resource_bind_child_resource(_resource_room, resource_door);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_resource_destroy(resource_door);
        iotcon_resource_destroy(_resource_room);
        _resource_room = NULL;
        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_resource_create (const char *uri_path, iotcon_resource_types_h res_types, iotcon_resource_interfaces_h ifaces, uint8_t policies, iotcon_request_handler_cb cb, void *user_data, iotcon_resource_h *resource_handle)
 Creates a resource handle and registers the resource in server.
int iotcon_resource_destroy (iotcon_resource_h resource_handle)
 Destroys the resource and releases its data.
int iotcon_resource_bind_interface (iotcon_resource_h resource, const char *iface)
 Binds an interface to the resource.
int iotcon_resource_bind_type (iotcon_resource_h resource_handle, const char *resource_type)
 Binds a type to the resource.
int iotcon_resource_set_request_handler (iotcon_resource_h resource, iotcon_request_handler_cb cb, void *user_data)
 Sets a request handler to the resource.
int iotcon_resource_bind_child_resource (iotcon_resource_h parent, iotcon_resource_h child)
 Binds a child resource into the parent resource.
int iotcon_resource_unbind_child_resource (iotcon_resource_h parent, iotcon_resource_h child)
 Unbinds a child resource from the parent resource.
int iotcon_resource_notify (iotcon_resource_h resource, iotcon_representation_h repr, iotcon_observers_h observers, iotcon_qos_e qos)
 Notifies specific clients that resource's attributes have changed.
int iotcon_resource_get_child_count (iotcon_resource_h resource, unsigned int *count)
 Gets the number of child resources of the resource.
int iotcon_resource_get_nth_child (iotcon_resource_h parent, int index, iotcon_resource_h *child)
 Gets the child resource at the given index in the parent resource.
int iotcon_resource_get_uri_path (iotcon_resource_h resource, char **uri_path)
 Gets an URI path of the resource.
int iotcon_resource_get_types (iotcon_resource_h resource, iotcon_resource_types_h *types)
 Gets the list of types in the resource.
int iotcon_resource_get_interfaces (iotcon_resource_h resource, iotcon_resource_interfaces_h *ifaces)
 Gets the interfaces of the resource.
int iotcon_resource_get_policies (iotcon_resource_h resource, uint8_t *policies)
 Gets the policies in the resource.

Typedefs

typedef void(* iotcon_request_handler_cb )(iotcon_resource_h resource, iotcon_request_h request, void *user_data)
 Specifies the type of function passed to iotcon_resource_create() and iotcon_resource_set_request_handler().

Typedef Documentation

typedef void(* iotcon_request_handler_cb)(iotcon_resource_h resource, iotcon_request_h request, void *user_data)

Specifies the type of function passed to iotcon_resource_create() and iotcon_resource_set_request_handler().

Called when server receives request from the client.

Since :
3.0
Parameters:
[in]resourceThe resource requested
[in]requestThe request from client
[in]user_dataThe user data to pass to the function
Precondition:
The callback must be registered using iotcon_resource_create()
See also:
iotcon_resource_create()
iotcon_resource_set_request_handler()

Function Documentation

Binds a child resource into the parent resource.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/internet
Parameters:
[in]parentThe handle of the parent resource
[in]childThe handle of the child resource to be added to the parent resource
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_SYSTEMSystem error
IOTCON_ERROR_PERMISSION_DENIEDPermission denied
Precondition:
iotcon_initialize() should be called to initialize.
See also:
iotcon_resource_create()
iotcon_resource_destroy()
iotcon_resource_bind_interface()
iotcon_resource_bind_type()
iotcon_resource_set_request_handler()
iotcon_resource_unbind_child_resource()
iotcon_request_handler_cb()
int iotcon_resource_bind_interface ( iotcon_resource_h  resource,
const char *  iface 
)

Binds an interface to the resource.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/internet
Remarks:
iface could be a value such as IOTCON_INTERFACE_DEFAULT.
Parameters:
[in]resourceThe handle of the resource
[in]ifaceThe interface to be bound to the resource
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_SYSTEMSystem error
IOTCON_ERROR_PERMISSION_DENIEDPermission denied
IOTCON_ERROR_ALREADYAlready done
Precondition:
iotcon_initialize() should be called to initialize.
See also:
iotcon_resource_create()
iotcon_resource_destroy()
iotcon_resource_bind_type()
iotcon_resource_set_request_handler()
iotcon_resource_bind_child_resource()
iotcon_resource_unbind_child_resource()
iotcon_request_handler_cb()
int iotcon_resource_bind_type ( iotcon_resource_h  resource_handle,
const char *  resource_type 
)

Binds a type to the resource.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/internet
Remarks:
The length of resource_type should be less than or equal to 61.
The resource_type must start with a lowercase alphabetic character, followed by a sequence of lowercase alphabetic, numeric, ".", or "-" characters, and contains no white space.
Parameters:
[in]resource_handleThe handle of the resource
[in]resource_typeThe type to be bound to the resource
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_SYSTEMSystem error
IOTCON_ERROR_PERMISSION_DENIEDPermission denied
IOTCON_ERROR_ALREADYAlready done
Precondition:
iotcon_initialize() should be called to initialize.
See also:
iotcon_resource_create()
iotcon_resource_destroy()
iotcon_resource_bind_interface()
iotcon_resource_set_request_handler()
iotcon_resource_bind_child_resource()
iotcon_resource_unbind_child_resource()
iotcon_request_handler_cb()
int iotcon_resource_create ( const char *  uri_path,
iotcon_resource_types_h  res_types,
iotcon_resource_interfaces_h  ifaces,
uint8_t  policies,
iotcon_request_handler_cb  cb,
void *  user_data,
iotcon_resource_h resource_handle 
)

Creates a resource handle and registers the resource in server.

Registers a resource specified by uri_path, res_types, ifaces which has properties in IoTCon server.
When client finds the registered resource, iotcon_request_handler_cb() will be called automatically.
uri_path format would be relative URI path like '/a/light'
res_types is a list of resource types. Create a iotcon_resource_types_h handle and add types string to it.
ifaces is a list of resource interfaces. Create a iotcon_resource_interfaces_h handle and add interfaces string to it.
policies also can contain multiple policies like IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE.
iotcon_request_handler_cb() will be called when receive CRUD request to the registered resource.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/internet
Remarks:
uri_path length must be less than 128.
You must destroy resource by calling iotcon_resource_destroy() if resource is no longer needed.
Parameters:
[in]uri_pathThe URI path of the resource
[in]res_typesThe list of type of the resource
[in]ifacesThe list of interface of the resource
[in]policiesThe policies of the resource
Set of iotcon_resource_policy_e
[in]cbThe request handler callback function
[in]user_dataThe user data to pass to the callback function
[out]resource_handleThe handle of the resource
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_IOTIVITYIoTivity errors
IOTCON_ERROR_OUT_OF_MEMORYOut of memory
IOTCON_ERROR_PERMISSION_DENIEDPermission denied
Precondition:
iotcon_initialize() should be called to initialize.
Postcondition:
When the resource receive CRUD request, iotcon_request_handler_cb() will be called.
See also:
iotcon_resource_destroy()
iotcon_resource_bind_interface()
iotcon_resource_bind_type()
iotcon_resource_set_request_handler()
iotcon_resource_bind_child_resource()
iotcon_resource_unbind_child_resource()
iotcon_request_handler_cb()
int iotcon_resource_destroy ( iotcon_resource_h  resource_handle)

Destroys the resource and releases its data.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/internet
Remarks:
When a normal variable is used, there is only permission denied error. If the errors of this API are not handled, then you must check an application has the privileges for the API.
Parameters:
[in]resource_handleThe handle of the resource to be unregistered
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
Precondition:
iotcon_initialize() should be called to initialize.
See also:
iotcon_resource_create()
iotcon_resource_bind_interface()
iotcon_resource_bind_type()
iotcon_resource_set_request_handler()
iotcon_resource_bind_child_resource()
iotcon_resource_unbind_child_resource()
iotcon_request_handler_cb()
int iotcon_resource_get_child_count ( iotcon_resource_h  resource,
unsigned int *  count 
)

Gets the number of child resources of the resource.

Since :
3.0
Parameters:
[in]resourceThe handle of the resource
[out]countThe number of child resources
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter
See also:
iotcon_resource_get_nth_child()
iotcon_resource_get_uri_path()
iotcon_resource_get_types()
iotcon_resource_get_interfaces()
iotcon_resource_get_policies()

Gets the interfaces of the resource.

Since :
3.0
Remarks:
ifaces must not be released using iotcon_resource_interfaces_destroy().
Parameters:
[in]resourceThe handle of the resource
[out]ifacesThe interfaces of the resource
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter
See also:
iotcon_resource_get_child_count()
iotcon_resource_get_nth_child()
iotcon_resource_get_uri_path()
iotcon_resource_get_types()
iotcon_resource_get_policies()
int iotcon_resource_get_nth_child ( iotcon_resource_h  parent,
int  index,
iotcon_resource_h child 
)

Gets the child resource at the given index in the parent resource.

Since :
3.0
Remarks:
child must not be released using iotcon_resource_destroy().
Parameters:
[in]parentThe handle of the parent resource
[in]indexThe index of the child resource
[out]childThe child resource at the index
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
See also:
iotcon_resource_get_child_count()
iotcon_resource_get_uri_path()
iotcon_resource_get_types()
iotcon_resource_get_interfaces()
iotcon_resource_get_policies()
int iotcon_resource_get_policies ( iotcon_resource_h  resource,
uint8_t *  policies 
)

Gets the policies in the resource.

policies can contain multiple policies like IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE.

Since :
3.0
Parameters:
[in]resourceThe handle of the resource
[out]policiesThe policies of resource
Set of iotcon_resource_policy_e
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter
See also:
iotcon_resource_get_child_count()
iotcon_resource_get_nth_child()
iotcon_resource_get_uri_path()
iotcon_resource_get_types()
iotcon_resource_get_interfaces()

Gets the list of types in the resource.

Since :
3.0
Remarks:
types must not be released using iotcon_resource_types_destroy().
Parameters:
[in]resourceThe handle of the resource
[out]typesThe types of the resource
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter
See also:
iotcon_resource_get_child_count()
iotcon_resource_get_nth_child()
iotcon_resource_get_uri_path()
iotcon_resource_get_interfaces()
iotcon_resource_get_policies()
int iotcon_resource_get_uri_path ( iotcon_resource_h  resource,
char **  uri_path 
)

Gets an URI path of the resource.

Since :
3.0
Remarks:
uri_path must not be released using free().
Parameters:
[in]resourceThe handle of the resource
[out]uri_pathThe URI path of the resource
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter
See also:
iotcon_resource_get_child_count()
iotcon_resource_get_nth_child()
iotcon_resource_get_types()
iotcon_resource_get_interfaces()
iotcon_resource_get_policies()

Notifies specific clients that resource's attributes have changed.

If observers is NULL, the msg will notify to all observers.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/internet
Parameters:
[in]resourceThe handle of the resource
[in]reprThe handle of the representation
[in]observersThe handle of the observers
[in]qosThe quality of service for message transfer
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_REPRESENTATIONRepresentation error
IOTCON_ERROR_SYSTEMSystem error
IOTCON_ERROR_PERMISSION_DENIEDPermission denied
Precondition:
iotcon_initialize() should be called to initialize.
See also:
iotcon_remote_resource_observe_cb()
iotcon_remote_resource_observe_register()
iotcon_remote_resource_observe_deregister()
iotcon_observers_create()
iotcon_observers_destroy()
iotcon_observers_add()
iotcon_observers_remove()

Sets a request handler to the resource.

When the resource receive CRUD request, iotcon_request_handler_cb() will be called.

Since :
3.0
Remarks:
Registered callback function will be replaced with the new cb.
Parameters:
[in]resourceThe handle of the resource
[in]cbThe request handler to be bound to the resource
[in]user_dataThe user data to pass to the callback 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
See also:
iotcon_resource_create()
iotcon_resource_destroy()
iotcon_resource_bind_interface()
iotcon_resource_bind_type()
iotcon_resource_bind_child_resource()
iotcon_resource_unbind_child_resource()
iotcon_request_handler_cb()

Unbinds a child resource from the parent resource.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/internet
Parameters:
[in]parentThe handle of the parent resource
[in]childThe handle of the child resource to be unbound from the parent resource
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_SYSTEMSystem error
IOTCON_ERROR_PERMISSION_DENIEDPermission denied
IOTCON_ERROR_NO_DATANo data available
Precondition:
iotcon_initialize() should be called to initialize.
See also:
iotcon_resource_create()
iotcon_resource_destroy()
iotcon_resource_bind_interface()
iotcon_resource_bind_type()
iotcon_resource_set_request_handler()
iotcon_resource_bind_child_resource()
iotcon_request_handler_cb()