Tizen Native API
State

IoTCon State provides API to manage attributes.

Required Header

#include <iotcon.h>

Overview

The IoTCon attributes API provides string key based hash table. 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;

    ret = iotcon_request_get_request_type(request, &type);
    if (IOTCON_ERROR_NONE != ret)
        return;

    if (IOTCON_REQUEST_GET == type) {
        iotcon_response_h response = NULL;
        iotcon_representation_h representation = NULL;
        iotcon_attributes_h attributes = NULL;

        ret = iotcon_response_create(request, &response);
        if (IOTCON_ERROR_NONE != ret)
            return;

        ret = iotcon_representation_create(&representation);
        if (IOTCON_ERROR_NONE != ret) {
            iotcon_response_destroy(response);
            return;
        }

        ...

        ret = iotcon_attributes_create(&attributes);
        if (IOTCON_ERROR_NONE != ret) {
            iotcon_representation_destroy(representation);
            iotcon_response_destroy(response);
            return;
        }

        ret = iotcon_attributes_add_bool(attributes, "power", true);
        if (IOTCON_ERROR_NONE != ret) {
            iotcon_attributes_destroy(attributes);
            iotcon_representation_destroy(representation);
            iotcon_response_destroy(response);
            return;
        }

        ret = itocon_attributes_add_int(attributes, "brightness", 75);
        if (IOTCON_ERROR_NONE != ret) {
            iotcon_attributes_destroy(attributes);
            iotcon_representation_destroy(representation);
            iotcon_response_destroy(response);
            return;
        }

        ret = iotcon_representation_set_attributes(representation, attributes);
        if (IOTCON_ERROR_NONE != ret) {
            iotcon_attributes_destroy(attributes);
            iotcon_representation_destroy(representation);
            iotcon_response_destroy(response);
            return;
        }

        ...

        ret = iotcon_response_set_representation(response, representation);
        if (IOTCON_ERROR_NONE != ret) {
            iotcon_attributes_destroy(attributes);
            iotcon_representation_destroy(representation);
            iotcon_response_destroy(response);
            return;
        }

        ret = iotcon_response_send(response);
        if (IOTCON_ERROR_NONE != ret) {
            iotcon_attributes_destroy(attributes);
            iotcon_representation_destroy(representation);
            iotcon_response_destroy(response);
            return;
        }

        iotcon_attributes_destroy(attributes);
        iotcon_representation_destroy(representation);
        iotcon_response_destroy(response);
    }
    ...
}

Related Features

This API is related with the following features:

Functions

int iotcon_attributes_create (iotcon_attributes_h *attributes)
 Creates a new attributes handle.
int iotcon_attributes_destroy (iotcon_attributes_h attributes)
 Destroys the attributes.
int iotcon_attributes_clone (iotcon_attributes_h attributes, iotcon_attributes_h *attributes_clone)
 Clones the attributes handle.
int iotcon_attributes_add_int (iotcon_attributes_h attributes, const char *key, int val)
 Adds a new key and integer value into the attributes.
int iotcon_attributes_add_bool (iotcon_attributes_h attributes, const char *key, bool val)
 Adds a new key and boolean value into the attributes.
int iotcon_attributes_add_double (iotcon_attributes_h attributes, const char *key, double val)
 Adds a new key and double value into the attributes.
int iotcon_attributes_add_str (iotcon_attributes_h attributes, const char *key, char *val)
 Adds a new key and string value into the attributes.
int iotcon_attributes_add_byte_str (iotcon_attributes_h attributes, const char *key, unsigned char *val, int len)
 Adds a new key and byte string value into the attributes.
int iotcon_attributes_add_list (iotcon_attributes_h attributes, const char *key, iotcon_list_h list)
 Adds a new key and list value into the attributes.
int iotcon_attributes_add_attributes (iotcon_attributes_h dest, const char *key, iotcon_attributes_h src)
 Adds a new key and attributes value into the attributes.
int iotcon_attributes_add_null (iotcon_attributes_h attributes, const char *key)
 Adds a new key with NULL value into the attributes.
int iotcon_attributes_get_int (iotcon_attributes_h attributes, const char *key, int *val)
 Gets the integer value from the given key.
int iotcon_attributes_get_bool (iotcon_attributes_h attributes, const char *key, bool *val)
 Gets the boolean value from the given key.
int iotcon_attributes_get_double (iotcon_attributes_h attributes, const char *key, double *val)
 Gets the double value from the given key.
int iotcon_attributes_get_str (iotcon_attributes_h attributes, const char *key, char **val)
 Gets the string value from the given key.
int iotcon_attributes_get_byte_str (iotcon_attributes_h attributes, const char *key, unsigned char **val, int *len)
 Gets the byte string value from the given key.
int iotcon_attributes_get_list (iotcon_attributes_h attributes, const char *key, iotcon_list_h *list)
 Gets the list value from the given key.
int iotcon_attributes_get_attributes (iotcon_attributes_h src, const char *key, iotcon_attributes_h *dest)
 Gets the attributes value from the given key.
int iotcon_attributes_is_null (iotcon_attributes_h attributes, const char *key, bool *is_null)
 Checks whether the value of given key is NULL or not.
int iotcon_attributes_remove (iotcon_attributes_h attributes, const char *key)
 Removes the key and its associated value from the attributes.
int iotcon_attributes_get_type (iotcon_attributes_h attributes, const char *key, iotcon_type_e *type)
 Gets the type of a value at the given key.
int iotcon_attributes_foreach (iotcon_attributes_h attributes, iotcon_attributes_cb cb, void *user_data)
 Calls a function for each element of attributes.
int iotcon_attributes_get_keys_count (iotcon_attributes_h attributes, unsigned int *count)
 Gets the number of keys in the attributes.

Typedefs

typedef bool(* iotcon_attributes_cb )(iotcon_attributes_h attributes, const char *key, void *user_data)
 Specifies the type of function passed to iotcon_attributes_foreach().

Typedef Documentation

typedef bool(* iotcon_attributes_cb)(iotcon_attributes_h attributes, const char *key, void *user_data)

Specifies the type of function passed to iotcon_attributes_foreach().

Since :
3.0
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
[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_attributes_foreach() will invoke this callback function.
See also:
iotcon_attributes_foreach()

Function Documentation

int iotcon_attributes_add_attributes ( iotcon_attributes_h  dest,
const char *  key,
iotcon_attributes_h  src 
)

Adds a new key and attributes value into the attributes.

If key already exists, current attributes will be replaced with new src.

Since :
3.0
Parameters:
[in]destThe attributes handle
[in]keyThe key
[in]srcThe attributes handle to 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
int iotcon_attributes_add_bool ( iotcon_attributes_h  attributes,
const char *  key,
bool  val 
)

Adds a new key and boolean value into the attributes.

If key is already exists, current value will be replaced with new val.

Since :
3.0
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
[in]valThe value
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
int iotcon_attributes_add_byte_str ( iotcon_attributes_h  attributes,
const char *  key,
unsigned char *  val,
int  len 
)

Adds a new key and byte string value into the attributes.

If key is already exists, current value will be replaced with new val.

Since :
3.0
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
[in]valThe value
[in]lenThe length of val
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
int iotcon_attributes_add_double ( iotcon_attributes_h  attributes,
const char *  key,
double  val 
)

Adds a new key and double value into the attributes.

If key is already exists, current value will be replaced with new val.

Since :
3.0
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
[in]valThe value
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
int iotcon_attributes_add_int ( iotcon_attributes_h  attributes,
const char *  key,
int  val 
)

Adds a new key and integer value into the attributes.

If key is already exists, current value will be replaced with new val.

Since :
3.0
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
[in]valThe value
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
int iotcon_attributes_add_list ( iotcon_attributes_h  attributes,
const char *  key,
iotcon_list_h  list 
)

Adds a new key and list value into the attributes.

If key already exists, current list will be replaced with new list.

Since :
3.0
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
[in]listThe value
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
int iotcon_attributes_add_null ( iotcon_attributes_h  attributes,
const char *  key 
)

Adds a new key with NULL value into the attributes.

If key already exists, current value will be replaced with NULL.

Since :
3.0
Parameters:
[in]attributesThe attributes handle
[in]keyThe key to be set NULL
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
int iotcon_attributes_add_str ( iotcon_attributes_h  attributes,
const char *  key,
char *  val 
)

Adds a new key and string value into the attributes.

If key is already exists, current value will be replaced with new val.

Since :
3.0
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
[in]valThe value
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
int iotcon_attributes_clone ( iotcon_attributes_h  attributes,
iotcon_attributes_h attributes_clone 
)

Clones the attributes handle.

Since :
3.0
Remarks:
You must destroy attributes_clone by calling iotcon_attributes_destroy() if attributes_clone is no longer needed.
Parameters:
[in]attributesThe attributes handle
[out]attributes_cloneThe cloned attributes 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_attributes_create()
iotcon_attributes_destroy()

Creates a new attributes handle.

Since :
3.0
Remarks:
You must destroy attributes by calling iotcon_attributes_destroy() if attributes is no longer needed.
Parameters:
[out]attributesA newly allocated attributes 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_attributes_destroy()

Destroys the attributes.

Releases attributes and its internal data.

Since :
3.0
Parameters:
[in]attributesThe attributes 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_attributes_create()
int iotcon_attributes_foreach ( iotcon_attributes_h  attributes,
iotcon_attributes_cb  cb,
void *  user_data 
)

Calls a function for each element of attributes.

iotcon_attributes_cb() will be called for each child.

Since :
3.0
Parameters:
[in]attributesThe attributes 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_attributes_cb() will be called for each child.
See also:
iotcon_attributes_cb()
int iotcon_attributes_get_attributes ( iotcon_attributes_h  src,
const char *  key,
iotcon_attributes_h dest 
)

Gets the attributes value from the given key.

Since :
3.0
Remarks:
attributes must not be released using iotcon_attributes_destroy().
Parameters:
[in]srcThe attributes handle
[in]keyThe key
[out]destThe attributes value at the key
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
IOTCON_ERROR_INVALID_TYPEInvalid type
int iotcon_attributes_get_bool ( iotcon_attributes_h  attributes,
const char *  key,
bool *  val 
)

Gets the boolean value from the given key.

Since :
3.0
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
[out]valThe boolean value
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
IOTCON_ERROR_INVALID_TYPEInvalid type
int iotcon_attributes_get_byte_str ( iotcon_attributes_h  attributes,
const char *  key,
unsigned char **  val,
int *  len 
)

Gets the byte string value from the given key.

Since :
3.0
Remarks:
val must not be released using free().
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
[out]valThe byte string value
[out]lenThe length of val
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
IOTCON_ERROR_INVALID_TYPEInvalid type
int iotcon_attributes_get_double ( iotcon_attributes_h  attributes,
const char *  key,
double *  val 
)

Gets the double value from the given key.

Since :
3.0
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
[out]valThe double value
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
IOTCON_ERROR_INVALID_TYPEInvalid type
int iotcon_attributes_get_int ( iotcon_attributes_h  attributes,
const char *  key,
int *  val 
)

Gets the integer value from the given key.

Since :
3.0
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
[out]valThe integer value
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
IOTCON_ERROR_INVALID_TYPEInvalid type
int iotcon_attributes_get_keys_count ( iotcon_attributes_h  attributes,
unsigned int *  count 
)

Gets the number of keys in the attributes.

Since :
3.0
Parameters:
[in]attributesThe attributes handle
[out]countThe number of keys
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_attributes_get_list ( iotcon_attributes_h  attributes,
const char *  key,
iotcon_list_h list 
)

Gets the list value from the given key.

Since :
3.0
Remarks:
list must not be released using iotcon_list_destroy().
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
[out]listThe list value
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
IOTCON_ERROR_INVALID_TYPEInvalid type
int iotcon_attributes_get_str ( iotcon_attributes_h  attributes,
const char *  key,
char **  val 
)

Gets the string value from the given key.

Since :
3.0
Remarks:
val must not be released using free().
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
[out]valThe string value
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
IOTCON_ERROR_INVALID_TYPEInvalid type
int iotcon_attributes_get_type ( iotcon_attributes_h  attributes,
const char *  key,
iotcon_type_e type 
)

Gets the type of a value at the given key.

It gets the data type of value related to the key in attributes. The data type could be one of iotcon_type_e.

Since :
3.0
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
[out]typeThe data type of value related to the key in attributes 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
IOTCON_ERROR_NO_DATANo data available
int iotcon_attributes_is_null ( iotcon_attributes_h  attributes,
const char *  key,
bool *  is_null 
)

Checks whether the value of given key is NULL or not.

Since :
3.0
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
[out]is_nulltrue if the type of the given key is null, otherwise false
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_attributes_remove ( iotcon_attributes_h  attributes,
const char *  key 
)

Removes the key and its associated value from the attributes.

Since :
3.0
Parameters:
[in]attributesThe attributes handle
[in]keyThe key
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