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 48 extern "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 */ 65 int 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 */ 80 int 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 */ 93 int 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 */ 105 int 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 /** @} */