IoTCon Client provides API for client side.

Required Header

#include <iotcon.h>

Overview

This API set consists of client side API for Remote Resource.

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_add_presence_cb (const char host_address, iotcon_connectivity_type_e connectivity_type, const char resource_type, iotcon_presence_cb cb, void user_data, iotcon_presence_h presence_handle)
	Adds callback to a server to receive presence events.
int	iotcon_remove_presence_cb (iotcon_presence_h presence_handle)
	Removes callback to a server's presence events.
int	iotcon_presence_get_host_address (iotcon_presence_h presence, char **host_address)
	Gets host address from the presence handle.
int	iotcon_presence_get_connectivity_type (iotcon_presence_h presence, iotcon_connectivity_type_e *connectivity_type)
	Gets connectivity type from the presence handle.
int	iotcon_presence_get_resource_type (iotcon_presence_h presence, char **resource_type)
	Gets resource type from the presence handle.
int	iotcon_presence_response_get_result (iotcon_presence_response_h response, iotcon_presence_result_e *result)
	Gets result from the presence response handle.
int	iotcon_presence_response_get_trigger (iotcon_presence_response_h response, iotcon_presence_trigger_e *trigger)
	Gets trigger from the presence response handle.
int	iotcon_presence_response_get_host_address (iotcon_presence_response_h response, char **host_address)
	Gets host address from the presence response handle.
int	iotcon_presence_response_get_connectivity_type (iotcon_presence_response_h response, iotcon_connectivity_type_e *connectivity_type)
	Gets connectivity type from the presence response handle.
int	iotcon_presence_response_get_resource_type (iotcon_presence_response_h response, char **resource_type)
	Gets resource type from the presence response handle.
int	iotcon_find_resource (const char host_address, int connectivity_type, iotcon_query_h query, iotcon_found_resource_cb cb, void user_data)
	Finds resources asynchronously.
int	iotcon_find_device_info (const char host_address, int connectivity_type, iotcon_query_h query, iotcon_device_info_cb cb, void user_data)
	Finds the device information of remote server asynchronously.
int	iotcon_device_info_get_property (iotcon_device_info_h device_info, iotcon_device_info_e property, char **value)
	Gets device properties from the device information handle.
int	iotcon_find_platform_info (const char host_address, int connectivity_type, iotcon_query_h query, iotcon_platform_info_cb cb, void user_data)
	Finds the platform information of remote server asynchronously.
int	iotcon_platform_info_get_property (iotcon_platform_info_h platform_info, iotcon_platform_info_e property, char **value)
	Gets platform properties from the platform information handle.
Typedefs
typedef void(*	iotcon_presence_cb )(iotcon_presence_h presence, iotcon_error_e err, iotcon_presence_response_h response, void *user_data)
	Specifies the type of function passed to iotcon_add_presence_cb().
typedef bool(*	iotcon_found_resource_cb )(iotcon_remote_resource_h resource, iotcon_error_e result, void *user_data)
	Specifies the type of function passed to iotcon_find_resource().
typedef bool(*	iotcon_device_info_cb )(iotcon_device_info_h device_info, iotcon_error_e result, void *user_data)
	Specifies the type of function passed to iotcon_find_device_info().
typedef bool(*	iotcon_platform_info_cb )(iotcon_platform_info_h platform_info, iotcon_error_e result, void *user_data)
	Specifies the type of function passed to iotcon_find_platform_info().

Typedef Documentation

typedef bool(* iotcon_device_info_cb)(iotcon_device_info_h device_info, iotcon_error_e result, void *user_data)

Specifies the type of function passed to iotcon_find_device_info().

The result could be one of iotcon_error_e.

Since :: 3.0

Parameters:

[in]	device_info	The device information from remote server
[in]	result	The result code (`0` on success, otherwise a negative error value)
[in]	user_data	The user data to pass to the function

Returns:: true to continue to find device information, otherwise false to stop
IOTCON_FUNC_CONTINUE and IOTCON_FUNC_STOP are more friendly values for the return

Precondition:: iotcon_find_device_info() will invoke this callback function.

See also:: iotcon_find_device_info(); iotcon_device_info_get_property()

typedef bool(* iotcon_found_resource_cb)(iotcon_remote_resource_h resource, iotcon_error_e result, void *user_data)

Specifies the type of function passed to iotcon_find_resource().

Called when a resource is found from the remote server.
The resource completes its life cycle in the function. If you want to send requests(GET, PUT, POST, DELETE, and OBSERVE) on the resource, you must clone the resource using iotcon_remote_resource_clone().
The result could be one of iotcon_error_e.

Since :: 3.0

Parameters:

[in]	resource	The handle of resource which is found
[in]	result	The result code (Lesser than 0 on fail, otherwise a response result value)
[in]	user_data	The user data to pass to the function

Returns:: true to continue to find resource, otherwise false to stop
IOTCON_FUNC_CONTINUE and IOTCON_FUNC_STOP are more friendly values for the return

Precondition:: The callback must be registered using iotcon_find_resource()

See also:: iotcon_find_resource()

typedef bool(* iotcon_platform_info_cb)(iotcon_platform_info_h platform_info, iotcon_error_e result, void *user_data)

Specifies the type of function passed to iotcon_find_platform_info().

The result could be one of iotcon_error_e.

Since :: 3.0

Parameters:

[in]	platform_info	The platform information from remote server
[in]	result	The result code (`0` on success, otherwise a negative error value)
[in]	user_data	The user data to pass to the function

Returns:: true to continue to find platform information, otherwise false to stop
IOTCON_FUNC_CONTINUE and IOTCON_FUNC_STOP are more friendly values for the return

Precondition:: iotcon_find_platform_info() will invoke this callback function.

See also:: iotcon_find_platform_info(); iotcon_platform_info_get_property()

typedef void(* iotcon_presence_cb)(iotcon_presence_h presence, iotcon_error_e err, iotcon_presence_response_h response, void *user_data)

Specifies the type of function passed to iotcon_add_presence_cb().

Called when client receives presence events from the server. The response handle contains presence information.

Since :: 3.0

Parameters:

[in]	presence	The presence handle
[in]	err	The error code(`0` on success, otherwise a negative error value)
[in]	response	The presence response handle
[in]	user_data	The user data to pass to the function

Precondition:: The callback must be registered using iotcon_add_presence_cb().

See also:: iotcon_add_presence_cb(); iotcon_remove_presence_cb(); iotcon_presence_response_get_connectivity_type(); iotcon_presence_response_get_host_address(); iotcon_presence_response_get_resource_type(); iotcon_presence_response_get_result(); iotcon_presence_response_get_trigger()

Function Documentation

int iotcon_add_presence_cb	(	const char *	host_address,
		iotcon_connectivity_type_e	connectivity_type,
		const char *	resource_type,
		iotcon_presence_cb	cb,
		void *	user_data,
		iotcon_presence_h *	presence_handle
	)

Adds callback to a server to receive presence events.

Request to receive presence to an interested server's resource with resource_type.
If succeeded to subscribe, iotcon_presence_cb() will be invoked when the server sends presence.
A server sends presence events when adds/removes/alters a resource or start/stop presence.
host_address could be IOTCON_MULTICAST_ADDRESS for IPv4 multicast.

Since :: 3.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/internet

Remarks:: The length of resource_type should be less than or equal to 61.
The resource_type must start with a lowercase alphabetic character, followed by a sequence of lowercase alphabetic, numeric, ".", or "-" characters, and contains no white space.
You must destroy presence by calling iotcon_unsubscribe_presence() if presence is no longer needed.

Parameters:

[in]	host_address	The address or addressable name of the server
[in]	connectivity_type	The connectivity type
[in]	resource_type	A resource type that a client is interested in
[in]	cb	The callback function to invoke
[in]	user_data	The user data to pass to the function
[out]	presence_handle	The generated presence handle

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
IOTCON_ERROR_IOTIVITY	IoTivity errors
IOTCON_ERROR_OUT_OF_MEMORY	Out of memory
IOTCON_ERROR_PERMISSION_DENIED	Permission denied

Precondition:: iotcon_initialize() should be called to initialize.

Postcondition:: When the resource receive presence, iotcon_presence_cb() will be called.

See also:: iotcon_start_presence(); iotcon_stop_presence(); iotcon_remove_presence_cb(); iotcon_presence_cb()

int iotcon_device_info_get_property	(	iotcon_device_info_h	device_info,
		iotcon_device_info_e	property,
		char **	value
	)

Gets device properties from the device information handle.

Since :: 3.0

Remarks:: value must not be released using free().

Parameters:

[in]	device_info	The handle of the device information
[in]	property	The properties of the device information
[out]	value	The value of the property

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_set_device_name(); iotcon_device_info_cb(); iotcon_find_device_info()

int iotcon_find_device_info	(	const char *	host_address,
		int	connectivity_type,
		iotcon_query_h	query,
		iotcon_device_info_cb	cb,
		void *	user_data
	)

Finds the device information of remote server asynchronously.

Request device information to server and pass the information by calling iotcon_device_info_cb().
host_address could be IOTCON_MULTICAST_ADDRESS for multicast.
If succeeded in getting device information, iotcon_device_info_cb() will be invoked with information.

Since :: 3.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/internet

Remarks:: host_address should be in the format coap://address:port.
(ex. coap://[fe80::ae5a:14ff:fe24:b8fe]:12345, or coap://192.168.1.10:12345)
connectivity_type can be set with extra options. If connectivity_type is set without IOTCON_CONNECTIVITY_IPV4_ONLY and IOTCON_CONNECTIVITY_IPV6_ONLY, device informations are discovered by default setting of IoTivity(IPv6 is preferred over IPv4).
If there are no preference options(PREFER_XXX), it will reply using UDP.

Parameters:

[in]	host_address	The host address of remote server
[in]	connectivity_type	The connectivity type
[in]	query	The query specified as a filter for the device information
[in]	cb	The callback function to invoke
[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
IOTCON_ERROR_OUT_OF_MEMORY	Out of memory
IOTCON_ERROR_PERMISSION_DENIED	Permission denied

Precondition:: iotcon_initialize() should be called to initialize.

Postcondition:: iotcon_device_info_cb() will be invoked.

See also:: iotcon_set_device_name(); iotcon_device_info_cb(); iotcon_device_info_get_property(); iotcon_set_timeout()

int iotcon_find_platform_info	(	const char *	host_address,
		int	connectivity_type,
		iotcon_query_h	query,
		iotcon_platform_info_cb	cb,
		void *	user_data
	)

Finds the platform information of remote server asynchronously.

Request platform information to server and pass the information by calling iotcon_platform_info_cb().
host_address could be IOTCON_MULTICAST_ADDRESS for multicast.
If succeeded in getting platform information, iotcon_platform_info_cb() will be invoked with information.

Since :: 3.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/internet

Remarks:: host_address should be in the format coap://address:port.
(ex. coap://[fe80::ae5a:14ff:fe24:b8fe]:12345, or coap://192.168.1.10:12345)
connectivity_type can be set with extra options. If connectivity_type is set without IOTCON_CONNECTIVITY_IPV4_ONLY and IOTCON_CONNECTIVITY_IPV6_ONLY, platform informations are discovered by default setting of IoTivity(IPv6 is preferred over IPv4).
If there are no preference options(PREFER_XXX), it will reply using UDP.

Parameters:

[in]	host_address	The host address of remote server
[in]	connectivity_type	The connectivity type
[in]	query	The query specified as a filter for the platform information
[in]	cb	The callback function to invoke
[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
IOTCON_ERROR_SYSTEM	System error
IOTCON_ERROR_OUT_OF_MEMORY	Out of memory
IOTCON_ERROR_PERMISSION_DENIED	Permission denied

Precondition:: iotcon_initialize() should be called to initialize.

Postcondition:: iotcon_platform_info_cb() will be invoked.

See also:: iotcon_platform_info_cb(); iotcon_platform_info_get_property(); iotcon_set_timeout()

int iotcon_find_resource	(	const char *	host_address,
		int	connectivity_type,
		iotcon_query_h	query,
		iotcon_found_resource_cb	cb,
		void *	user_data
	)

Finds resources asynchronously.

Request to find a resource of host_address server with query.
host_address could be IOTCON_MULTICAST_ADDRESS for multicast.
If succeeded to find the resource, iotcon_found_resource_cb() will be invoked with information of the resource.

Since :: 3.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/internet

Remarks:: host_address should be in the format coap://address:port.
(ex. coaps://[fe80::ae5a:14ff:fe24:b8fe]:12345, or coaps://192.168.1.10:12345)
connectivity_type can be set with extra options. If connectivity_type is set without IOTCON_CONNECTIVITY_IPV4_ONLY and IOTCON_CONNECTIVITY_IPV6_ONLY, the resources are discovered by default setting of IoTivity(IPv6 is preferred over IPv4).
If there are no preference options(PREFER_XXX), resources will reply using each of opened protocol(TCP/UDP). Therefore, you can get remote resource handles which include different host address, but indicates same resource.
(coaps://192.168.0.2:1234/res/light, coaps+tcp://192.168.0.2/1235/res/light) query can be set using specific resource types, or resource interfaces. If query is NULL, every resource discovered is listed.

Parameters:

[in]	host_address	The address or addressable name of server
[in]	connectivity_type	The connectivity type
[in]	query	The query specified as a filter for the resource
[in]	cb	The callback function to invoke
[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
IOTCON_ERROR_SYSTEM	System error
IOTCON_ERROR_PERMISSION_DENIED	Permission denied

Precondition:: iotcon_initialize() should be called to initialize.

Postcondition:: iotcon_found_resource_cb() will be invoked.

See also:: iotcon_found_resource_cb(); iotcon_set_timeout()

int iotcon_platform_info_get_property	(	iotcon_platform_info_h	platform_info,
		iotcon_platform_info_e	property,
		char **	value
	)

Gets platform properties from the platform information handle.

Since :: 3.0

Remarks:: value must not be released using free().

Parameters:

[in]	platform_info	The handle of the platform information
[in]	property	The properties of the platform information
[out]	value	The value of the property

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_platform_info_cb(); iotcon_find_platform_info()

int iotcon_presence_get_connectivity_type	(	iotcon_presence_h	presence,
		iotcon_connectivity_type_e *	connectivity_type
	)

Gets connectivity type from the presence handle.

The connectivity_type could be one of iotcon_connectivity_type_e.

Since :: 3.0

Parameters:

[in]	presence	The handle of the presence
[out]	connectivity_type	The connectivity type of the presence

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_presence_get_host_address(); iotcon_presence_get_resource_type()

int iotcon_presence_get_host_address	(	iotcon_presence_h	presence,
		char **	host_address
	)

Gets host address from the presence handle.

Since :: 3.0

Remarks:: host_address must not be released using free().

Parameters:

[in]	presence	The handle of the presence
[out]	host_address	The host address of the presence

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_presence_get_connectivity_type(); iotcon_presence_get_resource_type()

int iotcon_presence_get_resource_type	(	iotcon_presence_h	presence,
		char **	resource_type
	)

Gets resource type from the presence handle.

Since :: 3.0

Remarks:: resource_type must not be released using free().

Parameters:

[in]	presence	The handle of the presence
[out]	resource_type	The resource type of the presence

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_presence_get_host_address(); iotcon_presence_get_connectivity_type()

int iotcon_presence_response_get_connectivity_type	(	iotcon_presence_response_h	response,
		iotcon_connectivity_type_e *	connectivity_type
	)

Gets connectivity type from the presence response handle.

The connectivity_type could be one of iotcon_connectivity_type_e.

Since :: 3.0

Parameters:

[in]	response	The handle of the presence response
[out]	connectivity_type	The connectivity type of the presence response

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_presence_response_get_result(); iotcon_presence_response_get_trigger(); iotcon_presence_response_get_host_address(); iotcon_presence_response_get_resource_type()

int iotcon_presence_response_get_host_address	(	iotcon_presence_response_h	response,
		char **	host_address
	)

Gets host address from the presence response handle.

Since :: 3.0

Remarks:: host_address must not be released using free().

Parameters:

[in]	response	The handle of the presence response
[out]	host_address	The host address of the presence response

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_presence_response_get_result(); iotcon_presence_response_get_trigger(); iotcon_presence_response_get_connectivity_type(); iotcon_presence_response_get_resource_type()

int iotcon_presence_response_get_resource_type	(	iotcon_presence_response_h	response,
		char **	resource_type
	)

Gets resource type from the presence response handle.

Since :: 3.0

Remarks:: resource_type must not be released using free().

Parameters:

[in]	response	The handle of the presence response
[out]	resource_type	The resource type of the presence response

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_presence_response_get_result(); iotcon_presence_response_get_trigger(); iotcon_presence_response_get_host_address(); iotcon_presence_response_get_connectivity_type()

int iotcon_presence_response_get_result	(	iotcon_presence_response_h	response,
		iotcon_presence_result_e *	result
	)

Gets result from the presence response handle.

The result could be one of iotcon_presence_result_e.

Since :: 3.0

Parameters:

[in]	response	The handle of the presence response
[out]	result	The result code

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_presence_response_get_trigger(); iotcon_presence_response_get_host_address(); iotcon_presence_response_get_connectivity_type(); iotcon_presence_response_get_resource_type()

int iotcon_presence_response_get_trigger	(	iotcon_presence_response_h	response,
		iotcon_presence_trigger_e *	trigger
	)

Gets trigger from the presence response handle.

The trigger could be one of iotcon_presence_trigger_e. It is set only if a response result is IOTCON_PRESENCE_OK.

Since :: 3.0

Parameters:

[in]	response	The handle of the presence response
[out]	trigger	The presence trigger value

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_presence_response_get_result(); iotcon_presence_response_get_host_address(); iotcon_presence_response_get_connectivity_type(); iotcon_presence_response_get_resource_type()

int iotcon_remove_presence_cb ( iotcon_presence_h presence_handle )

Removes callback to a server's presence events.

Request not to receive server's presence any more.

Since :: 3.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/internet

Parameters:

[in] presence_handle The presence handle to be unsubscribed

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
IOTCON_ERROR_SYSTEM	System error
IOTCON_ERROR_PERMISSION_DENIED	Permission denied

Precondition:: iotcon_initialize() should be called to initialize.

See also:: iotcon_start_presence(); iotcon_stop_presence(); iotcon_add_presence_cb(); iotcon_presence_cb()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Function Documentation