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. Ture is empty, false is not empty. 247 * @return Returns the error code. 248 * Returns {@link RDB_OK} if the execution is successful. 249 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 250 * @since 18 251 */ 252 int OH_Values_IsNull(OH_Data_Values *values, int index, bool *val); 253 254 /** 255 * @brief Get integer data from OH_Data_Values object. 256 * 257 * @param values Represents a pointer to an instance of OH_Data_Values. 258 * @param index Represents the zero-based index of target data in values. 259 * @param val Represents a pointer to an integer data. It is an output parameter. 260 * @return Returns the error code. 261 * Returns {@link RDB_OK} if the execution is successful. 262 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 263 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 264 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 265 * @since 18 266 */ 267 int OH_Values_GetInt(OH_Data_Values *values, int index, int64_t *val); 268 269 /** 270 * @brief Get decimal data from OH_Data_Values object. 271 * 272 * @param values Represents a pointer to an instance of OH_Data_Values. 273 * @param index Represents the zero-based index of target data in values. 274 * @param val Represents a pointer to an decimal data. It is an output parameter. 275 * @return Returns the error code. 276 * Returns {@link RDB_OK} if the execution is successful. 277 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 278 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 279 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 280 * @since 18 281 */ 282 int OH_Values_GetReal(OH_Data_Values *values, int index, double *val); 283 284 /** 285 * @brief Get string data from OH_Data_Values object. 286 * 287 * @param values Represents a pointer to an instance of OH_Data_Values. 288 * @param index Represents the zero-based index of target data in values. 289 * @param val Represents a pointer to a string data. It is an output parameter. 290 * The caller does not need to apply for memory and release memory. 291 * The life cycle of val follows the value of index in values. 292 * @return Returns the error code. 293 * Returns {@link RDB_OK} if the execution is successful. 294 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 295 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 296 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 297 * @since 18 298 */ 299 int OH_Values_GetText(OH_Data_Values *values, int index, const char **val); 300 301 /** 302 * @brief Get binary data from OH_Data_Values object. 303 * 304 * @param values Represents a pointer to an instance of OH_Data_Values. 305 * @param index Represents the zero-based index of target data in values. 306 * @param val Represents a pointer to a binary data. It is an output parameter. 307 * The caller does not need to apply for memory and release memory. 308 * The life cycle of val follows the value of index in values. 309 * @param length Represents the size of binary array. 310 * @return Returns the error code. 311 * Returns {@link RDB_OK} if the execution is successful. 312 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 313 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 314 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 315 * @since 18 316 */ 317 int OH_Values_GetBlob(OH_Data_Values *values, int index, const uint8_t **val, size_t *length); 318 319 /** 320 * @brief Get Data_Asset data from OH_Data_Values object. 321 * 322 * @param values Represents a pointer to an instance of OH_Data_Values. 323 * @param index Represents the zero-based index of target data in values. 324 * @param val Represents a pointer to an instance of Data_Asset. The caller needs to apply for data memory. 325 * This function only fills data. Otherwise, the execution fails. 326 * @return Returns the error code. 327 * Returns {@link RDB_OK} if the execution is successful. 328 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 329 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 330 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 331 * @since 18 332 */ 333 int OH_Values_GetAsset(OH_Data_Values *values, int index, Data_Asset *val); 334 335 /** 336 * @brief Get multiple Data_Asset size from OH_Data_Values object. 337 * 338 * @param values Represents a pointer to an instance of OH_Data_Values. 339 * @param index Represents the zero-based index of target data in values. 340 * @param length Represents the size of Data_Asset array. It is an output parameter. 341 * @return Returns the error code. 342 * Returns {@link RDB_OK} if the execution is successful. 343 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 344 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 345 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 346 * @since 18 347 */ 348 int OH_Values_GetAssetsCount(OH_Data_Values *values, int index, size_t *length); 349 350 /** 351 * @brief Get multiple Data_Asset data from OH_Data_Values object. 352 * 353 * @param values Represents a pointer to an instance of OH_Data_Values. 354 * @param index Represents the zero-based index of target data in values. 355 * @param val Represents a pointer to Data_Asset array. The caller needs to apply for data memory. 356 * This function only fills data. Otherwise, the execution fails. 357 * @param inLen Represents the size of val. It can be obtained through the OH_Values_GetAssetsCount function. 358 * @param outLen Represents the actual amount of data obtained. It is an output parameter. 359 * @return Returns the error code. 360 * Returns {@link RDB_OK} if the execution is successful. 361 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 362 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 363 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 364 * @see OH_Values_GetAssetsCount. 365 * @since 18 366 */ 367 int OH_Values_GetAssets(OH_Data_Values *values, int index, Data_Asset **val, size_t inLen, size_t *outLen); 368 369 /** 370 * @brief Get float array data size from OH_Data_Values object. 371 * 372 * @param values Represents a pointer to an instance of OH_Data_Values. 373 * @param index Represents the zero-based index of target data in values. 374 * @param length Represents the size of float array. It is an output parameter. 375 * @return Returns the error code. 376 * Returns {@link RDB_OK} if the execution is successful. 377 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 378 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 379 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 380 * @since 18 381 */ 382 int OH_Values_GetFloatVectorCount(OH_Data_Values *values, int index, size_t *length); 383 384 /** 385 * @brief Get float array from OH_Data_Values object. 386 * 387 * @param values Represents a pointer to an instance of OH_Data_Values. 388 * @param index Represents the zero-based index of target data in values. 389 * @param val Represents a pointer to float array. The caller needs to apply for data memory. 390 * This function only fills data. Otherwise, the execution fails. 391 * @param inLen Represents the size of val. It can be obtained through the OH_Values_GetFloatVectorCount function. 392 * @param outLen Represents the actual amount of data obtained. It is an output parameter. 393 * @return Returns the error code. 394 * Returns {@link RDB_OK} if the execution is successful. 395 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 396 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 397 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 398 * @see OH_Values_GetFloatVectorCount. 399 * @since 18 400 */ 401 int OH_Values_GetFloatVector(OH_Data_Values *values, int index, float *val, size_t inLen, size_t *outLen); 402 403 /** 404 * @brief Get an integer of any length data size from OH_Data_Values object. 405 * 406 * @param values Represents a pointer to an instance of OH_Data_Values. 407 * @param index Represents the zero-based index of target data in values. 408 * @param length Represents the size of integer array. It is an output parameter. 409 * @return Returns the error code. 410 * Returns {@link RDB_OK} if the execution is successful. 411 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 412 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 413 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 414 * @since 18 415 */ 416 int OH_Values_GetUnlimitedIntBand(OH_Data_Values *values, int index, size_t *length); 417 418 /** 419 * @brief Get an integer of any length data from OH_Data_Values object. 420 * 421 * @param values Represents a pointer to an instance of OH_Data_Values. 422 * @param index Represents the zero-based index of target data in values. 423 * @param sign Represents 0 is positive integer, 1 is negative integer. It is an output parameter. 424 * @param trueForm Represents a pointer to integer array. The caller needs to apply for data memory. 425 * This function only fills data. Otherwise, the execution fails. 426 * @param inLen Represents the size of trueForm. It can be obtained through the OH_Values_GetUnlimitedIntBand function. 427 * @param outLen Represents the actual amount of data obtained. It is an output parameter. 428 * @return Returns the error code. 429 * Returns {@link RDB_OK} if the execution is successful. 430 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 431 * Returns {@link RDB_E_DATA_TYPE_NULL} the content stored in parameter value is null. 432 * Returns {@link RDB_E_TYPE_MISMATCH} storage data type mismatch. 433 * @see OH_Values_GetUnlimitedIntBand. 434 * @since 18 435 */ 436 int OH_Values_GetUnlimitedInt(OH_Data_Values *values, int index, int *sign, uint64_t *trueForm, size_t inLen, 437 size_t *outLen); 438 439 #ifdef __cplusplus 440 }; 441 #endif 442 #endif 443 /** @} */