Tizen(Headless) Native API  6.5
Representation

IoTCon Representation provides API to manage representation.

Required Header

#include <iotcon.h>

Overview

The IoTCon Representation API provides data type of resp_repr handling.
A resp_repr is a payload of a request or a response.
It has uri_path, list of resource interfaces, list of resource types and its attributes.
Attributes have capabilities to store and retrieve integer, boolean, double, string, byte string, list, null, resp_repr.
A list is a container that includes number of data of same type.
It has capabilities to store and retrieve integer, boolean, double, string, byte string, list, null, resp_repr. Example :

#include <iotcon.h>
...
{
    int ret;
    iotcon_representation_h repr;
    iotcon_resource_types_h types;
    iotcon_list_h bright_step_list;

    ret = iotcon_representation_create(&resp_repr);
    if (IOTCON_ERROR_NONE != ret) {
        return;
    }

    ret = iotcon_representation_set_uri_path(resp_repr, "/a/light");
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_resource_types_create(&types);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_resource_types_add(types, "core.light");
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_resource_types_destroy(types);
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_representation_set_resource_types(resp_repr, types);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_resource_types_destroy(types);
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_representation_set_resource_interfaces(resp_repr, IOTCON_INTERFACE_LINK);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_resource_types_destroy(types);
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_attributes_add_str(resp_repr, "type", "lamp");
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_resource_types_destroy(types);
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_attributes_add_str(resp_repr, "where", "desk");
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_resource_types_destroy(types);
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_attributes_add_double(resp_repr, "default_bright", 200.0);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_resource_types_destroy(types);
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_attributes_add_str(resp_repr, "unit", "lux");
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_resource_types_destroy(types);
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_attributes_add_bool(resp_repr, "bright_step", true);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_resource_types_destroy(types);
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_list_create(IOTCON_TYPE_DOUBLE, &bright_step_list);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_resource_types_destroy(types);
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_list_add_double(bright_step_list, 100.0, -1);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_list_destroy(bright_step_list);
        iotcon_resource_types_destroy(types);
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_list_add_double(bright_step_list, 200.0, -1);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_list_destroy(bright_step_list);
        iotcon_resource_types_destroy(types);
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_list_add_double(bright_step_list, 300.0, -1);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_list_destroy(bright_step_list);
        iotcon_resource_types_destroy(types);
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_list_add_double(bright_step_list, 400.0, -1);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_list_destroy(bright_step_list);
        iotcon_resource_types_destroy(types);
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_list_add_double(bright_step_list, 500.0, -1);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_list_destroy(bright_step_list);
        iotcon_resource_types_destroy(types);
        iotcon_representation_destroy(resp_repr);
        return;
    }

    ret = iotcon_attributes_add_list(resp_repr, "bright_step_list", bright_step_list);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_list_destroy(bright_step_list);
        iotcon_resource_types_destroy(types);
        iotcon_representation_destroy(resp_repr);
        return;
    }

    iotcon_list_destroy(bright_step_list);
    iotcon_resource_types_destroy(types);
    iotcon_representation_destroy(resp_repr);
}

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_representation_create (iotcon_representation_h *repr)
 Creates a new Representation handle.
int iotcon_representation_destroy (iotcon_representation_h repr)
 Destroys a Representation.
int iotcon_representation_clone (const iotcon_representation_h src, iotcon_representation_h *dest)
 Clones from the source Representation.
int iotcon_representation_set_uri_path (iotcon_representation_h repr, const char *uri_path)
 Appends resource type name.
int iotcon_representation_get_uri_path (iotcon_representation_h repr, char **uri_path)
 Gets a URI path from the Representation.
int iotcon_representation_set_resource_types (iotcon_representation_h repr, iotcon_resource_types_h types)
 Sets resource type list to the Representation.
int iotcon_representation_get_resource_types (iotcon_representation_h repr, iotcon_resource_types_h *types)
 Gets list of resource type from the Representation.
int iotcon_representation_set_resource_interfaces (iotcon_representation_h repr, iotcon_resource_interfaces_h ifaces)
 Sets list of resource interfaces to the Representation.
int iotcon_representation_get_resource_interfaces (iotcon_representation_h repr, iotcon_resource_interfaces_h *ifaces)
 Gets list of resource interfaces from the Representation.
int iotcon_representation_set_attributes (iotcon_representation_h repr, iotcon_attributes_h attributes)
 Sets a new attributes handle into the Representation.
int iotcon_representation_get_attributes (iotcon_representation_h repr, iotcon_attributes_h *attributes)
 Gets the attributes handle in the Representation.
int iotcon_representation_add_child (iotcon_representation_h parent, iotcon_representation_h child)
 Adds a new child Representation on to the end of the parent Representation.
int iotcon_representation_remove_child (iotcon_representation_h parent, iotcon_representation_h child)
 Removes a child Representation from parent Representation without freeing.
int iotcon_representation_foreach_children (iotcon_representation_h parent, iotcon_children_cb cb, void *user_data)
 Calls a function for each child Representation of parent.
int iotcon_representation_get_child_count (iotcon_representation_h parent, unsigned int *count)
 Gets the number of child Representations in the parent Representation.
int iotcon_representation_get_nth_child (iotcon_representation_h parent, int pos, iotcon_representation_h *child)
 Gets the child Representation at the given position.

Typedefs

typedef bool(* iotcon_children_cb )(iotcon_representation_h child, void *user_data)
 Specifies the type of function passed to iotcon_representation_foreach_children().

Typedef Documentation

typedef bool(* iotcon_children_cb)(iotcon_representation_h child, void *user_data)

Specifies the type of function passed to iotcon_representation_foreach_children().

Since :
3.0
Parameters:
[in]childThe child Representation handle
[in]user_dataThe user data to pass to the function
Returns:
true to continue with the next iteration of the loop, otherwise false to break out of the loop IOTCON_FUNC_CONTINUE and IOTCON_FUNC_STOP are more friendly values for the return
Precondition:
iotcon_representation_foreach_children() will invoke this callback function.
See also:
iotcon_representation_foreach_children()

Function Documentation

Adds a new child Representation on to the end of the parent Representation.

Duplicated child Representation is allowed to append.

Since :
3.0
Parameters:
[in]parentThe parent Representation handle
[in]childThe child Representation handle
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter

Clones from the source Representation.

Makes a deep copy of a source Representation.

Since :
3.0
Remarks:
You must destroy dest by calling iotcon_representation_destroy() if dest is no longer needed.
Parameters:
[in]srcSource of Representation to be copied
[out]destClone of a source Representation
Returns:
Clone of a source Representation, otherwise NULL on failure
Return values:
iotcon_representation_hSuccess
NULLFailure

Creates a new Representation handle.

Since :
3.0
Remarks:
You must destroy repr by calling iotcon_representation_destroy() if repr is no longer needed.
Parameters:
[out]reprA newly allocated Representation handle
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_OUT_OF_MEMORYOut of memory
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter
See also:
iotcon_representation_destroy()

Destroys a Representation.

Releases Representation and its internal data.

Since :
3.0
Parameters:
[in]reprThe representation handle to free
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_representation_create()

Calls a function for each child Representation of parent.

iotcon_children_cb() will be called for each child.

Since :
3.0
Parameters:
[in]parentThe parent Representation handle
[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
Postcondition:
iotcon_children_cb() will be called for each child.
See also:
iotcon_children_cb()

Gets the attributes handle in the Representation.

Since :
3.0
Remarks:
attributes must not be released using iotcon_attributes_destroy().
Parameters:
[in]reprThe Representation handle
[in]attributesThe attributes handle to get
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter
int iotcon_representation_get_child_count ( iotcon_representation_h  parent,
unsigned int *  count 
)

Gets the number of child Representations in the parent Representation.

Since :
3.0
Parameters:
[in]parentThe parent Representation handle
[out]countThe number of child Representations
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter

Gets the child Representation at the given position.

Iterates over the parent until it reaches the pos-1 position.

Since :
3.0
Remarks:
child must not be released using iotcon_representation_destroy().
Parameters:
[in]parentThe parent Representation handle
[in]posThe position of the child Representation
[out]childThe handle to the child Representation
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

Gets list of resource interfaces from the Representation.

Since :
3.0
Remarks:
ifaces must not be released using iotcon_resource_interfaces_destroy().
Parameters:
[in]reprThe Representation handle
[out]ifacesThe list of resource interfaces to get
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter

Gets list of resource type from the Representation.

Since :
3.0
Remarks:
types must not be released using iotcon_resource_types_destroy().
Parameters:
[in]reprThe Representation handle
[out]typesThe list of resource types to get
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter
int iotcon_representation_get_uri_path ( iotcon_representation_h  repr,
char **  uri_path 
)

Gets a URI path from the Representation.

Since :
3.0
Remarks:
uri_path must not be released using free().
Parameters:
[in]reprThe Representation handle
[out]uri_pathThe URI path to get
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

Removes a child Representation from parent Representation without freeing.

Since :
3.0
Parameters:
[in]parentThe parent Representation handle
[in]childThe child Representation handle
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter

Sets a new attributes handle into the Representation.

Since :
3.0
Parameters:
[in]reprThe Representation handle
[in]attributesThe attributes handle to be set newly
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_OUT_OF_MEMORYOut of memory
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter

Sets list of resource interfaces to the Representation.

Since :
3.0
Remarks:
Stored list is replaced with ifaces. If ifaces is NULL, stored list is set to NULL.
Parameters:
[in]reprThe Representation handle
[in]ifacesThe list of resource interfaces
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter

Sets resource type list to the Representation.

Since :
3.0
Remarks:
Stored list is replaced with types. If types is NULL, stored list is set to NULL.
Parameters:
[in]reprThe handle to the Representation
[in]typesThe resource type list
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter
int iotcon_representation_set_uri_path ( iotcon_representation_h  repr,
const char *  uri_path 
)

Appends resource type name.

Since :
3.0
Remarks:
Stored string is replaced with uri_path. If uri_path is NULL, stored string is set to NULL.
Parameters:
[in]reprThe handle to the Representation
[in]uri_pathThe URI of resource
Returns:
0 on success, otherwise a negative error value
Return values:
IOTCON_ERROR_NONESuccessful
IOTCON_ERROR_NOT_SUPPORTEDNot supported
IOTCON_ERROR_OUT_OF_MEMORYOut of memory
IOTCON_ERROR_INVALID_PARAMETERInvalid parameter