Tizen Native API  5.0

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:

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