include/utility/fw_ref.h

   1 /*
   2  * sync-agent
   3  * Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the License);
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17
  18 #ifndef FW_REF_H_
  19 #define FW_REF_H_
  20
  21 #include <stdbool.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif                          /* __cplusplus */
  26
  27 /**
  28  * @file fw_ref.h
  29  * @brief Provides conversion service from regular object to referenced object
  30  */
  31
  32 /** @addtogroup utility
  33  *      @{
  34  */
  35
  36 /**
  37  * Function which is called when need to alloc some object
  38  *
  39  * @return object to alloc on success, NULL on error
  40  *
  41  * @par Since:
  42  *
  43  *
  44  * @see
  45  *
  46  */
  47         typedef void *(*sync_agent_alloc_cb) (void);
  48
  49 /**
  50  * Function which is called when need to free some object
  51  *
  52  * @param[in] void* object to free
  53  *
  54  * @par Since:
  55  *
  56  *
  57  * @see sync_agent_create_referenced_object(void *, sync_agent_free_cb)
  58  *
  59  */
  60         typedef void (*sync_agent_free_cb) (void *);
  61
  62 /**
  63  * Structure of referenced object
  64  */
  65         typedef struct utility_ref_object {
  66                 int refcount;           /**< Reference count */
  67                 void *data;             /**< Void pointer for original regular object */
  68                 sync_agent_free_cb free_func;
  69                                      /**< Free function */
  70         } sync_agent_util_ref_object_s;
  71
  72 /**
  73  * API to create referenced object using given data with void pointer and function pointer for free logic
  74  *
  75  * @par Usage:
  76  * @code
  77                 void data_free_cb(void *data)
  78                 {
  79                 }
  80                 ...
  81                 void *data = NULL;
  82                 ...
  83                 sync_agent_util_ref_object_s *ref_obj = sync_agent_create_referenced_object(data, data_free_cb);
  84                 if (ref_obj == NULL) {
  85                         // error handling
  86                         ...
  87                 }
  88  *
  89  * @endcode
  90  *
  91  * @param[in] data data to maintain reference information for
  92  * @param[in] data_free_func function pointer for free logic
  93  *
  94  * @return referenced object in sync_agent_util_ref_object_s type of structure on success, NULL on error
  95  *
  96  * @par Since:
  97  *
  98  *
  99  * @see sync_agent_create_referenced_object(void *, sync_agent_free_cb)
 100  *
 101  */
 102         sync_agent_util_ref_object_s *sync_agent_create_referenced_object(void *data, sync_agent_free_cb data_free_func);
 103
 104 /**
 105  * API to return referenced object using already referenced object and just increase reference count
 106  *
 107  * @par Usage:
 108  * @code
 109                 sync_agent_util_ref_object_s *object = NULL;
 110                 ...
 111                 sync_agent_util_ref_object_s *ref_obj = sync_agent_get_referenced_object(object);
 112                 if (ref_obj == NULL) {
 113                         // error handling
 114                         ...
 115                 }
 116  *
 117  * @endcode
 118  *
 119  * @param[in] object referenced object to increase reference count by 1
 120  *
 121  * @return referenced object in sync_agent_util_ref_object_s type of structure on success, NULL on error
 122  *
 123  * @par Since:
 124  *
 125  *
 126  * @see sync_agent_get_referenced_object(sync_agent_util_ref_object_s *)
 127  *
 128  */
 129         sync_agent_util_ref_object_s *sync_agent_get_referenced_object(sync_agent_util_ref_object_s * object);
 130
 131 /**
 132  * API to return original object taking from referenced object
 133  *
 134  * @par Usage:
 135  * @code
 136                 sync_agent_util_ref_object_s *ref_obj = NULL;
 137                 ...
 138                 void *origin_obj = sync_agent_get_original_object(ref_obj);
 139  *
 140  * @endcode
 141  *
 142  * @param[in] object referenced object
 143  *
 144  * @return original object
 145  *
 146  * @par Since:
 147  *
 148  *
 149  * @see sync_agent_get_original_object(sync_agent_util_ref_object_s *)
 150  *
 151  */
 152         void *sync_agent_get_original_object(sync_agent_util_ref_object_s * object);
 153
 154 /**
 155  * API to compares if two referenced object has same original object
 156  *
 157  * @par Usage:
 158  * @code
 159                 sync_agent_util_ref_object_s *obj1 = NULL;
 160                 sync_agent_util_ref_object_s *obj2 = NULL;
 161                 ...
 162                 bool is_same = sync_agent_compare_object(obj1, obj2);
 163                 if (is_same) {
 164                         // same case
 165                         ...
 166                 } else {
 167                         // different case
 168                         ...
 169                 }
 170  *
 171  * @endcode
 172  *
 173  * @param[in] object1 referenced object to compare with
 174  * @param[in] object2 referenced object to compare with
 175  *
 176  * @return 1 when two are same, otherwise 0
 177  *
 178  * @par Since:
 179  *
 180  *
 181  * @see sync_agent_compare_object(sync_agent_util_ref_object_s *, sync_agent_util_ref_object_s *)
 182  *
 183  */
 184         bool sync_agent_compare_object(sync_agent_util_ref_object_s * object1, sync_agent_util_ref_object_s * object2);
 185
 186 /**
 187  * API to decrease reference count of given referenced object
 188  * The object will be freed in case reference count becomes 0
 189  *
 190  * @par Usage:
 191  * @code
 192                 sync_agent_util_ref_object_s *ref_obj = NULL;
 193                 ...
 194                 if (ref_obj != NULL) {
 195                         sync_agent_unref_referenced_object(ref_obj);
 196                 }
 197  *
 198  * @endcode
 199  *
 200  * @param[in] ref referenced object to decrease ref count by 1
 201  *
 202  * @par Since:
 203  *
 204  *
 205  * @see sync_agent_unref_referenced_object(sync_agent_util_ref_object_s *)
 206  *
 207  */
 208         void sync_agent_unref_referenced_object(sync_agent_util_ref_object_s * ref);
 209
 210 /**
 211  *      @}
 212  */
 213
 214 #ifdef __cplusplus
 215 }
 216 #endif                          /* __cplusplus */
 217 #endif                          /* FW_REF_H_ */