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
46extern "C" {
47#endif
48
49/**
50 * @brief Enumerates the Preference value types.
51 *
52 * @since 13
53 */
54typedef 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 */
82typedef 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 */
89typedef 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 */
101const 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 */
113const 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 */
124Preference_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 */
139int 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 */
154int 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 */
171int OH_PreferencesValue_GetString(const OH_PreferencesValue *object, char **value, uint32_t *valueLen);
172#ifdef __cplusplus
173};
174#endif
175#endif // OH_PREFERENCES_VALUE_H