Tizen Native API
5.5
|
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, otherwisefalse
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.
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, otherwisefalse
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, otherwisefalse
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.
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().
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.
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
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.
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.
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.
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
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
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
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
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
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
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
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
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
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.