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_values.h 30 * 31 * @brief Provides functions and enumerations related to the data values. 32 * 33 * @kit ArkData 34 * @library libnative_rdb_ndk.z.so 35 * @syscap SystemCapability.DistributedDataManager.RelationalStore.Core 36 * 37 * @since 18 38 */ 39 #ifndef OH_DATA_VALUES_H 40 #define OH_DATA_VALUES_H 41 #include <inttypes.h> 42 43 #include "database/data/data_asset.h" 44 #include "database/data/oh_data_value.h" 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @brief Define the OH_Data_Values structure type. 51 * 52 * @since 18 53 */ 54 typedef struct OH_Data_Values OH_Data_Values; 55 56 /** 57 * @brief Creates an OH_Data_Values instance object. 58 * 59 * @return Returns a pointer to OH_Data_Values instance when the execution is successful. 60 * Otherwise, nullptr is returned. The memory must be released through the OH_Values_Destroy 61 * interface after the use is complete. 62 * @see OH_Values_Destroy. 63 * @since 18 64 */ 65 OH_Data_Values *OH_Values_Create(void); 66 67 /** 68 * @brief Destroys an OH_Data_Values instance object. 69 * 70 * @param values Represents a pointer to an instance of OH_Data_Values. 71 * @return Returns the error code. 72 * Returns {@link RDB_OK} if the execution is successful. 73 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 74 * @since 18 75 */ 76 int OH_Values_Destroy(OH_Data_Values *values); 77 78 /** 79 * @brief Add OH_Data_Value data to the OH_Data_Values object. 80 * 81 * @param values Represents a pointer to an instance of OH_Data_Values. 82 * @param val Represents a pointer to an instance of OH_Data_Value. 83 * @return Returns the error code. 84 * Returns {@link RDB_OK} if the execution is successful. 85 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 86 * @since 18 87 */ 88 int OH_Values_Put(OH_Data_Values *values, const OH_Data_Value *val); 89 90 /** 91 * @brief Add empty data to the OH_Data_Values object. 92 * 93 * @param values Represents a pointer to an instance of OH_Data_Values. 94 * @return Returns the error code. 95 * Returns {@link RDB_OK} if the execution is successful. 96 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 97 * @since 18 98 */ 99 int OH_Values_PutNull(OH_Data_Values *values); 100 101 /** 102 * @brief Add integer data to the OH_Data_Values object. 103 * 104 * @param values Represents a pointer to an instance of OH_Data_Values. 105 * @param val Represents a integer data. 106 * @return Returns the error code. 107 * Returns {@link RDB_OK} if the execution is successful. 108 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 109 * @since 18 110 */ 111 int OH_Values_PutInt(OH_Data_Values *values, int64_t val); 112 113 /** 114 * @brief Add decimal data to the OH_Data_Values object. 115 * 116 * @param values Represents a pointer to an instance of OH_Data_Values. 117 * @param val Represents a decimal data. 118 * @return Returns the error code. 119 * Returns {@link RDB_OK} if the execution is successful. 120 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 121 * @since 18 122 */ 123 int OH_Values_PutReal(OH_Data_Values *values, double val); 124 125 /** 126 * @brief Add string data to the OH_Data_Values object. 127 * 128 * @param values Represents a pointer to an instance of OH_Data_Values. 129 * @param val Represents a string data. 130 * @return Returns the error code. 131 * Returns {@link RDB_OK} if the execution is successful. 132 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 133 * @since 18 134 */ 135 int OH_Values_PutText(OH_Data_Values *values, const char *val); 136 137 /** 138 * @brief Add binary data to the OH_Data_Values object. 139 * 140 * @param values Represents a pointer to an instance of OH_Data_Values. 141 * @param val Represents a binary data. 142 * @param length Represents the size of binary data. 143 * @return Returns the error code. 144 * Returns {@link RDB_OK} if the execution is successful. 145 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 146 * @since 18 147 */ 148 int OH_Values_PutBlob(OH_Data_Values *values, const unsigned char *val, size_t length); 149 150 /** 151 * @brief Add Data_Asset data to the OH_Data_Values object. 152 * 153 * @param values Represents a pointer to an instance of OH_Data_Values. 154 * @param val Represents a pointer to an instance of Data_Asset. 155 * @return Returns the error code. 156 * Returns {@link RDB_OK} if the execution is successful. 157 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 158 * @since 18 159 */ 160 int OH_Values_PutAsset(OH_Data_Values *values, const Data_Asset *val); 161 162 /** 163 * @brief Add multiple Data_Asset data to the OH_Data_Values object. 164 * 165 * @param values Represents a pointer to an instance of OH_Data_Values. 166 * @param val Represents a pointer to multiple Data_Asset. 167 * @param length Represents the count of multiple data. 168 * @return Returns the error code. 169 * Returns {@link RDB_OK} if the execution is successful. 170 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 171 * @since 18 172 */ 173 int OH_Values_PutAssets(OH_Data_Values *values, const Data_Asset * const * val, size_t length); 174 175 /** 176 * @brief Add float array data to the OH_Data_Values object. 177 * 178 * @param values Represents a pointer to an instance of OH_Data_Values. 179 * @param val Represents a pointer to float array. 180 * @param length Represents the size of float array. 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_Values_PutFloatVector(OH_Data_Values *values, const float *val, size_t length); 187 188 /** 189 * @brief Add an integer of any length data to the OH_Data_Values object. 190 * 191 * @param values Represents a pointer to an instance of OH_Data_Values. 192 * @param sign Represents 0 is positive integer, 1 is negative integer. 193 * @param trueForm Represents a pointer to integer array. 194 * @param length Represents the size of integer array. 195 * @return Returns the error code. 196 * Returns {@link RDB_OK} if the execution is successful. 197 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 198 * @since 18 199 */ 200 int OH_Values_PutUnlimitedInt(OH_Data_Values *values, int sign, const uint64_t *trueForm, size_t length); 201 202 /** 203 * @brief Get data count from OH_Data_Values object. 204 * 205 * @param values Represents a pointer to an instance of OH_Data_Values. 206 * @param count Represents the count of data in values. It is an output parameter. 207 * @return Returns the error code. 208 * Returns {@link RDB_OK} if the execution is successful. 209 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 210 * @since 18 211 */ 212 int OH_Values_Count(OH_Data_Values *values, size_t *count); 213 214 /** 215 * @brief Get data type from OH_Data_Values object. 216 * 217 * @param values Represents a pointer to an instance of OH_Data_Values. 218 * @param index Represents the zero-based index of target data in values. 219 * @param type Represents the parameter of the data type. It is an output parameter. 220 * @return Returns the error code. 221 * Returns {@link RDB_OK} if the execution is successful. 222 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 223 * @since 18 224 */ 225 int OH_Values_GetType(OH_Data_Values *values, int index, OH_ColumnType *type); 226 227 /** 228 * @brief Get OH_Data_Value data from OH_Data_Values object. 229 * 230 * @param values Represents a pointer to an instance of OH_Data_Values. 231 * @param index Represents the zero-based index of target data in values. 232 * @param val Represents a pointer to an instance of OH_Data_Value. It is an output parameter. 233 * The caller does not need to apply for memory and release memory. 234 * @return Returns the error code. 235 * Returns {@link RDB_OK} if the execution is successful. 236 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 237 * @since 18 238 */ 239 int OH_Values_Get(OH_Data_Values *values, int index, OH_Data_Value **val); 240 241 /** 242 * @brief Check whether the data is empty from OH_Data_Values object. 243 * 244 * @param values Represents a pointer to an instance of OH_Data_Values. 245 * @param index Represents the zero-based index of target data in values. 246 * @param val Represents empty data flag. It is an output parameter. 247 * The value true means that the data is empty, and false means the opposite. 248 * @return Returns the error code. 249 * Returns {@link RDB_OK} if the execution is successful. 250 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 251 * @since 18 252 */ 253 int OH_Values_IsNull(OH_Data_Values *values, int index, bool *val); 254 255 /** 256 * @brief Get integer data from OH_Data_Values object. 257 * 258 * @param values Represents a pointer to an instance of OH_Data_Values. 259 * @param index Represents the zero-based index of target data in values. 260 * @param val Represents a pointer to an integer data. It is an output parameter. 261 * @return Returns the error code. 262 * Returns {@link RDB_OK} if the execution is successful. 263 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 264 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 265 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 266 * @since 18 267 */ 268 int OH_Values_GetInt(OH_Data_Values *values, int index, int64_t *val); 269 270 /** 271 * @brief Get decimal data from OH_Data_Values object. 272 * 273 * @param values Represents a pointer to an instance of OH_Data_Values. 274 * @param index Represents the zero-based index of target data in values. 275 * @param val Represents a pointer to an decimal data. It is an output parameter. 276 * @return Returns the error code. 277 * Returns {@link RDB_OK} if the execution is successful. 278 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 279 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 280 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 281 * @since 18 282 */ 283 int OH_Values_GetReal(OH_Data_Values *values, int index, double *val); 284 285 /** 286 * @brief Get string data from OH_Data_Values object. 287 * 288 * @param values Represents a pointer to an instance of OH_Data_Values. 289 * @param index Represents the zero-based index of target data in values. 290 * @param val Represents a pointer to a string data. It is an output parameter. 291 * The caller does not need to apply for memory and release memory. 292 * The life cycle of val follows the value of index in values. 293 * @return Returns the error code. 294 * Returns {@link RDB_OK} if the execution is successful. 295 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 296 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 297 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 298 * @since 18 299 */ 300 int OH_Values_GetText(OH_Data_Values *values, int index, const char **val); 301 302 /** 303 * @brief Get binary data from OH_Data_Values object. 304 * 305 * @param values Represents a pointer to an instance of OH_Data_Values. 306 * @param index Represents the zero-based index of target data in values. 307 * @param val Represents a pointer to a binary data. It is an output parameter. 308 * The caller does not need to apply for memory and release memory. 309 * The life cycle of val follows the value of index in values. 310 * @param length Represents the size of binary array. 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 18 317 */ 318 int OH_Values_GetBlob(OH_Data_Values *values, int index, const uint8_t **val, size_t *length); 319 320 /** 321 * @brief Get Data_Asset data from OH_Data_Values object. 322 * 323 * @param values Represents a pointer to an instance of OH_Data_Values. 324 * @param index Represents the zero-based index of target data in values. 325 * @param val Represents a pointer to an instance of Data_Asset. The caller needs to apply for data memory. 326 * This function only fills data. Otherwise, the execution fails. 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 18 333 */ 334 int OH_Values_GetAsset(OH_Data_Values *values, int index, Data_Asset *val); 335 336 /** 337 * @brief Get multiple Data_Asset size from OH_Data_Values object. 338 * 339 * @param values Represents a pointer to an instance of OH_Data_Values. 340 * @param index Represents the zero-based index of target data in values. 341 * @param length Represents the size of Data_Asset array. It is an output parameter. 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 18 348 */ 349 int OH_Values_GetAssetsCount(OH_Data_Values *values, int index, size_t *length); 350 351 /** 352 * @brief Get multiple Data_Asset data from OH_Data_Values object. 353 * 354 * @param values Represents a pointer to an instance of OH_Data_Values. 355 * @param index Represents the zero-based index of target data in values. 356 * @param val Represents a pointer to Data_Asset array. The caller needs to apply for data memory. 357 * This function only fills data. Otherwise, the execution fails. 358 * @param inLen Represents the size of val. It can be obtained through the OH_Values_GetAssetsCount function. 359 * @param outLen Represents the actual amount of data obtained. It is an output parameter. 360 * @return Returns the error code. 361 * Returns {@link RDB_OK} if the execution is successful. 362 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 363 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 364 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 365 * @see OH_Values_GetAssetsCount. 366 * @since 18 367 */ 368 int OH_Values_GetAssets(OH_Data_Values *values, int index, Data_Asset **val, size_t inLen, size_t *outLen); 369 370 /** 371 * @brief Get float array data size from OH_Data_Values object. 372 * 373 * @param values Represents a pointer to an instance of OH_Data_Values. 374 * @param index Represents the zero-based index of target data in values. 375 * @param length Represents the size of float array. It is an output parameter. 376 * @return Returns the error code. 377 * Returns {@link RDB_OK} if the execution is successful. 378 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 379 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 380 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 381 * @since 18 382 */ 383 int OH_Values_GetFloatVectorCount(OH_Data_Values *values, int index, size_t *length); 384 385 /** 386 * @brief Get float array from OH_Data_Values object. 387 * 388 * @param values Represents a pointer to an instance of OH_Data_Values. 389 * @param index Represents the zero-based index of target data in values. 390 * @param val Represents a pointer to float array. The caller needs to apply for data memory. 391 * This function only fills data. Otherwise, the execution fails. 392 * @param inLen Represents the size of val. It can be obtained through the OH_Values_GetFloatVectorCount function. 393 * @param outLen Represents the actual amount of data obtained. It is an output parameter. 394 * @return Returns the error code. 395 * Returns {@link RDB_OK} if the execution is successful. 396 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 397 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 398 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 399 * @see OH_Values_GetFloatVectorCount. 400 * @since 18 401 */ 402 int OH_Values_GetFloatVector(OH_Data_Values *values, int index, float *val, size_t inLen, size_t *outLen); 403 404 /** 405 * @brief Get an integer of any length data size from OH_Data_Values object. 406 * 407 * @param values Represents a pointer to an instance of OH_Data_Values. 408 * @param index Represents the zero-based index of target data in values. 409 * @param length Represents the size of integer array. It is an output parameter. 410 * @return Returns the error code. 411 * Returns {@link RDB_OK} if the execution is successful. 412 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 413 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 414 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 415 * @since 18 416 */ 417 int OH_Values_GetUnlimitedIntBand(OH_Data_Values *values, int index, size_t *length); 418 419 /** 420 * @brief Get an integer of any length data from OH_Data_Values object. 421 * 422 * @param values Represents a pointer to an instance of OH_Data_Values. 423 * @param index Represents the zero-based index of target data in values. 424 * @param sign Represents 0 is positive integer, 1 is negative integer. It is an output parameter. 425 * @param trueForm Represents a pointer to integer array. The caller needs to apply for data memory. 426 * This function only fills data. Otherwise, the execution fails. 427 * @param inLen Represents the size of trueForm. It can be obtained through the OH_Values_GetUnlimitedIntBand function. 428 * @param outLen Represents the actual amount of data obtained. It is an output parameter. 429 * @return Returns the error code. 430 * Returns {@link RDB_OK} if the execution is successful. 431 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 432 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 433 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 434 * @see OH_Values_GetUnlimitedIntBand. 435 * @since 18 436 */ 437 int OH_Values_GetUnlimitedInt(OH_Data_Values *values, int index, int *sign, uint64_t *trueForm, size_t inLen, 438 size_t *outLen); 439 440 #ifdef __cplusplus 441 }; 442 #endif 443 #endif 444 /** @} */