Tizen Native API  3.0

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_infoThe device information from remote server
[in]resultThe result code (0 on success, otherwise a negative error value)
[in]user_dataThe 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]resourceThe handle of resource which is found
[in]resultThe result code (Lesser than 0 on fail, otherwise a response result value)
[in]user_dataThe 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_infoThe platform information from remote server
[in]resultThe result code (0 on success, otherwise a negative error value)
[in]user_dataThe 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]presenceThe presence handle
[in]errThe error code(0 on success, otherwise a negative error value)
[in]responseThe presence response handle
[in]user_dataThe 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_addressThe address or addressable name of the server
[in]connectivity_typeThe connectivity type
[in]resource_typeA resource type that a client is interested in
[in]cbThe callback function to invoke
[in]user_dataThe user data to pass to the function
[out]presence_handleThe generated presence 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_IOTIVITYIoTivity errors
IOTCON_ERROR_OUT_OF_MEMORYOut of memory
IOTCON_ERROR_PERMISSION_DENIEDPermission 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_infoThe handle of the device information
[in]propertyThe properties of the device information
[out]valueThe value of the property
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_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_addressThe host address of remote server
[in]connectivity_typeThe connectivity type
[in]queryThe query specified as a filter for the device information
[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
IOTCON_ERROR_OUT_OF_MEMORYOut of memory
IOTCON_ERROR_PERMISSION_DENIEDPermission 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_addressThe host address of remote server
[in]connectivity_typeThe connectivity type
[in]queryThe query specified as a filter for the platform information
[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
IOTCON_ERROR_SYSTEMSystem error
IOTCON_ERROR_OUT_OF_MEMORYOut of memory
IOTCON_ERROR_PERMISSION_DENIEDPermission 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_addressThe address or addressable name of server
[in]connectivity_typeThe connectivity type
[in]queryThe query specified as a filter for the resource
[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
IOTCON_ERROR_SYSTEMSystem error
IOTCON_ERROR_PERMISSION_DENIEDPermission 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_infoThe handle of the platform information
[in]propertyThe properties of the platform information
[out]valueThe value of the property
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_platform_info_cb()
iotcon_find_platform_info()

Gets connectivity type from the presence handle.

The connectivity_type could be one of iotcon_connectivity_type_e.

Since :
3.0
Parameters:
[in]presenceThe handle of the presence
[out]connectivity_typeThe connectivity type of the presence
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_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]presenceThe handle of the presence
[out]host_addressThe host address of the presence
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_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]presenceThe handle of the presence
[out]resource_typeThe resource type of the presence
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_presence_get_host_address()
iotcon_presence_get_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]responseThe handle of the presence response
[out]connectivity_typeThe connectivity type of the presence response
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_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]responseThe handle of the presence response
[out]host_addressThe host address of the presence response
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_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]responseThe handle of the presence response
[out]resource_typeThe resource type of the presence response
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_presence_response_get_result()
iotcon_presence_response_get_trigger()
iotcon_presence_response_get_host_address()
iotcon_presence_response_get_connectivity_type()

Gets result from the presence response handle.

The result could be one of iotcon_presence_result_e.

Since :
3.0
Parameters:
[in]responseThe handle of the presence response
[out]resultThe result code
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_presence_response_get_trigger()
iotcon_presence_response_get_host_address()
iotcon_presence_response_get_connectivity_type()
iotcon_presence_response_get_resource_type()

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]responseThe handle of the presence response
[out]triggerThe presence trigger 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
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_handleThe presence handle to be unsubscribed
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_SYSTEMSystem error
IOTCON_ERROR_PERMISSION_DENIEDPermission denied
Precondition:
iotcon_initialize() should be called to initialize.
See also:
iotcon_start_presence()
iotcon_stop_presence()
iotcon_add_presence_cb()
iotcon_presence_cb()