Tizen Native API  5.0
Options

IoTCon Options provides API to manage options.

Required Header

#include <iotcon.h>

Overview

The IoTcon options API provides methods for managing vendor specific options of coap packet.
See more about coap packet in http://tools.ietf.org/html/rfc7252. Example (Client side) :

#include <iotcon.h>
...
static void _request_get_with_option(iotcon_remote_resource_h resource)
{
    int i;
    int ret;
    unsigned short opt_id = 3000;
    const char *opt_val = "12345";
    iotcon_options_h options = NULL;

    ..
    ret = iotcon_options_create(&options);
    if (IOTCON_ERROR_NONE != ret)
        return;

    ret = iotcon_options_add(options, opt_id, opt_val);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_options_destroy(options);
        return;
    }

    ret = iotcon_remote_resource_set_options(resource, options);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_options_destroy(options);
        return;
    }

    ret = iotcon_remote_resource_get(resource, NULL, _on_get, NULL);
    if (IOTCON_ERROR_NONE != ret) {
        iotcon_options_destroy(options);
        return;
    }

    iotcon_options_destroy(options);
    ...
}

Example (Server side) :

#include <iotcon.h>
...
static bool _options_foreach(unsigned short id, const char *data, void *user_data)
{
    // handle options
    return IOTCON_FUNC_CONTINUE;
}

static void _request_handler(iotcon_resource_h resource, iotcon_request_h request,
        void *user_data)
{
    int ret;
    iotcon_options_h options;

    ret = iotcon_request_get_options(request, &options);
    if (IOTCON_ERROR_NONE == ret && options) {
        ret = iotcon_options_foreach(options, _options_foreach, NULL);
        if (IOTCON_ERROR_NONE != ret)
            return;
    }
    ...
}

Related Features

This API is related with the following features:

Functions

int iotcon_options_create (iotcon_options_h *options)
 Creates a new option handle.
int iotcon_options_destroy (iotcon_options_h options)
 Destroys an option handle.
int iotcon_options_add (iotcon_options_h options, unsigned short id, const char *data)
 Adds a new ID and a corresponding data into the options.
int iotcon_options_remove (iotcon_options_h options, unsigned short id)
 Removes the ID and its associated data from the options.
int iotcon_options_lookup (iotcon_options_h options, unsigned short id, char **data)
 Looks up data at the given ID from the options.
int iotcon_options_foreach (iotcon_options_h options, iotcon_options_foreach_cb cb, void *user_data)
 Gets all data of the options by invoking the callback function.

Typedefs

typedef bool(* iotcon_options_foreach_cb )(unsigned short id, const char *data, void *user_data)
 Specifies the type of function passed to iotcon_options_foreach().

Typedef Documentation

typedef bool(* iotcon_options_foreach_cb)(unsigned short id, const char *data, void *user_data)

Specifies the type of function passed to iotcon_options_foreach().

Since :
3.0
Parameters:
[in]idThe information of the option
[in]dataThe data of the option
[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_options_foreach() will invoke this callback function.
See also:
iotcon_options_foreach()

Function Documentation

int iotcon_options_add ( iotcon_options_h  options,
unsigned short  id,
const char *  data 
)

Adds a new ID and a corresponding data into the options.

Since :
3.0
Remarks:
iotcon_options_h can have up to 2 options.
Option ID is always situated between 2048 and 3000.
Length of option data is less than or equal to 15.
Parameters:
[in]optionsThe handle of the options
[in]idThe ID of the option to insert
[in]dataThe string data to insert into the options
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_options_create()
iotcon_options_destroy()
iotcon_options_remove()
iotcon_options_lookup()

Creates a new option handle.

Since :
3.0
Remarks:
You must destroy options by calling iotcon_options_destroy() if options is no longer needed.
Parameters:
[out]optionsA newly allocated option 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_options_destroy()
iotcon_options_add()
iotcon_options_remove()
iotcon_options_lookup()

Destroys an option handle.

Since :
3.0
Parameters:
[in]optionsThe handle of the options
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_options_create()
iotcon_options_add()
iotcon_options_remove()
iotcon_options_lookup()
int iotcon_options_foreach ( iotcon_options_h  options,
iotcon_options_foreach_cb  cb,
void *  user_data 
)

Gets all data of the options by invoking the callback function.

iotcon_options_foreach_cb() will be called for each option.
If iotcon_options_foreach_cb() returns false, iteration will be stopped.

Since :
3.0
Parameters:
[in]optionsThe handle of the options
[in]cbThe callback function to get data
[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_options_foreach_cb() will be called for each option.
See also:
iotcon_options_foreach_cb()
int iotcon_options_lookup ( iotcon_options_h  options,
unsigned short  id,
char **  data 
)

Looks up data at the given ID from the options.

Since :
3.0
Remarks:
data must not be released using free().
Parameters:
[in]optionsThe handle of the options
[in]idThe ID of the option to lookup
[out]dataFound data from options
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_options_create()
iotcon_options_destroy()
iotcon_options_add()
iotcon_options_remove()
int iotcon_options_remove ( iotcon_options_h  options,
unsigned short  id 
)

Removes the ID and its associated data from the options.

Since :
3.0
Parameters:
[in]optionsThe handle of the options
[in]idThe ID of the option to delete
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_options_create()
iotcon_options_destroy()
iotcon_options_add()
iotcon_options_lookup()