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 16 38 */ 39 40 #ifndef OH_DATA_VALUE_H 41 #define OH_DATA_VALUE_H 42 43 #include <inttypes.h> 44 #include "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 * 59 * @since 10 Moved from oh_cursor.h file. 60 */ 61 TYPE_NULL = 0, 62 /** 63 * @brief Indicates the column type is INT64. 64 * 65 * @since 10 Moved from oh_cursor.h file. 66 */ 67 TYPE_INT64, 68 /** 69 * @brief Indicates the column type is REAL. 70 * 71 * @since 10 Moved from oh_cursor.h file. 72 */ 73 TYPE_REAL, 74 /** 75 * @brief Indicates the column type is TEXT. 76 * 77 * @since 10 Moved from oh_cursor.h file. 78 */ 79 TYPE_TEXT, 80 /** 81 * @brief Indicates the column type is BLOB. 82 * 83 * @since 10 Moved from oh_cursor.h file. 84 */ 85 TYPE_BLOB, 86 /** 87 * @brief Indicates the column type is {@link Data_Asset}. 88 * 89 * @since 11 Moved from oh_cursor.h file. 90 */ 91 TYPE_ASSET, 92 /** 93 * @brief Indicates the column type is array of {@link Data_Asset}. 94 * 95 * @since 11 Moved from oh_cursor.h file. 96 */ 97 TYPE_ASSETS, 98 /** 99 * @brief Indicates the column type is FLOAT VECTOR. 100 * 101 * @since 16 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 16 108 */ 109 TYPE_UNLIMITED_INT, 110 } OH_ColumnType; 111 112 /** 113 * @brief Define the OH_Data_Value structure type. 114 * 115 * @since 16 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 16 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 16 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 16 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 16 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 16 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 16 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 16 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 16 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 16 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 16 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 16 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 16 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. Ture is empty, false is not empty. 270 * @return Returns the error code. 271 * Returns {@link RDB_OK} if the execution is successful. 272 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 273 * @since 16 274 */ 275 int OH_Value_IsNull(OH_Data_Value *value, bool *val); 276 277 /** 278 * @brief Get integer data from OH_Data_Value object. 279 * 280 * @param value Represents a pointer to an instance of OH_Data_Value. 281 * @param val Represents a pointer to an integer data. It is an output parameter. 282 * @return Returns the error code. 283 * Returns {@link RDB_OK} if the execution is successful. 284 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 285 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 286 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 287 * @since 16 288 */ 289 int OH_Value_GetInt(OH_Data_Value *value, int64_t *val); 290 291 /** 292 * @brief Get decimal data from OH_Data_Value object. 293 * 294 * @param value Represents a pointer to an instance of OH_Data_Value. 295 * @param val Represents a pointer to an decimal data. It is an output parameter. 296 * @return Returns the error code. 297 * Returns {@link RDB_OK} if the execution is successful. 298 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 299 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 300 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 301 * @since 16 302 */ 303 int OH_Value_GetReal(OH_Data_Value *value, double *val); 304 305 /** 306 * @brief Get string data from OH_Data_Value object. 307 * 308 * @param value Represents a pointer to an instance of OH_Data_Value. 309 * @param val Represents a pointer to a string data. It is an output parameter. 310 * The caller does not need to apply for memory and release memory. The life cycle of val follows value. 311 * @return Returns the error code. 312 * Returns {@link RDB_OK} if the execution is successful. 313 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 314 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 315 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 316 * @since 16 317 */ 318 int OH_Value_GetText(OH_Data_Value *value, const char **val); 319 320 /** 321 * @brief Get binary data from OH_Data_Value object. 322 * 323 * @param value Represents a pointer to an instance of OH_Data_Value. 324 * @param val Represents a pointer to a binary data. It is an output parameter. 325 * The caller does not need to apply for memory and release memory. The life cycle of val follows value. 326 * @param length Represents the size of binary array. 327 * @return Returns the error code. 328 * Returns {@link RDB_OK} if the execution is successful. 329 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 330 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 331 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 332 * @since 16 333 */ 334 int OH_Value_GetBlob(OH_Data_Value *value, const uint8_t **val, size_t *length); 335 336 /** 337 * @brief Get Data_Asset data from OH_Data_Value object. 338 * 339 * @param value Represents a pointer to an instance of OH_Data_Value. 340 * @param val Represents a pointer to an instance of Data_Asset. The caller needs to apply for data memory. 341 * This function only fills data. Otherwise, the execution fails. 342 * @return Returns the error code. 343 * Returns {@link RDB_OK} if the execution is successful. 344 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 345 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 346 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 347 * @since 16 348 */ 349 int OH_Value_GetAsset(OH_Data_Value *value, Data_Asset *val); 350 351 /** 352 * @brief Get multiple Data_Asset size from OH_Data_Value object. 353 * 354 * @param value Represents a pointer to an instance of OH_Data_Value. 355 * @param length Represents the size of Data_Asset array. It is an output parameter. 356 * @return Returns the error code. 357 * Returns {@link RDB_OK} if the execution is successful. 358 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 359 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 360 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 361 * @since 16 362 */ 363 int OH_Value_GetAssetsCount(OH_Data_Value *value, size_t *length); 364 365 /** 366 * @brief Get multiple Data_Asset data from OH_Data_Value object. 367 * 368 * @param value Represents a pointer to an instance of OH_Data_Value. 369 * @param val Represents a pointer to Data_Asset array. The caller needs to apply for data memory. 370 * This function only fills data. Otherwise, the execution fails. 371 * @param inLen Represents the size of val. It can be obtained through the OH_Value_GetAssetsCount function. 372 * @param outLen Represents the actual amount of data obtained. It is an output parameter. 373 * @return Returns the error code. 374 * Returns {@link RDB_OK} if the execution is successful. 375 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 376 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 377 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 378 * @see OH_Value_GetAssetsCount. 379 * @since 16 380 */ 381 int OH_Value_GetAssets(OH_Data_Value *value, Data_Asset **val, size_t inLen, size_t *outLen); 382 383 /** 384 * @brief Get float array data size from OH_Data_Value object. 385 * 386 * @param value Represents a pointer to an instance of OH_Data_Value. 387 * @param length Represents the size of float array. It is an output parameter. 388 * @return Returns the error code. 389 * Returns {@link RDB_OK} if the execution is successful. 390 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 391 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 392 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 393 * @since 16 394 */ 395 int OH_Value_GetFloatVectorCount(OH_Data_Value *value, size_t *length); 396 397 /** 398 * @brief Get float array from OH_Data_Value object. 399 * 400 * @param value Represents a pointer to an instance of OH_Data_Value. 401 * @param val Represents a pointer to float array. The caller needs to apply for data memory. 402 * This function only fills data. Otherwise, the execution fails. 403 * @param inLen Represents the size of val. It can be obtained through the OH_Value_GetFloatVectorCount function. 404 * @param outLen Represents the actual amount of data obtained. It is an output parameter. 405 * @return Returns the error code. 406 * Returns {@link RDB_OK} if the execution is successful. 407 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 408 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 409 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 410 * @see OH_Value_GetFloatVectorCount. 411 * @since 16 412 */ 413 int OH_Value_GetFloatVector(OH_Data_Value *value, float *val, size_t inLen, size_t *outLen); 414 415 /** 416 * @brief Get an integer of any length data size from OH_Data_Value object. 417 * 418 * @param value Represents a pointer to an instance of OH_Data_Value. 419 * @param length Represents the size of integer array. It is an output parameter. 420 * @return Returns the error code. 421 * Returns {@link RDB_OK} if the execution is successful. 422 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 423 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 424 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 425 * @since 16 426 */ 427 int OH_Value_GetUnlimitedIntBand(OH_Data_Value *value, size_t *length); 428 429 /** 430 * @brief Get an integer of any length data from OH_Data_Value object. 431 * 432 * @param value Represents a pointer to an instance of OH_Data_Value. 433 * @param sign Represents 0 is positive integer, 1 is negative integer. It is an output parameter. 434 * @param trueForm Represents a pointer to integer array. The caller needs to apply for data memory. 435 * This function only fills data. Otherwise, the execution fails. 436 * @param inLen Represents the size of trueForm. It can be obtained through the OH_Value_GetUnlimitedIntBand function. 437 * @param outLen Represents the actual amount of data obtained. It is an output parameter. 438 * @return Returns the error code. 439 * Returns {@link RDB_OK} if the execution is successful. 440 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 441 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 442 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 443 * @see OH_Value_GetUnlimitedIntBand. 444 * @since 16 445 */ 446 int OH_Value_GetUnlimitedInt(OH_Data_Value *value, int *sign, uint64_t *trueForm, size_t inLen, size_t *outLen); 447 448 #ifdef __cplusplus 449 }; 450 #endif 451 #endif 452 /** @} */