include/data-control-map.h

   1 //
   2 // Copyright (c) 2013 Samsung Electronics Co., Ltd.
   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
  17 /**
  18  * @file        data-control-map.h
  19  * @brief       This is the header file for the key-value structured data control.
  20  */
  21
  22 #ifndef _APPFW_DATA_CONTROL_MAP_H_
  23 #define _APPFW_DATA_CONTROL_MAP_H_
  24
  25 #include <data-control-types.h>
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31
  32 /**
  33  * @brief               Called when the result value list is received from the key-value structured data control provider.
  34  *
  35  * @param [in]  request_id      The request ID
  36  * @param [in]  provider                The provider handle
  37  * @param [in]  result_value_list       The result value list of the data control request that gets the matching values
  38  * @param [in]  result_value_count      The number of the values
  39  * @param [in]  provider_result Set to true if the data control provider successfully processed. @n
  40  *                                                              false otherwise.
  41  * @param [in]  error           The error message from the data control provider
  42  * @param [in]  user_data       The user data passed from the register function
  43  */
  44 typedef void (*datacontrol_map_get_response_cb)(int request_id, datacontrol_h provider,
  45                 char ** result_value_list, int result_value_count, bool provider_result, const char *error, void *user_data);
  46
  47 /**
  48  * @brief               Called when the response is received from the key-value structured data control provider.
  49  *
  50  * @param [in]  request_id      The request ID that identifies the data control
  51  * @param [in]  provider                The provider handle
  52  * @param [in]  provider_result Set to true if the data control provider successfully processed. @n
  53  *                                                              false otherwise.
  54  * @param [in]  error           The error message from the data control provider
  55  * @param [in]  user_data       The user data passed from the register function
  56  */
  57 typedef void (*datacontrol_map_set_response_cb)(int request_id, datacontrol_h provider,
  58                 bool provider_result, const char *error, void *user_data);
  59
  60 /**
  61  * @brief               Called when the response is received from the key-value structured data control provider.
  62  *
  63  * @param [in]  request_id      The request ID that identifies the data control
  64  * @param [in]  provider                The provider handle
  65  * @param [in]  provider_result Set to true if the data control provider successfully processed. @n
  66  *                                                              false otherwise.
  67  * @param [in]  error           The error message from the data control provider
  68  * @param [in]  user_data       The user data passed from the register function
  69  */
  70 typedef void (*datacontrol_map_add_response_cb)(int request_id, datacontrol_h provider,
  71                 bool provider_result, const char *error, void *user_data);
  72
  73 /**
  74  * @brief               Called when the response is received from the key-value structured data control provider.
  75  *
  76  * @param [in]  request_id      The request ID that identifies the data control
  77  * @param [in]  provider                The provider handle
  78  * @param [in]  provider_result Set to true if the data control provider successfully processed. @n
  79  *                                                              false otherwise.
  80  * @param [in]  error           The error message from the data control provider
  81  * @param [in]  user_data       The user data passed from the register function
  82  */
  83 typedef void (*datacontrol_map_remove_response_cb)(int request_id, datacontrol_h provider,
  84                 bool provider_result, const char *error, void *user_data);
  85
  86 /**
  87  * @brief               The structure type to contain the set of callback functions for handling the response events
  88  *                      of the key-value structured data control.
  89  * @see         datacontrol_map_get_response_cb()
  90  * @see         datacontrol_map_set_response_cb()
  91  * @see         datacontrol_map_add_response_cb()
  92  * @see         datacontrol_map_remove_response_cb()
  93  */
  94 typedef struct
  95 {
  96         datacontrol_map_get_response_cb get;
  97         datacontrol_map_set_response_cb set;
  98         datacontrol_map_add_response_cb add;
  99         datacontrol_map_remove_response_cb remove;
 100 } datacontrol_map_response_cb;
 101
 102 /**
 103  * @brief               Creates a provider handle.
 104  * @param [out] provider        The provider handle
 105  * @return              0 on success, otherwise a negative error value.
 106  * @retval #DATACONTROL_ERROR_NONE      Successful
 107  * @retval #DATACONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 108  * @retval #DATACONTROL_ERROR_OUT_OF_MEMORY Out of memory
 109  * @see datacontrol_map_destroy()
 110  *
 111  * The following example demonstrates how to use the %datacontrol_map_create() method.
 112  *
 113  * @code
 114  *
 115  *      int main()
 116  *      {
 117  *              const char *provider_id = "http://tizen.org/datacontrol/provider/example";
 118  *              const char *data_id = "table";
 119  *              datacontrol_h provider;
 120  *              int result = 0;
 121  *
 122  *              result = datacontrol_map_create(&provider);
 123  *              if (result != DATACONTROL_ERROR_NONE) {
 124  *                      dlog_print(DLOG_ERROR, LOG_TAG, "Creating data control provider is failed with error: %d", result);
 125  *                      return result;
 126  *              }
 127  *
 128  *              result = datacontrol_map_set_provider_id(provider, provider_id);
 129  *              if (result != DATACONTROL_ERROR_NONE) {
 130  *                      dlog_print(DLOG_ERROR, LOG_TAG, "Setting providerID is failed with error: %d", result);
 131  *                      return result;
 132  *              }
 133  *
 134  *              result = datacontrol_map_set_data_id(provider, data_id);
 135  *              if (result != DATACONTROL_ERROR_NONE) {
 136  *                      dlog_print(DLOG_ERROR, LOG_TAG, "Setting dataID is failed with error: %d", result);
 137  *                      return result;
 138  *              }
 139  *
 140  *              // Executes some operations
 141  *
 142  *              result = datacontrol_map_destroy(provider);
 143  *              if (result != DATACONTROL_ERROR_NONE) {
 144  *                      dlog_print(DLOG_ERROR, LOG_TAG, "Destorying data control provider is failed with error: %d", result);
 145  *              }
 146  *
 147  *              return result;
 148  *      }
 149  *
 150  * @endcode
 151  */
 152 EXPORT_API int datacontrol_map_create(datacontrol_h *provider);
 153
 154 /**
 155  * @brief               Destroys the provider handle and releases all its resources.
 156  * @param [in]  provider        The provider handle
 157  * @return              0 on success, otherwise a negative error value.
 158  * @remark      When operations of data control are finished, this function must be called to prevent memory leak.
 159  * @see datacontrol_map_create()
 160  */
 161 EXPORT_API int datacontrol_map_destroy(datacontrol_h provider);
 162
 163 /**
 164  * @brief               Sets the Provider ID.
 165  * @param [in]  provider        The provider handle
 166  * @param [in]  provider_id      The data control provider ID
 167  * @return              0 on success, otherwise a negative error value.
 168  * @retval #DATACONTROL_ERROR_NONE      Successful
 169  * @retval #DATACONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 170  * @retval #DATACONTROL_ERROR_OUT_OF_MEMORY Out of memory
 171  * @see datacontrol_map_get_provider_id()
 172  */
 173 EXPORT_API int datacontrol_map_set_provider_id(datacontrol_h provider, const char *provider_id);
 174
 175 /**
 176  * @brief               Gets the Provider ID.
 177  * @param [in]  provider        The provider handle
 178  * @param [out] provider_id      The data control provider ID
 179  * @return              0 on success, otherwise a negative error value.
 180  * @retval #DATACONTROL_ERROR_NONE      Successful
 181  * @retval #DATACONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 182  * @retval #DATACONTROL_ERROR_OUT_OF_MEMORY Out of memory
 183  * @see datacontrol_map_set_provider_id()
 184  */
 185 EXPORT_API int datacontrol_map_get_provider_id(datacontrol_h provider, char **provider_id);
 186
 187 /**
 188  * @brief               Sets the Data ID.
 189  * @param [in]  provider        The provider handle
 190  * @param [in]  data_id A string for identifying a specific table to operate. @n
 191  *                                              The string consists of one or more components separated by a slash('/').
 192  * @return              0 on success, otherwise a negative error value.
 193  * @retval #DATACONTROL_ERROR_NONE      Successful
 194  * @retval #DATACONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 195  * @retval #DATACONTROL_ERROR_OUT_OF_MEMORY Out of memory
 196  * @see datacontrol_map_get_data_id()
 197  */
 198 EXPORT_API int datacontrol_map_set_data_id(datacontrol_h provider, const char *data_id);
 199
 200 /**
 201  * @brief               Gets the Data ID.
 202  * @param [in]  provider        The provider handle
 203  * @param [out] data_id A string for identifying a specific table to operate. @n
 204  *                                              The string consists of one or more components separated by a slash('/').
 205  * @return              0 on success, otherwise a negative error value.
 206  * @retval #DATACONTROL_ERROR_NONE      Successful
 207  * @retval #DATACONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 208  * @retval #DATACONTROL_ERROR_OUT_OF_MEMORY Out of memory
 209  * @see datacontrol_map_set_data_id()
 210  */
 211 EXPORT_API int datacontrol_map_get_data_id(datacontrol_h provider, char **data_id);
 212
 213 /**
 214  * @brief               Registers a callback function for the key-value structured data control response. @n
 215  *                              The application is notified when a data control response is received from the @c provider.
 216  * @param [in]  provider        The provider handle
 217  * @param [in]  callback        The callback function to be called when a response is received.
 218  * @param [in]  user_data       The user data to be passed to the callback function
 219  * @return              0 on success, otherwise a negative error value.
 220  * @retval #DATACONTROL_ERROR_NONE      Successful
 221  * @retval #DATACONTROL_ERROR_IO_ERROR I/O error
 222  * @retval #DATACONTROL_ERROR_OUT_OF_MEMORY Out of memory
 223  * @see datacontrol_map_unregister_response_cb()
 224  */
 225 EXPORT_API int datacontrol_map_register_response_cb(datacontrol_h provider, datacontrol_map_response_cb* callback, void *user_data);
 226
 227 /**
 228  * @brief               Unregisters the callback function in @c provider.
 229  * @param [in]  provider        The provider handle
 230  * @return              0 on success, otherwise a negative error value.
 231  */
 232 EXPORT_API int datacontrol_map_unregister_response_cb(datacontrol_h provider);
 233
 234 /**
 235  * @brief               Gets the value list associated with the specified @c key from the key-values map owned by the key-value structured data control provider.
 236  *
 237  * @param [in]  provider        The provider handle
 238  * @param [in]  key             The key of the value list to obtain
 239  * @param [out] request_id      The request ID
 240  * @return              0 on success, otherwise a negative error value.
 241  * @retval #DATACONTROL_ERROR_NONE      Successful
 242  * @retval #DATACONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 243  * @retval #DATACONTROL_ERROR_IO_ERROR I/O error
 244  * @retval #DATACONTROL_ERROR_OUT_OF_MEMORY Out of memory
 245  * @retval #DATACONTROL_ERROR_MAX_EXCEEDED Too long argument
 246  *
 247  * The following example demonstrates how to use the %datacontrol_map_get() method.
 248  *
 249  * @code
 250  *
 251  *      void map_get_response_cb(int request_id, datacontrol_h provider,
 252  *                      char **result_value_list, int result_value_count, bool provider_result, const char *error)
 253  *      {
 254  *              if (provider_result) {
 255  *                      dlog_print(DLOG_INFO, LOG_TAG, "The get operation is successful");
 256  *              }
 257  *              else {
 258  *                      dlog_print(DLOG_INFO, LOG_TAG, "The get operation for the request %d is failed. error message: %s", request_id, error);
 259  *              }
 260  *      }
 261  *
 262  *      datacontrol_map_response_cb map_callback;
 263  *
 264  *      int main()
 265  *      {
 266  *              int result = 0;
 267  *              int req_id = 0;
 268  *              char *key = "key";
 269  *
 270  *              map_callback.get = map_get_response_cb;
 271  *              result = datacontrol_map_register_response_cb(provider, &map_callback);
 272  *              if (result != DATACONTROL_ERROR_NONE) {
 273  *                      dlog_print(DLOG_ERROR, LOG_TAG, "Registering the callback function is failed with error: %d", result);
 274  *                      return result;
 275  *              }
 276  *
 277  *              result = datacontrol_map_get(provider, key, &req_id);
 278  *              if (result != DATACONTROL_ERROR_NONE) {
 279  *                      dlog_print(DLOG_ERROR, LOG_TAG, "Getting the value list of the key(%s) is failed with error: %d", key, result);
 280  *              }
 281  *              else {
 282  *                      dlog_print(DLOG_INFO, LOG_TAG, "req_id is %d", req_id);
 283  *              }
 284  *
 285  *              return result;
 286  *      }
 287  *
 288  * @endcode
 289  */
 290 EXPORT_API int datacontrol_map_get(datacontrol_h provider, const char *key, int *request_id);
 291
 292 /**
 293  * @brief               Gets the value list associated with the specified @c key from the key-values map owned by the key-value structured data control provider.
 294  *
 295  * @param [in]  provider        The provider handle
 296  * @param [in]  key             The key of the value list to obtain
 297  * @param [out] request_id      The request ID
 298  * @param [in]  page_number             The page number of the value set @n
 299  *                                                              It starts from 1.
 300  * @param [in]  count_per_page  The desired maximum count of the data items per page
 301  * @return              0 on success, otherwise a negative error value.
 302  * @retval #DATACONTROL_ERROR_NONE      Successful
 303  * @retval #DATACONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 304  * @retval #DATACONTROL_ERROR_IO_ERROR I/O error
 305  * @retval #DATACONTROL_ERROR_OUT_OF_MEMORY Out of memory
 306  * @retval #DATACONTROL_ERROR_MAX_EXCEEDED Too long argument
 307  */
 308 EXPORT_API int datacontrol_map_get_with_page(datacontrol_h provider, const char *key, int *request_id, int page_number, int count_per_page);
 309
 310 /**
 311  * @brief               Sets the value associated with the specified @c key to a new value.
 312  *
 313  * @param [in]  provider        The provider handle
 314  * @param [in]  key             The key of the value to replace
 315  * @param [in]  old_value               The value to replace
 316  * @param [in]  new_value       The new value that replaces the existing value
 317  * @param [out] request_id      The request ID
 318  * @return              0 on success, otherwise a negative error value.
 319  * @retval #DATACONTROL_ERROR_NONE      Successful
 320  * @retval #DATACONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 321  * @retval #DATACONTROL_ERROR_IO_ERROR I/O error
 322  * @retval #DATACONTROL_ERROR_OUT_OF_MEMORY Out of memory
 323  * @retval #DATACONTROL_ERROR_MAX_EXCEEDED Too long argument
 324  *
 325  * The following example demonstrates how to use the %datacontrol_map_set() method.
 326  *
 327  * @code
 328  *
 329  *      void map_set_response_cb(int request_id, datacontrol_h provider, bool provider_result, const char *error)
 330  *      {
 331  *              if (provider_result) {
 332  *                      dlog_print(DLOG_INFO, LOG_TAG, "The set operation is successful");
 333  *              }
 334  *              else {
 335  *                      dlog_print(DLOG_INFO, LOG_TAG, "The set operation for the request %d is failed. error message: %s", request_id, error);
 336  *              }
 337  *      }
 338  *
 339  *      datacontrol_map_response_cb map_callback;
 340  *
 341  *      int main()
 342  *      {
 343  *              int result = 0;
 344  *              int req_id = 0;
 345  *              char *key = "key";
 346  *              char *old_value = "old value";
 347  *              char *new_value = "new value";
 348  *
 349  *              map_callback.set = map_set_response_cb;
 350  *              result = datacontrol_map_register_response_cb(provider, &map_callback);
 351  *              if (result != DATACONTROL_ERROR_NONE) {
 352  *                      dlog_print(DLOG_ERROR, LOG_TAG, "Registering the callback function is failed with error: %d", result);
 353  *                      return result;
 354  *              }
 355  *
 356  *              result = datacontrol_map_set(provider, key, old_value, new_value, &req_id);
 357  *              if (result != DATACONTROL_ERROR_NONE) {
 358  *                      dlog_print(DLOG_ERROR, LOG_TAG, "Replacing old_value(%s) with new_value(%s) is failed with error: %d", old_value, new_value, result);
 359  *              }
 360  *              else {
 361  *                      dlog_print(DLOG_INFO, LOG_TAG, "req_id is %d", req_id);
 362  *              }
 363  *
 364  *              return result;
 365  *      }
 366  *
 367  * @endcode
 368  */
 369 EXPORT_API int datacontrol_map_set(datacontrol_h provider, const char *key, const char *old_value, const char *new_value, int *request_id);
 370
 371 /**
 372  * @brief               Adds the @c value associated with the specified @c key to the key-values map owned by the key-value structured data control provider.
 373  *
 374  * @param [in]  provider        The provider handle
 375  * @param [in]  key             The key of the value to add
 376  * @param [in]  value           The value to add
 377  * @param [out] request_id      The request ID
 378  * @return              0 on success, otherwise a negative error value.
 379  * @retval #DATACONTROL_ERROR_NONE      Successful
 380  * @retval #DATACONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 381  * @retval #DATACONTROL_ERROR_IO_ERROR I/O error
 382  * @retval #DATACONTROL_ERROR_OUT_OF_MEMORY Out of memory
 383  * @retval #DATACONTROL_ERROR_MAX_EXCEEDED Too long argument
 384  *
 385  * The following example demonstrates how to use the %datacontrol_map_add() method.
 386  *
 387  * @code
 388  *
 389  *      void map_add_response_cb(int request_id, datacontrol_h provider, bool provider_result, const char *error) {
 390  *              if (provider_result) {
 391  *                      dlog_print(DLOG_INFO, LOG_TAG, "The add operation is successful");
 392  *              }
 393  *              else {
 394  *                      dlog_print(DLOG_INFO, LOG_TAG, "The add operation for the request %d is failed. error message: %s", request_id, error);
 395  *              }
 396  *      }
 397  *
 398  *      datacontrol_map_response_cb map_callback;
 399  *
 400  *      int main()
 401  *      {
 402  *              int result = 0;
 403  *              int req_id = 0;
 404  *              const char *key = "key";
 405  *              const char *value = "value";
 406  *
 407  *              map_callback.add = map_add_response_cb;
 408  *              result = datacontrol_map_register_response_cb(provider, &map_callback);
 409  *              if (result != DATACONTROL_ERROR_NONE) {
 410  *                      dlog_print(DLOG_ERROR, LOG_TAG, "Registering the callback function is failed with error: %d", result);
 411  *                      return result;
 412  *              }
 413  *
 414  *              result = datacontrol_map_add(provider, key, value, &req_id);
 415  *              if (result != DATACONTROL_ERROR_NONE) {
 416  *                      dlog_print(DLOG_ERROR, LOG_TAG, "Adding %s-%s pair is failed with error: %d", key, value, result);
 417  *              }
 418  *              else {
 419  *                      dlog_print(DLOG_INFO, LOG_TAG, "req_id is %d", req_id);
 420  *              }
 421  *
 422  *              return result;
 423  *      }
 424  *
 425  * @endcode
 426  */
 427 EXPORT_API int datacontrol_map_add(datacontrol_h provider, const char *key, const char *value, int *request_id);
 428
 429 /**
 430  * @brief               Removes the @c value associated with the specified @c key from the key-values map owned by the key-value structured data control provider.
 431  *
 432  * @param [in]  provider        The provider handle
 433  * @param [in]  key             The key of the value to remove
 434  * @param [in]  value           The value to remove
 435  * @param [out] request_id      The request ID
 436  * @return              0 on success, otherwise a negative error value.
 437  * @retval #DATACONTROL_ERROR_NONE      Successful
 438  * @retval #DATACONTROL_ERROR_INVALID_PARAMETER Invalid parameter
 439  * @retval #DATACONTROL_ERROR_IO_ERROR I/O error
 440  * @retval #DATACONTROL_ERROR_OUT_OF_MEMORY Out of memory
 441  * @retval #DATACONTROL_ERROR_MAX_EXCEEDED Too long argument
 442  *
 443  * The following example demonstrates how to use the %datacontrol_map_remove() method.
 444  *
 445  * @code
 446  *
 447  *      void map_remove_response_cb(int request_id, datacontrol_h provider, bool provider_result, const char *error) {
 448  *              if (provider_result) {
 449  *                      dlog_print(DLOG_INFO, LOG_TAG, "The remove operation is successful");
 450  *              }
 451  *              else {
 452  *                      dlog_print(DLOG_INFO, LOG_TAG, "The remove operation for the request %d is failed. error message: %s", request_id, error);
 453  *              }
 454  *      }
 455  *
 456  *      datacontrol_map_response_cb map_callback;
 457  *
 458  *      int main()
 459  *      {
 460  *              int result = 0;
 461  *              int req_id = 0;
 462  *              const char *key = "key";
 463  *              const char *value = "value";
 464  *
 465  *              ...
 466  *
 467  *              map_callback.remove = map_remove_response_cb;
 468  *              result = datacontrol_map_register_response_cb(provider, &map_callback);
 469  *              if (result != DATACONTROL_ERROR_NONE) {
 470  *                      dlog_print(DLOG_ERROR, LOG_TAG, "Registering the callback function is failed with error: %d", result);
 471  *                      return result;
 472  *              }
 473  *
 474  *              result = datacontrol_map_remove(provider, key, value, &req_id);
 475  *              if (result != DATACONTROL_ERROR_NONE) {
 476  *                      dlog_print(DLOG_ERROR, LOG_TAG, "Removing %s-%s pair is failed with error: %d", key, value, result);
 477  *              }
 478  *              else {
 479  *                      dlog_print(DLOG_INFO, LOG_TAG, "req_id is %d", req_id);
 480  *              }
 481  *
 482  *              return result;
 483  *      }
 484  *
 485  * @endcode
 486  */
 487 EXPORT_API int datacontrol_map_remove(datacontrol_h provider, const char *key, const char *value, int *request_id);
 488
 489 #ifdef __cplusplus
 490 }
 491 #endif
 492
 493 #endif /* _APPFW_DATA_CONTROL_MAP_H_ */
 494