Tizen(Headed) Native API  6.5

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:

  • 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_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