1 /* 2 * Copyright (c) 2024 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 PREFERENCES 18 * @{ 19 * 20 * @brief Provides APIs for processing data in the form of key-value (KV) pairs. 21 * You can use the APIs provided by the Preferences module to query, modify, and persist KV pairs. 22 * The key is of the string type, and the value can be a number, a string, a boolean value. 23 * 24 * @since 13 25 */ 26 27 /** 28 * @file oh_preferences_value.h 29 * 30 * @brief Defines the APIs and enums related to preferences values. 31 * 32 * @kit ArkData 33 * @library libohpreferences.so 34 * @syscap SystemCapability.DistributedDataManager.Preferences.Core 35 * 36 * @since 13 37 */ 38 39 #ifndef OH_PREFERENCES_VALUE_H 40 #define OH_PREFERENCES_VALUE_H 41 42 #include <stdbool.h> 43 #include <stdint.h> 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @brief Enumerates the Preference value types. 51 * 52 * @since 13 53 */ 54 typedef enum Preference_ValueType { 55 /** 56 * @brief Null. 57 */ 58 PREFERENCE_TYPE_NULL = 0, 59 /** 60 * @brief Int. 61 */ 62 PREFERENCE_TYPE_INT, 63 /** 64 * @brief boolean. 65 */ 66 PREFERENCE_TYPE_BOOL, 67 /** 68 * @brief String. 69 */ 70 PREFERENCE_TYPE_STRING, 71 /** 72 * @brief end butt. 73 */ 74 PREFERENCE_TYPE_BUTT 75 } Preference_ValueType; 76 77 /** 78 * @brief Represents a KV pair in a Preferences instance. 79 * 80 * @since 13 81 */ 82 typedef struct OH_PreferencesPair OH_PreferencesPair; 83 84 /** 85 * @brief Represents the value in a KV pair of a Preferences instance. 86 * 87 * @since 13 88 */ 89 typedef struct OH_PreferencesValue OH_PreferencesValue; 90 91 /** 92 * @brief Obtains a key from an {@Link OH_PreferencesPair} instance. 93 * 94 * @param pairs Pointer to the target {@Link OH_PreferencesPair} instance. 95 * @param index Represents a target index of the pairs 96 * @return Returns preferences pointer to the key that when input parameters valid, 97 * return nullptr otherwise while invalid args are passed in. 98 * @see OH_PreferencesPair. 99 * @since 13 100 */ 101 const char *OH_PreferencesPair_GetKey(const OH_PreferencesPair *pairs, uint32_t index); 102 103 /** 104 * @brief Obtains a value from an {@Link OH_PreferencesPair} instance. 105 * 106 * @param pairs Pointer to the target {@Link OH_PreferencesPair} instance. 107 * @param index Index of the value to obtain. 108 * @return Returns a pointer to the {@Link OH_PreferencesValue} obtained if the operation is successful, 109 * returns nullptr otherwise while invalid args are passed in. 110 * @see OH_PreferencesValue. 111 * @since 13 112 */ 113 const OH_PreferencesValue *OH_PreferencesPair_GetPreferencesValue(const OH_PreferencesPair *pairs, uint32_t index); 114 115 /** 116 * @brief Obtains the type of a preferences value. 117 * 118 * @param object Pointer to the target {@Link OH_PreferencesValue} instance. 119 * @return Returns the value type obtained. 120 * {@link PREFERENCE_TYPE_NULL} indicates invalid args are passed in. 121 * @see OH_PreferencesValue. 122 * @since 13 123 */ 124 Preference_ValueType OH_PreferencesValue_GetValueType(const OH_PreferencesValue *object); 125 126 /** 127 * @brief Obtains the int value of an {@Link OH_PreferencesValue} instance. 128 * 129 * @param object Pointer to the target {@Link OH_PreferencesValue} instance. 130 * @param value Pointer to the value obtained. 131 * @return Returns the status code of the execution. 132 * {@link PREFERENCES_OK} indicates the operation is successful. 133 * {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in. 134 * {@link PREFERENCES_ERROR_STORAGE} indicates an storage error. 135 * {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error. 136 * @see OH_PreferencesValue. 137 * @since 13 138 */ 139 int OH_PreferencesValue_GetInt(const OH_PreferencesValue *object, int *value); 140 141 /** 142 * @brief Obtains the Boolean value of an {@Link OH_PreferencesValue} instance. 143 * 144 * @param object Pointer to the target {@Link OH_PreferencesValue} instance. 145 * @param value Pointer to the Boolean value obtained. 146 * @return Returns the status code of the execution. 147 * {@link PREFERENCES_OK} indicates the operation is successful. 148 * {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in. 149 * {@link PREFERENCES_ERROR_STORAGE} indicates an storage error. 150 * {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error. 151 * @see OH_PreferencesValue. 152 * @since 13 153 */ 154 int OH_PreferencesValue_GetBool(const OH_PreferencesValue *object, bool *value); 155 156 /** 157 * @brief Obtains the string value of an {@Link OH_PreferencesValue} instance. 158 * 159 * @param object Pointer to target {@Link OH_PreferencesValue} instance. 160 * @param value Double pointer to the value obtained in an char * array. Release {@Link OH_Preferences_FreeString} the 161 * memory by user when this parameter is no longer required. 162 * @param valueLen Pointer to the string length. 163 * @return Returns the status code of the execution. 164 * {@link PREFERENCES_OK} indicates the operation is successful. 165 * {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in. 166 * {@link PREFERENCES_ERROR_STORAGE} indicates an storage error. 167 * {@link PREFERENCES_ERROR_MALLOC} indicates an malloc memory error. 168 * @see OH_PreferencesValue. 169 * @since 13 170 */ 171 int OH_PreferencesValue_GetString(const OH_PreferencesValue *object, char **value, uint32_t *valueLen); 172 #ifdef __cplusplus 173 }; 174 #endif 175 #endif // OH_PREFERENCES_VALUE_H