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_option.h
29 *
30 * @brief Defines the APIs and enums related to preferences option.
31 *
32 * @kit ArkData
33 * @library libohpreferences.so
34 * @syscap SystemCapability.DistributedDataManager.Preferences.Core
35 *
36 * @since 13
37 */
38
39#ifndef OH_PREFERENCES_OPTION_H
40#define OH_PREFERENCES_OPTION_H
41
42#include <stdint.h>
43
44#ifdef __cplusplus
45extern "C" {
46#endif
47
48/**
49 * @brief Represents an OH_PreferencesOption instance.
50 *
51 * @since 13
52 */
53typedef struct OH_PreferencesOption OH_PreferencesOption;
54
55/**
56 * @brief Creates an {@Link OH_PreferencesOption} instance.
57 *
58 * @return Returns a pointer to the {@Link OH_PreferencesOption} instance created if the operation is successful;
59 * returns nullptr otherwise while malloc memory failed.
60 * @see OH_PreferencesOption.
61 * @since 13
62 */
63OH_PreferencesOption *OH_PreferencesOption_Create(void);
64
65/**
66 * @brief Sets the file path in an {@Link OH_PreferencesOption} instance.
67 *
68 * @param option Pointer to the target {@Link OH_PreferencesOption} instance.
69 * @param fileName Pointer to the file name to set.
70 * @return Returns the status code of the execution.
71 *         {@link PREFERENCES_OK} success.
72 *         {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in.
73 * @see OH_PreferencesOption.
74 * @since 13
75 */
76int OH_PreferencesOption_SetFileName(OH_PreferencesOption *option, const char *fileName);
77
78/**
79 * @brief Sets the bundle name in an {@Link OH_PreferencesOption} instance.
80 *
81 * @param option Pointer to the target {@Link OH_PreferencesOption} instance.
82 * @param bundleName Pointer to the bundle name to set.
83 * @return Returns the status code of the execution.
84 *         {@link PREFERENCES_OK} success.
85 *         {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in.
86 * @see OH_PreferencesOption.
87 * @since 13
88 */
89int OH_PreferencesOption_SetBundleName(OH_PreferencesOption *option, const char *bundleName);
90
91/**
92 * @brief Sets the data group ID in an {@Link OH_PreferencesOption} instance.
93 *
94 * @param option Represents a pointer to an {@link OH_PreferencesOption} instance.
95 * @param dataGroupId Represents preferences data group id param.
96 * @return Returns the status code of the execution.
97 *         {@link PREFERENCES_OK} success.
98 *         {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in.
99 * @see OH_PreferencesOption.
100 * @since 13
101 */
102int OH_PreferencesOption_SetDataGroupId(OH_PreferencesOption *option, const char *dataGroupId);
103
104/**
105 * @brief Destroys an {@Link OH_PreferencesOption} instance.
106 *
107 * @param option Pointer to the {@Link OH_PreferencesOption} instance to destroy.
108 * @return Returns the status code of the execution.
109 *         {@link PREFERENCES_OK} indicates the operation is successful.
110 *         {@link PREFERENCES_ERROR_INVALID_PARAM} indicates invalid args are passed in.
111 * @see OH_PreferencesOption.
112 * @since 13
113 */
114int OH_PreferencesOption_Destroy(OH_PreferencesOption *option);
115#ifdef __cplusplus
116};
117#endif
118#endif // OH_PREFERENCES_OPTION_H