Tizen Native API  5.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:

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