lib/include/iotcon-lite-resource.h

   1 /*
   2  * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 #ifndef __IOT_CONNECTIVITY_MANAGER_SERVER_LITE_RESOURCE_H__
  17 #define __IOT_CONNECTIVITY_MANAGER_SERVER_LITE_RESOURCE_H__
  18
  19 #include <iotcon-types.h>
  20
  21 /**
  22  * @file iotcon-lite-resource.h
  23  */
  24
  25 /**
  26  * @ingroup CAPI_IOT_CONNECTIVITY_SERVER_MODULE
  27  * @defgroup CAPI_IOT_CONNECTIVITY_SERVER_LITE_RESOURCE_MODULE Lite Resource
  28  *
  29  * @brief Iotcon Lite Resource provides API to encapsulate resources.
  30  *
  31  * @section CAPI_IOT_CONNECTIVITY_SERVER_LITE_RESOURCE_MODULE_OVERVIEW Overview
  32  * This API provides that the users manages resources without request handler.
  33  * When client request by CRUD functions, internal default request handler will be invoked.
  34  * The default request handler will create response and send to client automatically.
  35  * When updated state by iotcon_lite_update_state(), changes will notify to observers.
  36  *
  37  * @section CAPI_IOT_CONNECTIVITY_SERVER_LITE_RESOURCE_MODULE_HEADER Header
  38  *  \#include <iotcon.h>
  39  *
  40  * @{
  41  */
  42
  43 /**
  44  * @brief Creates a lite resource handle and registers the resource in server
  45  * @details Registers a resource specified by @a uri_path, @a res_types, @a state which have
  46  * @a properties in Iotcon server.\n
  47  * When client requests some operations, it send a response to client, automatically.\n
  48  *
  49  * @since_tizen 3.0
  50  * @privlevel public
  51  * @privilege %http://tizen.org/privilege/internet
  52  *
  53  * @remarks @a uri_path length must be less than or equal 36.\n
  54  * You must destroy @a resource_handle by calling iotcon_lite_resource_destroy()
  55  * if @a remote_handle is no longer needed.
  56  *
  57  * @param[in] uri_path The URI path of the resource.
  58  * @param[in] res_types The list of type of the resource.
  59  * @param[in] properties The property of the resource.
  60  * @param[in] state The state handle to set.
  61  * @param[out] resource_handle The handle of the resource
  62  *
  63  * @return 0 on success, otherwise a negative error value.
  64  * @retval #IOTCON_ERROR_NONE  Successful
  65  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
  66  * @retval #IOTCON_ERROR_IOTIVITY  Iotivity errors
  67  * @retval #IOTCON_ERROR_DBUS  Dbus errors
  68  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
  69  * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied
  70  *
  71  * @post When the resource receive CRUD request, iotcon_request_handler_cb() will be called.
  72  *
  73  * @see iotcon_lite_resource_destroy()
  74  */
  75 int iotcon_lite_resource_create(const char *uri_path,
  76                 iotcon_resource_types_h res_types,
  77                 int properties,
  78                 iotcon_state_h state,
  79                 iotcon_lite_resource_h *resource_handle);
  80
  81 /**
  82  * @brief Destroys the resource and releases its data.
  83  *
  84  * @since_tizen 3.0
  85  * @privlevel public
  86  * @privilege %http://tizen.org/privilege/internet
  87  *
  88  * @remarks When a normal variable is used, there are only dbus error and permission\n
  89  * denied error. If the errors of this API are not handled, then you must check\n
  90  * whether dbus is running and an application have the privileges for the API.
  91  *
  92  * @param[in] resource The handle of the lite resource to be unregistered
  93  *
  94  * @return 0 on success, otherwise a negative error value.
  95  * @retval #IOTCON_ERROR_NONE  Successful
  96  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
  97  * @retval #IOTCON_ERROR_DBUS  Dbus error
  98  * @retval #IOTCON_ERROR_PERMISSION_DENIED Permission denied
  99  *
 100  * @see iotcon_lite_resource_create()
 101  */
 102 int iotcon_lite_resource_destroy(iotcon_lite_resource_h resource);
 103
 104 /**
 105  * @brief Updates state into the lite resource handle
 106  *
 107  * @since_tizen 3.0
 108  *
 109  * @param[in] resource The handle of the lite resource
 110  * @param[in] state The state handle to update
 111  *
 112  * @return 0 on success, otherwise a negative error value.
 113  * @retval #IOTCON_ERROR_NONE  Successful
 114  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 115  * @retval #IOTCON_ERROR_OUT_OF_MEMORY  Out of memory
 116  *
 117  * @see iotcon_lite_resource_get_state()
 118  */
 119 int iotcon_lite_resource_update_state(iotcon_lite_resource_h resource,
 120                 iotcon_state_h state);
 121
 122 /**
 123  * @brief Gets state from the lite resource handle
 124  *
 125  * @since_tizen 3.0
 126  *
 127  * @remarks @a state must not be released using iotcon_state_destroy().
 128  *
 129  * @param[in] resource The handle of the lite resource
 130  * @param[out] state The state handle of the lite resource
 131  *
 132  * @return 0 on success, otherwise a negative error value.
 133  * @retval #IOTCON_ERROR_NONE  Successful
 134  * @retval #IOTCON_ERROR_INVALID_PARAMETER  Invalid parameter
 135  *
 136  * @see iotcon_lite_resource_update_state()
 137  */
 138 int iotcon_lite_resource_get_state(iotcon_lite_resource_h resource,
 139                 iotcon_state_h *state);
 140
 141 /**
 142  * @}
 143  */
 144
 145 #endif /* __IOT_CONNECTIVITY_MANAGER_SERVER_LITE_RESOURCE_H__ */