Persisting User Preferences (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

• Versions earlier than API version 18: ArkTS APIs support only the XML storage format, and C APIs support only the GSKV storage format. Storage formats are incompatible, so ArkTS and C APIs cannot operate the same Preferences instance.
• API version 18 and later: Both ArkTS and C APIs support the XML and GSKV storage formats. ArkTS and C APIs can operate the same Preferences instance if they use the same format.
• 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 <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.

   // 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.
   }
   // Delete the PreferencesOption that is no longer used.
   errCode = OH_Preferences_DeletePreferences(option);
   if (errCode != PREFERENCES_OK) {
       // Error handling.
   }
   

   napi_init.cpp

3. Define DataChangeObserverCallback.

   // 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 PreferencesValue 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.
           }
       }
   }
   

   napi_init.cpp

   Call **OH_Preferences_RegisterDataObserver** to subscribe to data changes for three keys.

   // 3. Subscribe to data changes of key_int, key_bool, and key_string.
   const char *keys[] = {"key_int", "key_bool", "key_string"};
   int ret = OH_Preferences_RegisterDataObserver(preference, nullptr, DataChangeObserverCallback, keys, 3);
   if (ret != PREFERENCES_OK) {
       (void)OH_Preferences_Close(preference);
       // Error handling.
   }
   // Subscribe to data changes with multi-process compatibility.
   int contextData = 42;
   ret = OH_Preferences_RegisterMultiProcessDataObserver(preference, &contextData, DataChangeObserverCallback);
   if (ret != PREFERENCES_OK) {
       // Error handling.
   }
   // Unsubscribe from data changes with multi-process compatibility.
   ret = OH_Preferences_UnregisterMultiProcessDataObserver(preference, &contextData, DataChangeObserverCallback);
   if (ret != PREFERENCES_OK) {
       // Error handling.
   }
   

   napi_init.cpp

4. Set KV data in the Preferences instance.

   // 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.
   }
   int32_t stringIndex = 2;
   ret = OH_Preferences_SetString(preference, keys[stringIndex], "string value");
   if (ret != PREFERENCES_OK) {
       (void)OH_Preferences_Close(preference);
       // Error handling.
   }
   ret = OH_Preferences_Flush(preference);
   if (ret != PREFERENCES_OK) {
       (void)OH_Preferences_Close(preference);
       // Error handling.
   }
   OH_PreferencesValue* setIntValue = OH_PreferencesValue_Create();
   if (setIntValue  == nullptr) {
       // Error handling.
   }
   const int value = 456;
   ret = OH_PreferencesValue_SetInt(setIntValue, value);
   if (ret != PREFERENCES_OK) {
       (void)OH_PreferencesValue_Destroy(setIntValue);
       // Error handling.
   }
   ret = OH_Preferences_SetValue(preference, "int_key", setIntValue);
   if (ret != PREFERENCES_OK) {
       (void)OH_Preferences_Close(preference);
       // Error handling.
   }
   

   napi_init.cpp

5. Obtain data in the Preferences instance.

   // 5. Obtain KV data from the Preferences instance.
   int intValue = 0;
   int ret = PREFERENCES_OK;
   const char *keys[] = {"key_int", "key_bool", "key_string"};
   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;
   int32_t stringIndex = 2;
   ret = OH_Preferences_GetString(preference, keys[stringIndex], &stringValue, &valueLen);
   if (ret == PREFERENCES_OK) {
       // Service logic.
       // Release the string obtained by OH_Preferences_GetString.
       OH_Preferences_FreeString(stringValue);
       stringValue = nullptr;
   }
   
   OH_PreferencesValue* getIntValue = OH_PreferencesValue_Create();
   if (getIntValue  == nullptr) {
       // Error handling.
   }
   ret = OH_Preferences_GetValue(preference, "int_key", &getIntValue);
   if (ret == PREFERENCES_OK) {
       // Service logic.
   }
   
   OH_PreferencesPair* pairs = nullptr;
   uint32_t count = 0;
   ret = OH_Preferences_GetAll(preference, &pairs, &count);
   if (ret == PREFERENCES_OK) {
       // Service logic.
       if (pairs != nullptr) {
           // Destroy all KV data from OH_PreferencesPair.
           OH_PreferencesPair_Destroy(pairs, count);
       }
   }
   
   // Check whether the key in the Preferences instance has data.
   bool result = OH_Preferences_HasKey(preference, "int_key");
   if (result == true) {
       // Data exists. Service logic.
   }
   
   // Clear the cache data.
   ret = OH_Preferences_ClearCache(preference);
   

   napi_init.cpp

6. Call OH_Preferences_Close to close the Preferences instance and set the instance pointer to null.

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

   napi_init.cpp

7. Set and obtain OH_PreferencesValue data.

   const int arg5 = 5;
   const int arg4 = 4;
   const int arg3 = 3;
   int ret = PREFERENCES_OK;
   OH_PreferencesValue* setValue = OH_PreferencesValue_Create();
   bool boolArray[] = {true, false, true, false};
   ret = OH_PreferencesValue_SetBoolArray(setValue, boolArray, arg4);
   if (ret != PREFERENCES_OK) {
       // Error handling.
   }
   uint32_t count = 0;
   bool* outBoolArray = nullptr;
   ret = OH_PreferencesValue_GetBoolArray(setValue, &outBoolArray, &count);
   if (ret != PREFERENCES_OK) {
       // Error handling.
   }
   
   const char* strArray[] = {"hello", "world", "test"};
   ret = OH_PreferencesValue_SetStringArray(setValue, strArray, arg3);
   if (ret != PREFERENCES_OK) {
       // Error handling.
   }
   char** outStrArray = nullptr;
   ret = OH_PreferencesValue_GetStringArray(setValue, &outStrArray, &count);
   if (ret != PREFERENCES_OK) {
       // Error handling.
   }
   
   int64_t int64Array[] = {1234567890LL, 9876543210LL, -1234567890LL};
   ret = OH_PreferencesValue_SetInt64Array(setValue, int64Array, arg3);
   if (ret != PREFERENCES_OK) {
       // Error handling.
   }
   int64_t* outArrayInt64 = nullptr;
   ret = OH_PreferencesValue_GetInt64Array(setValue, &outArrayInt64, &count);
   if (ret != PREFERENCES_OK) {
       // Error handling.
   }
   
   double doubleArray[] = {1.1, 2.2, 3.3, 4.4};
   ret = OH_PreferencesValue_SetDoubleArray(setValue, doubleArray, arg4);
   if (ret != PREFERENCES_OK) {
       // Error handling.
   }
   double* outDoubleArray = nullptr;
   ret = OH_PreferencesValue_GetDoubleArray(setValue, &outDoubleArray, &count);
   if (ret != PREFERENCES_OK) {
       // Error handling.
   }
   
   uint8_t blobData[] = {0x01, 0x02, 0x03, 0x04, 0x05};
   ret = OH_PreferencesValue_SetBlob(setValue, blobData, arg5);
   if (ret != PREFERENCES_OK) {
       // Error handling.
   }
   uint8_t* outBlob = nullptr;
   ret = OH_PreferencesValue_GetBlob(setValue, &outBlob, &count);
   if (ret != PREFERENCES_OK) {
       // Error handling.
   }
   

   napi_init.cpp