Preferences

OH_Preferences_Delete()

int OH_Preferences_Delete (OH_Preferences *preference, const char *key )

描述

在Preferences实例对象中删除Key对应的KV数据。

起始版本： 13

参数:

名称	描述
preference	指向目标OH_Preferences实例对象的指针。
key	指向需要删除的Key的指针。

返回：

返回执行的错误码。

若错误码为PREFERENCES_OK，表示操作成功。

若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。

若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。

参见：

OH_Preferences_FreeString()

void OH_Preferences_FreeString (char *string)

描述

释放从Preferences实例对象中获取的字符串。

起始版本： 13

参数:

名称	描述
string	需要释放的字符串指针。

参见：

OH_Preferences_GetBool()

int OH_Preferences_GetBool (OH_Preferences *preference, const char *key, bool *value )

描述

获取Preferences实例对象中Key对应的布尔值。

起始版本： 13

参数:

名称	描述
preference	指向目标OH_Preferences实例对象的指针。
key	需要获取的Key的指针。
value	该参数作为出参使用，表示指向获取到的布尔值的指针。

返回：

返回执行的错误码。

若错误码为PREFERENCES_OK，表示操作成功。

若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。

若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。

若错误码为PREFERENCES_ERROR_KEY_NOT_FOUND，表示查询的key不存在。

参见：

OH_Preferences_GetInt()

int OH_Preferences_GetInt (OH_Preferences *preference, const char *key, int *value )

描述

获取Preferences实例对象中Key对应的整型值。

起始版本： 13

参数:

名称	描述
preference	指向目标OH_Preferences实例对象的指针。
key	需要获取的Key的指针。
value	该参数作为出参使用，表示指向获取到的整型值的指针。

返回：

返回执行的错误码。

若错误码为PREFERENCES_OK，表示操作成功。

若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。

若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。

若错误码为PREFERENCES_ERROR_KEY_NOT_FOUND，表示查询的Key不存在。

参见：

OH_Preferences_GetString()

int OH_Preferences_GetString (OH_Preferences *preference, const char *key, char **value, uint32_t *valueLen )

描述

获取Preferences实例对象中Key对应的字符串。

起始版本： 13

参数:

名称	描述
preference	指向目标OH_Preferences实例对象的指针。
key	需要获取的Key的指针。
value	该参数作为出参使用，表示指向获取到的字符串的二级指针，使用完毕后需要调用释放函数OH_Preferences_FreeString释放内存。
valueLen	该参数作为出参使用，表示获取到的字符串长度的指针。

返回：

返回执行的错误码。

若错误码为PREFERENCES_OK，表示操作成功。

若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。

若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。

若错误码为PREFERENCES_ERROR_KEY_NOT_FOUND，表示查询的Key不存在。

参见：

OH_Preferences_Open()

OH_Preferences* OH_Preferences_Open (OH_PreferencesOption *option, int *errCode )

描述

打开一个Preferences实例对象并创建指向它的指针。当不再需要使用指针时，请使用OH_Preferences_Close关闭实例对象。

起始版本： 13

参数:

名称	描述
option	指向Preferences配置选项OH_PreferencesOption的指针。
errCode	该参数作为出参使用，表示指向返回错误码的指针，详见OH_Preferences_ErrCode。

返回：

当操作成功时，返回指向打开的Preferences对象OH_Preferences实例对象的指针，失败返回空指针。

参见：

OH_Preferences_RegisterDataObserver()

int OH_Preferences_RegisterDataObserver (OH_Preferences *preference, void *context, OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount )

描述

对选取的Key注册数据变更订阅。订阅的Key的值发生变更后，在调用OH_Preferences_Close()后触发回调。

起始版本： 13

参数:

名称	描述
preference	指向目标OH_Preferences实例对象的指针。
context	应用上下文的指针。
observer	订阅数据变更关联的回调函数OH_PreferencesDataObserver。
keys	需要订阅的Key数组。
keyCount	需要订阅的Key的数量。

返回：

返回执行的错误码。

若错误码为PREFERENCES_OK，表示操作成功。

若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。

若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。

若错误码为PREFERENCES_ERROR_GET_DATAOBSMGRCLIENT，表示获取数据变更订阅服务失败。

参见：

OH_PreferencesDataObserver

OH_Preferences_SetBool()

int OH_Preferences_SetBool (OH_Preferences *preference, const char *key, bool value )

描述

根据Key设置Preferences实例对象中的布尔值。

起始版本： 13

参数:

名称	描述
preference	指向目标OH_Preferences实例对象的指针。
key	指向需要设置的Key的指针。
value	需要设置的布尔值。

返回：

返回执行的错误码。

若错误码为PREFERENCES_OK，表示操作成功。

若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。

若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。

参见：

OH_Preferences_SetInt()

int OH_Preferences_SetInt (OH_Preferences *preference, const char *key, int value )

描述

根据Key设置Preferences实例对象中的整型值。

起始版本： 13

参数:

名称	描述
preference	指向目标OH_Preferences实例对象的指针。
key	指向需要设置的Key的指针。
value	需要设置的整型值。

返回：

返回执行的错误码。

若错误码为PREFERENCES_OK，表示操作成功。

若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。

若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。

参见：

OH_Preferences_SetString()

int OH_Preferences_SetString (OH_Preferences *preference, const char *key, const char *value )

描述

根据Key设置Preferences实例对象中的字符串。

起始版本： 13

参数:

名称	描述
preference	指向目标OH_Preferences实例对象的指针。
key	指向需要设置的Key的指针。
value	指向需要设置的字符串指针。

返回：

返回执行的错误码。

若错误码为PREFERENCES_OK，表示操作成功。

若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。

若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。

参见：

OH_Preferences_UnregisterDataObserver()

int OH_Preferences_UnregisterDataObserver (OH_Preferences *preference, void *context, OH_PreferencesDataObserver observer, const char *keys[], uint32_t keyCount )

描述

取消注册选取Key的数据变更订阅。

起始版本： 13

参数:

名称	描述
preference	指向目标OH_Preferences实例对象的指针。
context	应用上下文的指针。
observer	订阅数据变更关联的回调函数OH_PreferencesDataObserver。
keys	需要取消订阅的Key数组。
keyCount	需要取消订阅的Key的数量。

返回：

返回执行的错误码。

若错误码为PREFERENCES_OK，表示操作成功。

若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。

若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。

参见：

OH_PreferencesDataObserver

OH_PreferencesOption_Create()

OH_PreferencesOption* OH_PreferencesOption_Create (void )

描述

创建一个Preferences配置选项的OH_PreferencesOption实例对象以及指向它的指针。
当不再需要使用指针时，请使用OH_PreferencesOption_Destroy销毁实例对象，否则会导致内存泄漏。

起始版本： 13

返回：

如果操作成功，返回指向Preferences配置选项OH_PreferencesOption实例对象的指针。失败返回空指针。

参见：

OH_PreferencesOption_Destroy()

int OH_PreferencesOption_Destroy (OH_PreferencesOption *option)

描述

销毁Preferences配置选项OH_PreferencesOption实例。

起始版本： 13

参数:

名称	描述
option	Preferences配置选项OH_PreferencesOption实例对象的指针。

返回：

返回执行的错误码。若错误码为PREFERENCES_OK，表示操作成功。若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

参见：

OH_PreferencesOption_SetBundleName()

int OH_PreferencesOption_SetBundleName (OH_PreferencesOption *option, const char *bundleName )

描述

设置Preferences配置选项OH_PreferencesOption实例对象的包名称。

起始版本： 13

参数:

名称	描述
option	Preferences配置选项OH_PreferencesOption实例对象的指针。
bundleName	需要设置的包名称。

返回：

返回执行的错误码。

若错误码为PREFERENCES_OK，表示操作成功。

若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

参见：

OH_PreferencesOption_SetDataGroupId()

int OH_PreferencesOption_SetDataGroupId (OH_PreferencesOption *option, const char *dataGroupId )

描述

设置Preferences配置选项OH_PreferencesOption实例对象的应用组ID。

设置应用组ID后，会指定在此应用组ID对应的沙箱路径下创建Preferences实例。

应用组ID需要向应用市场获取，暂不支持。

当传入的应用组ID为空字符串时，默认在本应用沙箱目录下创建Preferences实例。

起始版本： 13

参数:

名称	描述
option	Preferences配置选项OH_PreferencesOption实例对象的指针。
dataGroupId	需要设置的应用组ID。

返回：

返回执行的错误码。

若错误码为PREFERENCES_OK，表示操作成功。

若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

参见：

OH_PreferencesOption_SetFileName()

int OH_PreferencesOption_SetFileName (OH_PreferencesOption *option, const char *fileName )

描述

设置Preferences配置选项OH_PreferencesOption实例对象的文件名称。

起始版本： 13

参数:

名称	描述
option	指向Preferences配置选项OH_PreferencesOption实例对象的指针。
fileName	需要设置的文件名称。

返回：

返回执行的错误码。

若错误码为PREFERENCES_OK，表示操作成功。

若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

参见：

OH_PreferencesPair_GetKey()

const char* OH_PreferencesPair_GetKey (const OH_PreferencesPair *pairs, uint32_t index )

描述

获取KV数据中索引对应数据的键。

起始版本： 13

参数:

名称	描述
pairs	目标KV数据OH_PreferencesPair的指针。
index	目标KV数据OH_PreferencesPair的索引值。

返回：

如果操作成功，返回获取到的键的指针。操作失败或传参不合法返回空指针。

参见：

OH_PreferencesPair

OH_PreferencesPair_GetPreferencesValue()

const OH_PreferencesValue* OH_PreferencesPair_GetPreferencesValue (const OH_PreferencesPair *pairs, uint32_t index )

描述

获取KV数据数组中索引对应的值。

起始版本： 13

参数:

名称	描述
pairs	目标KV数据OH_PreferencesPair的指针。
index	目标KV数据OH_PreferencesPair的索引值。

返回：

如果操作成功，返回获取到的值对象的指针。操作失败或传参不合法返回空指针。

参见：

OH_PreferencesValue_GetBool()

int OH_PreferencesValue_GetBool (const OH_PreferencesValue *object, bool *value )

描述

从PreferencesValue对象OH_PreferencesValue中获取一个布尔值。

起始版本： 13

参数:

名称	描述
object	PreferencesValue对象OH_PreferencesValue的指针。
value	该参数作为出参使用，表示指向获取到的布尔值的指针。

返回：

返回执行的错误码。

若错误码为PREFERENCES_OK，表示操作成功。

若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。

若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。

参见：

OH_PreferencesValue_GetInt()

int OH_PreferencesValue_GetInt (const OH_PreferencesValue* object, int* value )

描述

从PreferencesValue对象OH_PreferencesValue中获取一个整型值。

起始版本： 13

参数:

名称	描述
object	PreferencesValue对象OH_PreferencesValue的指针。
value	该参数作为出参使用，表示指向获取到的整型值的指针。

返回：

返回执行的错误码。

若错误码为PREFERENCES_OK，表示操作成功。

若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。

若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。

参见：

OH_PreferencesValue_GetString()

int OH_PreferencesValue_GetString (const OH_PreferencesValue *object, char **value, uint32_t *valueLen )

描述

从PreferencesValue对象OH_PreferencesValue中获取字符串。

起始版本： 13

参数:

名称	描述
object	PreferencesValue对象OH_PreferencesValue的指针。
value	该参数作为出参使用，表示指向获取到的字符串的二级指针，使用完毕后需要调用释放函数OH_Preferences_FreeString释放内存。
valueLen	该参数作为出参使用，表示指向获取到的字符串长度的指针。

返回：

返回执行的错误码。

若错误码为PREFERENCES_OK，表示操作成功。

若错误码为PREFERENCES_ERROR_INVALID_PARAM，表示参数不合法。

若错误码为PREFERENCES_ERROR_STORAGE，表示存储异常。

若错误码为PREFERENCES_ERROR_MALLOC，表示内存分配失败。

参见：

OH_PreferencesValue_GetValueType()

Preference_ValueType OH_PreferencesValue_GetValueType (const OH_PreferencesValue *object)

描述

获取PreferencesValue对象的数据类型。

起始版本： 13

参数:

名称	描述
object	PreferencesValue对象OH_PreferencesValue的指针。

返回：

返回获取到的数据类型枚举。若返回数据类型枚举为PREFERENCE_TYPE_NULL，代表传参不合法。

参见：