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]	resource	The resource requested
[in]	request	The request from client
[in]	user_data	The 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

int iotcon_resource_bind_child_resource	(	iotcon_resource_h	parent,
		iotcon_resource_h	child
	)

Binds a child resource into the parent resource.

Since :: 3.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/internet

Parameters:

[in]	parent	The handle of the parent resource
[in]	child	The 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_NONE	Successful
IOTCON_ERROR_NOT_SUPPORTED	Not supported
IOTCON_ERROR_INVALID_PARAMETER	Invalid parameter
IOTCON_ERROR_ALREADY	Already done
IOTCON_ERROR_SYSTEM	System error
IOTCON_ERROR_PERMISSION_DENIED	Permission 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]	resource	The handle of the resource
[in]	iface	The interface to be bound to the resource

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_SYSTEM	System error
IOTCON_ERROR_PERMISSION_DENIED	Permission denied
IOTCON_ERROR_ALREADY	Already 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_handle	The handle of the resource
[in]	resource_type	The type to be bound to the resource

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_SYSTEM	System error
IOTCON_ERROR_PERMISSION_DENIED	Permission denied
IOTCON_ERROR_ALREADY	Already 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_path	The URI path of the resource
[in]	res_types	The list of type of the resource
[in]	ifaces	The list of interface of the resource
[in]	policies	The policies of the resource Set of iotcon_resource_policy_e
[in]	cb	The request handler callback function
[in]	user_data	The user data to pass to the callback function
[out]	resource_handle	The handle of the resource

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_IOTIVITY	IoTivity errors
IOTCON_ERROR_OUT_OF_MEMORY	Out of memory
IOTCON_ERROR_PERMISSION_DENIED	Permission 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_handle The handle of the resource to be unregistered

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

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]	resource	The handle of the resource
[out]	count	The number of child resources

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

See also:: iotcon_resource_get_nth_child(); iotcon_resource_get_uri_path(); iotcon_resource_get_types(); iotcon_resource_get_interfaces(); iotcon_resource_get_policies()

int iotcon_resource_get_interfaces	(	iotcon_resource_h	resource,
		iotcon_resource_interfaces_h *	ifaces
	)

Gets the interfaces of the resource.

Since :: 3.0

Remarks:: ifaces must not be released using iotcon_resource_interfaces_destroy().

Parameters:

[in]	resource	The handle of the resource
[out]	ifaces	The interfaces of the resource

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

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]	parent	The handle of the parent resource
[in]	index	The index of the child resource
[out]	child	The child resource at the index

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

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]	resource	The handle of the resource
[out]	policies	The policies of resource Set of iotcon_resource_policy_e

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

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

int iotcon_resource_get_types	(	iotcon_resource_h	resource,
		iotcon_resource_types_h *	types
	)

Gets the list of types in the resource.

Since :: 3.0

Remarks:: types must not be released using iotcon_resource_types_destroy().

Parameters:

[in]	resource	The handle of the resource
[out]	types	The types of the resource

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

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]	resource	The handle of the resource
[out]	uri_path	The URI path of the resource

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

See also:: iotcon_resource_get_child_count(); iotcon_resource_get_nth_child(); iotcon_resource_get_types(); iotcon_resource_get_interfaces(); iotcon_resource_get_policies()

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.

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]	resource	The handle of the resource
[in]	repr	The handle of the representation
[in]	observers	The handle of the observers
[in]	qos	The quality of service for message transfer

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_REPRESENTATION	Representation error
IOTCON_ERROR_SYSTEM	System error
IOTCON_ERROR_PERMISSION_DENIED	Permission 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()

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.

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]	resource	The handle of the resource
[in]	cb	The request handler to be bound to the resource
[in]	user_data	The user data to pass to the callback 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

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

int iotcon_resource_unbind_child_resource	(	iotcon_resource_h	parent,
		iotcon_resource_h	child
	)

Unbinds a child resource from the parent resource.

Since :: 3.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/internet

Parameters:

[in]	parent	The handle of the parent resource
[in]	child	The 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_NONE	Successful
IOTCON_ERROR_NOT_SUPPORTED	Not supported
IOTCON_ERROR_INVALID_PARAMETER	Invalid parameter
IOTCON_ERROR_SYSTEM	System error
IOTCON_ERROR_PERMISSION_DENIED	Permission denied
IOTCON_ERROR_NO_DATA	No 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()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Function Documentation