oh_data_value.h

Overview

Defines APIs and enums related to a single data value.
Since API version 18, OH_ColumnType is moved from oh_cursor.h to this file. This type is supported in versions earlier than API version 18 and can be used in all versions.

File to include: <database/data/oh_data_value.h>

Library: libnative_rdb_ndk.z.so

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

Since: 18

Related module: RDB

Summary

Structs

Name	typedef Keyword	Description
OH_Data_Value	OH_Data_Value	Defines the OH_Data_Value struct.

Enums

Name	typedef Keyword	Description
OH_ColumnType	OH_ColumnType	Enumerates the column types.

Functions

Name	Description
OH_Data_Value *OH_Value_Create(void)	Creates an OH_Data_Values instance to store a single KV pair.
int OH_Value_Destroy(OH_Data_Value *value)	Destroys an OH_Data_Value instance.
int OH_Value_PutNull(OH_Data_Value *value)	Adds empty data to an OH_Data_Value instance.
int OH_Value_PutInt(OH_Data_Value *value, int64_t val)	Adds an integer to an OH_Data_Value instance.
int OH_Value_PutReal(OH_Data_Value *value, double val)	Adds REAL data to an OH_Data_Value instance.
int OH_Value_PutText(OH_Data_Value *value, const char *val)	Adds a string to an OH_Data_Value instance.
int OH_Value_PutBlob(OH_Data_Value *value, const unsigned char *val, size_t length)	Adds BLOB data to an OH_Data_Value instance.
int OH_Value_PutAsset(OH_Data_Value *value, const Data_Asset *val)	Adds an asset to an OH_Data_Value instance.
int OH_Value_PutAssets(OH_Data_Value *value, const Data_Asset * const * val, size_t length)	Adds assets to an OH_Data_Value instance.
int OH_Value_PutFloatVector(OH_Data_Value *value, const float *val, size_t length)	Adds a float array to an OH_Data_Value instance.
int OH_Value_PutUnlimitedInt(OH_Data_Value *value, int sign, const uint64_t *trueForm, size_t length)	Adds an integer array of any length to an OH_Data_Value instance.
int OH_Value_GetType(OH_Data_Value *value, OH_ColumnType *type)	Obtains the type of a value in an OH_Data_Values instance.
int OH_Value_IsNull(OH_Data_Value *value, bool *val)	Checks whether a value is null.
int OH_Value_GetInt(OH_Data_Value *value, int64_t *val)	Obtains the integer from an OH_Data_Value instance.
int OH_Value_GetReal(OH_Data_Value *value, double *val)	Obtains the REAL data from an OH_Data_Value instance.
int OH_Value_GetText(OH_Data_Value *value, const char **val)	Obtains the string from an OH_Data_Value instance.
int OH_Value_GetBlob(OH_Data_Value *value, const uint8_t **val, size_t *length)	Obtains the BLOB data from an OH_Data_Value instance.
int OH_Value_GetAsset(OH_Data_Value *value, Data_Asset *val)	Obtains the asset from an OH_Data_Value instance.
int OH_Value_GetAssetsCount(OH_Data_Value *value, size_t *length)	Obtains the length of the assets in an OH_Data_Value instance.
int OH_Value_GetAssets(OH_Data_Value *value, Data_Asset **val, size_t inLen, size_t *outLen)	Obtains the assets from an OH_Data_Value instance.
int OH_Value_GetFloatVectorCount(OH_Data_Value *value, size_t *length)	Obtains the length of the float array in an OH_Data_Values instance.
int OH_Value_GetFloatVector(OH_Data_Value *value, float *val, size_t inLen, size_t *outLen)	Obtains the float array from an OH_Data_Values instance.
int OH_Value_GetUnlimitedIntBand(OH_Data_Value *value, size_t *length)	Obtains the length of the unlimited integer from an OH_Data_Value instance.
int OH_Value_GetUnlimitedInt(OH_Data_Value *value, int *sign, uint64_t *trueForm, size_t inLen, size_t *outLen)	Obtains the unlimited integer from an OH_Data_Value instance.

Enum Description

OH_ColumnType

enum OH_ColumnType

Description

Enumerates the column types.

Since: 10

Enum Item	Description
TYPE_NULL = 0	NULL.
TYPE_INT64	INT64.
TYPE_REAL	REAL.
TYPE_TEXT	TEXT.
TYPE_BLOB	BLOB.
TYPE_ASSET	ASSET (asset attachment). Since: 11
TYPE_ASSETS	ASSETS (multiple asset attachments). Since: 11
TYPE_FLOAT_VECTOR	FLOAT VECTOR. Since: 18
TYPE_UNLIMITED_INT	Number longer than 64 digits. Since: 18

Function Description

OH_Value_Create()

OH_Data_Value *OH_Value_Create(void)

Description

Creates an OH_Data_Values instance to store a single KV pair.

Since: 18

Returns

Type	Description
OH_Data_Value	Returns a pointer to the OH_Data_Value instance if the operation is successful; returns nullptr otherwise. Use OH_Value_Destroy to release the memory in time.

OH_Value_Destroy()

int OH_Value_Destroy(OH_Data_Value *value)

Description

Destroys an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid.

OH_Value_PutNull()

int OH_Value_PutNull(OH_Data_Value *value)

Description

Adds empty data to an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid.

OH_Value_PutInt()

int OH_Value_PutInt(OH_Data_Value *value, int64_t val)

Description

Adds an integer to an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
int64_t val	Integer to add.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid.

OH_Value_PutReal()

int OH_Value_PutReal(OH_Data_Value *value, double val)

Description

Adds REAL data to an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
double val	REAL data to add.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid.

OH_Value_PutText()

int OH_Value_PutText(OH_Data_Value *value, const char *val)

Description

Adds a string to an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
const char *val	Pointer to the string to add.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid.

OH_Value_PutBlob()

int OH_Value_PutBlob(OH_Data_Value *value, const unsigned char *val, size_t length)

Description

Adds BLOB data to an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
const unsigned char *val	Pointer to the BLOB data to add.
size_t length	Length of the BLOB data to add.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid.

OH_Value_PutAsset()

int OH_Value_PutAsset(OH_Data_Value *value, const Data_Asset *val)

Description

Adds an asset to an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
const Data_Asset *val	Pointer to the Data_Asset instance.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid.

OH_Value_PutAssets()

int OH_Value_PutAssets(OH_Data_Value *value, const Data_Asset * const * val, size_t length)

Description

Adds assets to an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
const Data_Asset * const * val	Pointer to the Data_Asset instance.
size_t length	Number of elements in the Data_Asset object to add.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid.

OH_Value_PutFloatVector()

int OH_Value_PutFloatVector(OH_Data_Value *value, const float *val, size_t length)

Description

Adds a float array to an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
const float *val	Pointer to the float array to add.
size_t length	Length of the float array to add.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid.

OH_Value_PutUnlimitedInt()

int OH_Value_PutUnlimitedInt(OH_Data_Value *value, int sign, const uint64_t *trueForm, size_t length)

Description

Adds an integer array of any length to an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
int sign	Sign notation of the integer array to add. The value 0 indicates a positive integer, and the value 1 indicates a negative integer.
const uint64_t *trueForm	Pointer to the integer array to add.
size_t length	Length of the integer array to add.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid.

OH_Value_GetType()

int OH_Value_GetType(OH_Data_Value *value, OH_ColumnType *type)

Description

Obtains the data type.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
OH_ColumnType *type	Pointer to the data type obtained.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid.

OH_Value_IsNull()

int OH_Value_IsNull(OH_Data_Value *value, bool *val)

Description

Checks whether a value is null.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
bool *val	Pointer to the check result. The value true means the value is empty, and the value false means the opposite.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid.

OH_Value_GetInt()

int OH_Value_GetInt(OH_Data_Value *value, int64_t *val)

Description

Obtains the integer from an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
int64_t *val	Pointer to the integer data obtained.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid. RDB_E_DATA_TYPE_NULL indicates the stored data is empty. RDB_E_TYPE_MISMATCH indicates the data types do not match.

OH_Value_GetReal()

int OH_Value_GetReal(OH_Data_Value *value, double *val)

Description

Obtains the REAL data from an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
double *val	Pointer to the REAL data obtained.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid. RDB_E_DATA_TYPE_NULL indicates the stored data is empty. RDB_E_TYPE_MISMATCH indicates the data types do not match.

OH_Value_GetText()

int OH_Value_GetText(OH_Data_Value *value, const char **val)

Description

Obtains the string from an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
const char **val	Double pointer to the string obtained. You do not need to apply for or release memory for it. The lifecycle of val complies with the value of index in value.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid. RDB_E_DATA_TYPE_NULL indicates the stored data is empty. RDB_E_TYPE_MISMATCH indicates the data types do not match.

OH_Value_GetBlob()

int OH_Value_GetBlob(OH_Data_Value *value, const uint8_t **val, size_t *length)

Description

Obtains the BLOB data from an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
const uint8_t **val	Double pointer to the BLOB data obtained. You do not need to apply for or release memory for it. The lifecycle of val complies with the value of index in value.
size_t *length	Pointer to the length of the BLOB data obtained.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid. RDB_E_DATA_TYPE_NULL indicates the stored data is empty. RDB_E_TYPE_MISMATCH indicates the data types do not match.

OH_Value_GetAsset()

int OH_Value_GetAsset(OH_Data_Value *value, Data_Asset *val)

Description

Obtains the asset from an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
Data_Asset *val	Pointer to the Data_Asset instance. Data memory should be requested. This function is used to fill in data only. Otherwise, the operation fails.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid. RDB_E_DATA_TYPE_NULL indicates the stored data is empty. RDB_E_TYPE_MISMATCH indicates the data types do not match.

OH_Value_GetAssetsCount()

int OH_Value_GetAssetsCount(OH_Data_Value *value, size_t *length)

Description

Obtains the length of the assets in an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
size_t *length	Pointer to the length of the ASSETS data obtained.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid. RDB_E_DATA_TYPE_NULL indicates the stored data is empty. RDB_E_TYPE_MISMATCH indicates the data types do not match.

OH_Value_GetAssets()

int OH_Value_GetAssets(OH_Data_Value *value, Data_Asset **val, size_t inLen, size_t *outLen)

Description

Obtains the assets from an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
Data_Asset **val	Double pointer to the Data_Asset instance. Data memory should be requested. This function is used to fill in data only. Otherwise, the operation fails.
size_t inLen	Size of val, which can be obtained using OH_Values_GetAssetsCount.
size_t *outLen	Pointer to the actual length of the data obtained.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid. RDB_E_DATA_TYPE_NULL indicates the stored data is empty. RDB_E_TYPE_MISMATCH indicates the data types do not match.

OH_Value_GetFloatVectorCount()

int OH_Value_GetFloatVectorCount(OH_Data_Value *value, size_t *length)

Description

Obtains the length of the float array in an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
size_t *length	Pointer to the length of the float data obtained.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid. RDB_E_DATA_TYPE_NULL indicates the stored data is empty. RDB_E_TYPE_MISMATCH indicates the data types do not match.

OH_Value_GetFloatVector()

int OH_Value_GetFloatVector(OH_Data_Value *value, float *val, size_t inLen, size_t *outLen)

Description

Obtains the float array from an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
float *val	Pointer to the float array obtained. Data memory should be requested. This function is used to fill in data only. Otherwise, the operation fails.
size_t inLen	Size of val, which can be obtained using OH_Values_GetFloatVectorCount.
size_t *outLen	Pointer to the actual length of the data obtained.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid. RDB_E_DATA_TYPE_NULL indicates the stored data is empty. RDB_E_TYPE_MISMATCH indicates the data types do not match.

OH_Value_GetUnlimitedIntBand()

int OH_Value_GetUnlimitedIntBand(OH_Data_Value *value, size_t *length)

Description

Obtains the length of the unlimited integer from an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
size_t *length	Pointer to the length of the integer obtained.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid. RDB_E_DATA_TYPE_NULL indicates the stored data is empty. RDB_E_TYPE_MISMATCH indicates the data types do not match.

OH_Value_GetUnlimitedInt()

int OH_Value_GetUnlimitedInt(OH_Data_Value *value, int *sign, uint64_t *trueForm, size_t inLen, size_t *outLen)

Description

Obtains the unlimited integer from an OH_Data_Value instance.

Since: 18

Parameters

Name	Description
OH_Data_Value *value	Pointer to the OH_Data_Value instance.
int *sign	Pointer to the sign notation of the integer obtained. The value 0 indicates a positive integer, and the value 1 indicates a negative integer.
uint64_t *trueForm	Pointer to the integer array obtained. Data memory should be requested. This function is used to fill in data only. Otherwise, the operation fails.
size_t inLen	trueForm length, which can be obtained using OH_Values_GetUnlimitedIntBand.
size_t *outLen	Pointer to the actual length of the data obtained.

Returns

Type	Description
int	Returns an error code. RDB_OK indicates the operation is successful. RDB_E_INVALID_ARGS indicates the parameters are invalid. RDB_E_DATA_TYPE_NULL indicates the stored data is empty. RDB_E_TYPE_MISMATCH indicates the data types do not match.