diff options
-rw-r--r-- | include/iotcon-attributes.h | 445 | ||||
-rw-r--r-- | include/iotcon-client.h | 488 | ||||
-rw-r--r-- | include/iotcon-constant.h | 88 | ||||
-rw-r--r-- | include/iotcon-errors.h | 10 | ||||
-rw-r--r-- | include/iotcon-list.h | 579 | ||||
-rw-r--r-- | include/iotcon-lite-resource.h | 155 | ||||
-rw-r--r-- | include/iotcon-observers.h | 103 | ||||
-rw-r--r-- | include/iotcon-options.h | 166 | ||||
-rw-r--r-- | include/iotcon-query.h | 222 | ||||
-rw-r--r-- | include/iotcon-remote-resource.h | 662 | ||||
-rw-r--r-- | include/iotcon-representation.h | 400 | ||||
-rw-r--r-- | include/iotcon-request.h | 171 | ||||
-rw-r--r-- | include/iotcon-resource-interfaces.h | 167 | ||||
-rw-r--r-- | include/iotcon-resource-types.h | 166 | ||||
-rw-r--r-- | include/iotcon-resource.h | 353 | ||||
-rw-r--r-- | include/iotcon-response.h | 183 | ||||
-rw-r--r-- | include/iotcon-server.h | 78 | ||||
-rw-r--r-- | include/iotcon-types.h | 173 | ||||
-rw-r--r-- | include/iotcon.h | 174 | ||||
-rw-r--r-- | packaging/iotcon.spec | 2 |
20 files changed, 2016 insertions, 2769 deletions
diff --git a/include/iotcon-attributes.h b/include/iotcon-attributes.h index 6796ad4..36865d7 100644 --- a/include/iotcon-attributes.h +++ b/include/iotcon-attributes.h @@ -13,27 +13,28 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_STRUCT_ATTRIBUTES_H__ #define __IOTCON_STRUCT_ATTRIBUTES_H__ + #include <iotcon-types.h> + /** * @file iotcon-attributes.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_ATTRIBUTES_MODULE State - * * @brief IoTCon State provides API to manage attributes. - * * @section CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_ATTRIBUTES_MODULE_HEADER Required Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_ATTRIBUTES_MODULE_OVERVIEW Overview - * The iotcon attributes API provides string key based hash table. - * + * The IoTCon attributes API provides string key based hash table. * Example : * @code #include <iotcon.h> @@ -121,471 +122,425 @@ static void _request_handler(iotcon_resource_h resource, iotcon_request_h reques ... } * @endcode - * * @section CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_ATTRIBUTES_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/iot.ocf\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * 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.\n - * - * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> - * + * This API is related with the following features: \n + * - http://tizen.org/feature/iot.ocf \n + * It is recommended to design feature related codes in your application for reliability. \n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n + * 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. \n + * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> * @{ */ + /** * @brief Creates a new attributes handle. - * * @since_tizen 3.0 - * - * @remarks You must destroy @a attributes by calling iotcon_attributes_destroy() - * if @a attributes is no longer needed. - * + * @remarks You must destroy @a attributes by calling iotcon_attributes_destroy() if @a attributes is no longer needed. * @param[out] attributes A newly allocated attributes handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_attributes_destroy() */ int iotcon_attributes_create(iotcon_attributes_h *attributes); + /** - * @brief Destroys a attributes. - * @details Releases a @a attributes and its internal data. - * + * @brief Destroys the attributes. + * @details Releases @a attributes and its internal data. * @since_tizen 3.0 - * * @param[in] attributes The attributes handle to free - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_attributes_create() */ int iotcon_attributes_destroy(iotcon_attributes_h attributes); + /** - * @brief Clones a attributes handle. - * + * @brief Clones the attributes handle. * @since_tizen 3.0 - * - * @remarks You must destroy @a attributes_clone by calling iotcon_attributes_destroy() - * if @a attributes_clone is no longer needed. - * + * @remarks You must destroy @a attributes_clone by calling iotcon_attributes_destroy() if @a attributes_clone is no longer needed. * @param[in] attributes The attributes handle * @param[out] attributes_clone The cloned attributes handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_attributes_create() * @see iotcon_attributes_destroy() */ int iotcon_attributes_clone(iotcon_attributes_h attributes, iotcon_attributes_h *attributes_clone); + /** * @brief Adds a new key and integer value into the attributes. * @details If @a key is already exists, current value will be replaced with new @a val. - * * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[in] key The key * @param[in] val The value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ int iotcon_attributes_add_int(iotcon_attributes_h attributes, const char *key, int val); + /** * @brief Adds a new key and boolean value into the attributes. * @details If @a key is already exists, current value will be replaced with new @a val. - * * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[in] key The key * @param[in] val The value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ int iotcon_attributes_add_bool(iotcon_attributes_h attributes, const char *key, bool val); + /** * @brief Adds a new key and double value into the attributes. * @details If @a key is already exists, current value will be replaced with new @a val. - * * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[in] key The key * @param[in] val The value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ int iotcon_attributes_add_double(iotcon_attributes_h attributes, const char *key, double val); + /** * @brief Adds a new key and string value into the attributes. * @details If @a key is already exists, current value will be replaced with new @a val. - * * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[in] key The key * @param[in] val The value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ int iotcon_attributes_add_str(iotcon_attributes_h attributes, const char *key, char *val); + /** * @brief Adds a new key and byte string value into the attributes. * @details If @a key is already exists, current value will be replaced with new @a val. - * * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[in] key The key * @param[in] val The value * @param[in] len The length of @a val - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ -int iotcon_attributes_add_byte_str(iotcon_attributes_h attributes, const char *key, unsigned char *val, - int len); +int iotcon_attributes_add_byte_str(iotcon_attributes_h attributes, const char *key, unsigned char *val, int len); + /** * @brief Adds a new key and list value into the attributes. - * @details If @a key is already exists, current list will be replaced with new @a list. - * + * @details If @a key already exists, current list will be replaced with new @a list. * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[in] key The key * @param[in] list The value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ int iotcon_attributes_add_list(iotcon_attributes_h attributes, const char *key, iotcon_list_h list); + /** * @brief Adds a new key and attributes value into the attributes. - * @details If @a key is already exists, current attributes will be replaced with new @a src. - * + * @details If @a key already exists, current attributes will be replaced with new @a src. * @since_tizen 3.0 - * * @param[in] dest The attributes handle * @param[in] key The key * @param[in] src The attributes handle to set newly - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ int iotcon_attributes_add_attributes(iotcon_attributes_h dest, const char *key, iotcon_attributes_h src); + /** * @brief Adds a new key with NULL value into the attributes. - * @details If @a key is already exists, current value will be replaced with NULL. - * + * @details If @a key already exists, current value will be replaced with NULL. * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[in] key The key to be set NULL - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ int iotcon_attributes_add_null(iotcon_attributes_h attributes, const char *key); + /** * @brief Gets the integer value from the given key. - * * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[in] key The key * @param[out] val The integer value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available + * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type */ int iotcon_attributes_get_int(iotcon_attributes_h attributes, const char *key, int *val); + /** * @brief Gets the boolean value from the given key. - * * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[in] key The key * @param[out] val The boolean value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available + * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type */ int iotcon_attributes_get_bool(iotcon_attributes_h attributes, const char *key, bool *val); + /** * @brief Gets the double value from the given key. - * * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[in] key The key * @param[out] val The double value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available + * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type */ int iotcon_attributes_get_double(iotcon_attributes_h attributes, const char *key, double *val); + /** * @brief Gets the string value from the given key. - * * @since_tizen 3.0 - * * @remarks @a val must not be released using free(). - * * @param[in] attributes The attributes handle * @param[in] key The key * @param[out] val The string value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available + * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type */ int iotcon_attributes_get_str(iotcon_attributes_h attributes, const char *key, char **val); + /** * @brief Gets the byte string value from the given key. - * * @since_tizen 3.0 - * * @remarks @a val must not be released using free(). - * * @param[in] attributes The attributes handle * @param[in] key The key * @param[out] val The byte string value * @param[out] len The length of @a val - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available + * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type */ -int iotcon_attributes_get_byte_str(iotcon_attributes_h attributes, const char *key, unsigned char **val, - int *len); +int iotcon_attributes_get_byte_str(iotcon_attributes_h attributes, const char *key, unsigned char **val, int *len); + /** * @brief Gets the list value from the given key. - * * @since_tizen 3.0 - * * @remarks @a list must not be released using iotcon_list_destroy(). - * * @param[in] attributes The attributes handle * @param[in] key The key * @param[out] list The list value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available + * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type */ int iotcon_attributes_get_list(iotcon_attributes_h attributes, const char *key, iotcon_list_h *list); + /** * @brief Gets the attributes value from the given key. - * * @since_tizen 3.0 - * * @remarks @a attributes must not be released using iotcon_attributes_destroy(). - * * @param[in] src The attributes handle * @param[in] key The key * @param[out] dest The attributes value at the key - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available + * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type */ int iotcon_attributes_get_attributes(iotcon_attributes_h src, const char *key, iotcon_attributes_h *dest); + /** * @brief Checks whether the value of given key is NULL or not. - * * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[in] key The key - * @param[out] is_null true if the type of the given key is null, otherwise false - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @param[out] is_null true if the type of the given key is null, + * otherwise false + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ int iotcon_attributes_is_null(iotcon_attributes_h attributes, const char *key, bool *is_null); + /** * @brief Removes the key and its associated value from the attributes. - * * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[in] key The key - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available */ int iotcon_attributes_remove(iotcon_attributes_h attributes, const char *key); + /** * @brief Gets the type of a value at the given key. - * @details It gets the data type of value related the @a key in @a attributes. - * The data type could be one of #iotcon_type_e. - * + * @details It gets the data type of value related to the @a key in @a attributes. + * The data type could be one of #iotcon_type_e. * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[in] key The key - * @param[out] type The data type of value related the key in attributes handle. - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available + * @param[out] type The data type of value related to the key in attributes handle + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available */ -int iotcon_attributes_get_type(iotcon_attributes_h attributes, const char *key, - iotcon_type_e *type); +int iotcon_attributes_get_type(iotcon_attributes_h attributes, const char *key, iotcon_type_e *type); + /** * @brief Specifies the type of function passed to iotcon_attributes_foreach(). - * * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[in] key The key * @param[in] user_data The user data to pass to the function - * - * @return 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. - * + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre iotcon_attributes_foreach() will invoke this callback function. - * * @see iotcon_attributes_foreach() */ typedef bool (*iotcon_attributes_cb)(iotcon_attributes_h attributes, const char *key, void *user_data); + /** * @brief Calls a function for each element of attributes. * @details iotcon_attributes_cb() will be called for each child. - * * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[in] cb The callback function to invoke * @param[in] user_data The user data to pass to the function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @post iotcon_attributes_cb() will be called for each child. - * * @see iotcon_attributes_cb() */ int iotcon_attributes_foreach(iotcon_attributes_h attributes, iotcon_attributes_cb cb, void *user_data); + /** - * @brief Gets the number of keys in the attributes. - * + * @brief Gets the number of keys in the attributes. * @since_tizen 3.0 - * * @param[in] attributes The attributes handle * @param[out] count The number of keys - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ int iotcon_attributes_get_keys_count(iotcon_attributes_h attributes, unsigned int *count); + /** * @} */ + #endif /* __IOTCON_STRUCT_ATTRIBUTES_H__ */ diff --git a/include/iotcon-client.h b/include/iotcon-client.h index e03f499..df0a636 100644 --- a/include/iotcon-client.h +++ b/include/iotcon-client.h @@ -13,57 +13,50 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_CLIENT_H__ #define __IOTCON_CLIENT_H__ + #include <iotcon-types.h> #include <iotcon-remote-resource.h> + /** * @file iotcon-client.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_CLIENT_MODULE Client - * * @brief IoTCon Client provides API for client side. - * * @section CAPI_IOT_CONNECTIVITY_CLIENT_MODULE_HEADER Required Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_CLIENT_MODULE_OVERVIEW Overview - * This API set consists of client side API for @ref CAPI_IOT_CONNECTIVITY_CLIENT_REMOTE_RESOURCE_MODULE. - * + * This API set consists of client side API for @ref CAPI_IOT_CONNECTIVITY_CLIENT_REMOTE_RESOURCE_MODULE. * @section CAPI_IOT_CONNECTIVITY_CLIENT_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/iot.ocf\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * 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.\n - * - * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> - * + * This API is related with the following features: \n + * - http://tizen.org/feature/iot.ocf \n + * It is recommended to design feature related codes in your application for reliability. \n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n + * 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. \n + * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> * @{ */ + /** * @brief Specifies the type of function passed to iotcon_add_presence_cb(). - * @details Called when client receive presence events from the server. - * The @a response handle contains about presence information. - * + * @details Called when client receives presence events from the server. + * The @a response handle contains presence information. * @since_tizen 3.0 - * * @param[in] presence The presence handle - * @param[in] err The error code(0 on success, otherwise a negative error value) + * @param[in] err The error code(@c 0 on success, otherwise a negative error value) * @param[in] response The presence response handle * @param[in] user_data The user data to pass to the function - * - * @pre The callback must be registered using iotcon_add_presence_cb() - * + * @pre The callback must be registered using iotcon_add_presence_cb(). * @see iotcon_add_presence_cb() * @see iotcon_remove_presence_cb() * @see iotcon_presence_response_get_connectivity_type() @@ -72,75 +65,62 @@ * @see iotcon_presence_response_get_result() * @see iotcon_presence_response_get_trigger() */ -typedef void (*iotcon_presence_cb)(iotcon_presence_h presence, iotcon_error_e err, - iotcon_presence_response_h response, void *user_data); +typedef void (*iotcon_presence_cb)(iotcon_presence_h presence, iotcon_error_e err, iotcon_presence_response_h response, void *user_data); + /** * @brief Adds callback to a server to receive presence events. - * @details Request to receive presence to an interested server's resource with @a resource_type.\n - * If succeed to subscribe, iotcon_presence_cb() will be invoked when the server sends presence.\n - * A server sends presence events when adds/removes/alters a resource or start/stop presence.\n - * @a host_address could be #IOTCON_MULTICAST_ADDRESS for IPv4 multicast. - * + * @details Request to receive presence to an interested server's resource with @a resource_type. \n + * If succeeded to subscribe, iotcon_presence_cb() will be invoked when the server sends presence. \n + * A server sends presence events when adds/removes/alters a resource or start/stop presence. \n + * @a host_address could be #IOTCON_MULTICAST_ADDRESS for IPv4 multicast. * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @remarks The length of @a resource_type should be less than or equal to 61.\n - * The @a resource_type must start with a lowercase alphabetic character, followed by a sequence - * of lowercase alphabetic, numeric, ".", or "-" characters, and contains no white space.\n - * You must destroy @a presence by calling iotcon_unsubscribe_presence() - * if @a presence is no longer needed. - * + * The @a resource_type must start with a lowercase alphabetic character, followed by a sequence + * of lowercase alphabetic, numeric, ".", or "-" characters, and contains no white space.\n + * You must destroy @a presence by calling iotcon_unsubscribe_presence() + * if @a presence is no longer needed. * @param[in] host_address The address or addressable name of the server * @param[in] connectivity_type The connectivity type - * @param[in] resource_type A resource type that a client has interested in + * @param[in] resource_type A resource type that a client is interested in * @param[in] cb The callback function to invoke * @param[in] user_data The user data to pass to the function * @param[out] presence_handle The generated presence handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_IOTIVITY IoTivity errors - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_IOTIVITY IoTivity errors + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. * @post When the resource receive presence, iotcon_presence_cb() will be called. - * * @see iotcon_start_presence() * @see iotcon_stop_presence() * @see iotcon_remove_presence_cb() * @see iotcon_presence_cb() */ -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); +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); + /** * @brief Removes callback to a server's presence events. * @details Request not to receive server's presence any more. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] presence_handle The presence handle to be unsubscribed - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_SYSTEM System error * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_start_presence() * @see iotcon_stop_presence() * @see iotcon_add_presence_cb() @@ -148,438 +128,364 @@ int iotcon_add_presence_cb(const char *host_address, */ int iotcon_remove_presence_cb(iotcon_presence_h presence_handle); + /** * @brief Gets host address from the presence handle. - * * @since_tizen 3.0 - * * @remarks @a host_address must not be released using free(). - * * @param[in] presence The handle of the presence * @param[out] host_address The host address of the presence - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_presence_get_connectivity_type() * @see iotcon_presence_get_resource_type() */ int iotcon_presence_get_host_address(iotcon_presence_h presence, char **host_address); + /** * @brief Gets connectivity type from the presence handle. * @details The @a connectivity_type could be one of #iotcon_connectivity_type_e. - * * @since_tizen 3.0 - * * @param[in] presence The handle of the presence * @param[out] connectivity_type The connectivity type of the presence - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_presence_get_host_address() * @see iotcon_presence_get_resource_type() */ -int iotcon_presence_get_connectivity_type(iotcon_presence_h presence, - iotcon_connectivity_type_e *connectivity_type); +int iotcon_presence_get_connectivity_type(iotcon_presence_h presence, iotcon_connectivity_type_e *connectivity_type); + /** * @brief Gets resource type from the presence handle. - * * @since_tizen 3.0 - * * @remarks @a resource_type must not be released using free(). - * * @param[in] presence The handle of the presence * @param[out] resource_type The resource type of the presence - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_presence_get_host_address() * @see iotcon_presence_get_connectivity_type() */ -int iotcon_presence_get_resource_type(iotcon_presence_h presence, - char **resource_type); +int iotcon_presence_get_resource_type(iotcon_presence_h presence, char **resource_type); + /** * @brief Gets result from the presence response handle. - * * @details The @a result could be one of #iotcon_presence_result_e. * @since_tizen 3.0 - * * @param[in] response The handle of the presence response * @param[out] result The result code - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_presence_response_get_trigger() * @see iotcon_presence_response_get_host_address() * @see iotcon_presence_response_get_connectivity_type() * @see iotcon_presence_response_get_resource_type() */ -int iotcon_presence_response_get_result(iotcon_presence_response_h response, - iotcon_presence_result_e *result); +int iotcon_presence_response_get_result(iotcon_presence_response_h response, iotcon_presence_result_e *result); + /** * @brief Gets trigger from the presence response handle. - * * @details The @a trigger could be one of #iotcon_presence_trigger_e. - * It is set only if a response result is IOTCON_PRESENCE_OK. + * It is set only if a response result is IOTCON_PRESENCE_OK. * @since_tizen 3.0 - * * @param[in] response The handle of the presence response - * @param[out] trigger The presence trigger value. - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @param[out] trigger The presence trigger value + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_presence_response_get_result() * @see iotcon_presence_response_get_host_address() * @see iotcon_presence_response_get_connectivity_type() * @see iotcon_presence_response_get_resource_type() */ -int iotcon_presence_response_get_trigger(iotcon_presence_response_h response, - iotcon_presence_trigger_e *trigger); +int iotcon_presence_response_get_trigger(iotcon_presence_response_h response, iotcon_presence_trigger_e *trigger); + /** * @brief Gets host address from the presence response handle. - * * @since_tizen 3.0 - * * @remarks @a host_address must not be released using free(). - * * @param[in] response The handle of the presence response * @param[out] host_address The host address of the presence response - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * * @see iotcon_presence_response_get_result() * @see iotcon_presence_response_get_trigger() * @see iotcon_presence_response_get_connectivity_type() * @see iotcon_presence_response_get_resource_type() */ -int iotcon_presence_response_get_host_address(iotcon_presence_response_h response, - char **host_address); +int iotcon_presence_response_get_host_address(iotcon_presence_response_h response, char **host_address); + /** * @brief Gets connectivity type from the presence response handle. - * * @details The @a connectivity_type could be one of #iotcon_connectivity_type_e. * @since_tizen 3.0 - * * @param[in] response The handle of the presence response * @param[out] connectivity_type The connectivity type of the presence response - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_presence_response_get_result() * @see iotcon_presence_response_get_trigger() * @see iotcon_presence_response_get_host_address() * @see iotcon_presence_response_get_resource_type() */ -int iotcon_presence_response_get_connectivity_type(iotcon_presence_response_h response, - iotcon_connectivity_type_e *connectivity_type); +int iotcon_presence_response_get_connectivity_type(iotcon_presence_response_h response, iotcon_connectivity_type_e *connectivity_type); + /** * @brief Gets resource type from the presence response handle. - * * @since_tizen 3.0 - * * @remarks @a resource_type must not be released using free(). - * * @param[in] response The handle of the presence response * @param[out] resource_type The resource type of the presence response - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_presence_response_get_result() * @see iotcon_presence_response_get_trigger() * @see iotcon_presence_response_get_host_address() * @see iotcon_presence_response_get_connectivity_type() */ -int iotcon_presence_response_get_resource_type(iotcon_presence_response_h response, - char **resource_type); +int iotcon_presence_response_get_resource_type(iotcon_presence_response_h response, char **resource_type); + /** * @brief Specifies the type of function passed to iotcon_find_resource(). * @details Called when a resource is found from the remote server. \n - * The @a resource completes its life cycle in the function. - * If you want to send requests(GET, PUT, POST, DELETE, and OBSERVE) on the @a resource, - * you must clone the @a resource using iotcon_remote_resource_clone(). \n - * The @a result could be one of #iotcon_error_e. - * + * The @a resource completes its life cycle in the function. + * If you want to send requests(GET, PUT, POST, DELETE, and OBSERVE) on the @a resource, + * you must clone the @a resource using iotcon_remote_resource_clone(). \n + * The @a result could be one of #iotcon_error_e. * @since_tizen 3.0 - * * @param[in] resource The handle of resource which is found * @param[in] result The result code (Lesser than 0 on fail, otherwise a response result value) * @param[in] user_data The user data to pass to the function - * - * @return true to continue to find resource, otherwise false to stop. \n - * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return. - * + * @return @c true to continue to find resource, + * otherwise @c false to stop \n + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre The callback must be registered using iotcon_find_resource() - * * @see iotcon_find_resource() */ -typedef bool (*iotcon_found_resource_cb)(iotcon_remote_resource_h resource, - iotcon_error_e result, void *user_data); +typedef bool (*iotcon_found_resource_cb)(iotcon_remote_resource_h resource, iotcon_error_e result, void *user_data); + /** - * @brief Finds resources, asynchronously. + * @brief Finds resources asynchronously. * @details Request to find a resource of @a host_address server with @a query.\n - * @a host_address could be #IOTCON_MULTICAST_ADDRESS for multicast.\n - * If succeed to find the resource, iotcon_found_resource_cb() will be invoked with - * information of the resource. - * + * @a host_address could be #IOTCON_MULTICAST_ADDRESS for multicast.\n + * If succeeded to find the resource, iotcon_found_resource_cb() will be invoked with information of the resource. * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * - * @remarks @a host_address should be in the format coap://address:port.\n - * (ex. coaps://[fe80::ae5a:14ff:fe24:b8fe]:12345, or coaps://192.168.1.10:12345)\n - * @a connectivity_type can be set with extra options. - * If @a 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).\n - * 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.\n (coaps://192.168.0.2:1234/res/light, - * coaps+tcp://192.168.0.2/1235/res/light) - * @a query can be set using specific resource types, or resource interfaces. - * If @a query is NULL, every resource discovered is listed. - * + * @remarks @a host_address should be in the format coap://address:port. \n + * (ex. coaps://[fe80::ae5a:14ff:fe24:b8fe]:12345, or coaps://192.168.1.10:12345)\n + * @a connectivity_type can be set with extra options. + * If @a 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). \n + * 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. \n + * (coaps://192.168.0.2:1234/res/light, coaps+tcp://192.168.0.2/1235/res/light) + * @a query can be set using specific resource types, or resource interfaces. + * If @a query is NULL, every resource discovered is listed. * @param[in] host_address The address or addressable name of server * @param[in] connectivity_type The connectivity type * @param[in] query The query specified as a filter for the resource * @param[in] cb The callback function to invoke * @param[in] user_data The user data to pass to the function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_SYSTEM System error * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. * @post iotcon_found_resource_cb() will be invoked. - * * @see iotcon_found_resource_cb() * @see 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); +int iotcon_find_resource(const char *host_address, int connectivity_type, iotcon_query_h query, iotcon_found_resource_cb cb, void *user_data); + /** * @brief Specifies the type of function passed to iotcon_find_device_info(). * @details The @a result could be one of #iotcon_error_e. - * * @since_tizen 3.0 - * - * @param[in] device_info the device information from remote server. - * @param[in] result The result code (0 on success, other wise a negative error value) + * @param[in] device_info The device information from remote server + * @param[in] result The result code (@c 0 on success, otherwise a negative error value) * @param[in] user_data The user data to pass to the function - * - * @return true to continue to find device information, otherwise false to stop. \n - * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return. - * + * @return @c true to continue to find device information, + * otherwise @c false to stop \n + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre iotcon_find_device_info() will invoke this callback function. - * * @see iotcon_find_device_info() * @see iotcon_device_info_get_property() */ -typedef bool (*iotcon_device_info_cb)(iotcon_device_info_h device_info, - iotcon_error_e result, void *user_data); +typedef bool (*iotcon_device_info_cb)(iotcon_device_info_h device_info, iotcon_error_e result, void *user_data); + /** - * @brief Finds the device information of remote server, asynchronously. - * @details Request device information to server and pass the information by calling - * iotcon_device_info_cb().\n - * @a host_address could be #IOTCON_MULTICAST_ADDRESS for multicast.\n - * If succeed to getting device information, iotcon_device_info_cb() will be invoked with - * information. - * + * @brief Finds the device information of remote server asynchronously. + * @details Request device information to server and pass the information by calling iotcon_device_info_cb(). \n + * @a host_address could be #IOTCON_MULTICAST_ADDRESS for multicast. \n + * If succeeded in getting device information, iotcon_device_info_cb() will be invoked with information. * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * - * @remarks @a host_address should be in the format coap://address:port.\n - * (ex. coap://[fe80::ae5a:14ff:fe24:b8fe]:12345, or coap://192.168.1.10:12345)\n - * @a connectivity_type can be set with extra options. - * If @a 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).\n - * If there are no preference options(PREFER_XXX), it will reply using UDP. - * + * @remarks @a host_address should be in the format coap://address:port. \n + * (ex. coap://[fe80::ae5a:14ff:fe24:b8fe]:12345, or coap://192.168.1.10:12345) \n + * @a connectivity_type can be set with extra options. + * If @a 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). \n + * If there are no preference options(PREFER_XXX), it will reply using UDP. * @param[in] host_address The host address of remote server * @param[in] connectivity_type The connectivity type * @param[in] query The query specified as a filter for the device information * @param[in] cb The callback function to invoke * @param[in] user_data The user data to pass to the function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. * @post iotcon_device_info_cb() will be invoked. - * * @see iotcon_set_device_name() * @see iotcon_device_info_cb() * @see iotcon_device_info_get_property() * @see iotcon_set_timeout() */ -int iotcon_find_device_info(const char *host_address, - int connectivity_type, - iotcon_query_h query, - iotcon_device_info_cb cb, - void *user_data); +int iotcon_find_device_info(const char *host_address, int connectivity_type, iotcon_query_h query, iotcon_device_info_cb cb, void *user_data); + /** * @brief Gets device properties from the device information handle. - * * @since_tizen 3.0 - * * @remarks @a value must not be released using free(). - * * @param[in] device_info The handle of the device information * @param[in] property The properties of the device information * @param[out] value The value of the property - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_set_device_name() * @see iotcon_device_info_cb() * @see iotcon_find_device_info() */ -int iotcon_device_info_get_property(iotcon_device_info_h device_info, - iotcon_device_info_e property, char **value); +int iotcon_device_info_get_property(iotcon_device_info_h device_info, iotcon_device_info_e property, char **value); + /** * @brief Specifies the type of function passed to iotcon_find_platform_info(). * @details The @a result could be one of #iotcon_error_e. - * * @since_tizen 3.0 - * - * @param[in] platform_info The platform information from remote server. - * @param[in] result The result code (0 on success, other wise a negative error value) + * @param[in] platform_info The platform information from remote server + * @param[in] result The result code (@c 0 on success, otherwise a negative error value) * @param[in] user_data The user data to pass to the function - * - * @return true to continue to find platform information, otherwise false to stop. \n - * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return. - * + * @return @c true to continue to find platform information, + * otherwise @c false to stop \n + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre iotcon_find_platform_info() will invoke this callback function. - * * @see iotcon_find_platform_info() * @see iotcon_platform_info_get_property() */ -typedef bool (*iotcon_platform_info_cb)(iotcon_platform_info_h platform_info, - iotcon_error_e result, void *user_data); +typedef bool (*iotcon_platform_info_cb)(iotcon_platform_info_h platform_info, iotcon_error_e result, void *user_data); + /** - * @brief Finds the platform information of remote server, asynchronously. - * @details Request platform information to server and pass the information by calling - * iotcon_platform_info_cb().\n - * @a host_address could be #IOTCON_MULTICAST_ADDRESS for multicast.\n - * If succeed to getting platform information, iotcon_platform_info_cb() will be invoked - * with information. - * + * @brief Finds the platform information of remote server asynchronously. + * @details Request platform information to server and pass the information by calling iotcon_platform_info_cb(). \n + * @a host_address could be #IOTCON_MULTICAST_ADDRESS for multicast. \n + * If succeeded in getting platform information, iotcon_platform_info_cb() will be invoked with information. * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * - * @remarks @a host_address should be in the format coap://address:port.\n - * (ex. coap://[fe80::ae5a:14ff:fe24:b8fe]:12345, or coap://192.168.1.10:12345)\n - * @a connectivity_type can be set with extra options. - * If @a 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).\n - * If there are no preference options(PREFER_XXX), it will reply using UDP. - * + * @remarks @a host_address should be in the format coap://address:port. \n + * (ex. coap://[fe80::ae5a:14ff:fe24:b8fe]:12345, or coap://192.168.1.10:12345) \n + * @a connectivity_type can be set with extra options. + * If @a 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). \n + * If there are no preference options(PREFER_XXX), it will reply using UDP. * @param[in] host_address The host address of remote server * @param[in] connectivity_type The connectivity type * @param[in] query The query specified as a filter for the platform information * @param[in] cb The callback function to invoke * @param[in] user_data The user data to pass to the function - * - * @return 0 on success, otherwise a negative error value. - * + * @return @c 0 on success, + * otherwise a negative error value * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_SYSTEM System error * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. * @post iotcon_platform_info_cb() will be invoked. - * * @see iotcon_platform_info_cb() * @see iotcon_platform_info_get_property() * @see 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); +int iotcon_find_platform_info(const char *host_address, int connectivity_type, iotcon_query_h query, iotcon_platform_info_cb cb, void *user_data); + /** * @brief Gets platform properties from the platform information handle. - * * @since_tizen 3.0 - * * @remarks @a value must not be released using free(). - * * @param[in] platform_info The handle of the platform information * @param[in] property The properties of the platform information * @param[out] value The value of the property - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_platform_info_cb() * @see iotcon_find_platform_info() */ -int iotcon_platform_info_get_property(iotcon_platform_info_h platform_info, - iotcon_platform_info_e property, char **value); +int iotcon_platform_info_get_property(iotcon_platform_info_h platform_info, iotcon_platform_info_e property, char **value); + /** * @} */ + #endif /* __IOTCON_CLIENT_H__ */ diff --git a/include/iotcon-constant.h b/include/iotcon-constant.h index 6da1ae2..60b4947 100644 --- a/include/iotcon-constant.h +++ b/include/iotcon-constant.h @@ -13,82 +13,81 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_CONSTANT_H__ #define __IOTCON_CONSTANT_H__ + /** * @file iotcon-constant.h */ + /** * @addtogroup CAPI_IOT_CONNECTIVITY_COMMON_MODULE - * * @{ */ + /** - * @brief The IP Address for multicast. - * + * @brief Definition for the IP Address for multicast. * @since_tizen 3.0 */ #define IOTCON_MULTICAST_ADDRESS NULL + /** - * @brief Use this value as the return value to stop foreach function. - * + * @brief Definition for using this value as the return value to stop foreach function. * @since_tizen 3.0 */ #define IOTCON_FUNC_STOP false + /** - * @brief Use this value as the return value to continue foreach function. - * + * @brief Definition for using this value as the return value to continue foreach function. * @since_tizen 3.0 */ #define IOTCON_FUNC_CONTINUE true + /** - * @brief Default Interface. - * + * @brief Definition for the default Interface. * @since_tizen 3.0 */ #define IOTCON_INTERFACE_DEFAULT "oic.if.baseline" + /** - * @brief List Links Interface which is used to list the references to other resources - * contained in a resource. - * + * @brief Definition for using List Links Interface which is used to list the references to other resources contained in a resource. * @since_tizen 3.0 */ #define IOTCON_INTERFACE_LINK "oic.if.ll" + /** - * @brief Batch Interface which is used to manipulate (GET, PUT, POST, DELETE) on other - * resource contained in a resource. - * + * @brief Definition for the Batch Interface which is used to manipulate (GET, PUT, POST, DELETE) on other resource contained in a resource. * @since_tizen 3.0 */ #define IOTCON_INTERFACE_BATCH "oic.if.b" + /** - * @brief Group Interface which is used to manipulate (GET, PUT, POST) a group of remote - * resources. - * + * @brief Definition for the Group Interface which is used to manipulate (GET, PUT, POST) a group of remote resources. * @since_tizen 3.0 */ #define IOTCON_INTERFACE_GROUP "oic.mi.grp" + /** - * @brief Read-Only Interface which is used to limit the methods that can be applied to a - * resource to GET only. - * + * @brief Definition for the Read-Only Interface which is used to limit the methods that can be applied to a resource to GET only. * @since_tizen 3.0 */ #define IOTCON_INTERFACE_READONLY "oic.if.r" + /** * @brief Enumeration for type of observation. - * * @since_tizen 3.0 */ typedef enum { @@ -97,9 +96,9 @@ typedef enum { IOTCON_OBSERVE_DEREGISTER = 2, /**< Indicates action of unregistering observation */ } iotcon_observe_type_e; + /** * @brief Enumeration for policy of observation. - * * @since_tizen 3.0 */ typedef enum { @@ -107,14 +106,11 @@ typedef enum { IOTCON_OBSERVE_ACCEPT_OUT_OF_ORDER = 1 /**< Indicates observation request for all notifications including state notifications */ } iotcon_observe_policy_e; + /** - * @brief Enumeration for of connectivities which can be held in a resource. - * - * @remarks IOTCON_CONNECTIVITY_PREFER_UDP and IOTCON_CONNECTIVITY_PREFER_TCP should be - * mutually exclusive. - * @remarks IOTCON_CONNECTIVITY_IPV4_ONLY and IOTCON_CONNECTIVITY_IPV6_ONLY should be - * mutually exclusive. - * + * @brief Enumeration for connectivities which can be held in a resource. + * @remarks IOTCON_CONNECTIVITY_PREFER_UDP and IOTCON_CONNECTIVITY_PREFER_TCP should be mutually exclusive. + * @remarks IOTCON_CONNECTIVITY_IPV4_ONLY and IOTCON_CONNECTIVITY_IPV6_ONLY should be mutually exclusive. * @since_tizen 3.0 */ typedef enum { @@ -127,9 +123,9 @@ typedef enum { IOTCON_CONNECTIVITY_IPV6_ONLY = (1 << 19), /**< When this bit is set with IOTCON_CONNECTIVITY_IP, resources are discovered for IPv6 */ } iotcon_connectivity_type_e; + /** * @brief Enumeration for policy which can be held in a resource. - * * @since_tizen 3.0 */ typedef enum { @@ -142,9 +138,9 @@ typedef enum { IOTCON_RESOURCE_EXPLICIT_DISCOVERABLE = (1 << 5), /**< When this bit is set, the resource is allowed to be discovered only if discovery request contains an explicit querystring. */ } iotcon_resource_policy_e; + /** * @brief Enumeration for type of request. - * * @since_tizen 3.0 */ typedef enum { @@ -155,24 +151,24 @@ typedef enum { IOTCON_REQUEST_DELETE = 4, /**< Indicates delete method of request */ } iotcon_request_type_e; + /** * @brief Enumeration for result of response. - * * @since_tizen 3.0 */ typedef enum { IOTCON_RESPONSE_OK = 0, /**< Indicates result of response for success */ - IOTCON_RESPONSE_ERROR, /**< Indicates result of response for something error */ - IOTCON_RESPONSE_RESOURCE_CREATED, /**< Indicates result of response for resource has created */ - IOTCON_RESPONSE_RESOURCE_DELETED, /**< Indicates result of response for resource has deleted */ - IOTCON_RESPONSE_RESOURCE_CHANGED, /**< Indicates result of response for resource has changed */ + IOTCON_RESPONSE_ERROR, /**< Indicates result of response for error */ + IOTCON_RESPONSE_RESOURCE_CREATED, /**< Indicates result of response for resource creation */ + IOTCON_RESPONSE_RESOURCE_DELETED, /**< Indicates result of response for resource deletion */ + IOTCON_RESPONSE_RESOURCE_CHANGED, /**< Indicates result of response for resource change */ IOTCON_RESPONSE_SLOW, /**< Indicates result of response for slow resource */ IOTCON_RESPONSE_FORBIDDEN, /**< Indicates result of response for accessing unauthorized resource */ } iotcon_response_result_e; + /** * @brief Enumeration for result of presence. - * * @since_tizen 3.0 */ typedef enum { @@ -181,9 +177,9 @@ typedef enum { IOTCON_PRESENCE_TIMEOUT, /**< Indicates for no response of presence for some time */ } iotcon_presence_result_e; + /** * @brief Enumeration for operation of presence response. - * * @since_tizen 3.0 */ typedef enum { @@ -192,9 +188,9 @@ typedef enum { IOTCON_PRESENCE_RESOURCE_DESTROYED, /**< Indicates for resource destruction operation of server */ } iotcon_presence_trigger_e; + /** - * @brief Enumeration for types of representation that is able to have. - * + * @brief Enumeration for types of representation that is possible to have. * @since_tizen 3.0 */ typedef enum { @@ -209,9 +205,9 @@ typedef enum { IOTCON_TYPE_ATTRIBUTES, /**< Indicates for representation that have another representation type */ } iotcon_type_e; + /** * @brief Enumeration for properties of device information. - * * @since_tizen 3.0 */ typedef enum { @@ -221,9 +217,9 @@ typedef enum { IOTCON_DEVICE_INFO_DATA_MODEL_VER, /**< Indicates version of the specs this device data model is implemented to */ } iotcon_device_info_e; + /** * @brief Enumeration for properties of platform information. - * * @since_tizen 3.0 */ typedef enum { @@ -240,9 +236,9 @@ typedef enum { IOTCON_PLATFORM_INFO_SYSTEM_TIME, /**< Indicates reference time for the device */ } iotcon_platform_info_e; + /** * @brief Enumeration for states of remote resource. - * * @since_tizen 3.0 */ typedef enum { @@ -250,9 +246,9 @@ typedef enum { IOTCON_REMOTE_RESOURCE_LOST_SIGNAL, /**< Indicates remote resource is lost */ } iotcon_remote_resource_state_e; + /** * @brief Enumeration for quality of service. - * * @since_tizen 3.0 */ typedef enum { @@ -260,8 +256,10 @@ typedef enum { IOTCON_QOS_HIGH, /**< Indicates high quality of service */ } iotcon_qos_e; + /** * @} */ + #endif /* __IOTCON_CONSTANT_H__ */ diff --git a/include/iotcon-errors.h b/include/iotcon-errors.h index 4cd7e62..13a5916 100644 --- a/include/iotcon-errors.h +++ b/include/iotcon-errors.h @@ -13,24 +13,29 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_ERRORS_H__ #define __IOTCON_ERRORS_H__ + #include <tizen.h> + #ifndef TZ_VER_3 #define TIZEN_ERROR_IOTCON -0x01C80000 #endif + /** * @file iotcon-errors.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_MODULE * @brief Enumeration for IoTCon error code. * @since_tizen 3.0 - * * @{ */ typedef enum { @@ -49,6 +54,7 @@ typedef enum { IOTCON_ERROR_SYSTEM = TIZEN_ERROR_IOTCON | 0x06, /**< System errors */ } iotcon_error_e; + /* * IOTCON_ERROR_NONE 0 * IOTCON_ERROR_IO_ERROR -5 @@ -65,8 +71,10 @@ typedef enum { * IOTCON_ERROR_SYSTEM -29884410 */ + /** * @} */ + #endif /* __IOTCON_ERRORS_H__ */ diff --git a/include/iotcon-list.h b/include/iotcon-list.h index 0c9b114..e246f5b 100644 --- a/include/iotcon-list.h +++ b/include/iotcon-list.h @@ -13,27 +13,28 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_STRUCT_LIST_H__ #define __IOTCON_STRUCT_LIST_H__ + #include <iotcon-types.h> + /** * @file iotcon-list.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_ATTRIBUTES_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_ATTRIBUTES_LIST_MODULE List - * * @brief IoTCon List provides API to get data from list and set data to list. - * * @section CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_ATTRIBUTES_LIST_MODULE_HEADER Required Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_ATTRIBUTES_LIST_MODULE_OVERVIEW Overview - * The iotcon list API provides list of bool, integer, double, string, byte string, list and attributes handle. - * + * The IoTCon list API provides list of bool, integer, double, string, byte string, list and attributes handle. * Example : * @code static void _request_handler(iotcon_resource_h resource, iotcon_request_h request, @@ -152,676 +153,586 @@ static void _request_handler(iotcon_resource_h resource, iotcon_request_h reques ... } * @endcode - * * @section CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_ATTRIBUTES_LIST_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/iot.ocf\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * 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.\n - * - * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> - * + * This API is related with the following features: \n + * - http://tizen.org/feature/iot.ocf \n + * It is recommended to design feature related codes in your application for reliability. \n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n + * 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. \n + * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> * @{ */ + /** * @brief Creates a new list handle. - * * @since_tizen 3.0 - * - * @remarks You must destroy @a list by calling iotcon_list_destroy() - * if @a list is no longer needed. - * + * @remarks You must destroy @a list by calling iotcon_list_destroy() if @a list is no longer needed. * @param[in] type The type of list * @param[out] list A newly allocated list handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type */ int iotcon_list_create(iotcon_type_e type, iotcon_list_h *list); + /** * @brief Destroys a list handle. * @details Releases a @a list and its internal data. - * * @since_tizen 3.0 - * * @param[in] list The handle to the list - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ int iotcon_list_destroy(iotcon_list_h list); + /** * @brief Adds a new element integer value into the list at the given position. - * @details If @a pos is negative, or is larger than the number of elements in the list, - * the new value is added on to the end of the list. - * + * @details If @a pos is negative, or is larger than the number of elements in the list, the new value is added on to the end of the list. * @since_tizen 3.0 - * * @param[in] list The list handle * @param[in] val The new integer value * @param[in] pos The position to insert value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type */ int iotcon_list_add_int(iotcon_list_h list, int val, int pos); + /** * @brief Adds a new element boolean value into the list at the given position. - * @details If @a pos is negative, or is larger than the number of elements in the list, - * the new value is added on to the end of the list. - * + * @details If @a pos is negative, or is larger than the number of elements in the list, the new value is added on to the end of the list. * @since_tizen 3.0 - * * @param[in] list The list handle * @param[in] val The new boolean value * @param[in] pos The position to insert value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type */ int iotcon_list_add_bool(iotcon_list_h list, bool val, int pos); + /** * @brief Adds a new element double value into the list at the given position. - * @details If @a pos is negative, or is larger than the number of elements in the list, - * the new value is added on to the end of the list. - * + * @details If @a pos is negative, or is larger than the number of elements in the list, the new value is added on to the end of the list. * @since_tizen 3.0 - * * @param[in] list The list handle * @param[in] val The new double value * @param[in] pos The position to insert value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type */ int iotcon_list_add_double(iotcon_list_h list, double val, int pos); + /** * @brief Adds a new element string value into the list at the given position. - * @details If @a pos is negative, or is larger than the number of elements in the list, - * the new value is added on to the end of the list. - * + * @details If @a pos is negative, or is larger than the number of elements in the list, the new value is added on to the end of the list. * @since_tizen 3.0 - * * @param[in] list The list handle * @param[in] val The new char value * @param[in] pos The position to insert value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type */ int iotcon_list_add_str(iotcon_list_h list, char *val, int pos); + /** * @brief Adds a new element byte string value into the list at the given position. - * @details If @a pos is negative, or is larger than the number of elements in the list, - * the new value is added on to the end of the list. - * + * @details If @a pos is negative, or is larger than the number of elements in the list, the new value is added on to the end of the list. * @since_tizen 3.0 - * * @param[in] list The list handle * @param[in] val The new byte string value * @param[in] len The length of @a val * @param[in] pos The position to insert value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type */ int iotcon_list_add_byte_str(iotcon_list_h list, unsigned char *val, int len, int pos); + /** * @brief Adds a new element list into the list at the given position. - * @details If @a pos is negative, or is larger than the number of elements in the list, - * the new value is added on to the end of the list. - * + * @details If @a pos is negative, or is larger than the number of elements in the list, the new value is added on to the end of the list. * @since_tizen 3.0 - * * @param[in] list The list handle * @param[in] val The new list value * @param[in] pos The position to insert value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type */ int iotcon_list_add_list(iotcon_list_h list, iotcon_list_h val, int pos); /** * @brief Adds a new element attributes value into the list at the given position. - * @details If @a pos is negative, or is larger than the number of elements in the list, - * the new value is added on to the end of the list. - * + * @details If @a pos is negative, or is larger than the number of elements in the list, the new value is added on to the end of the list. * @since_tizen 3.0 - * * @param[in] list The list handle * @param[in] val The new attributes value * @param[in] pos The position to insert value - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_INVALID_TYPE Invalid type */ int iotcon_list_add_attributes(iotcon_list_h list, iotcon_attributes_h val, int pos); + /** * @brief Gets the integer value at the given position. * @details Iterates over the list until it reaches the @a pos-1 position. - * * @since_tizen 3.0 - * * @param[in] list The list handle * @param[in] pos The position * @param[out] val The integer value to get - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * @retval #IOTCON_ERROR_REPRESENTATION Representation errors + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available + * @retval #IOTCON_ERROR_REPRESENTATION Representation errors */ int iotcon_list_get_nth_int(iotcon_list_h list, int pos, int *val); + /** * @brief Gets the boolean value at the given position. * @details Iterates over the list until it reaches the @a pos-1 position. - * * @since_tizen 3.0 - * * @param[in] list The list handle * @param[in] pos The position * @param[out] val The boolean value to get - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * @retval #IOTCON_ERROR_REPRESENTATION Representation errors + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available + * @retval #IOTCON_ERROR_REPRESENTATION Representation errors */ int iotcon_list_get_nth_bool(iotcon_list_h list, int pos, bool *val); + /** * @brief Gets the double value at the given position. * @details Iterates over the list until it reaches the @a pos-1 position. - * * @since_tizen 3.0 - * * @param[in] list The list handle * @param[in] pos The position * @param[out] val The double value to get - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * @retval #IOTCON_ERROR_REPRESENTATION Representation errors + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available + * @retval #IOTCON_ERROR_REPRESENTATION Representation errors */ int iotcon_list_get_nth_double(iotcon_list_h list, int pos, double *val); + /** * @brief Gets the string value at the given position. * @details Iterates over the list until it reaches the @a pos-1 position. - * * @since_tizen 3.0 - * * @remarks @a val must not be released using free(). - * * @param[in] list The list handle * @param[in] pos The position * @param[out] val The string value to get - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * @retval #IOTCON_ERROR_REPRESENTATION Representation errors + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available + * @retval #IOTCON_ERROR_REPRESENTATION Representation errors */ int iotcon_list_get_nth_str(iotcon_list_h list, int pos, char **val); + /** * @brief Gets the string value at the given position. * @details Iterates over the list until it reaches the @a pos-1 position. - * * @since_tizen 3.0 - * * @remarks @a val must not be released using free(). - * * @param[in] list The list handle * @param[in] pos The position * @param[out] val The byte string value to get * @param[out] len The length of the @a val - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * @retval #IOTCON_ERROR_REPRESENTATION Representation errors + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available + * @retval #IOTCON_ERROR_REPRESENTATION Representation errors */ -int iotcon_list_get_nth_byte_str(iotcon_list_h list, int pos, unsigned char **val, - int *len); +int iotcon_list_get_nth_byte_str(iotcon_list_h list, int pos, unsigned char **val, int *len); + /** * @brief Gets the list value at the given position. * @details Iterates over the list until it reaches the @a pos-1 position. - * * @since_tizen 3.0 - * * @remarks @a dest must not be released using iotcon_list_destroy(). - * * @param[in] src The list handle * @param[in] pos The position * @param[out] dest The list value to get - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * @retval #IOTCON_ERROR_REPRESENTATION Representation errors + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available + * @retval #IOTCON_ERROR_REPRESENTATION Representation errors */ int iotcon_list_get_nth_list(iotcon_list_h src, int pos, iotcon_list_h *dest); + /** * @brief Gets the attributes value at the given position. * @details Iterates over the list until it reaches the @a pos-1 position. - * * @since_tizen 3.0 - * * @remarks @a attributes must not be released using iotcon_attributes_destroy(). - * * @param[in] list The list handle * @param[in] pos The position * @param[out] attributes The attributes value to get - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * @retval #IOTCON_ERROR_REPRESENTATION Representation errors + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available + * @retval #IOTCON_ERROR_REPRESENTATION Representation errors */ int iotcon_list_get_nth_attributes(iotcon_list_h list, int pos, iotcon_attributes_h *attributes); + /** * @brief Removes the value at the given position. * @details Iterates over the list until it reaches the @a pos-1 position. - * * @since_tizen 3.0 - * * @param[in] list The list handle * @param[in] pos The position to delete - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available */ int iotcon_list_remove_nth(iotcon_list_h list, int pos); + /** * @brief Gets the type of the list. - * @details It gets the data type of value related the @a key in @a attributes. - * The data type could be one of #iotcon_type_e. - * + * @details It gets the data type of value related to the @a key in @a attributes. + * The data type could be one of #iotcon_type_e. * @since_tizen 3.0 - * * @param[in] list The list handle - * @param[out] type The data type of list. - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @param[out] type The data type of list + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ int iotcon_list_get_type(iotcon_list_h list, iotcon_type_e *type); + /** * @brief Gets the number of elements in a list. - * * @since_tizen 3.0 - * * @param[in] list The handle to the list * @param[out] length The length of list - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ int iotcon_list_get_length(iotcon_list_h list, unsigned int *length); + /** * @brief Specifies the type of function passed to iotcon_list_foreach_int(). - * * @since_tizen 3.0 - * * @param[in] pos The number of the integer value (0 being the first) * @param[in] value The integer value * @param[in] user_data The user data to pass to the function - * - * @return 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. - * + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre iotcon_list_foreach_int() will invoke this callback function. - * * @see iotcon_list_foreach_int() */ typedef bool (*iotcon_list_int_cb)(int pos, int value, void *user_data); + /** * @brief Gets all integer values of the given list by invoking the callback function. * @details iotcon_list_int_cb() will be called for each child. - * * @since_tizen 3.0 - * * @param[in] list The handle to the list * @param[in] cb The callback function to get each integer value * @param[in] user_data The user data to be passed to the callback function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @post iotcon_list_int_cb() will be called for each item. - * * @see iotcon_list_int_cb() */ int iotcon_list_foreach_int(iotcon_list_h list, iotcon_list_int_cb cb, void *user_data); + /** * @brief Specifies the type of function passed to iotcon_list_foreach_bool(). - * * @since_tizen 3.0 - * * @param[in] pos The number of the boolean value (0 being the first) * @param[in] value The boolean value * @param[in] user_data The user data to pass to the function - * - * @return 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. - * + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre iotcon_list_foreach_bool() will invoke this callback function. - * * @see iotcon_list_foreach_bool() */ typedef bool (*iotcon_list_bool_cb)(int pos, bool value, void *user_data); + /** * @brief Gets all boolean values of the given list by invoking the callback function. * @details iotcon_list_bool_cb() will be called for each child. - * * @since_tizen 3.0 - * * @param[in] list The handle to the list * @param[in] cb The callback function to get each boolean value * @param[in] user_data The user data to be passed to the callback function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @post iotcon_list_bool_cb() will be called for each item. - * * @see iotcon_list_bool_cb() */ int iotcon_list_foreach_bool(iotcon_list_h list, iotcon_list_bool_cb cb, void *user_data); + /** - * @brief Specifies the type of function passed to iotcon_list_foreach_double() - * + * @brief Specifies the type of function passed to iotcon_list_foreach_double(). * @since_tizen 3.0 - * * @param[in] pos The number of the double value (0 being the first) * @param[in] value The double value * @param[in] user_data The user data to pass to the function - * - * @return 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. - * + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre iotcon_list_foreach_double() will invoke this callback function. - * * @see iotcon_list_foreach_double() */ typedef bool (*iotcon_list_double_cb)(int pos, double value, void *user_data); + /** * @brief Gets all double values of the given list by invoking the callback function. * @details iotcon_list_double_cb() will be called for each child. - * * @since_tizen 3.0 - * * @param[in] list The handle to the list * @param[in] cb The callback function to get each double value * @param[in] user_data The user data to be passed to the callback function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @post iotcon_list_double_cb() will be called for each item. - * * @see iotcon_list_double_cb() */ -int iotcon_list_foreach_double(iotcon_list_h list, iotcon_list_double_cb cb, - void *user_data); +int iotcon_list_foreach_double(iotcon_list_h list, iotcon_list_double_cb cb, void *user_data); + /** * @brief Specifies the type of function passed to iotcon_list_foreach_byte_str(). - * * @since_tizen 3.0 - * * @param[in] pos The number of the string value (0 being the first) * @param[in] value The byte string value * @param[in] len The length of @a value * @param[in] user_data The user data to pass to the function - * - * @return 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. - * + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre iotcon_list_foreach_byte_str() will invoke this callback function. - * * @see iotcon_list_foreach_byte_str() */ -typedef bool (*iotcon_list_byte_str_cb)(int pos, const unsigned char *value, int len, - void *user_data); +typedef bool (*iotcon_list_byte_str_cb)(int pos, const unsigned char *value, int len, void *user_data); + /** * @brief Gets all string values of the given list by invoking the callback function. * @details iotcon_list_byte_str_cb() will be called for each child. - * * @since_tizen 3.0 - * * @param[in] list The handle to the list * @param[in] cb The callback function to get each string value * @param[in] user_data The user data to be passed to the callback function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @post iotcon_list_byte_str_cb() will be called for each item. - * * @see iotcon_list_byte_str_cb() */ -int iotcon_list_foreach_byte_str(iotcon_list_h list, iotcon_list_byte_str_cb cb, - void *user_data); +int iotcon_list_foreach_byte_str(iotcon_list_h list, iotcon_list_byte_str_cb cb, void *user_data); + /** * @brief Specifies the type of function passed to iotcon_list_foreach_str(). - * * @since_tizen 3.0 - * * @param[in] pos The number of the string value (0 being the first) * @param[in] value The string value * @param[in] user_data The user data to pass to the function - * - * @return 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. - * + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre iotcon_list_foreach_str() will invoke this callback function. - * * @see iotcon_list_foreach_str() */ typedef bool (*iotcon_list_str_cb)(int pos, const char *value, void *user_data); + /** * @brief Gets all string values of the given list by invoking the callback function. * @details iotcon_list_str_cb() will be called for each child. - * * @since_tizen 3.0 - * * @param[in] list The handle to the list * @param[in] cb The callback function to get each string value * @param[in] user_data The user data to be passed to the callback function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @post iotcon_list_str_cb() will be called for each item. - * * @see iotcon_list_str_cb() */ int iotcon_list_foreach_str(iotcon_list_h list, iotcon_list_str_cb cb, void *user_data); + /** * @brief Specifies the type of function passed to iotcon_list_foreach_list(). - * * @since_tizen 3.0 - * * @param[in] pos The number of the list value (0 being the first) * @param[in] value The list value * @param[in] user_data The user data to pass to the function - * - * @return 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. - * + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre iotcon_list_foreach_list() will invoke this callback function. - * * @see iotcon_list_foreach_list() */ typedef bool (*iotcon_list_list_cb)(int pos, iotcon_list_h value, void *user_data); + /** * @brief Gets all sub lists of the given list by invoking the callback function. * @details iotcon_list_list_cb() will be called for each child. - * * @since_tizen 3.0 - * * @param[in] list The handle to the origin list * @param[in] cb The callback function to get each sub list * @param[in] user_data The user data to be passed to the callback function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @post iotcon_list_list_cb() will be called for each item. - * * @see iotcon_list_list_cb() */ int iotcon_list_foreach_list(iotcon_list_h list, iotcon_list_list_cb cb, void *user_data); + /** * @brief Specifies the type of function passed to iotcon_list_foreach_attributes(). - * * @since_tizen 3.0 - * * @param[in] pos The number of the attributes value (0 being the first) * @param[in] value The attributes value * @param[in] user_data The user data to pass to the function - * - * @return 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. - * + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre iotcon_list_foreach_attributes() will invoke this callback function. - * * @see iotcon_list_foreach_attributes() */ typedef bool (*iotcon_list_attributes_cb)(int pos, iotcon_attributes_h value, void *user_data); + /** * @brief Gets all attributes of the given list by invoking the callback function. * @details iotcon_list_attributes_cb() will be called for each child. - * * @since_tizen 3.0 - * * @param[in] list The handle to the list * @param[in] cb The callback function to get each attributes * @param[in] user_data The user data to be passed to the callback function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @post iotcon_list_attributes_cb() will be called for each item. - * * @see iotcon_list_attributes_cb() */ int iotcon_list_foreach_attributes(iotcon_list_h list, iotcon_list_attributes_cb cb, void *user_data); + /** * @} */ + #endif /* __IOTCON_STRUCT_LIST_H__ */ diff --git a/include/iotcon-lite-resource.h b/include/iotcon-lite-resource.h index dd54aee..b4502d7 100644 --- a/include/iotcon-lite-resource.h +++ b/include/iotcon-lite-resource.h @@ -13,31 +13,32 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_SERVER_LITE_RESOURCE_H__ #define __IOTCON_SERVER_LITE_RESOURCE_H__ + #include <stdint.h> #include <iotcon-types.h> + /** * @file iotcon-lite-resource.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_SERVER_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_SERVER_LITE_RESOURCE_MODULE Lite Resource - * * @brief IoTCon Lite Resource provides API to encapsulate resources. - * * @section CAPI_IOT_CONNECTIVITY_SERVER_LITE_RESOURCE_MODULE_HEADER Required Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_SERVER_LITE_RESOURCE_MODULE_OVERVIEW Overview - * This API provides that the users manages resources without request handler. - * When client request by CRUD functions, internal default request handler will be invoked. - * The default request handler will create response and send to client automatically. - * When updated attributes by iotcon_lite_resource_update_attributes(), changes will notify to observers. - * + * This API provides that the users manage resources without request handler. + * When client request by CRUD functions, internal default request handler will be invoked. + * The default request handler will create response and send to client automatically. + * When updated attributes by iotcon_lite_resource_update_attributes(), changes will be notified to observers. * Example : * @code #include <iotcon.h> @@ -131,156 +132,122 @@ static void _update_brightness(int brightness) } * @endcode - * * @section CAPI_IOT_CONNECTIVITY_SERVER_LITE_RESOURCE_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/iot.ocf\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * 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.\n - * - * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> - * + * This API is related with the following features: \n + * - http://tizen.org/feature/iot.ocf \n + * It is recommended to design feature related codes in your application for reliability. \n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n + * 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. \n + * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> * @{ */ + /** * @brief Specifies the type of function passed to iotcon_lite_resource_create(). - * * @since_tizen 3.0 - * * @param[in] resource The handle of the lite resource * @param[in] attributes The attributes of the lite resource * @param[in] user_data The user data to pass to the function - * - * @pre The callback must be registered using iotcon_lite_resource_create() - * - * @return true to accept post request, otherwise false to reject it. - * + * @return @c true to accept post request, + * otherwise @c false to reject it + * @pre The callback must be registered using iotcon_lite_resource_create(). * @see iotcon_lite_resource_create() */ -typedef bool (*iotcon_lite_resource_post_request_cb)(iotcon_lite_resource_h resource, - iotcon_attributes_h attributes, void *user_data); +typedef bool (*iotcon_lite_resource_post_request_cb)(iotcon_lite_resource_h resource, iotcon_attributes_h attributes, void *user_data); /** * @brief Creates a lite resource handle and registers the resource in server. - * @details Registers a resource specified by @a uri_path, @a res_types, @a attributes which have - * @a properties in IoTCon server.\n - * When client requests some operations, it send a response to client, automatically.\n - * The @a policies can contain multiple policies like - * IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE. - * + * @details Registers a resource specified by @a uri_path, @a res_types, @a attributes which have @a properties in IoTCon server. \n + * When client requests some operations, it send a response to client, automatically.\n + * The @a policies can contain multiple policies like IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE. * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * - * @remarks @a uri_path length must be less than 128.\n - * You must destroy @a resource_handle by calling iotcon_lite_resource_destroy() - * if @a remote_handle is no longer needed. - * + * @remarks @a uri_path length must be less than 128. \n + * You must destroy @a resource_handle by calling iotcon_lite_resource_destroy() if @a remote_handle is no longer needed. * @param[in] uri_path The URI path of the resource * @param[in] res_types The list of type of the resource - * @param[in] policies The policies of the resource\n Set of #iotcon_resource_policy_e + * @param[in] policies The policies of the resource \n + * Set of #iotcon_resource_policy_e * @param[in] attributes The attributes handle to set * @param[in] cb The callback function to add into callback list * @param[in] user_data The user data to pass to the callback function * @param[out] resource_handle The handle of the resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_IOTIVITY IoTivity errors - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_IOTIVITY IoTivity errors + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_lite_resource_destroy() */ -int iotcon_lite_resource_create(const char *uri_path, - iotcon_resource_types_h res_types, - uint8_t policies, - iotcon_attributes_h attributes, - iotcon_lite_resource_post_request_cb cb, - void *user_data, - iotcon_lite_resource_h *resource_handle); +int iotcon_lite_resource_create(const char *uri_path, iotcon_resource_types_h res_types, uint8_t policies, iotcon_attributes_h attributes, iotcon_lite_resource_post_request_cb cb, void *user_data, iotcon_lite_resource_h *resource_handle); + /** * @brief Destroys the resource and releases its data. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * - * @remarks When a normal variable is used, there are only permission denied error. - * If the errors of this API are not handled, then you must check an application have - * the privileges for the API. - * + * @remarks When a normal variable is used, there is only permission denied error. + * If the errors of this API are not handled, then you must check an application having the privileges for the API. * @param[in] resource The handle of the lite resource to be unregistered - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_lite_resource_create() */ int iotcon_lite_resource_destroy(iotcon_lite_resource_h resource); + /** * @brief Updates attributes into the lite resource handle. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] resource The handle of the lite resource * @param[in] attributes The attributes handle to update - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_lite_resource_get_attributes() */ -int iotcon_lite_resource_update_attributes(iotcon_lite_resource_h resource, - iotcon_attributes_h attributes); +int iotcon_lite_resource_update_attributes(iotcon_lite_resource_h resource, iotcon_attributes_h attributes); + /** * @brief Gets attributes from the lite resource handle. - * * @since_tizen 3.0 - * * @remarks @a attributes must not be released using iotcon_attributes_destroy(). - * * @param[in] resource The handle of the lite resource * @param[out] attributes The attributes handle of the lite resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_lite_resource_update_attributes() */ -int iotcon_lite_resource_get_attributes(iotcon_lite_resource_h resource, - iotcon_attributes_h *attributes); +int iotcon_lite_resource_get_attributes(iotcon_lite_resource_h resource, iotcon_attributes_h *attributes); + /** * @} */ + #endif /* __IOTCON_SERVER_LITE_RESOURCE_H__ */ diff --git a/include/iotcon-observers.h b/include/iotcon-observers.h index 9961936..9dc9062 100644 --- a/include/iotcon-observers.h +++ b/include/iotcon-observers.h @@ -13,27 +13,28 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_SERVER_OBSERVERS_H__ #define __IOTCON_SERVER_OBSERVERS_H__ + #include <iotcon-types.h> + /** * @file iotcon-observers.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_SERVER_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_SERVER_OBSERVERS_MODULE Observers - * * @brief IoTCon Observers provides API to manage client observing a resource. - * * @section CAPI_IOT_CONNECTIVITY_SERVER_OBSERVERS_MODULE_HEADER Required Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_SERVER_OBSERVERS_MODULE_OVERVIEW Overview - * The iotcon overview API provides methods for managing observe id. - * + * The IoTcon overview API provides methods for managing observe ID. * Example : * @code #include <iotcon.h> @@ -112,102 +113,88 @@ static void _request_handler(iotcon_resource_h resource, iotcon_request_h reques ... } * @endcode - * * @section CAPI_IOT_CONNECTIVITY_SERVER_OBSERVERS_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/iot.ocf\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * 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.\n - * - * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> - * + * This API is related with the following features: \n + * - http://tizen.org/feature/iot.ocf \n + * It is recommended to design feature related codes in your application for reliability.\n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n + * 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.\n + * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> * @{ */ + /** * @brief Creates a new observers handle. - * * @since_tizen 3.0 - * - * @remarks You must destroy @a observers by calling iotcon_observers_destroy() - * if @a observers is no longer needed. - * + * @remarks You must destroy @a observers by calling iotcon_observers_destroy() if @a observers is no longer needed. * @param[out] observers A newly allocated list of observers handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @see iotcon_observers_destroy() * @see iotcon_observers_add() * @see iotcon_observers_remove() */ int iotcon_observers_create(iotcon_observers_h *observers); + /** * @brief Destroys a observers handle. - * * @since_tizen 3.0 - * * @param[in] observers The handle of the observers - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_observers_create() * @see iotcon_observers_add() * @see iotcon_observers_remove() */ int iotcon_observers_destroy(iotcon_observers_h observers); + /** - * @brief Adds a observer id into the observers handle. - * + * @brief Adds an observers ID into the observers handle. * @since_tizen 3.0 - * * @param[in] observers The handle of the observers - * @param[in] obs_id The id to be appended to observers - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @param[in] obs_id The ID to be appended to observers + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_observers_create() * @see iotcon_observers_destroy() * @see iotcon_observers_remove() */ int iotcon_observers_add(iotcon_observers_h observers, int obs_id); + /** - * @brief Removes id from the observers. - * + * @brief Removes ID from the observers. * @since_tizen 3.0 - * * @param[in] observers observers The handle of the observers - * @param[in] obs_id The id to be removed from observers - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @param[in] obs_id The ID to be removed from observers + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_observers_create() * @see iotcon_observers_destroy() * @see iotcon_observers_add() */ int iotcon_observers_remove(iotcon_observers_h observers, int obs_id); + /** * @} */ + #endif /* __IOTCON_SERVER_OBSERVERS_H__ */ diff --git a/include/iotcon-options.h b/include/iotcon-options.h index 0fcaa44..ba29f84 100644 --- a/include/iotcon-options.h +++ b/include/iotcon-options.h @@ -13,28 +13,29 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_STRUCT_OPTIONS_H__ #define __IOTCON_STRUCT_OPTIONS_H__ + #include <iotcon-types.h> + /** * @file iotcon-options.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_COMMON_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_COMMON_OPTIONS_MODULE Options - * * @brief IoTCon Options provides API to manage options. - * * @section CAPI_IOT_CONNECTIVITY_COMMON_OPTIONS_MODULE_HEADER Required Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_COMMON_OPTIONS_MODULE_OVERVIEW Overview - * The iotcon options API provides methods for managing vendor specific options of coap packet.\n - * See more about coap packet in http://tools.ietf.org/html/rfc7252. - * + * The IoTcon options API provides methods for managing vendor specific options of coap packet. \n + * See more about coap packet in http://tools.ietf.org/html/rfc7252. * Example (Client side) : * @code #include <iotcon.h> @@ -101,38 +102,28 @@ static void _request_handler(iotcon_resource_h resource, iotcon_request_h reques } * @endcode - * * @section CAPI_IOT_CONNECTIVITY_COMMON_OPTIONS_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/iot.ocf\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * 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.\n - * - * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> - * + * This API is related with the following features: \n + * - http://tizen.org/feature/iot.ocf \n + * It is recommended to design feature related codes in your application for reliability. \n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n + * 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. \n + * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> * @{ */ + /** * @brief Creates a new option handle. - * * @since_tizen 3.0 - * - * @remarks You must destroy @a options by calling iotcon_options_destroy() - * if @a options is no longer needed. - * + * @remarks You must destroy @a options by calling iotcon_options_destroy() if @a options is no longer needed. * @param[out] options A newly allocated option handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * * @see iotcon_options_destroy() * @see iotcon_options_add() * @see iotcon_options_remove() @@ -140,18 +131,16 @@ static void _request_handler(iotcon_resource_h resource, iotcon_request_h reques */ int iotcon_options_create(iotcon_options_h *options); + /** * @brief Destroys an option handle. - * * @since_tizen 3.0 - * * @param[in] options The handle of the options - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * * @see iotcon_options_create() * @see iotcon_options_add() * @see iotcon_options_remove() @@ -159,45 +148,40 @@ int iotcon_options_create(iotcon_options_h *options); */ int iotcon_options_destroy(iotcon_options_h options); + /** - * @brief Adds a new id and a corresponding data into the options. - * + * @brief Adds a new ID and a corresponding data into the options. * @since_tizen 3.0 * @remarks iotcon_options_h can have up to 2 options. \n - * option id is always situated between 2048 and 3000. \n - * Length of option data is less than or equal to 15. - * + * Option ID is always situated between 2048 and 3000. \n + * Length of option data is less than or equal to 15. * @param[in] options The handle of the options - * @param[in] id The id of the option to insert + * @param[in] id The ID of the option to insert * @param[in] data The string data to insert into the options - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_options_create() * @see iotcon_options_destroy() * @see iotcon_options_remove() * @see iotcon_options_lookup() */ -int iotcon_options_add(iotcon_options_h options, unsigned short id, - const char *data); +int iotcon_options_add(iotcon_options_h options, unsigned short id, const char *data); + /** - * @brief Removes the id and its associated data from the options. - * + * @brief Removes the ID and its associated data from the options. * @since_tizen 3.0 - * * @param[in] options The handle of the options - * @param[in] id The id of the option to delete - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @param[in] id The ID of the option to delete + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_options_create() * @see iotcon_options_destroy() * @see iotcon_options_add() @@ -205,22 +189,19 @@ int iotcon_options_add(iotcon_options_h options, unsigned short id, */ int iotcon_options_remove(iotcon_options_h options, unsigned short id); + /** - * @brief Looks up data at the given id from the options. - * + * @brief Looks up data at the given ID from the options. * @since_tizen 3.0 - * * @remarks @a data must not be released using free(). - * * @param[in] options The handle of the options - * @param[in] id The id of the option to lookup + * @param[in] id The ID of the option to lookup * @param[out] data Found data from options - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_options_create() * @see iotcon_options_destroy() * @see iotcon_options_add() @@ -228,51 +209,44 @@ int iotcon_options_remove(iotcon_options_h options, unsigned short id); */ int iotcon_options_lookup(iotcon_options_h options, unsigned short id, char **data); + /** * @brief Specifies the type of function passed to iotcon_options_foreach(). - * * @since_tizen 3.0 - * * @param[in] id The information of the option * @param[in] data The data of the option * @param[in] user_data The user data to pass to the function - * - * @return 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. - * + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre iotcon_options_foreach() will invoke this callback function. - * * @see iotcon_options_foreach() */ -typedef bool (*iotcon_options_foreach_cb)(unsigned short id, const char *data, - void *user_data); +typedef bool (*iotcon_options_foreach_cb)(unsigned short id, const char *data, void *user_data); + /** * @brief Gets all data of the options by invoking the callback function. - * @details iotcon_options_foreach_cb() will be called for each option.\n - * If iotcon_options_foreach_cb() returns false, iteration will be stop. - * + * @details iotcon_options_foreach_cb() will be called for each option. \n + * If iotcon_options_foreach_cb() returns false, iteration will be stopped. * @since_tizen 3.0 - * * @param[in] options The handle of the options * @param[in] cb The callback function to get data * @param[in] user_data The user data to pass to the function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @post iotcon_options_foreach_cb() will be called for each option. - * * @see iotcon_options_foreach_cb() */ -int iotcon_options_foreach(iotcon_options_h options, iotcon_options_foreach_cb cb, - void *user_data); +int iotcon_options_foreach(iotcon_options_h options, iotcon_options_foreach_cb cb, void *user_data); + /** * @} */ + #endif /* __IOTCON_STRUCT_OPTIONS_H__ */ diff --git a/include/iotcon-query.h b/include/iotcon-query.h index 908984b..4821788 100644 --- a/include/iotcon-query.h +++ b/include/iotcon-query.h @@ -13,27 +13,28 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_STRUCT_QUERY_H__ #define __IOTCON_STRUCT_QUERY_H__ + #include <iotcon-types.h> + /** * @file iotcon-query.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_COMMON_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_COMMON_QUERY_MODULE Query - * * @brief IoTCon Query provides API to manage query. - * * @section CAPI_IOT_CONNECTIVITY_COMMON_QUERY_MODULE_HEADER Required Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_COMMON_QUERY_MODULE_OVERVIEW Overview - * The iotcon query API provides methods for managing query of request. - * + * The IoTCon Query API provides methods for managing query of request. * Example (Client side) : * @code #include <iotcon.h> @@ -91,38 +92,28 @@ static void _request_handler(iotcon_resource_h resource, iotcon_request_h reques ... } * @endcode - * * @section CAPI_IOT_CONNECTIVITY_COMMON_QUERY_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/iot.ocf\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * 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.\n - * - * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> - * + * This API is related with the following features: \n + * - http://tizen.org/feature/iot.ocf\n + * It is recommended to design feature related codes in your application for reliability. \n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n + * 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. \n + * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> * @{ */ + /** * @brief Creates a new query handle. - * * @since_tizen 3.0 - * - * @remarks You must destroy @a query by calling iotcon_query_destroy() - * if @a query is no longer needed. - * + * @remarks You must destroy @a query by calling iotcon_query_destroy() if @a query is no longer needed. * @param[out] query A newly allocated query handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_query_destroy() * @see iotcon_query_add() * @see iotcon_query_remove() @@ -130,18 +121,16 @@ static void _request_handler(iotcon_resource_h resource, iotcon_request_h reques */ int iotcon_query_create(iotcon_query_h *query); + /** * @brief Destroys a query handle. - * * @since_tizen 3.0 - * * @param[in] query The handle of the query - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_query_create() * @see iotcon_query_add() * @see iotcon_query_remove() @@ -149,25 +138,22 @@ int iotcon_query_create(iotcon_query_h *query); */ int iotcon_query_destroy(iotcon_query_h query); + /** * @brief Gets resource type from the query. - * * @since_tizen 3.0 - * * @remarks @a resource_type must not be released using free(). - * @a resource_type must start with a lowercase alphabetic character, followed by a sequence - * of lowercase alphabetic, numeric, ".", or "-" characters, and contains no white space. - * + * @a resource_type must start with a lowercase alphabetic character, followed by a sequence + * of lowercase alphabetic, numeric, ".", or "-" characters, and contains no white space. * @param[in] query The handle of the query * @param[out] resource_type Found resource type from query - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @see iotcon_query_create() * @see iotcon_query_destroy() * @see iotcon_query_add() @@ -176,23 +162,20 @@ int iotcon_query_destroy(iotcon_query_h query); */ int iotcon_query_get_resource_type(iotcon_query_h query, char **resource_type); + /** * @brief Gets resource interface from the query. - * * @since_tizen 3.0 - * * @remarks @a resource_iface could be a value such as #IOTCON_INTERFACE_DEFAULT. * @remarks @a resource_iface must not be released using free(). - * * @param[in] query The handle of the query * @param[out] resource_iface Found resource interface from query - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available * @see iotcon_query_create() * @see iotcon_query_destroy() * @see iotcon_query_add() @@ -201,20 +184,18 @@ int iotcon_query_get_resource_type(iotcon_query_h query, char **resource_type); */ int iotcon_query_get_interface(iotcon_query_h query, char **resource_iface); + /** * @brief Sets the resource type into the query. - * * @since_tizen 3.0 - * * @param[in] query The handle of the query * @param[in] resource_type The resource type to set into the query - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_query_create() * @see iotcon_query_destroy() * @see iotcon_query_add() @@ -224,22 +205,19 @@ int iotcon_query_get_interface(iotcon_query_h query, char **resource_iface); */ int iotcon_query_set_resource_type(iotcon_query_h query, const char *resource_type); + /** * @brief Sets the resource interface into the query. - * * @since_tizen 3.0 - * * @remarks @a resource_iface could be a value such as #IOTCON_INTERFACE_DEFAULT. - * * @param[in] query The handle of the query * @param[in] resource_iface The resource interface to add into the query - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_query_create() * @see iotcon_query_destroy() * @see iotcon_query_add() @@ -249,22 +227,20 @@ int iotcon_query_set_resource_type(iotcon_query_h query, const char *resource_ty */ int iotcon_query_set_interface(iotcon_query_h query, const char *resource_iface); + /** * @brief Adds a new key and corresponding value into the query. - * * @since_tizen 3.0 * @remarks The full length of query should be less than or equal to 64. - * * @param[in] query The handle of the query * @param[in] key The key of the query to insert * @param[in] value The string data to insert into the query - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_query_create() * @see iotcon_query_destroy() * @see iotcon_query_remove() @@ -272,19 +248,17 @@ int iotcon_query_set_interface(iotcon_query_h query, const char *resource_iface) */ int iotcon_query_add(iotcon_query_h query, const char *key, const char *value); + /** * @brief Removes the key and its associated value from the query. - * * @since_tizen 3.0 - * * @param[in] query The handle of the query * @param[in] key The key of the option to delete - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_query_create() * @see iotcon_query_destroy() * @see iotcon_query_add() @@ -292,22 +266,19 @@ int iotcon_query_add(iotcon_query_h query, const char *key, const char *value); */ int iotcon_query_remove(iotcon_query_h query, const char *key); + /** * @brief Looks up data at the given key from the query. - * * @since_tizen 3.0 - * * @remarks @a data must not be released using free(). - * * @param[in] query The handle of the query * @param[in] key The key of the query to lookup * @param[out] data Found data from query - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_query_create() * @see iotcon_query_destroy() * @see iotcon_query_add() @@ -315,51 +286,44 @@ int iotcon_query_remove(iotcon_query_h query, const char *key); */ int iotcon_query_lookup(iotcon_query_h query, const char *key, char **data); + /** * @brief Specifies the type of function passed to iotcon_query_foreach(). - * * @since_tizen 3.0 - * * @param[in] key The key of the query * @param[in] value The value of the query * @param[in] user_data The user data to pass to the function - * - * @return 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. - * + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre iotcon_query_foreach() will invoke this callback function. - * * @see iotcon_query_foreach() */ -typedef bool (*iotcon_query_foreach_cb)(const char *key, const char *value, - void *user_data); +typedef bool (*iotcon_query_foreach_cb)(const char *key, const char *value, void *user_data); + /** * @brief Gets all data of the query by invoking the callback function. - * @details iotcon_query_foreach_cb() will be called for each query.\n - * If iotcon_query_foreach_cb() returns false, iteration will be stop. - * + * @details iotcon_query_foreach_cb() will be called for each query. \n + * If iotcon_query_foreach_cb() returns false, iteration will be stopped. * @since_tizen 3.0 - * * @param[in] query The handle of the query * @param[in] cb The callback function to get data * @param[in] user_data The user data to be passed to the callback function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @post iotcon_query_foreach_cb() will be called for each query. - * * @see iotcon_query_foreach_cb() */ -int iotcon_query_foreach(iotcon_query_h query, iotcon_query_foreach_cb cb, - void *user_data); +int iotcon_query_foreach(iotcon_query_h query, iotcon_query_foreach_cb cb, void *user_data); + /** * @} */ + #endif /* __IOTCON_STRUCT_QUERY_H__ */ diff --git a/include/iotcon-remote-resource.h b/include/iotcon-remote-resource.h index 620e38b..64af3de 100644 --- a/include/iotcon-remote-resource.h +++ b/include/iotcon-remote-resource.h @@ -13,28 +13,29 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_CLIENT_REMOTE_RESOURCE_H__ #define __IOTCON_CLIENT_REMOTE_RESOURCE_H__ + #include <stdint.h> #include <iotcon-types.h> + /** * @file iotcon-remote-resource.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_CLIENT_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_CLIENT_REMOTE_RESOURCE_MODULE Remote Resource - * * @brief IoTCon Remote Resource provides API to manage remote resource. - * * @section CAPI_IOT_CONNECTIVITY_CLIENT_REMOTE_RESOURCE_MODULE_HEADER Required Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_CLIENT_REMOTE_RESOURCE_MODULE_OVERVIEW Overview - * The iotcon remote resource API provides methods for managing resource handle and send request. - * + * The IoTCon Remote Resource API provides methods for managing resource handle and send request. * Example : * @code #include <iotcon.h> @@ -91,505 +92,411 @@ static void _find_light_resource() * @endcode * * @section CAPI_IOT_CONNECTIVITY_CLIENT_REMOTE_RESOURCE_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/iot.ocf\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * 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.\n - * - * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> - * + * This API is related with the following features: \n + * - http://tizen.org/feature/iot.ocf \n + * It is recommended to design feature related codes in your application for reliability. \n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n + * 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. \n + * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> * @{ */ /** * @brief Creates a new resource handle. * @details Creates a resource proxy object so that iotcon_remote_resource_get(), - * iotcon_remote_resource_put(), iotcon_remote_resource_post(), - * iotcon_remote_resource_delete(), iotcon_remote_resource_observe_register(), - * iotcon_remote_resource_start_caching() and iotcon_remote_resource_start_monitoring() - * API can be used without discovering the object in advance.\n - * To use this API, you should provide all of the details required to correctly contact and - * observe the object.\n - * If not, you should discover the resource object manually.\n - * The @a policies can contain multiple policies like - * IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE.\n - * + * iotcon_remote_resource_put(), iotcon_remote_resource_post(), + * iotcon_remote_resource_delete(), iotcon_remote_resource_observe_register(), + * iotcon_remote_resource_start_caching() and iotcon_remote_resource_start_monitoring() + * API can be used without discovering the object in advance.\n + * To use this API, you should provide all of the details required to correctly contact and observe the object.\n + * If not, you should discover the resource object manually.\n + * The @a policies can contain multiple policies like IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE. * @since_tizen 3.0 - * - * @remarks You must destroy @a remote_resource by calling iotcon_remote_resource_destroy() - * if @a remote_resource is no longer needed. - * + * @remarks You must destroy @a remote_resource by calling iotcon_remote_resource_destroy() if @a remote_resource is no longer needed. * @param[in] host_address The host address of the resource * @param[in] connectivity_type The connectivity type. Can not use @a IOTCON_CONNECTIVITY_ALL. \n - * Connectivity type of specific remote resource(It has specific host address, not @a IOTCON_MULTICAST_ADDRESS) is already decided. \n - * Use specific connectivity type of the remote resource. \n - * You can refer to the @a iotcon_remote_resource_get_connectivity_type(). + * Connectivity type of specific remote resource(It has specific host address, not @a IOTCON_MULTICAST_ADDRESS) is already decided. \n + * Use specific connectivity type of the remote resource. \n + * You can refer to the @a iotcon_remote_resource_get_connectivity_type(). * @param[in] uri_path The URI path of the resource - * @param[in] policies The policies of the resource\n Set of #iotcon_resource_policy_e + * @param[in] policies The policies of the resource \n + * Set of #iotcon_resource_policy_e * @param[in] resource_types The resource types of the resource. For example, "core.light" - * @param[in] resource_ifaces The resource interfaces of the resource. + * @param[in] resource_ifaces The resource interfaces of the resource * @param[out] remote_resource Generated resource handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_IOTIVITY IoTivity errors - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_IOTIVITY IoTivity errors + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @see iotcon_remote_resource_destroy() * @see iotcon_remote_resource_clone() */ -int iotcon_remote_resource_create(const char *host_address, - iotcon_connectivity_type_e connectivity_type, - const char *uri_path, - uint8_t policies, - iotcon_resource_types_h resource_types, - iotcon_resource_interfaces_h resource_ifaces, - iotcon_remote_resource_h *remote_resource); +int iotcon_remote_resource_create(const char *host_address, iotcon_connectivity_type_e connectivity_type, const char *uri_path, uint8_t policies, iotcon_resource_types_h resource_types, iotcon_resource_interfaces_h resource_ifaces, iotcon_remote_resource_h *remote_resource); + /** * @brief Destroys a resource handle. * @since_tizen 3.0 - * * @param[in] resource The handle of the resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_remote_resource_create() * @see iotcon_remote_resource_clone() */ int iotcon_remote_resource_destroy(iotcon_remote_resource_h resource); + /** * @brief Clones a clone of a remote resource. - * * @since_tizen 3.0 - * - * @remarks You must destroy @a dest by calling iotcon_remote_resource_destroy() - * if @a dest is no longer needed. - * + * @remarks You must destroy @a dest by calling iotcon_remote_resource_destroy() if @a dest is no longer needed. * @param[in] src The Source of resource * @param[out] dest The cloned resource handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_remote_resource_create() * @see iotcon_remote_resource_destroy() */ int iotcon_remote_resource_clone(iotcon_remote_resource_h src, iotcon_remote_resource_h *dest); + /** - * @brief Specifies the type of observe callback passed to - * iotcon_remote_resource_observe_register(). - * The @a err could be one of #iotcon_error_e.\n - * The @a response is created by a server. Therefore, you can't get any values that the server didn't set. - * + * @brief Specifies the type of observe callback passed to iotcon_remote_resource_observe_register(). + * The @a err could be one of #iotcon_error_e. \n + * The @a response is created by a server. Therefore, you can't get any values that the server didn't set. * @since_tizen 3.0 - * * @param[in] resource The handle of the remote resource * @param[in] err The error code * @param[in] sequence_number The sequence number of observe * @param[in] response The handle of the response * @param[in] user_data The user data passed from the callback registration function - * * @pre The callback must be registered using iotcon_remote_resource_observe_register() - * * @see iotcon_remote_resource_observe_register() * @see iotcon_remote_resource_observe_deregister() * @see iotcon_resource_notify() */ -typedef void (*iotcon_remote_resource_observe_cb)(iotcon_remote_resource_h resource, - iotcon_error_e err, int sequence_number, iotcon_response_h response, void *user_data); +typedef void (*iotcon_remote_resource_observe_cb)(iotcon_remote_resource_h resource, iotcon_error_e err, int sequence_number, iotcon_response_h response, void *user_data); + /** * @brief Registers observe callback on the resource. * @details When server sends notification message, iotcon_remote_resource_observe_cb() will be called. - * The @a observe_policy could be one of #iotcon_observe_policy_e. - * + * The @a observe_policy could be one of #iotcon_observe_policy_e. * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] resource The handle of the resource - * @param[in] observe_policy The type to specify how client wants to observe. + * @param[in] observe_policy The type to specify how client wants to observe * @param[in] query The query to send to server * @param[in] cb The callback function to get notifications from server * @param[in] user_data The user data to pass to the function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_IOTIVITY IoTivity errors - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_IOTIVITY IoTivity errors + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. * @post When the @a resource receive notification message, iotcon_remote_resource_observe_cb() will be called. - * * @see iotcon_remote_resource_observe_cb() * @see iotcon_remote_resource_observe_deregister() * @see iotcon_resource_notify() */ -int iotcon_remote_resource_observe_register(iotcon_remote_resource_h resource, - iotcon_observe_policy_e observe_policy, - iotcon_query_h query, - iotcon_remote_resource_observe_cb cb, - void *user_data); +int iotcon_remote_resource_observe_register(iotcon_remote_resource_h resource, iotcon_observe_policy_e observe_policy, iotcon_query_h query, iotcon_remote_resource_observe_cb cb, void *user_data); + /** * @brief Deregisters observe callback on the resource. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] resource The handle of the resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_SYSTEM System error * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_remote_resource_observe_cb() * @see iotcon_remote_resource_observe_register() * @see iotcon_resource_notify() */ int iotcon_remote_resource_observe_deregister(iotcon_remote_resource_h resource); + /** * @brief Specifies the type of response function. * @details The function passed to iotcon_remote_resource_get(), iotcon_remote_resource_put(), - * iotcon_remote_resource_post(), iotcon_remote_resource_delete().\n - * The @a err could be one of #iotcon_error_e.\n - * The @a request_type could be one of #iotcon_request_type_e.\n - * The @a response is created by a server. Therefore, you can't get any values that the server didn't set. - * + * iotcon_remote_resource_post(), iotcon_remote_resource_delete().\n + * The @a err could be one of #iotcon_error_e.\n + * The @a request_type could be one of #iotcon_request_type_e.\n + * The @a response is created by a server. Therefore, you can't get any values that the server didn't set. * @since_tizen 3.0 - * * @param[in] resource The handle of the resource * @param[in] err The error code * @param[in] request_type The request type * @param[in] response The handle of the response * @param[in] user_data The user data passed from the callback registration function - * - * @pre The callback must be registered using iotcon_remote_resource_get(), - * iotcon_remote_resource_put(), iotcon_remote_resource_post(), iotcon_remote_resource_delete() - * + * @pre The callback must be registered using iotcon_remote_resource_get(), iotcon_remote_resource_put(), iotcon_remote_resource_post(), iotcon_remote_resource_delete(). * @see iotcon_remote_resource_get() * @see iotcon_remote_resource_put() * @see iotcon_remote_resource_post() * @see iotcon_remote_resource_delete() - */ -typedef void (*iotcon_remote_resource_response_cb)(iotcon_remote_resource_h resource, - iotcon_error_e err, - iotcon_request_type_e request_type, - iotcon_response_h response, - void *user_data); + */ +typedef void (*iotcon_remote_resource_response_cb)(iotcon_remote_resource_h resource, iotcon_error_e err, iotcon_request_type_e request_type, iotcon_response_h response, void *user_data); + /** - * @brief Gets the attributes of a resource, asynchronously. + * @brief Gets the attributes of a resource asynchronously. * @details When server sends response on get request, iotcon_remote_resource_response_cb() will be called. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] resource The handle of the resource * @param[in] query The query to send to server * @param[in] cb The callback function * @param[in] user_data The user data to pass to the function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. * @post When the client receive get response, iotcon_remote_resource_response_cb() will be called. - * * @see iotcon_remote_resource_response_cb() * @see iotcon_set_timeout() */ -int iotcon_remote_resource_get(iotcon_remote_resource_h resource, iotcon_query_h query, - iotcon_remote_resource_response_cb cb, void *user_data); +int iotcon_remote_resource_get(iotcon_remote_resource_h resource, iotcon_query_h query, iotcon_remote_resource_response_cb cb, void *user_data); + /** - * @brief Puts the representation of a resource, asynchronously. + * @brief Puts the representation of a resource asynchronously. * @details When server sends response on put request, iotcon_remote_resource_response_cb() will be called. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] resource The handle of the resource * @param[in] repr The handle of the representation * @param[in] query The query to send to server * @param[in] cb The callback function * @param[in] user_data The user data to pass to the function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. * @post When the client receive put response, iotcon_remote_resource_response_cb() will be called. - * * @see iotcon_remote_resource_response_cb() * @see iotcon_set_timeout() */ -int iotcon_remote_resource_put(iotcon_remote_resource_h resource, - iotcon_representation_h repr, - iotcon_query_h query, - iotcon_remote_resource_response_cb cb, - void *user_data); +int iotcon_remote_resource_put(iotcon_remote_resource_h resource, iotcon_representation_h repr, iotcon_query_h query, iotcon_remote_resource_response_cb cb, void *user_data); + /** - * @brief Posts on a resource, asynchronously. + * @brief Posts on a resource asynchronously. * @details When server sends response on post request, iotcon_remote_resource_response_cb() will be called. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] resource The handle of the resource * @param[in] repr The handle of the representation * @param[in] query The query to send to server * @param[in] cb The callback function * @param[in] user_data The user data to pass to the function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. * @post When the client receive post response, iotcon_remote_resource_response_cb() will be called. - * * @see iotcon_remote_resource_response_cb() * @see iotcon_set_timeout() */ -int iotcon_remote_resource_post(iotcon_remote_resource_h resource, - iotcon_representation_h repr, - iotcon_query_h query, - iotcon_remote_resource_response_cb cb, - void *user_data); +int iotcon_remote_resource_post(iotcon_remote_resource_h resource, iotcon_representation_h repr, iotcon_query_h query, iotcon_remote_resource_response_cb cb, void *user_data); + /** - * @brief Deletes a resource, asynchronously. + * @brief Deletes a resource asynchronously. * @details When server sends response on delete request, iotcon_remote_resource_response_cb() will be called. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] resource The handle of the resource * @param[in] cb The callback function * @param[in] user_data The user data to pass to the function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. * @post When the client receive delete response, iotcon_remote_resource_response_cb() will be called. - * * @see iotcon_remote_resource_response_cb() * @see iotcon_set_timeout() */ -int iotcon_remote_resource_delete(iotcon_remote_resource_h resource, - iotcon_remote_resource_response_cb cb, void *user_data); +int iotcon_remote_resource_delete(iotcon_remote_resource_h resource, iotcon_remote_resource_response_cb cb, void *user_data); + /** * @brief Specifies the type of function passed to iotcon_remote_resource_start_caching(). - * * @since_tizen 3.0 - * * @param[in] resource The handle of the remote resource * @param[in] representation The handle of the representation * @param[in] user_data The user data to pass to the function - * * @pre The callback must be registered using iotcon_remote_resource_start_caching() - * * @see iotcon_remote_resource_start_caching() * @see iotcon_remote_resource_stop_caching() */ -typedef void (*iotcon_remote_resource_cached_representation_changed_cb)( - iotcon_remote_resource_h resource, - iotcon_representation_h representation, - void *user_data); +typedef void (*iotcon_remote_resource_cached_representation_changed_cb)( iotcon_remote_resource_h resource, iotcon_representation_h representation, void *user_data); + /** * @brief Starts caching of a remote resource. - * @details Use this function to start caching the resource's attribute.\n - * Although, remote resource is not observable, it keeps the representation up-to-date. - * Because It checks whether representation is changed, periodically.\n - * Therefore, you can get the cached representation even when the remote resource is off-line. - * The default checking interval is 10 seconds. - * It can be changed by iotcon_remote_resource_set_checking_interval(). - * + * @details Use this function to start caching the resource's attribute. \n + * Although, remote resource is not observable, it keeps the representation up-to-date. + * Because it checks whether representation is changed periodically. \n + * Therefore, you can get the cached representation even when the remote resource is off-line. + * The default checking interval is 10 seconds. + * It can be changed by iotcon_remote_resource_set_checking_interval(). * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] resource The handle of the remote resource to be cached * @param[in] cb The callback function to add into callback list * @param[in] user_data The user data to pass to the callback function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @retval #IOTCON_ERROR_SYSTEM System error - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_ALREADY Already done - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_remote_resource_stop_caching() * @see iotcon_remote_resource_cached_representation_changed_cb() */ -int iotcon_remote_resource_start_caching(iotcon_remote_resource_h resource, - iotcon_remote_resource_cached_representation_changed_cb cb, void *user_data); +int iotcon_remote_resource_start_caching(iotcon_remote_resource_h resource, iotcon_remote_resource_cached_representation_changed_cb cb, void *user_data); + /** * @brief Stops caching of a remote resource. - * @details Use this function to stop caching the resource's attribute.\n - * + * @details Use this function to stop caching the resource's attribute. * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] resource The handle of the remote resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_SYSTEM System error * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_remote_resource_start_caching() * @see iotcon_remote_resource_cached_representation_changed_cb() */ int iotcon_remote_resource_stop_caching(iotcon_remote_resource_h resource); + /** * @brief Specifies the type of function passed to iotcon_remote_resource_start_monitoring(). - * * @since_tizen 3.0 - * * @param[in] resource The handle of the remote resource * @param[in] state The state of the remote resource * @param[in] user_data The user data to pass to the function - * * @pre The callback must be registered using iotcon_remote_resource_start_monitoring() - * * @see iotcon_remote_resource_start_monitoring() * @see iotcon_remote_resource_stop_monitoring() */ -typedef void (*iotcon_remote_resource_state_changed_cb)(iotcon_remote_resource_h resource, - iotcon_remote_resource_state_e state, void *user_data); +typedef void (*iotcon_remote_resource_state_changed_cb)(iotcon_remote_resource_h resource, iotcon_remote_resource_state_e state, void *user_data); + /** * @brief Starts monitoring of a remote resource. - * @details When remote resource's state are changed, registered callbacks will be called - * in turn. Although, remote resource does not call iotcon_start_presence(), it knows - * the state of resource. Because it checks the state of resource, periodically.\n - * The default checking interval is 10 seconds. - * It can be changed by iotcon_remote_resource_set_checking_interval(). - * + * @details When remote resource's state is changed, registered callbacks will be called in turn. + * Although, remote resource does not call iotcon_start_presence(), it knows the state of resource. + * Because it checks the state of resource, periodically. \n + * The default checking interval is 10 seconds. + * It can be changed by iotcon_remote_resource_set_checking_interval(). * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] resource The handle of the remote resource * @param[in] cb The callback function to add into callback list * @param[in] user_data The user data to pass to the callback function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_ALREADY Already done - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_ALREADY Already done + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_remote_resource_stop_monitoring() * @see iotcon_remote_resource_state_changed_cb() */ -int iotcon_remote_resource_start_monitoring(iotcon_remote_resource_h resource, - iotcon_remote_resource_state_changed_cb cb, void *user_data); +int iotcon_remote_resource_start_monitoring(iotcon_remote_resource_h resource, iotcon_remote_resource_state_changed_cb cb, void *user_data); + /** * @brief Stops monitoring of a remote resource. * @details Use this function to stop monitoring the remote resource. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] resource The handle of the remote resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_SYSTEM System error * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_remote_resource_start_monitoring() * @see iotcon_remote_resource_state_changed_cb() */ int iotcon_remote_resource_stop_monitoring(iotcon_remote_resource_h resource); + /** * @brief Gets an URI path of the remote resource. - * * @since_tizen 3.0 - * * @remarks @a uri_path must not be released using free(). - * * @param[in] resource The handle of the remote resource * @param[out] uri_path The URI path of the remote resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_remote_resource_get_host_address() * @see iotcon_remote_resource_get_connectivity_type() * @see iotcon_remote_resource_get_device_id() @@ -599,22 +506,19 @@ int iotcon_remote_resource_stop_monitoring(iotcon_remote_resource_h resource); * @see iotcon_remote_resource_get_policies() * @see iotcon_remote_resource_set_options() */ -int iotcon_remote_resource_get_uri_path(iotcon_remote_resource_h resource, - char **uri_path); +int iotcon_remote_resource_get_uri_path(iotcon_remote_resource_h resource, char **uri_path); + /** * @brief Gets a connectivity type of the remote resource. - * * @since_tizen 3.0 - * * @param[in] resource The handle of the remote resource * @param[out] connectivity_type The connectivity type of the remote resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_remote_resource_get_uri_path() * @see iotcon_remote_resource_get_host_address() * @see iotcon_remote_resource_get_connectivity_type() @@ -625,24 +529,20 @@ int iotcon_remote_resource_get_uri_path(iotcon_remote_resource_h resource, * @see iotcon_remote_resource_get_policies() * @see iotcon_remote_resource_set_options() */ -int iotcon_remote_resource_get_connectivity_type(iotcon_remote_resource_h resource, - iotcon_connectivity_type_e *connectivity_type); +int iotcon_remote_resource_get_connectivity_type(iotcon_remote_resource_h resource, iotcon_connectivity_type_e *connectivity_type); + /** * @brief Gets a host address of the remote resource. - * * @since_tizen 3.0 - * * @remarks @a host_address must not be released using free(). - * * @param[in] resource The handle of the remote resource * @param[out] host_address The host address of the remote resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_remote_resource_get_connectivity_type() * @see iotcon_remote_resource_get_uri_path() * @see iotcon_remote_resource_get_device_id() @@ -652,27 +552,23 @@ int iotcon_remote_resource_get_connectivity_type(iotcon_remote_resource_h resour * @see iotcon_remote_resource_get_policies() * @see iotcon_remote_resource_set_options() */ -int iotcon_remote_resource_get_host_address(iotcon_remote_resource_h resource, - char **host_address); +int iotcon_remote_resource_get_host_address(iotcon_remote_resource_h resource, char **host_address); + /** - * @brief Gets a device id of the remote resource. - * + * @brief Gets a device ID of the remote resource. * @since_tizen 3.0 - * * @remarks @a device_id must not be released using free().\n - * If @a resource is created by calling iotcon_remote_resource_create(), you cannot get - * @a device_id. In this case, the return value of this function is #IOTCON_ERROR_NO_DATA. - * + * If @a resource is created by calling iotcon_remote_resource_create(), you cannot get @a device_id. + * In this case, the return value of this function is #IOTCON_ERROR_NO_DATA. * @param[in] resource The handle of the remote resource - * @param[out] device_id The device id of the remote resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @param[out] device_id The device ID of the remote resource + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_NO_DATA No data available - * * @see iotcon_remote_resource_get_uri_path() * @see iotcon_remote_resource_get_device_name() * @see iotcon_remote_resource_get_host_address() @@ -682,27 +578,23 @@ int iotcon_remote_resource_get_host_address(iotcon_remote_resource_h resource, * @see iotcon_remote_resource_get_policies() * @see iotcon_remote_resource_set_options() */ -int iotcon_remote_resource_get_device_id(iotcon_remote_resource_h resource, - char **device_id); +int iotcon_remote_resource_get_device_id(iotcon_remote_resource_h resource, char **device_id); + /** * @brief Gets the device name of the remote resource. - * * @since_tizen 3.0 - * * @remarks @a device_name must not be released using free().\n - * If @a resource is created by calling iotcon_remote_resource_create(), you cannot get - * @a device_name. In this case, the return value of this function is #IOTCON_ERROR_NO_DATA. - * + * If @a resource is created by calling iotcon_remote_resource_create(), you cannot get @a device_name. + * In this case, the return value of this function is #IOTCON_ERROR_NO_DATA. * @param[in] resource The handle of the remote resource * @param[out] device_name The device name of the remote resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_NO_DATA No data available - * * @see iotcon_set_device_name() * @see iotcon_remote_resource_get_uri_path() * @see iotcon_remote_resource_get_device_id() @@ -714,24 +606,20 @@ int iotcon_remote_resource_get_device_id(iotcon_remote_resource_h resource, * @see iotcon_remote_resource_get_properties() * @see iotcon_remote_resource_set_options() */ -int iotcon_remote_resource_get_device_name(iotcon_remote_resource_h resource, - char **device_name); +int iotcon_remote_resource_get_device_name(iotcon_remote_resource_h resource, char **device_name); + /** * @brief Gets resource types of the remote resource. - * * @since_tizen 3.0 - * * @remarks @a types must not be released using iotcon_resource_types_destroy(). - * * @param[in] resource The handle of the remote resource * @param[out] types The resource types of the remote resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_remote_resource_get_uri_path() * @see iotcon_remote_resource_get_host_address() * @see iotcon_remote_resource_get_connectivity_type() @@ -741,24 +629,20 @@ int iotcon_remote_resource_get_device_name(iotcon_remote_resource_h resource, * @see iotcon_remote_resource_get_policies() * @see iotcon_remote_resource_set_options() */ -int iotcon_remote_resource_get_types(iotcon_remote_resource_h resource, - iotcon_resource_types_h *types); +int iotcon_remote_resource_get_types(iotcon_remote_resource_h resource, iotcon_resource_types_h *types); + /** * @brief Gets resource interfaces of the remote resource. - * * @since_tizen 3.0 - * * @remarks @a ifaces must not be released using iotcon_resource_interfaces_destroy(). - * * @param[in] resource The handle of the remote resource * @param[out] ifaces The resource interfaces of the remote resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_remote_resource_get_uri_path() * @see iotcon_remote_resource_get_host_address() * @see iotcon_remote_resource_get_connectivity_type() @@ -768,24 +652,21 @@ int iotcon_remote_resource_get_types(iotcon_remote_resource_h resource, * @see iotcon_remote_resource_get_policies() * @see iotcon_remote_resource_set_options() */ -int iotcon_remote_resource_get_interfaces(iotcon_remote_resource_h resource, - iotcon_resource_interfaces_h *ifaces); +int iotcon_remote_resource_get_interfaces(iotcon_remote_resource_h resource, iotcon_resource_interfaces_h *ifaces); + /** * @brief Checks whether the remote resource is observable or not. - * - * @details The @a policies can contain multiple policies like - * IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE. + * @details The @a policies can contain multiple policies like IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE. * @since_tizen 3.0 - * * @param[in] resource The handle of the resource - * @param[out] policies The policies of the resource\n Set of #iotcon_resource_policy_e - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @param[out] policies The policies of the resource \n + * Set of #iotcon_resource_policy_e + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_remote_resource_get_uri_path() * @see iotcon_remote_resource_get_host_address() * @see iotcon_remote_resource_get_connectivity_type() @@ -795,25 +676,20 @@ int iotcon_remote_resource_get_interfaces(iotcon_remote_resource_h resource, * @see iotcon_remote_resource_get_interfaces() * @see iotcon_remote_resource_set_options() */ -int iotcon_remote_resource_get_policies(iotcon_remote_resource_h resource, - uint8_t *policies); +int iotcon_remote_resource_get_policies(iotcon_remote_resource_h resource, uint8_t *policies); /** * @brief Gets options of the remote resource. - * * @since_tizen 3.0 - * * @remarks @a options must not be released using iotcon_options_destroy(). - * * @param[in] resource The handle of the remote resource * @param[out] options The handle of the header options - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_remote_resource_get_uri_path() * @see iotcon_remote_resource_get_host_address() * @see iotcon_remote_resource_get_connectivity_type() @@ -824,22 +700,19 @@ int iotcon_remote_resource_get_policies(iotcon_remote_resource_h resource, * @see iotcon_remote_resource_set_options() * @see iotcon_remote_resource_get_policies() */ -int iotcon_remote_resource_get_options(iotcon_remote_resource_h resource, - iotcon_options_h *options); +int iotcon_remote_resource_get_options(iotcon_remote_resource_h resource, iotcon_options_h *options); + /** * @brief Sets options into the remote resource. - * * @since_tizen 3.0 - * * @param[in] resource The handle of the remote resource * @param[in] options The handle of the header options - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_remote_resource_get_uri_path() * @see iotcon_remote_resource_get_host_address() * @see iotcon_remote_resource_get_connectivity_type() @@ -850,78 +723,67 @@ int iotcon_remote_resource_get_options(iotcon_remote_resource_h resource, * @see iotcon_remote_resource_get_options() * @see iotcon_remote_resource_get_policies() */ -int iotcon_remote_resource_set_options(iotcon_remote_resource_h resource, - iotcon_options_h options); +int iotcon_remote_resource_set_options(iotcon_remote_resource_h resource, iotcon_options_h options); + /** * @brief Gets cached representation from the remote resource. - * * @since_tizen 3.0 - * * @remarks @a representation must not be released using iotcon_representation_destroy(). - * * @param[in] resource The handle of the remote resource * @param[out] representation The handle of the representation - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ -int iotcon_remote_resource_get_cached_representation( - iotcon_remote_resource_h resource, - iotcon_representation_h *representation); +int iotcon_remote_resource_get_cached_representation(iotcon_remote_resource_h resource, iotcon_representation_h *representation); + /** * @brief Gets the checking interval which is using on the monitoring & caching of remote resource. - * @details This API get the checking interval which is using in the process of monitoring - * and caching() of remote resource.\n - * The monitoring and caching will operate "GET method" with the checking interval. - * Default checking interval is 10 seconds. - * + * @details This API get the checking interval which is using in the process of monitoring and caching() of remote resource. \n + * The monitoring and caching will operate "GET method" with the checking interval. + * Default checking interval is 10 seconds. * @since_tizen 3.0 - * * @param[in] resource The handle of the remote resource * @param[out] interval Seconds for time interval - * - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, + * otherwise a negative error value * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * * @see iotcon_remote_resource_set_checking_interval() * @see iotcon_remote_resource_start_monitoring() * @see iotcon_remote_resource_start_caching() */ -int iotcon_remote_resource_get_checking_interval(iotcon_remote_resource_h resource, - int *interval); +int iotcon_remote_resource_get_checking_interval(iotcon_remote_resource_h resource, int *interval); + /** * @brief Sets the checking interval which is using on the monitoring & caching of remote resource. - * @details This API set the checking interval which is using in the process of monitoring - * and caching() of remote resource.\n - * The monitoring and caching will operate "GET method" with the checking interval changed by this function. - * Default checking interval is 10 seconds. - * + * @details This API set the checking interval which is using in the process of monitoring and caching() of remote resource. \n + * The monitoring and caching will operate "GET method" with the checking interval changed by this function. + * Default checking interval is 10 seconds. * @since_tizen 3.0 - * * @param[in] resource The handle of the remote resource * @param[in] interval Seconds for time interval (must be in range from 1 to 3600) - * - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, + * otherwise a negative error value * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * * @see iotcon_remote_resource_get_checking_interval() * @see iotcon_remote_resource_start_monitoring() * @see iotcon_remote_resource_start_caching() */ -int iotcon_remote_resource_set_checking_interval(iotcon_remote_resource_h resource, - int interval); +int iotcon_remote_resource_set_checking_interval(iotcon_remote_resource_h resource, int interval); + /** * @} */ + #endif /* __IOTCON_CLIENT_REMOTE_RESOURCE_H__ */ diff --git a/include/iotcon-representation.h b/include/iotcon-representation.h index 2c57218..0527f89 100644 --- a/include/iotcon-representation.h +++ b/include/iotcon-representation.h @@ -13,34 +13,33 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_STRUCT_REPRESENTATION_H__ #define __IOTCON_STRUCT_REPRESENTATION_H__ + #include <iotcon-types.h> + /** * @file iotcon-representation.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_COMMON_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_MODULE Representation - * * @brief IoTCon Representation provides API to manage representation. - * * @section CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_MODULE_HEADER Required Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_MODULE_OVERVIEW Overview - * The IoTCon Representation API provides data type of resp_repr handling.\n - * A resp_repr is a payload of a request or a response.\n - * It has uri_path, list of resource interfaces, list of resource types and its attributes.\n - * Attributes have capabilities to store and retrieve integer, boolean, double, string, - * byte string, list, null, resp_repr.\n - * A list is a container that includes number of data of same type.\n - * It has capabilities to store and retrieve integer, boolean, double, string, byte string, - * list, null, resp_repr. - * + * The IoTCon Representation API provides data type of resp_repr handling.\n + * A resp_repr is a payload of a request or a response.\n + * It has uri_path, list of resource interfaces, list of resource types and its attributes.\n + * Attributes have capabilities to store and retrieve integer, boolean, double, string, byte string, list, null, resp_repr. \n + * A list is a container that includes number of data of same type.\n + * It has capabilities to store and retrieve integer, boolean, double, string, byte string, list, null, resp_repr. * Example : *@code #include <iotcon.h> @@ -184,333 +183,282 @@ iotcon_representation_destroy(resp_repr); } * @endcode - * * @section CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/iot.ocf\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * 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.\n - * - * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> - * + * This API is related with the following features: \n + * - http://tizen.org/feature/iot.ocf \n + * It is recommended to design feature related codes in your application for reliability. \n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n + * 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. \n + * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> * @{ */ + /** - * @brief Creates a new representation handle. - * + * @brief Creates a new Representation handle. * @since_tizen 3.0 - * - * @remarks You must destroy @a repr by calling iotcon_representation_destroy() - * if @a repr is no longer needed. - * - * @param[out] repr A newly allocated representation handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @remarks You must destroy @a repr by calling iotcon_representation_destroy() if @a repr is no longer needed. + * @param[out] repr A newly allocated Representation handle + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_representation_destroy() */ int iotcon_representation_create(iotcon_representation_h *repr); + /** - * @brief Destroys a representation. - * @details Releases a @a representation and its internal data. - * + * @brief Destroys a Representation. + * @details Releases @a Representation and its internal data. * @since_tizen 3.0 - * * @param[in] repr The representation handle to free - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_representation_create() */ int iotcon_representation_destroy(iotcon_representation_h repr); + /** - * @brief Clones from the source representation. - * @details Makes a deep copy of a source representation. - * + * @brief Clones from the source Representation. + * @details Makes a deep copy of a source Representation. * @since_tizen 3.0 - * - * @remarks You must destroy @a dest by calling iotcon_representation_destroy() - * if @a dest is no longer needed. - * - * @param[in] src Source of representation to be copied - * @param[out] dest Clone of a source representation - * - * @return Clone of a source representation, otherwise NULL on failure + * @remarks You must destroy @a dest by calling iotcon_representation_destroy() if @a dest is no longer needed. + * @param[in] src Source of Representation to be copied + * @param[out] dest Clone of a source Representation + * @return Clone of a source Representation, + * otherwise NULL on failure * @retval iotcon_representation_h Success * @retval NULL Failure */ -int iotcon_representation_clone(const iotcon_representation_h src, - iotcon_representation_h *dest); +int iotcon_representation_clone(const iotcon_representation_h src, iotcon_representation_h *dest); + /** * @brief Appends resource type name. - * * @since_tizen 3.0 - * @remarks Stored string is replaced with @a uri_path. If @a uri_path is NULL, stored string - * is set by NULL. - * + * @remarks Stored string is replaced with @a uri_path. If @a uri_path is NULL, stored string is set to NULL. * @param[in] repr The handle to the Representation * @param[in] uri_path The URI of resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ -int iotcon_representation_set_uri_path(iotcon_representation_h repr, - const char *uri_path); +int iotcon_representation_set_uri_path(iotcon_representation_h repr, const char *uri_path); + /** - * @brief Gets an URI path from the representation. - * + * @brief Gets a URI path from the Representation. * @since_tizen 3.0 - * * @remarks @a uri_path must not be released using free(). - * - * @param[in] repr The representation handle + * @param[in] repr The Representation handle * @param[out] uri_path The URI path to get - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_NO_DATA No data available */ int iotcon_representation_get_uri_path(iotcon_representation_h repr, char **uri_path); + /** * @brief Sets resource type list to the Representation. - * * @since_tizen 3.0 - * @remarks Stored list is replaced with @a types. If @a types is NULL, stored list is set - * by NULL. + * @remarks Stored list is replaced with @a types. If @a types is NULL, stored list is set to NULL. * @param[in] repr The handle to the Representation * @param[in] types The resource type list - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ -int iotcon_representation_set_resource_types(iotcon_representation_h repr, - iotcon_resource_types_h types); +int iotcon_representation_set_resource_types(iotcon_representation_h repr, iotcon_resource_types_h types); + /** - * @brief Gets list of resource type from the representation. - * + * @brief Gets list of resource type from the Representation. * @since_tizen 3.0 - * * @remarks @a types must not be released using iotcon_resource_types_destroy(). - * - * @param[in] repr The representation handle + * @param[in] repr The Representation handle * @param[out] types The list of resource types to get - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ -int iotcon_representation_get_resource_types(iotcon_representation_h repr, - iotcon_resource_types_h *types); +int iotcon_representation_get_resource_types(iotcon_representation_h repr, iotcon_resource_types_h *types); + /** - * @brief Sets list of resource interfaces to the representation. - * + * @brief Sets list of resource interfaces to the Representation. * @since_tizen 3.0 - * - * @remarks Stored list is replaced with @a ifaces. If @a ifaces is NULL, stored list is set - * by NULL. - * - * @param[in] repr The representation handle + * @remarks Stored list is replaced with @a ifaces. If @a ifaces is NULL, stored list is set to NULL. + * @param[in] repr The Representation handle * @param[in] ifaces The list of resource interfaces - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ -int iotcon_representation_set_resource_interfaces(iotcon_representation_h repr, - iotcon_resource_interfaces_h ifaces); +int iotcon_representation_set_resource_interfaces(iotcon_representation_h repr, iotcon_resource_interfaces_h ifaces); + /** - * @brief Gets list of resource interfaces from the representation. - * + * @brief Gets list of resource interfaces from the Representation. * @since_tizen 3.0 - * * @remarks @a ifaces must not be released using iotcon_resource_interfaces_destroy(). - * - * @param[in] repr The representation handle + * @param[in] repr The Representation handle * @param[out] ifaces The list of resource interfaces to get - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ -int iotcon_representation_get_resource_interfaces(iotcon_representation_h repr, - iotcon_resource_interfaces_h *ifaces); +int iotcon_representation_get_resource_interfaces(iotcon_representation_h repr, iotcon_resource_interfaces_h *ifaces); + /** - * @brief Sets a new attributes handle into the representation. - * + * @brief Sets a new attributes handle into the Representation. * @since_tizen 3.0 - * - * @param[in] repr The representation handle - * @param[in] attributes The attributes handle to set newly - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @param[in] repr The Representation handle + * @param[in] attributes The attributes handle to be set newly + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ int iotcon_representation_set_attributes(iotcon_representation_h repr, iotcon_attributes_h attributes); + /** - * @brief Gets a attributes handle in the representation. - * + * @brief Gets the attributes handle in the Representation. * @since_tizen 3.0 - * * @remarks @a attributes must not be released using iotcon_attributes_destroy(). - * - * @param[in] repr The representation handle + * @param[in] repr The Representation handle * @param[in] attributes The attributes handle to get - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ int iotcon_representation_get_attributes(iotcon_representation_h repr, iotcon_attributes_h *attributes); + /** - * @brief Adds a new child representation on to the end of the parent representation. - * @details Duplicated child representation is allowed to append. - * + * @brief Adds a new child Representation on to the end of the parent Representation. + * @details Duplicated child Representation is allowed to append. * @since_tizen 3.0 - * - * @param[in] parent The parent representation handle - * @param[in] child The child representation handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @param[in] parent The parent Representation handle + * @param[in] child The child Representation handle + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ -int iotcon_representation_add_child(iotcon_representation_h parent, - iotcon_representation_h child); +int iotcon_representation_add_child(iotcon_representation_h parent, iotcon_representation_h child); + /** - * @brief Removes a child representation from parent representation without freeing. - * + * @brief Removes a child Representation from parent Representation without freeing. * @since_tizen 3.0 - * - * @param[in] parent The parent representation handle - * @param[in] child The child representation handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @param[in] parent The parent Representation handle + * @param[in] child The child Representation handle + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ -int iotcon_representation_remove_child(iotcon_representation_h parent, - iotcon_representation_h child); +int iotcon_representation_remove_child(iotcon_representation_h parent, iotcon_representation_h child); + /** * @brief Specifies the type of function passed to iotcon_representation_foreach_children(). - * * @since_tizen 3.0 - * - * @param[in] child The child representation handle + * @param[in] child The child Representation handle * @param[in] user_data The user data to pass to the function - * - * @return 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. - * + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre iotcon_representation_foreach_children() will invoke this callback function. - * * @see iotcon_representation_foreach_children() * */ typedef bool (*iotcon_children_cb)(iotcon_representation_h child, void *user_data); + /** - * @brief Calls a function for each children representation of parent. + * @brief Calls a function for each child Representation of parent. * @details iotcon_children_cb() will be called for each child. - * * @since_tizen 3.0 - * - * @param[in] parent The parent representation handle + * @param[in] parent The parent Representation handle * @param[in] cb The callback function to invoke * @param[in] user_data The user data to pass to the function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @post iotcon_children_cb() will be called for each child. - * * @see iotcon_children_cb() */ -int iotcon_representation_foreach_children(iotcon_representation_h parent, - iotcon_children_cb cb, void *user_data); +int iotcon_representation_foreach_children(iotcon_representation_h parent, iotcon_children_cb cb, void *user_data); + /** - * @brief Gets the number of child representations in the parent representation. - * + * @brief Gets the number of child Representations in the parent Representation. * @since_tizen 3.0 - * - * @param[in] parent The parent representation handle - * @param[out] count The number of child representations - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @param[in] parent The parent Representation handle + * @param[out] count The number of child Representations + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter */ -int iotcon_representation_get_child_count(iotcon_representation_h parent, - unsigned int *count); +int iotcon_representation_get_child_count(iotcon_representation_h parent, unsigned int *count); + /** - * @brief Gets the child representation at the given position. + * @brief Gets the child Representation at the given position. * @details Iterates over the parent until it reaches the @a pos-1 position. - * * @since_tizen 3.0 - * * @remarks @a child must not be released using iotcon_representation_destroy(). - * - * @param[in] parent The parent representation handle - * @param[in] pos The position of the child representation - * @param[out] child The handle to the child representation - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @param[in] parent The parent Representation handle + * @param[in] pos The position of the child Representation + * @param[out] child The handle to the child Representation + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_NO_DATA No data available */ -int iotcon_representation_get_nth_child(iotcon_representation_h parent, int pos, - iotcon_representation_h *child); +int iotcon_representation_get_nth_child(iotcon_representation_h parent, int pos, iotcon_representation_h *child); + /** * @} */ + #endif /* __IOTCON_STRUCT_REPRESENTATION_H__ */ diff --git a/include/iotcon-request.h b/include/iotcon-request.h index 5e4a6d0..e535506 100644 --- a/include/iotcon-request.h +++ b/include/iotcon-request.h @@ -13,27 +13,28 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_SERVER_REQUEST_H__ #define __IOTCON_SERVER_REQUEST_H__ + #include <iotcon-types.h> + /** * @file iotcon-request.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_SERVER_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_SERVER_REQUEST_MODULE Request - * * @brief IoTCon Request provides API to manage client's request. - * * @section CAPI_IOT_CONNECTIVITY_SERVER_REQUEST_MODULE_HEADER Required Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_SERVER_REQUEST_MODULE_OVERVIEW Overview - * The iotcon request API provides methods for managing request handle. - * + * The IoTCon Request API provides methods for managing request handle. * Example : * @code #include <iotcon.h> @@ -109,37 +110,28 @@ static void _request_handler(iotcon_resource_h resource, iotcon_request_h reques ... } * @endcode - * * @section CAPI_IOT_CONNECTIVITY_SERVER_REQUEST_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/iot.ocf\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * 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.\n - * - * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> - * + * This API is related with the following features: \n + * - http://tizen.org/feature/iot.ocf \n + * It is recommended to design feature related codes in your application for reliability. \n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n + * 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. \n + * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> * @{ */ + /** * @brief Gets host address of the request. - * * @since_tizen 3.0 - * * @remarks @a host_address must not be released using free(). - * * @param[in] request The handle of the request * @param[out] host_address The host address of the request - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_request_get_connectivity_type() * @see iotcon_request_get_representation() * @see iotcon_request_get_request_type() @@ -148,22 +140,19 @@ static void _request_handler(iotcon_resource_h resource, iotcon_request_h reques * @see iotcon_request_get_observe_type() * @see iotcon_request_get_observe_id() */ -int iotcon_request_get_host_address(iotcon_request_h request, - char **host_address); +int iotcon_request_get_host_address(iotcon_request_h request, char **host_address); + /** * @brief Gets connectivity type of the request. - * * @since_tizen 3.0 - * * @param[in] request The handle of the request * @param[out] connectivity_type The connectivity type of the request - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_request_get_host_address() * @see iotcon_request_get_representation() * @see iotcon_request_get_request_type() @@ -172,24 +161,20 @@ int iotcon_request_get_host_address(iotcon_request_h request, * @see iotcon_request_get_observe_type() * @see iotcon_request_get_observe_id() */ -int iotcon_request_get_connectivity_type(iotcon_request_h request, - iotcon_connectivity_type_e *connectivity_type); +int iotcon_request_get_connectivity_type(iotcon_request_h request, iotcon_connectivity_type_e *connectivity_type); + /** - * @brief Gets an representation of the request. - * + * @brief Gets a representation of the request. * @since_tizen 3.0 - * * @remarks @a repr must not be released using iotcon_representation_destroy(). - * * @param[in] request The handle of the request * @param[out] repr The representation of the request - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_request_get_host_address() * @see iotcon_request_get_connectivity_type() * @see iotcon_request_get_request_type() @@ -198,23 +183,20 @@ int iotcon_request_get_connectivity_type(iotcon_request_h request, * @see iotcon_request_get_observe_type() * @see iotcon_request_get_observe_id() */ -int iotcon_request_get_representation(iotcon_request_h request, - iotcon_representation_h *repr); +int iotcon_request_get_representation(iotcon_request_h request, iotcon_representation_h *repr); + /** * @brief Gets type of the request. * @details @a type could be one of the #iotcon_request_type_e. - * * @since_tizen 3.0 - * * @param[in] request The handle of the request - * @param[out] type The types of the request. - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @param[out] type The types of the request + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_request_get_host_address() * @see iotcon_request_get_connectivity_type() * @see iotcon_request_get_representation() @@ -225,21 +207,18 @@ int iotcon_request_get_representation(iotcon_request_h request, */ int iotcon_request_get_request_type(iotcon_request_h request, iotcon_request_type_e *type); + /** * @brief Gets options of the request. - * * @since_tizen 3.0 - * * @remarks @a options must not be released using iotcon_options_destroy(). - * * @param[in] request The handle of the request * @param[out] options The options of the request - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_request_get_host_address() * @see iotcon_request_get_connectivity_type() * @see iotcon_request_get_representation() @@ -250,21 +229,18 @@ int iotcon_request_get_request_type(iotcon_request_h request, iotcon_request_typ */ int iotcon_request_get_options(iotcon_request_h request, iotcon_options_h *options); + /** * @brief Gets query of the request. - * * @since_tizen 3.0 - * * @remarks @a query must not be released using iotcon_query_destroy(). - * * @param[in] request The handle of the request * @param[out] query The query of the request - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_request_get_host_address() * @see iotcon_request_get_connectivity_type() * @see iotcon_request_get_representation() @@ -275,20 +251,18 @@ int iotcon_request_get_options(iotcon_request_h request, iotcon_options_h *optio */ int iotcon_request_get_query(iotcon_request_h request, iotcon_query_h *query); + /** * @brief Gets observation action of the request. - * - * @since_tizen 3.0 * @details The @a observe_type could be one of #iotcon_observe_type_e. - * + * @since_tizen 3.0 * @param[in] request The handle of the request * @param[out] observe_type The observation type of the request - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_request_get_host_address() * @see iotcon_request_get_connectivity_type() * @see iotcon_request_get_representation() @@ -297,22 +271,19 @@ int iotcon_request_get_query(iotcon_request_h request, iotcon_query_h *query); * @see iotcon_request_get_query() * @see iotcon_request_get_observe_id() */ -int iotcon_request_get_observe_type(iotcon_request_h request, - iotcon_observe_type_e *observe_type); +int iotcon_request_get_observe_type(iotcon_request_h request, iotcon_observe_type_e *observe_type); + /** - * @brief Gets observation id of the request. - * + * @brief Gets observation ID of the request. * @since_tizen 3.0 - * * @param[in] request The handle of the request - * @param[out] observe_id The id of the observer - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @param[out] observe_id The ID of the observer + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_request_get_host_address() * @see iotcon_request_get_connectivity_type() * @see iotcon_request_get_representation() @@ -323,8 +294,10 @@ int iotcon_request_get_observe_type(iotcon_request_h request, */ int iotcon_request_get_observe_id(iotcon_request_h request, int *observe_id); + /** * @} */ + #endif /* __IOTCON_SERVER_REQUEST_H__ */ diff --git a/include/iotcon-resource-interfaces.h b/include/iotcon-resource-interfaces.h index c67c0e7..5f99e81 100644 --- a/include/iotcon-resource-interfaces.h +++ b/include/iotcon-resource-interfaces.h @@ -13,28 +13,29 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_STRUCT_RESOURCE_INTERFACES_H__ #define __IOTCON_STRUCT_RESOURCE_INTERFACES_H__ + #include <iotcon-types.h> + /** * @file iotcon-resource-interfaces.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_COMMON_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_COMMON_RESOURCE_INTERFACES_MODULE Resource Interfaces - * * @brief IoTCon Resource Interfaces provides API to manage resource interfaces. - * * @section CAPI_IOT_CONNECTIVITY_COMMON_RESOURCE_INTERFACES_MODULE_HEADER Required Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_COMMON_RESOURCE_INTERFACES_MODULE_OVERVIEW Overview - * The iotcon resource interfaces API provides methods for managing handle and add, remove resource interfaces. - * A resource interface indicates a class or category of resources. - * + * The IoTCon Resource Interfaces API provides methods for managing handle and add, remove resource interfaces. + * A resource interface indicates a class or category of resources. * Example : * @code #include <iotcon.h> @@ -86,38 +87,28 @@ static void _create_light_resource() iotcon_resource_types_destroy(resource_types); } * @endcode - * * @section CAPI_IOT_CONNECTIVITY_COMMON_RESOURCE_INTERFACES_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/iot.ocf\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * 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.\n - * - * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> - * + * This API is related with the following features: \n + * - http://tizen.org/feature/iot.ocf \n + * It is recommended to design feature related codes in your application for reliability. \n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n + * 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. \n + * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> * @{ */ + /** * @brief Creates a new resource interfaces handle. - * * @since_tizen 3.0 - * - * @remarks You must destroy @a ifaces by calling iotcon_resource_interfaces_destroy() - * if @a ifaces is no longer needed. - * + * @remarks You must destroy @a ifaces by calling iotcon_resource_interfaces_destroy() if @a ifaces is no longer needed. * @param[out] ifaces A newly allocated list of resource ifaces handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_resource_interfaces_destroy() * @see iotcon_resource_interfaces_add() * @see iotcon_resource_interfaces_remove() @@ -125,18 +116,16 @@ static void _create_light_resource() */ int iotcon_resource_interfaces_create(iotcon_resource_interfaces_h *ifaces); + /** * @brief Destroys a resource ifaces handle. - * * @since_tizen 3.0 - * * @param[in] ifaces The handle of the resource ifaces - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_resource_interfaces_create() * @see iotcon_resource_interfaces_add() * @see iotcon_resource_interfaces_remove() @@ -144,124 +133,104 @@ int iotcon_resource_interfaces_create(iotcon_resource_interfaces_h *ifaces); */ int iotcon_resource_interfaces_destroy(iotcon_resource_interfaces_h ifaces); + /** * @brief Inserts a resource iface into the list. - * * @since_tizen 3.0 - * * @remarks @a iface could be a value such as #IOTCON_INTERFACE_DEFAULT. - * * @param[in] ifaces The handle of the resource ifaces * @param[in] iface The string data to insert into the resource ifaces - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_ALREADY Already done - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_ALREADY Already done * @see iotcon_resource_interfaces_create() * @see iotcon_resource_interfaces_destroy() * @see iotcon_resource_interfaces_remove() * @see iotcon_resource_interfaces_clone() */ -int iotcon_resource_interfaces_add(iotcon_resource_interfaces_h ifaces, - const char *iface); +int iotcon_resource_interfaces_add(iotcon_resource_interfaces_h ifaces, const char *iface); + /** - * @brief Delete a resource iface form the list. - * + * @brief Deletes a resource iface from the list. * @since_tizen 3.0 - * * @remarks @a iface could be a value such as #IOTCON_INTERFACE_DEFAULT. - * * @param[in] ifaces The handle of the resource ifaces * @param[in] iface The string data to delete from the resource ifaces - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available * @see iotcon_resource_interfaces_create() * @see iotcon_resource_interfaces_destroy() * @see iotcon_resource_interfaces_add() * @see iotcon_resource_interfaces_clone() */ -int iotcon_resource_interfaces_remove(iotcon_resource_interfaces_h ifaces, - const char *iface); +int iotcon_resource_interfaces_remove(iotcon_resource_interfaces_h ifaces, const char *iface); + /** * @brief Specifies the iface of function passed to iotcon_resource_interfaces_foreach(). - * * @since_tizen 3.0 - * * @remarks @a iface could be a value such as #IOTCON_INTERFACE_DEFAULT. - * * @param[in] iface The value of the resource ifaces * @param[in] user_data The user data to pass to the function - * - * @return 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. - * + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre iotcon_resource_interfaces_foreach() will invoke this callback function. - * * @see iotcon_resource_interfaces_foreach() */ typedef bool (*iotcon_resource_interfaces_foreach_cb)(const char *iface, void *user_data); + /** * @brief Gets all of the resource ifaces of the list by invoking the callback function. - * @details iotcon_resource_interfaces_foreach_cb() will be called for each iface.\n - * If iotcon_resource_interfaces_foreach_cb() returns false, iteration will be stop. - * + * @details iotcon_resource_interfaces_foreach_cb() will be called for each iface. \n + * If iotcon_resource_interfaces_foreach_cb() returns false, iteration will be stopped. * @since_tizen 3.0 - * * @param[in] ifaces The handle of resource ifaces * @param[in] cb The callback function to get data * @param[in] user_data The user data to pass to the function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @post iotcon_resource_interfaces_foreach() will be called for each iface. - * * @see iotcon_resource_interfaces_foreach_cb() */ -int iotcon_resource_interfaces_foreach(iotcon_resource_interfaces_h ifaces, - iotcon_resource_interfaces_foreach_cb cb, void *user_data); +int iotcon_resource_interfaces_foreach(iotcon_resource_interfaces_h ifaces, iotcon_resource_interfaces_foreach_cb cb, void *user_data); + /** * @brief Clones the resource ifaces handle. * @details Makes a deep copy of a source list of resource ifaces. - * * @since_tizen 3.0 - * - * @remarks You must @a destroy dest by calling iotcon_resource_interfaces_destroy() - * if @a dest is no longer needed. - * + * @remarks You must @a destroy dest by calling iotcon_resource_interfaces_destroy() if @a dest is no longer needed. * @param[in] src The origin handle of the resource ifaces * @param[out] dest Clone of a source list of resource ifaces - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_resource_interfaces_create() * @see iotcon_resource_interfaces_destroy() * @see iotcon_resource_interfaces_add() * @see iotcon_resource_interfaces_remove() */ -int iotcon_resource_interfaces_clone(iotcon_resource_interfaces_h src, - iotcon_resource_interfaces_h *dest); +int iotcon_resource_interfaces_clone(iotcon_resource_interfaces_h src, iotcon_resource_interfaces_h *dest); + /** * @} */ + #endif /* __IOTCON_STRUCT_RESOURCE_INTERFACES_H__ */ diff --git a/include/iotcon-resource-types.h b/include/iotcon-resource-types.h index d3fc7e3..8fd9784 100644 --- a/include/iotcon-resource-types.h +++ b/include/iotcon-resource-types.h @@ -13,28 +13,29 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_STRUCT_RESOURCE_TYPES_H__ #define __IOTCON_STRUCT_RESOURCE_TYPES_H__ + #include <iotcon-types.h> + /** * @file iotcon-resource-types.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_COMMON_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_COMMON_RESOURCE_TYPES_MODULE Resource Types - * * @brief IoTCon Resource Types provides API to manage resource types. - * * @section CAPI_IOT_CONNECTIVITY_COMMON_RESOURCE_TYPES_MODULE_HEADER Required Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_COMMON_RESOURCE_TYPES_MODULE_OVERVIEW Overview - * The iotcon resource types API provides methods for managing handle and add, remove resource types. - * A resource type indicates a class or category of resources. - * + * The IoTCon Resource Types API provides methods for managing handle and add, remove resource types. + * A resource type indicates a class or category of resources. * Example : * @code #include <iotcon.h> @@ -86,38 +87,28 @@ static void _create_light_resource() iotcon_resource_types_destroy(resource_types); } * @endcode - * * @section CAPI_IOT_CONNECTIVITY_COMMON_RESOURCE_TYPES_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/iot.ocf\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * 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.\n - * - * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> - * + * This API is related with the following features: \n + * - http://tizen.org/feature/iot.ocf \n + * It is recommended to design feature related codes in your application for reliability. \n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n + * 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. \n + * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> * @{ */ + /** * @brief Creates a new resource types handle. - * * @since_tizen 3.0 - * - * @remarks You must destroy @a types by calling iotcon_resource_types_destroy() - * if @a types is no longer needed. - * + * @remarks You must destroy @a types by calling iotcon_resource_types_destroy() if @a types is no longer needed. * @param[out] types A newly allocated list of resource types handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_resource_types_destroy() * @see iotcon_resource_types_add() * @see iotcon_resource_types_remove() @@ -125,18 +116,16 @@ static void _create_light_resource() */ int iotcon_resource_types_create(iotcon_resource_types_h *types); + /** * @brief Destroys a resource types handle. - * * @since_tizen 3.0 - * * @param[in] types The handle of the resource types - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_resource_types_create() * @see iotcon_resource_types_add() * @see iotcon_resource_types_remove() @@ -144,24 +133,22 @@ int iotcon_resource_types_create(iotcon_resource_types_h *types); */ int iotcon_resource_types_destroy(iotcon_resource_types_h types); + /** - * @brief Inserts a resource type into the list. - * + * @brief Inserts a resource types into the list. * @since_tizen 3.0 * @remarks The length of @a type should be less than or equal to 61.\n - * The @a type must start with a lowercase alphabetic character, followed by a sequence - * of lowercase alphabetic, numeric, ".", or "-" characters, and contains no white space.\n - * Duplicate strings are not allowed. - * + * The @a type must start with a lowercase alphabetic character, followed by a sequence + * of lowercase alphabetic, numeric, ".", or "-" characters, and contains no white space.\n + * Duplicate strings are not allowed. * @param[in] types The handle of the resource types * @param[in] type The string data to insert into the resource types (e.g. "org.tizen.light") - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_ALREADY Already done - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_ALREADY Already done * @see iotcon_resource_types_create() * @see iotcon_resource_types_destroy() * @see iotcon_resource_types_remove() @@ -169,20 +156,18 @@ int iotcon_resource_types_destroy(iotcon_resource_types_h types); */ int iotcon_resource_types_add(iotcon_resource_types_h types, const char *type); + /** - * @brief Delete a resource type form the list. - * + * @brief Deletes a resource types from the list. * @since_tizen 3.0 - * * @param[in] types The handle of the resource types * @param[in] type The string data to delete from the resource types - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data available - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data available * @see iotcon_resource_types_create() * @see iotcon_resource_types_destroy() * @see iotcon_resource_types_add() @@ -190,74 +175,63 @@ int iotcon_resource_types_add(iotcon_resource_types_h types, const char *type); */ int iotcon_resource_types_remove(iotcon_resource_types_h types, const char *type); + /** * @brief Specifies the type of function passed to iotcon_resource_types_foreach(). - * * @since_tizen 3.0 - * * @param[in] type The value of the resource types * @param[in] user_data The user data to pass to the function - * - * @return 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. - * + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop + * #IOTCON_FUNC_CONTINUE and #IOTCON_FUNC_STOP are more friendly values for the return * @pre iotcon_resource_types_foreach() will invoke this callback function. - * * @see iotcon_resource_types_foreach() */ typedef bool (*iotcon_resource_types_foreach_cb)(const char *type, void *user_data); + /** * @brief Gets all of the resource types of the list by invoking the callback function. - * @details iotcon_resource_types_foreach_cb() will be called for each type.\n - * If iotcon_resource_types_foreach_cb() returns false, iteration will be stop. - * + * @details iotcon_resource_types_foreach_cb() will be called for each type. \n + * If iotcon_resource_types_foreach_cb() returns false, iteration will be stopped. * @since_tizen 3.0 - * * @param[in] types The handle of resource types * @param[in] cb The callback function to get data * @param[in] user_data The user data to pass to the function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @post iotcon_resource_types_foreach() will be called for each type. - * * @see iotcon_resource_types_foreach_cb() */ -int iotcon_resource_types_foreach(iotcon_resource_types_h types, - iotcon_resource_types_foreach_cb cb, void *user_data); +int iotcon_resource_types_foreach(iotcon_resource_types_h types, iotcon_resource_types_foreach_cb cb, void *user_data); + /** * @brief Clones the resource types handle. * @details Makes a deep copy of a source list of resource types. - * * @since_tizen 3.0 - * - * @remarks You must @a destroy dest by calling iotcon_resource_types_destroy() - * if @a dest is no longer needed. - * + * @remarks You must @a destroy dest by calling iotcon_resource_types_destroy() if @a dest is no longer needed. * @param[in] src The origin handle of the resource types * @param[out] dest Clone of a source list of resource types - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_resource_types_create() * @see iotcon_resource_types_destroy() * @see iotcon_resource_types_add() * @see iotcon_resource_types_remove() */ -int iotcon_resource_types_clone(iotcon_resource_types_h src, - iotcon_resource_types_h *dest); +int iotcon_resource_types_clone(iotcon_resource_types_h src, iotcon_resource_types_h *dest); + /** * @} */ + #endif /* __IOTCON_STRUCT_RESOURCE_TYPES_H__ */ diff --git a/include/iotcon-resource.h b/include/iotcon-resource.h index 2bf0f2f..30ec911 100644 --- a/include/iotcon-resource.h +++ b/include/iotcon-resource.h @@ -13,28 +13,29 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_SERVER_RESOURCE_H__ #define __IOTCON_SERVER_RESOURCE_H__ + #include <stdint.h> #include <iotcon-types.h> + /** * @file iotcon-resource.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_SERVER_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_SERVER_RESOURCE_MODULE Resource - * * @brief IoTCon Resource provides API to manage resource. - * * @section CAPI_IOT_CONNECTIVITY_SERVER_RESOURCE_MODULE_HEADER Required Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_SERVER_RESOURCE_MODULE_OVERVIEW Overview - * The iotcon resource API provides methods for managing handle and resource information. - * + * The IoTCon Resource API provides methods for managing handle and resource information. * Example : * @code #include <iotcon.h> @@ -164,83 +165,63 @@ static void _create_resource() } } * @endcode - * * @section CAPI_IOT_CONNECTIVITY_SERVER_RESOURCE_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/iot.ocf\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * 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.\n - * - * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> - * + * This API is related with the following features: \n + * - http://tizen.org/feature/iot.ocf \n + * It is recommended to design feature related codes in your application for reliability. \n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n + * 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. \n + * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> * @{ */ + /** - * @brief Specifies the type of function passed to iotcon_resource_create() and - * iotcon_resource_set_request_handler(). - * @details Called when server receive request from the client. - * + * @brief Specifies the type of function passed to iotcon_resource_create() and iotcon_resource_set_request_handler(). + * @details Called when server receives request from the client. * @since_tizen 3.0 - * * @param[in] resource The resource requested * @param[in] request The request from client * @param[in] user_data The user data to pass to the function - * * @pre The callback must be registered using iotcon_resource_create() - * * @see iotcon_resource_create() * @see iotcon_resource_set_request_handler() */ -typedef void (*iotcon_request_handler_cb)(iotcon_resource_h resource, - iotcon_request_h request, void *user_data); +typedef void (*iotcon_request_handler_cb)(iotcon_resource_h resource, iotcon_request_h request, void *user_data); + /** * @brief Creates a resource handle and registers the resource in server. - * @details Registers a resource specified by @a uri_path, @a res_types, @a ifaces which have - * @a properties in IoTCon server.\n - * When client find the registered resource, iotcon_request_handler_cb() will be called automatically.\n - * @a uri_path format would be relative URI path like '/a/light'\n - * @a res_types is a list of resource types. Create a iotcon_resource_types_h handle and - * add types string to it.\n - * @a ifaces is a list of resource interfaces. Create a iotcon_resource_interfaces_h handle and - * add interfaces string to it.\n - * @a policies also can contain multiple policies like - * IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE.\n - * iotcon_request_handler_cb() will be called when receive CRUD request to the registered - * resource. - * + * @details Registers a resource specified by @a uri_path, @a res_types, @a ifaces which has @a properties in IoTCon server. \n + * When client finds the registered resource, iotcon_request_handler_cb() will be called automatically. \n + * @a uri_path format would be relative URI path like '/a/light' \n + * @a res_types is a list of resource types. Create a iotcon_resource_types_h handle and add types string to it. \n + * @a ifaces is a list of resource interfaces. Create a iotcon_resource_interfaces_h handle and add interfaces string to it. \n + * @a policies also can contain multiple policies like IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE. \n + * iotcon_request_handler_cb() will be called when receive CRUD request to the registered resource. * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * - * @remarks @a uri_path length must be less than 128.\n - * You must destroy @a resource by calling iotcon_resource_destroy() - * if @a resource is no longer needed. - * + * @remarks @a uri_path length must be less than 128. \n + * You must destroy @a resource by calling iotcon_resource_destroy() if @a resource is no longer needed. * @param[in] uri_path The URI path of the resource * @param[in] res_types The list of type of the resource * @param[in] ifaces The list of interface of the resource - * @param[in] policies The policies of the resource\n Set of #iotcon_resource_policy_e + * @param[in] policies The policies of the resource \n + * Set of #iotcon_resource_policy_e * @param[in] cb The request handler callback function * @param[in] user_data The user data to pass to the callback function * @param[out] resource_handle The handle of the resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_IOTIVITY IoTivity errors - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_IOTIVITY IoTivity errors + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. * @post When the resource receive CRUD request, iotcon_request_handler_cb() will be called. - * * @see iotcon_resource_destroy() * @see iotcon_resource_bind_interface() * @see iotcon_resource_bind_type() @@ -249,35 +230,24 @@ typedef void (*iotcon_request_handler_cb)(iotcon_resource_h resource, * @see iotcon_resource_unbind_child_resource() * @see iotcon_request_handler_cb() */ -int iotcon_resource_create(const char *uri_path, - iotcon_resource_types_h res_types, - iotcon_resource_interfaces_h ifaces, - uint8_t policies, - iotcon_request_handler_cb cb, - void *user_data, - iotcon_resource_h *resource_handle); +int iotcon_resource_create(const char *uri_path, iotcon_resource_types_h res_types, iotcon_resource_interfaces_h ifaces, uint8_t policies, iotcon_request_handler_cb cb, void *user_data, iotcon_resource_h *resource_handle); + /** * @brief Destroys the resource and releases its data. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * - * @remarks When a normal variable is used, there are only permission denied error. - * If the errors of this API are not handled, then you must check an application have - * the privileges for the API. - * + * @remarks When a normal variable is used, there is only permission denied error. + * If the errors of this API are not handled, then you must check an application has the privileges for the API. * @param[in] resource_handle The handle of the resource to be unregistered - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_resource_create() * @see iotcon_resource_bind_interface() * @see iotcon_resource_bind_type() @@ -288,28 +258,24 @@ int iotcon_resource_create(const char *uri_path, */ int iotcon_resource_destroy(iotcon_resource_h resource_handle); + /** * @brief Binds an interface to the resource. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @remarks @a iface could be a value such as #IOTCON_INTERFACE_DEFAULT. - * * @param[in] resource The handle of the resource * @param[in] iface The interface to be bound to the resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_SYSTEM System error * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * @retval #IOTCON_ERROR_ALREADY Already done - * + * @retval #IOTCON_ERROR_ALREADY Already done * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_resource_create() * @see iotcon_resource_destroy() * @see iotcon_resource_bind_type() @@ -320,30 +286,26 @@ int iotcon_resource_destroy(iotcon_resource_h resource_handle); */ int iotcon_resource_bind_interface(iotcon_resource_h resource, const char *iface); + /** * @brief Binds a type to the resource. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @remarks The length of @a resource_type should be less than or equal to 61.\n - * The @a resource_type must start with a lowercase alphabetic character, followed by a sequence - * of lowercase alphabetic, numeric, ".", or "-" characters, and contains no white space. - * + * The @a resource_type must start with a lowercase alphabetic character, followed by a sequence + * of lowercase alphabetic, numeric, ".", or "-" characters, and contains no white space. * @param[in] resource_handle The handle of the resource * @param[in] resource_type The type to be bound to the resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_SYSTEM System error * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * @retval #IOTCON_ERROR_ALREADY Already done - * + * @retval #IOTCON_ERROR_ALREADY Already done * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_resource_create() * @see iotcon_resource_destroy() * @see iotcon_resource_bind_interface() @@ -352,27 +314,22 @@ int iotcon_resource_bind_interface(iotcon_resource_h resource, const char *iface * @see iotcon_resource_unbind_child_resource() * @see iotcon_request_handler_cb() */ -int iotcon_resource_bind_type(iotcon_resource_h resource_handle, - const char *resource_type); +int iotcon_resource_bind_type(iotcon_resource_h resource_handle, const char *resource_type); + /** * @brief Sets a request handler to the resource. - * @details When the resource receive CRUD request, iotcon_request_handler_cb() will be - * called. - * + * @details When the resource receive CRUD request, iotcon_request_handler_cb() will be called. * @since_tizen 3.0 - * * @remarks Registered callback function will be replaced with the new @a cb. - * * @param[in] resource The handle of the resource * @param[in] cb The request handler to be bound to the resource * @param[in] user_data The user data to pass to the callback function - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_resource_create() * @see iotcon_resource_destroy() * @see iotcon_resource_bind_interface() @@ -381,29 +338,25 @@ int iotcon_resource_bind_type(iotcon_resource_h resource_handle, * @see iotcon_resource_unbind_child_resource() * @see iotcon_request_handler_cb() */ -int iotcon_resource_set_request_handler(iotcon_resource_h resource, - iotcon_request_handler_cb cb, void *user_data); +int iotcon_resource_set_request_handler(iotcon_resource_h resource, iotcon_request_handler_cb cb, void *user_data); + /** * @brief Binds a child resource into the parent resource. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] parent The handle of the parent resource * @param[in] child The handle of the child resource to be added to the parent resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_ALREADY Already done + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_ALREADY Already done * @retval #IOTCON_ERROR_SYSTEM System error * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_resource_create() * @see iotcon_resource_destroy() * @see iotcon_resource_bind_interface() @@ -412,29 +365,25 @@ int iotcon_resource_set_request_handler(iotcon_resource_h resource, * @see iotcon_resource_unbind_child_resource() * @see iotcon_request_handler_cb() */ -int iotcon_resource_bind_child_resource(iotcon_resource_h parent, - iotcon_resource_h child); +int iotcon_resource_bind_child_resource(iotcon_resource_h parent, iotcon_resource_h child); + /** * @brief Unbinds a child resource from the parent resource. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] parent The handle of the parent resource * @param[in] child The handle of the child resource to be unbound from the parent resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_SYSTEM System error * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied * @retval #IOTCON_ERROR_NO_DATA No data available - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_resource_create() * @see iotcon_resource_destroy() * @see iotcon_resource_bind_interface() @@ -443,32 +392,28 @@ int iotcon_resource_bind_child_resource(iotcon_resource_h parent, * @see iotcon_resource_bind_child_resource() * @see iotcon_request_handler_cb() */ -int iotcon_resource_unbind_child_resource(iotcon_resource_h parent, - iotcon_resource_h child); +int iotcon_resource_unbind_child_resource(iotcon_resource_h parent, iotcon_resource_h child); + /** * @brief Notifies specific clients that resource's attributes have changed. * @details If @a observers is @c NULL, the @a msg will notify to all observers. - * * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] resource The handle of the resource * @param[in] repr The handle of the representation - * @param[in] observers The handle of the observers. - * @param[in] qos The quality of service for message transfer. - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_REPRESENTATION Representation error - * @retval #IOTCON_ERROR_SYSTEM System error + * @param[in] observers The handle of the observers + * @param[in] qos The quality of service for message transfer + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_REPRESENTATION Representation error + * @retval #IOTCON_ERROR_SYSTEM System error * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_remote_resource_observe_cb() * @see iotcon_remote_resource_observe_register() * @see iotcon_remote_resource_observe_deregister() @@ -477,72 +422,61 @@ int iotcon_resource_unbind_child_resource(iotcon_resource_h parent, * @see iotcon_observers_add() * @see iotcon_observers_remove() */ -int iotcon_resource_notify(iotcon_resource_h resource, iotcon_representation_h repr, - iotcon_observers_h observers, iotcon_qos_e qos); +int iotcon_resource_notify(iotcon_resource_h resource, iotcon_representation_h repr, iotcon_observers_h observers, iotcon_qos_e qos); + /** * @brief Gets the number of child resources of the resource. - * * @since_tizen 3.0 - * * @param[in] resource The handle of the resource * @param[out] count The number of child resources - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_resource_get_nth_child() * @see iotcon_resource_get_uri_path() * @see iotcon_resource_get_types() * @see iotcon_resource_get_interfaces() * @see iotcon_resource_get_policies() */ -int iotcon_resource_get_child_count(iotcon_resource_h resource, - unsigned int *count); +int iotcon_resource_get_child_count(iotcon_resource_h resource, unsigned int *count); + /** * @brief Gets the child resource at the given index in the parent resource. - * * @since_tizen 3.0 - * * @remarks @a child must not be released using iotcon_resource_destroy(). - * * @param[in] parent The handle of the parent resource * @param[in] index The index of the child resource * @param[out] child The child resource at the index - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_NO_DATA No data available - * * @see iotcon_resource_get_child_count() * @see iotcon_resource_get_uri_path() * @see iotcon_resource_get_types() * @see iotcon_resource_get_interfaces() * @see iotcon_resource_get_policies() */ -int iotcon_resource_get_nth_child(iotcon_resource_h parent, int index, - iotcon_resource_h *child); +int iotcon_resource_get_nth_child(iotcon_resource_h parent, int index, iotcon_resource_h *child); + /** * @brief Gets an URI path of the resource. - * * @since_tizen 3.0 - * * @remarks @a uri_path must not be released using free(). - * * @param[in] resource The handle of the resource * @param[out] uri_path The URI path of the resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_resource_get_child_count() * @see iotcon_resource_get_nth_child() * @see iotcon_resource_get_types() @@ -551,21 +485,18 @@ int iotcon_resource_get_nth_child(iotcon_resource_h parent, int index, */ int iotcon_resource_get_uri_path(iotcon_resource_h resource, char **uri_path); + /** * @brief Gets the list of types in the resource. - * * @since_tizen 3.0 - * * @remarks @a types must not be released using iotcon_resource_types_destroy(). - * * @param[in] resource The handle of the resource * @param[out] types The types of the resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_resource_get_child_count() * @see iotcon_resource_get_nth_child() * @see iotcon_resource_get_uri_path() @@ -574,45 +505,39 @@ int iotcon_resource_get_uri_path(iotcon_resource_h resource, char **uri_path); */ int iotcon_resource_get_types(iotcon_resource_h resource, iotcon_resource_types_h *types); + /** * @brief Gets the interfaces of the resource. - * * @since_tizen 3.0 - * * @remarks @a ifaces must not be released using iotcon_resource_interfaces_destroy(). - * * @param[in] resource The handle of the resource * @param[out] ifaces The interfaces of the resource - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_resource_get_child_count() * @see iotcon_resource_get_nth_child() * @see iotcon_resource_get_uri_path() * @see iotcon_resource_get_types() * @see iotcon_resource_get_policies() */ -int iotcon_resource_get_interfaces(iotcon_resource_h resource, - iotcon_resource_interfaces_h *ifaces); +int iotcon_resource_get_interfaces(iotcon_resource_h resource, iotcon_resource_interfaces_h *ifaces); + /** * @brief Gets the policies in the resource. - * @details @a policies can contain multiple policies like - * IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE. - * + * @details @a policies can contain multiple policies like IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE. * @since_tizen 3.0 - * * @param[in] resource The handle of the resource - * @param[out] policies The policies of resource\n Set of #iotcon_resource_policy_e - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @param[out] policies The policies of resource \n + * Set of #iotcon_resource_policy_e + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_resource_get_child_count() * @see iotcon_resource_get_nth_child() * @see iotcon_resource_get_uri_path() @@ -621,8 +546,10 @@ int iotcon_resource_get_interfaces(iotcon_resource_h resource, */ int iotcon_resource_get_policies(iotcon_resource_h resource, uint8_t *policies); + /** * @} */ + #endif /* __IOTCON_SERVER_RESOURCE_H__ */ diff --git a/include/iotcon-response.h b/include/iotcon-response.h index d44d46a..47344e2 100644 --- a/include/iotcon-response.h +++ b/include/iotcon-response.h @@ -13,27 +13,28 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_COMMON_RESPONSE_H__ #define __IOTCON_COMMON_RESPONSE_H__ + #include <iotcon-types.h> + /** * @file iotcon-response.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_COMMON_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_COMMON_RESPONSE_MODULE Response - * * @brief IoTCon Response provides API to manage response. - * * @section CAPI_IOT_CONNECTIVITY_COMMON_RESPONSE_MODULE_HEADER Required Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_COMMON_RESPONSE_MODULE_OVERVIEW Overview - * The iotcon response API provides methods for managing handle and get response information. - * + * The IoTCon Response API provides methods for managing handle and get response information. * Example (Client side) : * @code #include <iotcon.h> @@ -174,55 +175,43 @@ static void _request_handler(iotcon_resource_h resource, iotcon_request_h reques ... } * @endcode - * * @section CAPI_IOT_CONNECTIVITY_COMMON_RESPONSE_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/iot.ocf\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * 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.\n - * - * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> - * + * This API is related with the following features: \n + * - http://tizen.org/feature/iot.ocf \n + * It is recommended to design feature related codes in your application for reliability. \n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n + * 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. \n + * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> * @{ */ + /** * @brief Creates a response handle. - * * @since_tizen 3.0 - * - * @remarks You must destroy @a response by calling iotcon_response_destroy() - * if @a response is no longer needed. - * + * @remarks You must destroy @a response by calling iotcon_response_destroy() if @a response is no longer needed. * @param[in] request The handle of received request handle * @param[out] response Generated response handle - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @see iotcon_response_destroy() */ int iotcon_response_create(iotcon_request_h request, iotcon_response_h *response); + /** * @brief Destroys a response handle. - * * @since_tizen 3.0 - * * @param[in] resp The handle of the response - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_response_create() */ int iotcon_response_destroy(iotcon_response_h resp); @@ -230,146 +219,128 @@ int iotcon_response_destroy(iotcon_response_h resp); /** * @brief Gets header options of the response. - * * @since_tizen 3.0 - * * @remarks @a options must not be released using iotcon_options_destroy(). - * * @param[in] resp The handle of the response * @param[out] options The handle of the header options - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_response_get_representation() * @see iotcon_response_get_result() */ int iotcon_response_get_options(iotcon_response_h resp, iotcon_options_h *options); + /** * @brief Gets representation of the response. - * * @since_tizen 3.0 - * * @remarks @a repr must not be released using iotcon_representation_destroy(). - * * @param[in] resp The handle of the response * @param[out] repr The handle of the representation - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_NO_DATA No data - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_NO_DATA No data * @see iotcon_response_get_options() * @see iotcon_response_get_result() */ int iotcon_response_get_representation(iotcon_response_h resp, iotcon_representation_h *repr); + /** * @brief Gets result of the response. - * * @since_tizen 3.0 - * * @param[in] resp The handle of the response * @param[out] result The result of the response - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @see iotcon_response_get_options() * @see iotcon_response_get_representation() */ -int iotcon_response_get_result(iotcon_response_h resp, - iotcon_response_result_e *result); +int iotcon_response_get_result(iotcon_response_h resp, iotcon_response_result_e *result); /** * @brief Sets result into the response. * @details The @a result could be one of #iotcon_response_result_e. - * * @since_tizen 3.0 - * * @param[in] resp The handle of the response * @param[in] result The result to set - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @see iotcon_response_create() * @see iotcon_response_destroy() */ int iotcon_response_set_result(iotcon_response_h resp, iotcon_response_result_e result); + /** * @brief Sets representation into the response. - * * @since_tizen 3.0 - * * @param[in] resp The handle of the response * @param[in] repr The representation of the response - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @see iotcon_response_create() * @see iotcon_response_destroy() */ -int iotcon_response_set_representation(iotcon_response_h resp, - iotcon_representation_h repr); +int iotcon_response_set_representation(iotcon_response_h resp, iotcon_representation_h repr); + /** * @brief Sets header options into the response. - * * @since_tizen 3.0 - * * @param[in] resp The handle of the response * @param[in] options The header options of the response - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @see iotcon_response_create() * @see iotcon_response_destroy() */ int iotcon_response_set_options(iotcon_response_h resp, iotcon_options_h options); + /** - * @brief Send response for incoming request. - * + * @brief Sends response for incoming request. * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * * @param[in] resp The handle of the response to send - * - * @pre iotcon_initialize() should be called to initialize. - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_SYSTEM System error * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied + * @pre iotcon_initialize() should be called to initialize. */ int iotcon_response_send(iotcon_response_h resp); + /** * @} */ + #endif /* __IOTCON_COMMON_RESPONSE_H__ */ diff --git a/include/iotcon-server.h b/include/iotcon-server.h index 1beb06d..001470c 100644 --- a/include/iotcon-server.h +++ b/include/iotcon-server.h @@ -13,117 +13,109 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_SERVER_H__ #define __IOTCON_SERVER_H__ + #include <iotcon-resource.h> #include <iotcon-lite-resource.h> #include <iotcon-response.h> #include <iotcon-observers.h> #include <iotcon-request.h> + /** * @file iotcon-server.h */ + /** * @ingroup CAPI_IOT_CONNECTIVITY_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_SERVER_MODULE Server - * * @brief IoTCon Server provides API for server side. - * * @section CAPI_IOT_CONNECTIVITY_SERVER_MODULE_HEADER Required Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_SERVER_MODULE_OVERVIEW Overview - * This API set consists of server side API for - * @ref CAPI_IOT_CONNECTIVITY_SERVER_RESOURCE_MODULE, - * @ref CAPI_IOT_CONNECTIVITY_SERVER_LITE_RESOURCE_MODULE, - * @ref CAPI_IOT_CONNECTIVITY_SERVER_OBSERVERS_MODULE, - * @ref CAPI_IOT_CONNECTIVITY_SERVER_REQUEST_MODULE. - * + * This API set consists of server side API for + * @ref CAPI_IOT_CONNECTIVITY_SERVER_RESOURCE_MODULE, + * @ref CAPI_IOT_CONNECTIVITY_SERVER_LITE_RESOURCE_MODULE, + * @ref CAPI_IOT_CONNECTIVITY_SERVER_OBSERVERS_MODULE, + * @ref CAPI_IOT_CONNECTIVITY_SERVER_REQUEST_MODULE. * @{ */ + /** * @brief Starts presence of a server. - * @details Use this function to send server's announcements to clients.\n - * Server can call this function when online for the first time or come back from offline to online. - * + * @details Use this function to send server's announcements to clients. \n + * Server can call this function when online for the first time or come back from offline to online. * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * - * @remarks If @a time_to_live is 0, server will set default value as 60 seconds.\n - * If @a time_to_live is very big, server will set maximum value as (60 * 60 * 24) seconds - * (24 hours). - * - * @param[in] time_to_live The interval of announcing presence in seconds. - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @remarks If @a time_to_live is 0, server will set default value as 60 seconds. \n + * If @a time_to_live is very big, server will set maximum value as (60 * 60 * 24) seconds (24 hours). + * @param[in] time_to_live The interval of announcing presence in seconds + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @retval #IOTCON_ERROR_SYSTEM System error * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_stop_presence() * @see iotcon_add_presence_cb() * @see iotcon_remove_presence_cb() */ int iotcon_start_presence(unsigned int time_to_live); + /** * @brief Stops presence of a server. * @details Use this function to stop sending server's announcements to clients. - * Server can call this function when terminating, entering to offline or out of network. - * + * Server can call this function when terminating, entering to offline or out of network. * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @retval #IOTCON_ERROR_SYSTEM System error * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_start_presence() * @see iotcon_add_presence_cb() * @see iotcon_remove_presence_cb() */ int iotcon_stop_presence(void); + /** * @brief Sets the device name. * @details The function sets the name of the local device (the device calling the function). - * If the device name is set, clients can get the name using iotcon_device_info_get_property() - * or iotcon_remote_resource_get_device_name(). - * + * If the device name is set, clients can get the name using iotcon_device_info_get_property() or iotcon_remote_resource_get_device_name(). * @since_tizen 3.0 - * * @remarks @a device_name may not be an empty string. - * * @param[in] device_name The device name - * - * @return 0 on success, otherwise a negative error value. - * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @return @c 0 on success, + * otherwise a negative error value + * @retval #IOTCON_ERROR_NONE Successful + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory * @retval #IOTCON_ERROR_IOTIVITY Iotivity errors - * * @see iotcon_get_device_info() * @see iotcon_device_info_get_property() * @see iotcon_remote_resource_get_device_name() */ int iotcon_set_device_name(const char *device_name); + /** * @} */ + #endif /* __IOTCON_SERVER_H__ */ diff --git a/include/iotcon-types.h b/include/iotcon-types.h index bca283d..f49d4fe 100644 --- a/include/iotcon-types.h +++ b/include/iotcon-types.h @@ -13,13 +13,16 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_TYPES_H__ #define __IOTCON_TYPES_H__ -#include <tizen_type.h> +#include <tizen_type.h> #include <iotcon-constant.h> + /** * @file iotcon-types.h */ @@ -28,195 +31,180 @@ /** * @ingroup CAPI_IOT_CONNECTIVITY_MODULE * @defgroup CAPI_IOT_CONNECTIVITY_COMMON_MODULE Common - * * @brief IoTCon Common API provides the set of definitions to use server and client API. - * * @section CAPI_IOT_CONNECTIVITY_COMMON_MODULE_HEADER Header - * \#include <iotcon.h> - * + * \#include <iotcon.h> * @section CAPI_IOT_CONNECTIVITY_COMMON_MODULE_OVERVIEW Overview - * This API set consists of data structures for - * @ref CAPI_IOT_CONNECTIVITY_COMMON_RESOURCE_TYPES_MODULE, - * @ref CAPI_IOT_CONNECTIVITY_COMMON_QUERY_MODULE, - * @ref CAPI_IOT_CONNECTIVITY_COMMON_OPTIONS_MODULE, - * @ref CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_MODULE, - * @ref CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_ATTRIBUTES_MODULE, - * @ref CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_ATTRIBUTES_LIST_MODULE, - * @ref CAPI_IOT_CONNECTIVITY_COMMON_RESPONSE_MODULE. - * + * This API set consists of data structures for + * @ref CAPI_IOT_CONNECTIVITY_COMMON_RESOURCE_TYPES_MODULE, + * @ref CAPI_IOT_CONNECTIVITY_COMMON_QUERY_MODULE, + * @ref CAPI_IOT_CONNECTIVITY_COMMON_OPTIONS_MODULE, + * @ref CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_MODULE, + * @ref CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_ATTRIBUTES_MODULE, + * @ref CAPI_IOT_CONNECTIVITY_COMMON_REPRESENTATION_ATTRIBUTES_LIST_MODULE, + * @ref CAPI_IOT_CONNECTIVITY_COMMON_RESPONSE_MODULE. * @{ */ /** - * @brief The handle of resource. - * @details @a iotcon_resource_h is an opaque data structure to represent registered - * resource by server. A resource has host_address, uri_path, resource types, interfaces - * and internal handle. If observable attribute of resource is true, client can observe - * this resource. When client request by CRUD functions, handler will be invoked - * if registered. It could contain other resource as children. - * + * @brief The resource handle. + * @details @a iotcon_resource_h is an opaque data structure to represent registered resource by server. + * A resource has host_address, uri_path, resource types, interfaces and internal handle. + * If observable attribute of resource is true, client can observe this resource. + * When client requests by CRUD functions, handler will be invoked if registered. + * It could contain other resource as children. * @since_tizen 3.0 */ typedef struct icl_resource* iotcon_resource_h; + /** - * @brief The handle of lite resource. - * @details @a iotcon_lite_resource_h is an opaque data structure to represent registered - * resource by server. A resource has host_address, uri_path, resource types, and internal - * handle. If observable attribute of resource is true, client can observe this resource. - * + * @brief The lite resource handle. + * @details @a iotcon_lite_resource_h is an opaque data structure to represent registered resource by server. + * A resource has host_address, uri_path, resource types, and internal handle. + * If observable attribute of resource is true, client can observe this resource. * @since_tizen 3.0 */ typedef struct icl_lite_resource* iotcon_lite_resource_h; + /** - * @brief The handle of response. + * @brief The response handle. * @details @a iotcon_response_h is an opaque data structure to respond to client. - * @a iotcon_response_h is a data type of server's response which consists of result, - * header options, query, representation. - * - * + * @a iotcon_response_h is a data type of server's response which consists of result, header options, query, representation. * @since_tizen 3.0 */ typedef struct icl_resource_response* iotcon_response_h; + /** - * @brief The handle of observers. - * @details The list of observer ids. - * + * @brief The observers handle. + * @details The list of observer IDs. * @since_tizen 3.0 */ typedef struct icl_observers* iotcon_observers_h; + /** - * @brief The handle of request. + * @brief The request handle. * @details @a iotcon_request_h is an opaque data structure to request to a particular resource. - * @a iotcon_request_h is a data type of client's request which consists of header options, - * query, representation. - * + * @a iotcon_request_h is a data type of client's request which consists of header options, query, representation. * @since_tizen 3.0 */ typedef struct icl_resource_request* iotcon_request_h; /** - * @brief The handle of remote resource. - * @details When Client success to find out resource from remote server, - * server's resource information is reorganized as @a iotcon_remote_resource_h by IoTCon. - * Client can request CRUD to server by using this. - * @a iotcon_remote_resource_h is an opaque data structure to have host_address, uri_path, - * resource types, interfaces, options and device id. - * If observable attribute is true, remote resource is observable. - * When you observe remote resource, observe_handle will be set. - * + * @brief The remote resource handle. + * @details When Client is successful to find out resource from remote server, server's resource information is reorganized as @a iotcon_remote_resource_h by IoTCon. + * Client can request CRUD to server by using this. + * @a iotcon_remote_resource_h is an opaque data structure to have host_address, uri_path, resource types, interfaces, options and device id. + * If observable attribute is true, remote resource is observable. + * When you observe remote resource, observe_handle will be set. * @since_tizen 3.0 */ typedef struct icl_remote_resource* iotcon_remote_resource_h; + /** - * @brief The handle of presence. + * @brief The presence handle. * @details @a iotcon_presence_h is a handle of presence subscription. - * It is used to cancel presence. - * + * It is used to cancel presence. * @since_tizen 3.0 */ typedef struct icl_presence* iotcon_presence_h; + /** - * @brief The handle of presence response. - * @details @a iotcon_presence_response_h is a handle of presence response subscription.\n - * It is used to get the information of presence response from server. - * + * @brief The presence response handle. + * @details @a iotcon_presence_response_h is a handle of presence response subscription. \n + * It is used to get the information of presence response from server. * @since_tizen 3.0 */ typedef struct icl_presence_response* iotcon_presence_response_h; + /** - * @brief The handle of device information. + * @brief The device information handle. * @details @a iotcon_device_info_h is a handle of device information. - * * @since_tizen 3.0 */ typedef struct icl_device_info* iotcon_device_info_h; + /** - * @brief The handle of platform information. + * @brief The platform information handle. * @details @a iotcon_platform_info_h is a handle of platform information. - * * @since_tizen 3.0 */ typedef struct icl_platform_info* iotcon_platform_info_h; + /** - * @brief The handle of resource interface. - * @details @a iotcon_resource_interfaces_h is an opaque data structure to have list - * of resource interfaces. A resource interface is datatype of string. - * + * @brief The resource interface handle. + * @details @a iotcon_resource_interfaces_h is an opaque data structure to have list of resource interfaces. A resource interface is datatype of string. * @since_tizen 3.0 */ typedef struct icl_resource_ifaces* iotcon_resource_interfaces_h; + /** - * @brief The handle of resource types. - * @details @a iotcon_resource_types_h is an opaque data structure to have list - * of resource types. A resource type is datatype of string. - * + * @brief The resource types handle. + * @details @a iotcon_resource_types_h is an opaque data structure to have list of resource types. A resource type is datatype of string. * @since_tizen 3.0 */ typedef struct icl_resource_types* iotcon_resource_types_h; + /** - * @brief The handle of options. - * @details @a iotcon_options_h is an opaque data structure to have attribute value map - * which consists of a key and a value. - * Datatype of key is integer and value is string. - * + * @brief The options handle. + * @details @a iotcon_options_h is an opaque data structure to have attribute value map which consists of a key and a value. + * Datatype of key is an integer and value is string. * @since_tizen 3.0 */ typedef struct icl_options* iotcon_options_h; + /** - * @brief The handle of query. - * @details @a iotcon_query_h is an opaque data structure to have attribute value map - * which consists of key and value. - * Data ype of both key and value are string. - * @a iotcon_query_h also have length. - * The length is total length of all keys and values of map. - * The length should be less than or equal to 64. - * + * @brief The query handle. + * @details @a iotcon_query_h is an opaque data structure to have attribute value map which consists of key and value. + * Datatype of both key and value are string. + * @a iotcon_query_h also have length. + * The length is total length of all keys and values of map. + * The length should be less than or equal to 64. * @since_tizen 3.0 */ typedef struct icl_query* iotcon_query_h; + /** - * @brief The handle of representation. - * @details @a iotcon_representation_h is an opaque data structure to have uri_path, - * list of resource types and interfaces. - * It could contain other representation as children. - * + * @brief The representation handle. + * @details @a iotcon_representation_h is an opaque data structure to have uri_path, list of resource types and interfaces. + * It could contain other representation as children. * @since_tizen 3.0 */ typedef struct icl_representation_s* iotcon_representation_h; + /** - * @brief The handle of list which is consist of iotcon_value_h type values. + * @brief The iotcon_value_h type values list handle. * @details @a iotcon_list_h is an opaque data structure. - * * @since_tizen 3.0 */ typedef struct icl_list_s* iotcon_list_h; + /** - * @brief The handle of attributes. + * @brief The attributes handle. * @details @a iotcon_attributes_h is an opaque data structure to have attribute value map. - * Attribute value map consists of a key and a value. - * Datatype of the key is string and the value should be one of them #IOTCON_TYPE_INT, - * #IOTCON_TYPE_BOOL, #IOTCON_TYPE_DOUBLE, #IOTCON_TYPE_STR, #IOTCON_TYPE_NULL, - * #IOTCON_TYPE_LIST and #IOTCON_TYPE_ATTRIBUTES - * + * Attribute value map consists of a key and a value. + * Datatype of the key is string and the value should be one of them #IOTCON_TYPE_INT, + * #IOTCON_TYPE_BOOL, #IOTCON_TYPE_DOUBLE, #IOTCON_TYPE_STR, #IOTCON_TYPE_NULL, + * #IOTCON_TYPE_LIST and #IOTCON_TYPE_ATTRIBUTES. * @since_tizen 3.0 */ typedef struct icl_attributes_s* iotcon_attributes_h; + /** * @} */ @@ -229,4 +217,5 @@ typedef struct icl_attributes_s* iotcon_attributes_h; #include <iotcon-resource-types.h> #include <iotcon-resource-interfaces.h> + #endif /* __IOTCON_TYPES_H__ */ diff --git a/include/iotcon.h b/include/iotcon.h index fb29fa7..32dbdee 100644 --- a/include/iotcon.h +++ b/include/iotcon.h @@ -13,146 +13,130 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + #ifndef __IOTCON_H__ #define __IOTCON_H__ + #ifdef __cplusplus extern "C" { #endif + #include <iotcon-types.h> #include <iotcon-errors.h> #include <iotcon-server.h> #include <iotcon-client.h> + /** * @file iotcon.h */ + /** - * * @addtogroup CAPI_IOT_CONNECTIVITY_MODULE - * * @section CAPI_IOT_CONNECTIVITY_MODULE_FEATURE Related Features - * This API is related with the following features:\n - * - http://tizen.org/feature/iot.ocf\n - * - * It is recommended to design feature related codes in your application for reliability.\n - * - * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n - * - * 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.\n - * - * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> - * + * This API is related with the following features: \n + * - http://tizen.org/feature/iot.ocf \n + * It is recommended to design feature related codes in your application for reliability. \n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n + * 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. \n + * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a> * @{ */ + /** * @brief Initializes IoTCon. - * @details Call this function to start IoTCon. - * + * @details Calls this function to start IoTCon. * @since_tizen 3.0 * @privlevel public * @privilege %http://tizen.org/privilege/network.get * @privilege %http://tizen.org/privilege/internet - * - * @param[in] file_path The path of SVR(Secure Virtual Resources) DB - * * @remarks The @a file_path point to a file for handling secure virtual resources. - * The file that is CBOR(Concise Binary Object Representation)-format must already exist - * in @a file_path. We recommend to use application-local file for @a file_path.\n - * You must call iotcon_deinitialize() if IoTCon API is no longer needed. - * - * @return 0 on success, otherwise a negative error value. + * The file that is CBOR(Concise Binary Object Representation)-format must already exist in @a file_path. + * We recommend to use application-local file for @a file_path. \n + * You must call iotcon_deinitialize() if IoTCon API is no longer needed. + * @param[in] file_path The path of SVR(Secure Virtual Resources) DB + * @return @c 0 on success, + * otherwise a negative error value * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied - * * @see iotcon_deinitialize() */ int iotcon_initialize(const char *file_path); + /** * @brief Deinitializes IoTCon. * @details Frees the resources allocated to IoTCon. - * * @since_tizen 3.0 - * * @remarks This function must be called if IoTCon API is no longer needed. - * - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, + * otherwise a negative error value * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_initialize() */ int iotcon_deinitialize(void); + /** * @brief Gets the timeout seconds of asynchronous API. * @details This API get the timeout of iotcon_find_device_info(), - * iotcon_find_platform_info(), iotcon_find_resource(), - * iotcon_remote_resource_get(), iotcon_remote_resource_put(), - * iotcon_remote_resource_post() and iotcon_remote_resource_delete(). - * + * iotcon_find_platform_info(), iotcon_find_resource(), + * iotcon_remote_resource_get(), iotcon_remote_resource_put(), + * iotcon_remote_resource_post() and iotcon_remote_resource_delete(). * @since_tizen 3.0 - * * @param[out] timeout_seconds Seconds for timeout - * - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, + * otherwise a negative error value * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_set_timeout() */ int iotcon_get_timeout(int *timeout_seconds); + /** * @brief Sets the timeout seconds of asynchronous APIs. * @details This API set the timeout of iotcon_find_device_info(), - * iotcon_find_platform_info(), iotcon_find_resource(), - * iotcon_remote_resource_get(), iotcon_remote_resource_put(), - * iotcon_remote_resource_post() and iotcon_remote_resource_delete().\n - * Default timeout interval value is 30. - * + * iotcon_find_platform_info(), iotcon_find_resource(), + * iotcon_remote_resource_get(), iotcon_remote_resource_put(), + * iotcon_remote_resource_post() and iotcon_remote_resource_delete().\n + * Default timeout interval value is 30. * @since_tizen 3.0 - * * @param[in] timeout_seconds Seconds for timeout (must be in range from 1 to 3600) - * - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, + * otherwise a negative error value * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_get_timeout() */ int iotcon_set_timeout(int timeout_seconds); + /** * @brief Gets the polling interval(milliseconds) of IoTCon. * @details This API gets the polling interval of IoTCon. - * Default polling interval is 100 milliseconds. - * + * Default polling interval is 100 milliseconds. * @since_tizen 3.0 - * * @param[out] interval Milliseconds for polling interval - * - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, + * otherwise a negative error value * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_set_timeout() */ int iotcon_polling_get_interval(int *interval); @@ -160,108 +144,96 @@ int iotcon_polling_get_interval(int *interval); /** * @brief Sets the polling interval(milliseconds) of IoTCon. * @details This API sets the polling interval of IoTCon. - * The closer to 0, the faster it operates. It is invoked immediately for changing the interval. - * Default polling interval is 100 milliseconds. If you want the faster operation, - * we recommend you set 10 milliseconds for polling interval. - * + * The closer to 0, the faster it operates. It is invoked immediately for changing the interval. + * Default polling interval is 100 milliseconds. If you want the faster operation, + * we recommend you set 10 milliseconds for polling interval. * @since_tizen 3.0 - * * @param[in] interval Milliseconds for polling interval (must be in range from 1 to 999) - * - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, + * otherwise a negative error value * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_polling_get_interval() */ int iotcon_polling_set_interval(int interval); + /** - * @brief Invokes a next message from a queue for receiving messages from others, immediately. - * @details This API invokes a next message from a queue for receiving messages from others, immediately.\n - * After calling the API, it continues the polling with existing interval. - * + * @brief Invokes a next message from a queue for receiving messages from others immediately. + * @details This API invokes a next message from a queue for receiving messages from others immediately. \n + * After calling the API, it continues the polling with existing interval. * @since_tizen 3.0 - * - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, + * otherwise a negative error value * @retval #IOTCON_ERROR_NONE Successful - * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported - * + * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @pre iotcon_initialize() should be called to initialize. */ int iotcon_polling_invoke(void); + /** * @brief Specifies the type of function passed to iotcon_add_generated_pin_cb(). - * @details When a provisioning tool calls the function for registering this device, - * it is called, immediately. - * + * @details When a provisioning tool calls the function for registering this device, it is called, immediately. * @since_tizen 3.0 - * * @param[in] pin The pin number which is generated automatically * @param[in] user_data The user data to pass to the function - * * @pre The callback must be registered using iotcon_add_generated_pin_cb() - * * @see iotcon_add_generated_pin_cb() * @see iotcon_remove_generated_pin_cb() */ typedef void (*iotcon_generated_pin_cb)(const char *pin, void *user_data); + /** * @brief Adds callback to show pin number which is generated automatically. - * @details When a provisioning tool tries to register this device using random pin based\n - * ownership transfer method, it makes pin number which is generated automatically be shown. - * + * @details When a provisioning tool tries to register this device using random pin based \n + * ownership transfer method, it makes pin number which is generated automatically be shown. * @since_tizen 3.0 - * * @param[in] cb The callback function to invoke * @param[in] user_data The user data to pass to the function - * - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, + * otherwise a negative error value * @retval #IOTCON_ERROR_NONE Successful * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_ALREADY Already done * @retval #IOTCON_ERROR_OUT_OF_MEMORY Out of memory - * * @pre iotcon_initialize() should be called to initialize. * @post When the device is registered by provisioning tool, iotcon_generated_pin_cb() will be called. - * * @see iotcon_remove_generated_pin_cb() */ int iotcon_add_generated_pin_cb(iotcon_generated_pin_cb cb, void *user_data); + /** * @brief Removes callback to show pin number which is generated automatically. - * @details If this function is called, @a cb will be not called anymore.\n - * For removing @a cb that is used at iotcon_add_generated_pin_cb() should be used. - * + * @details If this function is called, @a cb will be not called anymore. \n + * For removing @a cb that is used at iotcon_add_generated_pin_cb() should be used. * @since_tizen 3.0 - * * @param[in] cb The callback function to invoke - * - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, + * otherwise a negative error value * @retval #IOTCON_ERROR_NONE Successful * @retval #IOTCON_ERROR_NOT_SUPPORTED Not supported * @retval #IOTCON_ERROR_INVALID_PARAMETER Invalid parameter * @retval #IOTCON_ERROR_NO_DATA No data available - * * @pre iotcon_initialize() should be called to initialize. - * * @see iotcon_add_generated_pin_cb() */ int iotcon_remove_generated_pin_cb(iotcon_generated_pin_cb cb); + /** * @} */ + #ifdef __cplusplus } #endif + #endif /* __IOTCON_H__ */ diff --git a/packaging/iotcon.spec b/packaging/iotcon.spec index 38aa22a..d3ed629 100644 --- a/packaging/iotcon.spec +++ b/packaging/iotcon.spec @@ -1,6 +1,6 @@ Name: iotcon Summary: Tizen IoT Connectivity -Version: 0.3.10 +Version: 0.3.11 Release: 0 Group: Network & Connectivity/Service License: Apache-2.0 |