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]	id	The information of the option
[in]	data	The data of the option
[in]	user_data	The 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]	options	The handle of the options
[in]	id	The ID of the option to insert
[in]	data	The string data to insert into the options

Returns:: 0 on success, otherwise a negative error value

Return values:

IOTCON_ERROR_NONE	Successful
IOTCON_ERROR_NOT_SUPPORTED	Not supported
IOTCON_ERROR_OUT_OF_MEMORY	Out of memory
IOTCON_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: iotcon_options_create(); iotcon_options_destroy(); iotcon_options_remove(); iotcon_options_lookup()

int iotcon_options_create ( iotcon_options_h * options )

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] options A newly allocated option handle

Returns:: 0 on success, otherwise a negative error value

Return values:

IOTCON_ERROR_NONE	Successful
IOTCON_ERROR_NOT_SUPPORTED	Not supported
IOTCON_ERROR_OUT_OF_MEMORY	Out of memory
IOTCON_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: iotcon_options_destroy(); iotcon_options_add(); iotcon_options_remove(); iotcon_options_lookup()

int iotcon_options_destroy ( iotcon_options_h options )

Destroys an option handle.

Since :: 3.0

Parameters:

[in] options The handle of the options

Returns:: 0 on success, otherwise a negative error value

Return values:

IOTCON_ERROR_NONE	Successful
IOTCON_ERROR_NOT_SUPPORTED	Not supported
IOTCON_ERROR_INVALID_PARAMETER	Invalid 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]	options	The handle of the options
[in]	cb	The callback function to get data
[in]	user_data	The user data to pass to the function

Returns:: 0 on success, otherwise a negative error value

Return values:

IOTCON_ERROR_NONE	Successful
IOTCON_ERROR_NOT_SUPPORTED	Not supported
IOTCON_ERROR_INVALID_PARAMETER	Invalid 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]	options	The handle of the options
[in]	id	The ID of the option to lookup
[out]	data	Found data from options

Returns:: 0 on success, otherwise a negative error value

Return values:

IOTCON_ERROR_NONE	Successful
IOTCON_ERROR_NOT_SUPPORTED	Not supported
IOTCON_ERROR_INVALID_PARAMETER	Invalid 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]	options	The handle of the options
[in]	id	The ID of the option to delete

Returns:: 0 on success, otherwise a negative error value

Return values:

IOTCON_ERROR_NONE	Successful
IOTCON_ERROR_NOT_SUPPORTED	Not supported
IOTCON_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: iotcon_options_create(); iotcon_options_destroy(); iotcon_options_add(); iotcon_options_lookup()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Function Documentation