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 RDB 18 * @{ 19 * 20 * @brief The relational database (RDB) store manages data based on relational models. 21 * With the underlying SQLite database, the RDB store provides a complete mechanism for managing local databases. 22 * To satisfy different needs in complicated scenarios, the RDB store offers a series of APIs for performing operations 23 * such as adding, deleting, modifying, and querying data, and supports direct execution of SQL statements. 24 * 25 * @since 10 26 */ 27 28 /** 29 * @file oh_data_value.h 30 * 31 * @brief Provides functions and enumerations related to the data value. 32 * 33 * @kit ArkData 34 * @library libnative_rdb_ndk.z.so 35 * @syscap SystemCapability.DistributedDataManager.RelationalStore.Core 36 * 37 * @since 18 38 */ 39 40 #ifndef OH_DATA_VALUE_H 41 #define OH_DATA_VALUE_H 42 43 #include <inttypes.h> 44 #include "database/data/data_asset.h" 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** 51 * @brief Indicates the column type. 52 * 53 * @since 10 54 */ 55 typedef enum OH_ColumnType { 56 /** 57 * @brief Indicates the column type is NULL. 58 * Moved from oh_cursor.h file. 59 * @since 10 60 */ 61 TYPE_NULL = 0, 62 /** 63 * @brief Indicates the column type is INT64. 64 * Moved from oh_cursor.h file. 65 * @since 10 66 */ 67 TYPE_INT64, 68 /** 69 * @brief Indicates the column type is REAL. 70 * Moved from oh_cursor.h file. 71 * @since 10 72 */ 73 TYPE_REAL, 74 /** 75 * @brief Indicates the column type is TEXT. 76 * Moved from oh_cursor.h file. 77 * @since 10 78 */ 79 TYPE_TEXT, 80 /** 81 * @brief Indicates the column type is BLOB. 82 * Moved from oh_cursor.h file. 83 * @since 10 84 */ 85 TYPE_BLOB, 86 /** 87 * @brief Indicates the column type is {@link Data_Asset}. 88 * Moved from oh_cursor.h file. 89 * @since 11 90 */ 91 TYPE_ASSET, 92 /** 93 * @brief Indicates the column type is array of {@link Data_Asset}. 94 * Moved from oh_cursor.h file. 95 * @since 11 96 */ 97 TYPE_ASSETS, 98 /** 99 * @brief Indicates the column type is FLOAT VECTOR. 100 * 101 * @since 18 102 */ 103 TYPE_FLOAT_VECTOR, 104 /** 105 * @brief Indicates that the column type is a number whose length is greater than 64 bits. 106 * 107 * @since 18 108 */ 109 TYPE_UNLIMITED_INT, 110 } OH_ColumnType; 111 112 /** 113 * @brief Define the OH_Data_Value structure type. 114 * 115 * @since 18 116 */ 117 typedef struct OH_Data_Value OH_Data_Value; 118 119 /** 120 * @brief Creates an OH_Data_Value instance object. 121 * 122 * @return Returns a pointer to OH_Data_Value instance when the execution is successful. 123 * Otherwise, nullptr is returned. The memory must be released through the OH_Value_Destroy 124 * interface after the use is complete. 125 * @see OH_Value_Destroy. 126 * @since 18 127 */ 128 OH_Data_Value *OH_Value_Create(void); 129 130 /** 131 * @brief Destroys an OH_Data_Value instance object. 132 * 133 * @param value Represents a pointer to an instance of OH_Data_Value. 134 * @return Returns the error code. 135 * Returns {@link RDB_OK} if the execution is successful. 136 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 137 * @since 18 138 */ 139 int OH_Value_Destroy(OH_Data_Value *value); 140 141 /** 142 * @brief Set empty data to the OH_Data_Value object. 143 * 144 * @param value Represents a pointer to an instance of OH_Data_Value. 145 * @return Returns the error code. 146 * Returns {@link RDB_OK} if the execution is successful. 147 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 148 * @since 18 149 */ 150 int OH_Value_PutNull(OH_Data_Value *value); 151 152 /** 153 * @brief Set integer data to the OH_Data_Value object. 154 * 155 * @param value Represents a pointer to an instance of OH_Data_Value. 156 * @param val Represents a integer data. 157 * @return Returns the error code. 158 * Returns {@link RDB_OK} if the execution is successful. 159 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 160 * @since 18 161 */ 162 int OH_Value_PutInt(OH_Data_Value *value, int64_t val); 163 164 /** 165 * @brief Set decimal data to the OH_Data_Value object. 166 * 167 * @param value Represents a pointer to an instance of OH_Data_Value. 168 * @param val Represents a decimal data. 169 * @return Returns the error code. 170 * Returns {@link RDB_OK} if the execution is successful. 171 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 172 * @since 18 173 */ 174 int OH_Value_PutReal(OH_Data_Value *value, double val); 175 176 /** 177 * @brief Set string data to the OH_Data_Value object. 178 * 179 * @param value Represents a pointer to an instance of OH_Data_Value. 180 * @param val Represents a string data. 181 * @return Returns the error code. 182 * Returns {@link RDB_OK} if the execution is successful. 183 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 184 * @since 18 185 */ 186 int OH_Value_PutText(OH_Data_Value *value, const char *val); 187 188 /** 189 * @brief Set binary data to the OH_Data_Value object. 190 * 191 * @param value Represents a pointer to an instance of OH_Data_Value. 192 * @param val Represents a binary data. 193 * @param length Represents the size of binary data. 194 * @return Returns the error code. 195 * Returns {@link RDB_OK} if the execution is successful. 196 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 197 * @since 18 198 */ 199 int OH_Value_PutBlob(OH_Data_Value *value, const unsigned char *val, size_t length); 200 201 /** 202 * @brief Set Data_Asset data to the OH_Data_Value object. 203 * 204 * @param value Represents a pointer to an instance of OH_Data_Value. 205 * @param val Represents a pointer to an instance of Data_Asset. 206 * @return Returns the error code. 207 * Returns {@link RDB_OK} if the execution is successful. 208 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 209 * @since 18 210 */ 211 int OH_Value_PutAsset(OH_Data_Value *value, const Data_Asset *val); 212 213 /** 214 * @brief Set multiple Data_Asset data to the OH_Data_Value object. 215 * 216 * @param value Represents a pointer to an instance of OH_Data_Value. 217 * @param val Represents a pointer to multiple Data_Asset. 218 * @param length Represents the count of multiple data. 219 * @return Returns the error code. 220 * Returns {@link RDB_OK} if the execution is successful. 221 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 222 * @since 18 223 */ 224 int OH_Value_PutAssets(OH_Data_Value *value, const Data_Asset * const * val, size_t length); 225 226 /** 227 * @brief Set float array data to the OH_Data_Value object. 228 * 229 * @param value Represents a pointer to an instance of OH_Data_Value. 230 * @param val Represents a pointer to float array. 231 * @param length Represents the size of float array. 232 * @return Returns the error code. 233 * Returns {@link RDB_OK} if the execution is successful. 234 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 235 * @since 18 236 */ 237 int OH_Value_PutFloatVector(OH_Data_Value *value, const float *val, size_t length); 238 239 /** 240 * @brief Set an integer of any length data to the OH_Data_Value object. 241 * 242 * @param value Represents a pointer to an instance of OH_Data_Value. 243 * @param sign Represents 0 is positive integer, 1 is negative integer. 244 * @param trueForm Represents a pointer to integer array. 245 * @param length Represents the size of integer array. 246 * @return Returns the error code. 247 * Returns {@link RDB_OK} if the execution is successful. 248 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 249 * @since 18 250 */ 251 int OH_Value_PutUnlimitedInt(OH_Data_Value *value, int sign, const uint64_t *trueForm, size_t length); 252 253 /** 254 * @brief Get data type from OH_Data_Value object. 255 * 256 * @param value Represents a pointer to an instance of OH_Data_Value. 257 * @param type Represents the parameter of the data type. It is an output parameter. 258 * @return Returns the error code. 259 * Returns {@link RDB_OK} if the execution is successful. 260 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 261 * @since 18 262 */ 263 int OH_Value_GetType(OH_Data_Value *value, OH_ColumnType *type); 264 265 /** 266 * @brief Check whether the data is empty from OH_Data_Value object. 267 * 268 * @param value Represents a pointer to an instance of OH_Data_Value. 269 * @param val Represents empty data flag. It is an output parameter. 270 * The value true means that the data is empty, and false means the opposite. 271 * @return Returns the error code. 272 * Returns {@link RDB_OK} if the execution is successful. 273 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 274 * @since 18 275 */ 276 int OH_Value_IsNull(OH_Data_Value *value, bool *val); 277 278 /** 279 * @brief Get integer data from OH_Data_Value object. 280 * 281 * @param value Represents a pointer to an instance of OH_Data_Value. 282 * @param val Represents a pointer to an integer data. It is an output parameter. 283 * @return Returns the error code. 284 * Returns {@link RDB_OK} if the execution is successful. 285 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 286 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 287 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 288 * @since 18 289 */ 290 int OH_Value_GetInt(OH_Data_Value *value, int64_t *val); 291 292 /** 293 * @brief Get decimal data from OH_Data_Value object. 294 * 295 * @param value Represents a pointer to an instance of OH_Data_Value. 296 * @param val Represents a pointer to an decimal data. It is an output parameter. 297 * @return Returns the error code. 298 * Returns {@link RDB_OK} if the execution is successful. 299 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 300 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 301 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 302 * @since 18 303 */ 304 int OH_Value_GetReal(OH_Data_Value *value, double *val); 305 306 /** 307 * @brief Get string data from OH_Data_Value object. 308 * 309 * @param value Represents a pointer to an instance of OH_Data_Value. 310 * @param val Represents a pointer to a string data. It is an output parameter. 311 * The caller does not need to apply for memory and release memory. The life cycle of val follows value. 312 * @return Returns the error code. 313 * Returns {@link RDB_OK} if the execution is successful. 314 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 315 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 316 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 317 * @since 18 318 */ 319 int OH_Value_GetText(OH_Data_Value *value, const char **val); 320 321 /** 322 * @brief Get binary data from OH_Data_Value object. 323 * 324 * @param value Represents a pointer to an instance of OH_Data_Value. 325 * @param val Represents a pointer to a binary data. It is an output parameter. 326 * The caller does not need to apply for memory and release memory. The life cycle of val follows value. 327 * @param length Represents the size of binary array. 328 * @return Returns the error code. 329 * Returns {@link RDB_OK} if the execution is successful. 330 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 331 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 332 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 333 * @since 18 334 */ 335 int OH_Value_GetBlob(OH_Data_Value *value, const uint8_t **val, size_t *length); 336 337 /** 338 * @brief Get Data_Asset data from OH_Data_Value object. 339 * 340 * @param value Represents a pointer to an instance of OH_Data_Value. 341 * @param val Represents a pointer to an instance of Data_Asset. The caller needs to apply for data memory. 342 * This function only fills data. Otherwise, the execution fails. 343 * @return Returns the error code. 344 * Returns {@link RDB_OK} if the execution is successful. 345 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 346 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 347 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 348 * @since 18 349 */ 350 int OH_Value_GetAsset(OH_Data_Value *value, Data_Asset *val); 351 352 /** 353 * @brief Get multiple Data_Asset size from OH_Data_Value object. 354 * 355 * @param value Represents a pointer to an instance of OH_Data_Value. 356 * @param length Represents the size of Data_Asset array. It is an output parameter. 357 * @return Returns the error code. 358 * Returns {@link RDB_OK} if the execution is successful. 359 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 360 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 361 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 362 * @since 18 363 */ 364 int OH_Value_GetAssetsCount(OH_Data_Value *value, size_t *length); 365 366 /** 367 * @brief Get multiple Data_Asset data from OH_Data_Value object. 368 * 369 * @param value Represents a pointer to an instance of OH_Data_Value. 370 * @param val Represents a pointer to Data_Asset array. The caller needs to apply for data memory. 371 * This function only fills data. Otherwise, the execution fails. 372 * @param inLen Represents the size of val. It can be obtained through the OH_Value_GetAssetsCount function. 373 * @param outLen Represents the actual amount of data obtained. It is an output parameter. 374 * @return Returns the error code. 375 * Returns {@link RDB_OK} if the execution is successful. 376 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 377 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 378 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 379 * @see OH_Value_GetAssetsCount. 380 * @since 18 381 */ 382 int OH_Value_GetAssets(OH_Data_Value *value, Data_Asset **val, size_t inLen, size_t *outLen); 383 384 /** 385 * @brief Get float array data size from OH_Data_Value object. 386 * 387 * @param value Represents a pointer to an instance of OH_Data_Value. 388 * @param length Represents the size of float array. It is an output parameter. 389 * @return Returns the error code. 390 * Returns {@link RDB_OK} if the execution is successful. 391 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 392 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 393 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 394 * @since 18 395 */ 396 int OH_Value_GetFloatVectorCount(OH_Data_Value *value, size_t *length); 397 398 /** 399 * @brief Get float array from OH_Data_Value object. 400 * 401 * @param value Represents a pointer to an instance of OH_Data_Value. 402 * @param val Represents a pointer to float array. The caller needs to apply for data memory. 403 * This function only fills data. Otherwise, the execution fails. 404 * @param inLen Represents the size of val. It can be obtained through the OH_Value_GetFloatVectorCount function. 405 * @param outLen Represents the actual amount of data obtained. It is an output parameter. 406 * @return Returns the error code. 407 * Returns {@link RDB_OK} if the execution is successful. 408 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 409 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 410 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 411 * @see OH_Value_GetFloatVectorCount. 412 * @since 18 413 */ 414 int OH_Value_GetFloatVector(OH_Data_Value *value, float *val, size_t inLen, size_t *outLen); 415 416 /** 417 * @brief Get an integer of any length data size from OH_Data_Value object. 418 * 419 * @param value Represents a pointer to an instance of OH_Data_Value. 420 * @param length Represents the size of integer array. It is an output parameter. 421 * @return Returns the error code. 422 * Returns {@link RDB_OK} if the execution is successful. 423 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 424 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 425 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 426 * @since 18 427 */ 428 int OH_Value_GetUnlimitedIntBand(OH_Data_Value *value, size_t *length); 429 430 /** 431 * @brief Get an integer of any length data from OH_Data_Value object. 432 * 433 * @param value Represents a pointer to an instance of OH_Data_Value. 434 * @param sign Represents 0 is positive integer, 1 is negative integer. It is an output parameter. 435 * @param trueForm Represents a pointer to integer array. The caller needs to apply for data memory. 436 * This function only fills data. Otherwise, the execution fails. 437 * @param inLen Represents the size of trueForm. It can be obtained through the OH_Value_GetUnlimitedIntBand function. 438 * @param outLen Represents the actual amount of data obtained. It is an output parameter. 439 * @return Returns the error code. 440 * Returns {@link RDB_OK} if the execution is successful. 441 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 442 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 443 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 444 * @see OH_Value_GetUnlimitedIntBand. 445 * @since 18 446 */ 447 int OH_Value_GetUnlimitedInt(OH_Data_Value *value, int *sign, uint64_t *trueForm, size_t inLen, size_t *outLen); 448 449 #ifdef __cplusplus 450 }; 451 #endif 452 #endif 453 /** @} */