1/*
2 * Copyright (c) 2020 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @addtogroup kv_store
18 * @{
19 *
20 * @brief Provides functions for obtaining, setting, and deleting a key-value pair.
21 *
22 *
23 * Key-value pairs can be permanently stored in the file system. \n
24 * If {@link FEATURE_KV_CACHE} is enabled, key-value pairs can be stored in the cache. \n
25 * For details about cache specifications, see {@link MAX_CACHE_SIZE}. \n
26 * For details about the number of key-value pairs that can be stored in an application, see {@link MAX_KV_SUM}. \n
27 *
28 * @since 1.0
29 * @version 1.0
30 */
31
32/**
33 * @file kv_store.h
34 *
35 * @brief Provides functions for obtaining, setting, and deleting a key-value pair.
36 *
37 * @since 1.0
38 * @version 1.0
39 */
40
41#ifndef KV_STORE_API_H
42#define KV_STORE_API_H
43
44#include "utils_config.h"
45
46#ifdef __cplusplus
47#if __cplusplus
48extern "C" {
49#endif
50#endif /* __cplusplus */
51
52/**
53 * @brief Obtains the value matching a specified key from the file system or cache.
54 *
55 * @param key Indicates the key to be indexed. It allows only lowercase letters, digits, underscores (_), and dots (.).
56 * Its length cannot exceed 32 bytes (including the end-of-text character in the string).
57 * @param value Indicates the buffer for storing the value that matches the key. This is an output parameter.
58 * @param len Indicates the size of the value space in the buffer.
59 * @return Returns the length of the value if the operation is successful;
60 * returns <b>-9</b> if a parameter is incorrect; returns <b>-1</b> in other scenarios;
61 * returns <b>0</b> if the value is obtained from the cache.
62 * @since 1.0.
63 * @version 1.0.
64 */
65int UtilsGetValue(const char* key, char* value, unsigned int len);
66
67/**
68 * @brief Adds or updates the value matching a specified key in the file system or cache.
69 *
70 * @param key Indicates the key whose value is to be added or updated.
71 * It allows only lowercase letters, digits, underscores (_), and dots (.).
72 * Its length cannot exceed 32 bytes (including the end-of-text character in the string).
73 * @param value Indicates the value to be added or updated.
74 * Its length cannot exceed 128 bytes (including the end-of-text character in the string).
75 * @return Returns <b>0</b> if the operation is successful; returns <b>-9</b> if a parameter is incorrect;
76 * returns <b>-1</b> in other scenarios.
77 * @since 1.0.
78 * @version 1.0.
79 */
80int UtilsSetValue(const char* key, const char* value);
81
82/**
83 * @brief Deletes the value matching a specified key from the file system or cache.
84 *
85 * @param key Indicates the key whose value is to be deleted.
86 * It allows only lowercase letters, digits, underscores (_), and dots (.).
87 * Its length cannot exceed 32 bytes (including the end-of-text character in the string).
88 * @return Returns <b>0</b> if the operation is successful; returns <b>-9</b> if a parameter is incorrect;
89 * returns <b>-1</b> in other scenarios.
90 * @since 1.0.
91 * @version 1.0.
92 */
93int UtilsDeleteValue(const char* key);
94
95#ifdef FEATURE_KV_CACHE
96
97/**
98 * @brief Clears all key-value pairs from the cache.
99 *
100 * @attention This function is available only if {@link FEATURE_KV_CACHE} is enabled.
101 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise.
102 * @since 1.0.
103 * @version 1.0.
104 */
105int ClearKVCache(void);
106#endif
107
108#ifdef __cplusplus
109#if __cplusplus
110}
111#endif
112#endif /* __cplusplus */
113
114#endif  // KV_STORE_API_H
115/** @} */