Rename API (iotcon_state_set_xxx -> iotcon_state_add_xxx)

[platform/core/iot/iotcon.git] / lib / include / iotcon-lite-resource.h

diff --git a/lib/include/iotcon-lite-resource.h b/lib/include/iotcon-lite-resource.h
index cbe0ab4..42743ac 100644 (file)
--- a/lib/include/iotcon-lite-resource.h
+++ b/lib/include/iotcon-lite-resource.h
@@ -16,7 +16,7 @@
 #ifndef __IOT_CONNECTIVITY_MANAGER_SERVER_LITE_RESOURCE_H__
 #define __IOT_CONNECTIVITY_MANAGER_SERVER_LITE_RESOURCE_H__
 
-#include <iotcon-constant.h>
+#include <iotcon-types.h>
 
 /**
  * @file iotcon-lite-resource.h
@@ -26,17 +26,110 @@
  * @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.\n
- * This API provides that the users manages resources, simply.
+ * @brief Iotcon Lite Resource provides API to encapsulate resources.
  *
- * @section CAPI_IOT_CONNECTIVITY_SERVER_LITE_RESOURCE_MODULE_HEADER Header
+ * @section CAPI_IOT_CONNECTIVITY_SERVER_LITE_RESOURCE_MODULE_HEADER Required Header
  *  \#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 state by iotcon_lite_update_state(), changes will notify to observers.
+ *
+ * Example :
+ * @code
+#include <iotcon.h>
+...
+static iotcon_lite_resource_h _resource;
+
+static void _create_light_resource()
+{
+       int ret;
+       iotcon_lite_resource_h resource = NULL;
+       iotcon_resource_types_h resource_types = NULL;
+       iotcon_state_h state = NULL;
+
+       ret = iotcon_resource_types_create(&resource_types);
+       if (IOTCON_ERROR_NONE != ret)
+               return;
+
+       ret = iotcon_resource_types_add(resource_types, "org.tizen.light");
+       if (IOTCON_ERROR_NONE != ret) {
+               iotcon_resource_types_destroy(resource_types);
+               return;
+       }
+
+       ret = iotcon_state_create(&state);
+       if (IOTCON_ERROR_NONE != ret) {
+               iotcon_resource_types_destroy(resource_types);
+               return;
+       }
+
+       ret = iotcon_state_add_bool(state, "power", true);
+       if (IOTCON_ERROR_NONE != ret) {
+               iotcon_state_destroy(state);
+               iotcon_resource_types_destroy(resource_types);
+               return;
+       }
+
+       ret = iotcon_state_add_int(state, "brightness", 75);
+       if (IOTCON_ERROR_NONE != ret) {
+               iotcon_state_destroy(state);
+               iotcon_resource_types_destroy(resource_types);
+               return;
+       }
+
+       ret = iotcon_lite_resource_create("/light/1", resource_types,
+                       IOTCON_RESOURCE_DISCOVERABLE | IOTCON_RESOURCE_OBSERVABLE, state, &resource);
+       if (IOTCON_ERROR_NONE != ret) {
+               iotcon_state_destroy(state);
+               iotcon_resource_types_destroy(resource_types);
+               return;
+       }
+
+       iotcon_state_destroy(state);
+       iotcon_resource_types_destroy(resource_types);
+
+       _resource = resource;
+}
+
+static void _update_brightness(int brightness)
+{
+       int ret;
+       iotcon_state_h state = NULL;
+       iotcon_state_h state_clone = NULL;
+
+       ret = iotcon_lite_resource_get_state(_resource, &state);
+       if (IOTCON_ERROR_NONE != ret)
+               return;
+
+       ret = iotcon_state_clone(state, &state_clone);
+       if (IOTCON_ERROR_NONE != ret)
+               return;
+
+       ret = iotcon_state_add_int(state_clone, "brightness", brightness);
+       if (IOTCON_ERROR_NONE != ret) {
+               iotcon_state_destroy(state_clone);
+               return;
+       }
+
+       ret = iotcon_lite_resource_update_state(_resource, state_clone);
+       if (IOTCON_ERROR_NONE != ret) {
+               iotcon_state_destroy(state_clone);
+               return;
+       }
+
+       iotcon_state_destroy(state_clone);
+}
+
+ * @endcode
+ *
  * @{
  */
 
 /**
- * @brief Create a lite resource handle and registers the resource in server
+ * @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 state which have
  * @a properties in Iotcon server.\n
  * When client requests some operations, it send a response to client, automatically.\n
@@ -46,8 +139,8 @@
  * @privilege %http://tizen.org/privilege/internet
  *
  * @remarks @a uri_path length must be less than or equal 36.\n
- * You must unregister resource by calling iotcon_resource_destroy()
- * if resource is no longer needed.
+ * 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.
@@ -74,7 +167,7 @@ int iotcon_lite_resource_create(const char *uri_path,
                iotcon_lite_resource_h *resource_handle);
 
 /**
- * @brief Destroy the resource and releases its data.
+ * @brief Destroys the resource and releases its data.
  *
  * @since_tizen 3.0
  * @privlevel public
@@ -97,7 +190,7 @@ int iotcon_lite_resource_create(const char *uri_path,
 int iotcon_lite_resource_destroy(iotcon_lite_resource_h resource);
 
 /**
- * @brief Update state into the lite resource handle
+ * @brief Updates state into the lite resource handle
  *
  * @since_tizen 3.0
  *
@@ -115,10 +208,12 @@ int iotcon_lite_resource_update_state(iotcon_lite_resource_h resource,
                iotcon_state_h state);
 
 /**
- * @brief Get state from the lite resource handle
+ * @brief Gets state from the lite resource handle
  *
  * @since_tizen 3.0
  *
+ * @remarks @a state must not be released using iotcon_state_destroy().
+ *
  * @param[in] resource The handle of the lite resource
  * @param[out] state The state handle of the lite resource
  *