2 // Copyright (c) 2013 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file data-control-map.h
19 * @brief This is the header file for the key-value structured data control.
22 #ifndef _APPFW_DATA_CONTROL_MAP_H_
23 #define _APPFW_DATA_CONTROL_MAP_H_
25 #include <data-control-types.h>
33 * @brief Called when the result value list is received from the key-value structured data control provider.
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
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
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);
48 * @brief Called when the response is received from the key-value structured data control provider.
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
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
57 typedef void (*datacontrol_map_set_response_cb)(int request_id, datacontrol_h provider,
58 bool provider_result, const char *error, void *user_data);
61 * @brief Called when the response is received from the key-value structured data control provider.
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
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
70 typedef void (*datacontrol_map_add_response_cb)(int request_id, datacontrol_h provider,
71 bool provider_result, const char *error, void *user_data);
74 * @brief Called when the response is received from the key-value structured data control provider.
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
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
83 typedef void (*datacontrol_map_remove_response_cb)(int request_id, datacontrol_h provider,
84 bool provider_result, const char *error, void *user_data);
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()
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;
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()
111 * The following example demonstrates how to use the %datacontrol_map_create() method.
117 * const char *provider_id = "http://tizen.org/datacontrol/provider/example";
118 * const char *data_id = "table";
119 * datacontrol_h provider;
122 * result = datacontrol_map_create(&provider);
123 * if (result != DATACONTROL_ERROR_NONE) {
124 * LOGE("Creating data control provider is failed with error: %d", result);
128 * result = datacontrol_map_set_provider_id(provider, provider_id);
129 * if (result != DATACONTROL_ERROR_NONE) {
130 * LOGE("Setting providerID is failed with error: %d", result);
134 * result = datacontrol_map_set_data_id(provider, data_id);
135 * if (result != DATACONTROL_ERROR_NONE) {
136 * LOGE("Setting dataID is failed with error: %d", result);
140 * // Executes some operations
142 * result = datacontrol_map_destroy(provider);
143 * if (result != DATACONTROL_ERROR_NONE) {
144 * LOGE("Destorying data control provider is failed with error: %d", result);
152 EXPORT_API int datacontrol_map_create(datacontrol_h *provider);
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()
161 EXPORT_API int datacontrol_map_destroy(datacontrol_h provider);
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()
173 EXPORT_API int datacontrol_map_set_provider_id(datacontrol_h provider, const char *provider_id);
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()
185 EXPORT_API int datacontrol_map_get_provider_id(datacontrol_h provider, char **provider_id);
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()
198 EXPORT_API int datacontrol_map_set_data_id(datacontrol_h provider, const char *data_id);
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()
211 EXPORT_API int datacontrol_map_get_data_id(datacontrol_h provider, char **data_id);
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()
225 EXPORT_API int datacontrol_map_register_response_cb(datacontrol_h provider, datacontrol_map_response_cb* callback, void *user_data);
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.
232 EXPORT_API int datacontrol_map_unregister_response_cb(datacontrol_h provider);
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.
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
247 * The following example demonstrates how to use the %datacontrol_map_get() method.
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)
254 * if (provider_result) {
255 * LOGI("The get operation is successful");
258 * LOGI("The get operation for the request %d is failed. error message: %s", request_id, error);
262 * datacontrol_map_response_cb map_callback;
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 * LOGE("Registering the callback function is failed with error: %d", result);
277 * result = datacontrol_map_get(provider, key, &req_id);
278 * if (result != DATACONTROL_ERROR_NONE) {
279 * LOGE("Getting the value list of the key(%s) is failed with error: %d", key, result);
282 * LOGI("req_id is %d", req_id);
290 EXPORT_API int datacontrol_map_get(datacontrol_h provider, const char *key, int *request_id);
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.
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
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
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);
311 * @brief Sets the value associated with the specified @c key to a new value.
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
325 * The following example demonstrates how to use the %datacontrol_map_set() method.
329 * void map_set_response_cb(int request_id, datacontrol_h provider, bool provider_result, const char *error)
331 * if (provider_result) {
332 * LOGI("The set operation is successful");
335 * LOGI("The set operation for the request %d is failed. error message: %s", request_id, error);
339 * datacontrol_map_response_cb map_callback;
346 * char *old_value = "old value";
347 * char *new_value = "new value";
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 * LOGE("Registering the callback function is failed with error: %d", result);
356 * result = datacontrol_map_set(provider, key, old_value, new_value, &req_id);
357 * if (result != DATACONTROL_ERROR_NONE) {
358 * LOGE("Replacing old_value(%s) with new_value(%s) is failed with error: %d", old_value, new_value, result);
361 * LOGI("req_id is %d", req_id);
369 EXPORT_API int datacontrol_map_set(datacontrol_h provider, const char *key, const char *old_value, const char *new_value, int *request_id);
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.
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
385 * The following example demonstrates how to use the %datacontrol_map_add() method.
389 * void map_add_response_cb(int request_id, datacontrol_h provider, bool provider_result, const char *error) {
390 * if (provider_result) {
391 * LOGI("The add operation is successful");
394 * LOGI("The add operation for the request %d is failed. error message: %s", request_id, error);
398 * datacontrol_map_response_cb map_callback;
404 * const char *key = "key";
405 * const char *value = "value";
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 * LOGE("Registering the callback function is failed with error: %d", result);
414 * result = datacontrol_map_add(provider, key, value, &req_id);
415 * if (result != DATACONTROL_ERROR_NONE) {
416 * LOGE("Adding %s-%s pair is failed with error: %d", key, value, result);
419 * LOGI("req_id is %d", req_id);
427 EXPORT_API int datacontrol_map_add(datacontrol_h provider, const char *key, const char *value, int *request_id);
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.
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
443 * The following example demonstrates how to use the %datacontrol_map_remove() method.
447 * void map_remove_response_cb(int request_id, datacontrol_h provider, bool provider_result, const char *error) {
448 * if (provider_result) {
449 * LOGI("The remove operation is successful");
452 * LOGI("The remove operation for the request %d is failed. error message: %s", request_id, error);
456 * datacontrol_map_response_cb map_callback;
462 * const char *key = "key";
463 * const char *value = "value";
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 * LOGE("Registering the callback function is failed with error: %d", result);
474 * result = datacontrol_map_remove(provider, key, value, &req_id);
475 * if (result != DATACONTROL_ERROR_NONE) {
476 * LOGE("Removing %s-%s pair is failed with error: %d", key, value, result);
479 * LOGI("req_id is %d", req_id);
487 EXPORT_API int datacontrol_map_remove(datacontrol_h provider, const char *key, const char *value, int *request_id);
493 #endif /* _APPFW_DATA_CONTROL_MAP_H_ */