Persisting User Preference Data (C/C++)

When to Use

Use the Preferences module to store small amounts of data in key-value (KV) format. The data is stored in files and memory for fast access. If a large amount of data needs to be stored, consider using a KV store or RDB store.

Constraints

• The C APIs and ArkTS APIs of the Preferences module cannot be used together.
• The maximum key length is 1024 bytes, and the maximum value length is 16 MB.

Available APIs

For details about the APIs, see Preferences.

Adding Dynamic Link Libraries

Add the following library to CMakeLists.txt.

libohpreferences.so

Including Header Files

#include <cstring>
#include <database/preferences/oh_preferences.h>
#include <database/preferences/oh_preferences_err_code.h>
#include <database/preferences/oh_preferences_option.h>
#include <database/preferences/oh_preferences_value.h>

How to Develop

The following example shows how to use Preferences APIs to modify and persist KV data. 1. Create a PreferencesOption instance and set the name, application group ID, bundle name, and storage type. If the PreferencesOption object is no longer required, call OH_PreferencesOption_Destroy to destroy it. 2. Call OH_Preferences_Open to open a Preferences instance. When the Preferences instance is not required, call OH_Preferences_Close to close it. 3. Call OH_Preferences_RegisterDataObserver to register a DataChangeObserverCallback callback to observe data changes of three keys. 4. Set KV data in the Preferences instance. 5. Obtain data in the Preferences instance. 6. Call OH_Preferences_Close to close the Preferences instance and set the instance pointer to null.

// Callback used to return data changes.
void DataChangeObserverCallback(void *context, const OH_PreferencesPair *pairs, uint32_t count) {
    for (uint32_t i = 0; i < count; i++) {
        // Obtain the value corresponding to index i.
        const OH_PreferencesValue *pValue = OH_PreferencesPair_GetPreferencesValue(pairs, i);
        // Obtain the data type of a value.
        Preference_ValueType type = OH_PreferencesValue_GetValueType(pValue);
        int ret = PREFERENCES_OK;
        if (type == PREFERENCE_TYPE_INT) {
            int intValue = 0;
            ret = OH_PreferencesValue_GetInt(pValue, &intValue);
            if (ret == PREFERENCES_OK) {
                // Service logic.
            }
        } else if (type == PREFERENCE_TYPE_BOOL) {
            bool boolValue = true;
            ret = OH_PreferencesValue_GetBool(pValue, &boolValue);
            if (ret == PREFERENCES_OK) {
                // Service logic.
            }
        } else if (type == PREFERENCE_TYPE_STRING) {
            char *stringValue = nullptr;
            uint32_t valueLen = 0;
            ret = OH_PreferencesValue_GetString(pValue, &stringValue, &valueLen);
            if (ret == PREFERENCES_OK) {
                // Service logic.
                OH_Preferences_FreeString(stringValue);
            }
        } else {
            // Invalid type.
        }
    }
}

// 1. Create a PreferencesOption instance.
OH_PreferencesOption *option = OH_PreferencesOption_Create();
if (option == nullptr) {
    // Error handling.
}
// Set the file name.
int ret = OH_PreferencesOption_SetFileName(option, "testdb");
if (ret != PREFERENCES_OK) {
    (void)OH_PreferencesOption_Destroy(option);
    // Error handling.
}
// Set the application group ID.
ret = OH_PreferencesOption_SetDataGroupId(option, "");
if (ret != PREFERENCES_OK) {
    (void)OH_PreferencesOption_Destroy(option);
    // Error handling.
}
// Set the bundle name.
ret = OH_PreferencesOption_SetBundleName(option, "com.example");
if (ret != PREFERENCES_OK) {
    (void)OH_PreferencesOption_Destroy(option);
    // Error handling.
}

// Set the storage type for the PreferencesOption instance. Before the setting, call OH_Preferences_IsStorageTypeSupported to check whether the storage type is supported.
bool isGskvSupported = false;
ret = OH_Preferences_IsStorageTypeSupported(Preferences_StorageType::PREFERENCES_STORAGE_GSKV, &isGskvSupported);
if (ret != PREFERENCES_OK) {
    (void)OH_PreferencesOption_Destroy(option);
    // Error handling.
}
if (isGskvSupported) {
    ret = OH_PreferencesOption_SetStorageType(option, Preferences_StorageType::PREFERENCES_STORAGE_GSKV);
    if (ret != PREFERENCES_OK) {
        (void)OH_PreferencesOption_Destroy(option);
        // Error handling.
    }
} else {
    ret = OH_PreferencesOption_SetStorageType(option, Preferences_StorageType::PREFERENCES_STORAGE_XML);
    if (ret != PREFERENCES_OK) {
        (void)OH_PreferencesOption_Destroy(option);
        // Error handling.
    }
}

// 2. Open a Preferences instance.
int errCode = PREFERENCES_OK;
OH_Preferences *preference = OH_Preferences_Open(option, &errCode);
// Destroy the PreferencesOption instance that is no longer used, and set the instance pointer to null.
(void)OH_PreferencesOption_Destroy(option);
option = nullptr;
if (preference == nullptr||errCode != PREFERENCES_OK) {
    // Error handling.
}

// 3. Subscribe to data changes of key_int, key_bool, and key_string.
const char *keys[] = {"key_int", "key_bool", "key_string"};
ret = OH_Preferences_RegisterDataObserver(preference, nullptr, DataChangeObserverCallback, keys, 3);
if (ret != PREFERENCES_OK) {
    (void)OH_Preferences_Close(preference);
    // Error handling.
}

// 4. Set KV data in the Preferences instance.
ret = OH_Preferences_SetInt(preference, keys[0], 0);
if (ret != PREFERENCES_OK) {
    (void)OH_Preferences_Close(preference);
    // Error handling.
}
ret = OH_Preferences_SetBool(preference, keys[1], true);
if (ret != PREFERENCES_OK) {
    (void)OH_Preferences_Close(preference);
    // Error handling.
}
ret = OH_Preferences_SetString(preference, keys[2], "string value");
if (ret != PREFERENCES_OK) {
    (void)OH_Preferences_Close(preference);
    // Error handling.
}

// 5. Obtain KV data from the Preferences instance.
int intValue = 0;
ret = OH_Preferences_GetInt(preference, keys[0], &intValue);
if (ret == PREFERENCES_OK) {
    // Service logic.
}

bool boolValue = false;
ret = OH_Preferences_GetBool(preference, keys[1], &boolValue);
if (ret == PREFERENCES_OK) {
    // Service logic.
}

char *stringValue = nullptr;
uint32_t valueLen = 0;
ret = OH_Preferences_GetString(preference, keys[2], &stringValue, &valueLen);
if (ret == PREFERENCES_OK) {
    // Service logic.
    // Release the string obtained by OH_Preferences_GetString.
    OH_Preferences_FreeString(stringValue);
    stringValue = nullptr;
}

// 6. Close the Preferences instance and set the pointer to null.
(void)OH_Preferences_Close(preference);
preference = nullptr;

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkData (Ark Data Management)

harmony 鸿蒙Access Control by Device and Data Level

harmony 鸿蒙Application Data Vectorization

harmony 鸿蒙AIP Overview

harmony 鸿蒙Application Data Persistence Overview

harmony 鸿蒙Database Backup and Restore

harmony 鸿蒙Database Encryption

harmony 鸿蒙Introduction to ArkData

harmony 鸿蒙Persisting Graph Store Data (for System Applications Only)

harmony 鸿蒙Persisting KV Store Data