1 /* 2 * Copyright (c) 2023 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_cursor.h 30 * 31 * @brief Provides functions and enumerations related to the resultSet. 32 * 33 * @kit ArkData 34 * @library libnative_rdb_ndk.so 35 * @syscap SystemCapability.DistributedDataManager.RelationalStore.Core 36 * @since 10 37 */ 38 39 #ifndef OH_CURSOR_H 40 #define OH_CURSOR_H 41 42 #ifdef __cplusplus 43 #include <cstdint> 44 #else 45 #include <stdint.h> 46 #endif 47 48 #include <stddef.h> 49 #include <stdbool.h> 50 #include "database/data/data_asset.h" 51 #include "database/data/oh_data_value.h" 52 #ifdef __cplusplus 53 extern "C" { 54 #endif 55 56 /** 57 * @brief Define the OH_Cursor structure type. 58 * 59 * Provides methods for accessing a database result set generated by query the database. 60 * 61 * @since 10 62 */ 63 typedef struct OH_Cursor OH_Cursor; 64 65 /** 66 * @brief Define the OH_Cursor structure type. 67 * 68 * Provides methods for accessing a database result set generated by query the database. 69 * 70 * @since 10 71 */ 72 struct OH_Cursor { 73 /** 74 * The id used to uniquely identify the OH_Cursor struct. 75 */ 76 int64_t id; 77 /** 78 * @brief Function pointer. Obtains the total number of columns. 79 * 80 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 81 * @param count This parameter is the output parameter, and the number of columns is written to this variable. 82 * @return Returns the status code of the execution. 83 * @see OH_Cursor. 84 * @since 10 85 */ 86 int (*getColumnCount)(OH_Cursor *cursor, int *count); 87 88 /** 89 * @brief Function pointer. Obtains data type of the given column's value. 90 * 91 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 92 * @param columnIndex Indicates the zero-based index of the target column. 93 * @param columnType This parameter is the output parameter, and the column value type is written to this variable. 94 * @return Returns the status code of the execution. 95 * @see OH_Cursor, OH_ColumnType. 96 * @since 10 97 */ 98 int (*getColumnType)(OH_Cursor *cursor, int32_t columnIndex, OH_ColumnType *columnType); 99 100 /** 101 * @brief Function pointer. Obtains the zero-based index for the given column name. 102 * 103 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 104 * @param name Indicates the name of the column. 105 * @param columnIndex This parameter is the output parameter, 106 * and the column index for the given column is written to this variable. 107 * @return Returns the status code of the execution. 108 * @see OH_Cursor. 109 * @since 10 110 */ 111 int (*getColumnIndex)(OH_Cursor *cursor, const char *name, int *columnIndex); 112 113 /** 114 * @brief Function pointer. Obtains the column name at the given column index. 115 * 116 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 117 * @param columnIndex Indicates the zero-based column index. 118 * @param name This parameter is the output parameter, 119 * and the column name for the given index is written to this variable. 120 * @param length Indicates the length of the name. 121 * @return Returns the status code of the execution. 122 * @see OH_Cursor. 123 * @since 10 124 */ 125 int (*getColumnName)(OH_Cursor *cursor, int32_t columnIndex, char *name, int length); 126 127 /** 128 * @brief Function pointer. Obtains the numbers of rows in the result set. 129 * 130 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 131 * @param count This parameter is the output parameter, 132 * and the numbers of rows in the result set is written to this variable. 133 * @return Returns the status code of the execution. 134 * @see OH_Cursor. 135 * @since 10 136 */ 137 int (*getRowCount)(OH_Cursor *cursor, int *count); 138 139 /** 140 * @brief Function pointer. Move the cursor to the next row. 141 * 142 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 143 * @return Returns the status code of the execution. 144 * @see OH_Cursor. 145 * @since 10 146 */ 147 int (*goToNextRow)(OH_Cursor *cursor); 148 149 /** 150 * @brief Function pointer. Obtains the size of blob or text. 151 * 152 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 153 * @param columnIndex Indicates the zero-based column index. 154 * @param size This parameter is the output parameter, 155 * and the value size of the requested column is written to this variable. 156 * @return Returns the status code of the execution. 157 * @see OH_Cursor. 158 * @since 10 159 */ 160 int (*getSize)(OH_Cursor *cursor, int32_t columnIndex, size_t *size); 161 162 /** 163 * @brief Function pointer. Obtains the value of the requested column as a string. 164 * 165 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 166 * @param columnIndex Indicates the zero-based column index. 167 * @param value This parameter is the output parameter, 168 * and the value of the requested column as a char * is written to this variable. 169 * @param length Indicates the length of the value, it can be obtained through the OH_Cursor_GetSize function. 170 * @return Returns the status code of the execution. 171 * @see OH_Cursor. 172 * @since 10 173 */ 174 int (*getText)(OH_Cursor *cursor, int32_t columnIndex, char *value, int length); 175 176 /** 177 * @brief Function pointer. Obtains the value of the requested column as a int64_t. 178 * 179 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 180 * @param columnIndex Indicates the zero-based column index. 181 * @param value This parameter is the output parameter, 182 * and the value of the requested column as a int64_t is written to this variable. 183 * @return Returns the status code of the execution. 184 * @see OH_Cursor. 185 * @since 10 186 */ 187 int (*getInt64)(OH_Cursor *cursor, int32_t columnIndex, int64_t *value); 188 189 /** 190 * @brief Function pointer. Obtains the value of the requested column as a double. 191 * 192 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 193 * @param columnIndex Indicates the zero-based column index. 194 * @param value This parameter is the output parameter, 195 * and the value of the requested column as a double is written to this variable. 196 * @return Returns the status code of the execution. 197 * @see OH_Cursor. 198 * @since 10 199 */ 200 int (*getReal)(OH_Cursor *cursor, int32_t columnIndex, double *value); 201 202 /** 203 * @brief Function pointer. Obtains the value of the requested column as a byte array. 204 * 205 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 206 * @param columnIndex Indicates the zero-based column index. 207 * @param value This parameter is the output parameter, 208 * and the value of the requested column as a byte array is written to this variable. 209 * @param length Indicates the length of the value, it can be obtained through the OH_Cursor_GetSize function. 210 * @return Returns the status code of the execution. 211 * @see OH_Cursor. 212 * @since 10 213 */ 214 int (*getBlob)(OH_Cursor *cursor, int32_t columnIndex, unsigned char *value, int length); 215 216 /** 217 * @brief Function pointer. Obtains Whether the value of the requested column is null. 218 * 219 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 220 * @param columnIndex Indicates the zero-based column index. 221 * @param isNull This parameter is the output parameter, 222 * and the value whether the column value is null is written to this variable. 223 * @return Returns the status code of the execution. 224 * @see OH_Cursor. 225 * @since 10 226 */ 227 int (*isNull)(OH_Cursor *cursor, int32_t columnIndex, bool *isNull); 228 229 /** 230 * @brief Function pointer. Destroy the result set, releasing all of its resources and making it completely invalid. 231 * 232 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 233 * @return Returns the status code of the execution. 234 * @see OH_Cursor. 235 * @since 10 236 */ 237 int (*destroy)(OH_Cursor *cursor); 238 239 /** 240 * @brief Function pointer. Obtains the value of the requested column as an {@link Data_Asset} instance. 241 * 242 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 243 * @param columnIndex Indicates the zero-based column index. 244 * @param value This parameter is the output parameter, 245 * and the value of the requested column as an {@link Data_Asset} instance is written to this variable. 246 * @return Returns the status code of the execution. 247 * @see OH_Cursor. 248 * @since 11 249 */ 250 int (*getAsset)(OH_Cursor *cursor, int32_t columnIndex, Data_Asset *value); 251 252 /** 253 * @brief Function pointer. Obtains the value of the requested column as an {@link Data_Asset} instance. 254 * 255 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 256 * @param columnIndex Indicates the zero-based column index. 257 * @param value This parameter is the output parameter, 258 * and the value of the requested column as an {@link Data_Asset} instance is written to this variable. 259 * @param length Indicates the length of the value. 260 * @return Returns the status code of the execution. 261 * @see OH_Cursor. 262 * @since 11 263 */ 264 int (*getAssets)(OH_Cursor *cursor, int32_t columnIndex, Data_Asset **value, uint32_t *length); 265 }; 266 267 /** 268 * @brief Get float array data size of the requested column from OH_Cursor object. 269 * 270 * @param cursor Represents a pointer to an instance of OH_Cursor. 271 * @param columnIndex Indicates the zero-based column index. 272 * @param length Represents the size of float array. It is an output parameter. 273 * @return Returns the status code of the execution. 274 * Returns {@link RDB_OK} if the execution is successful. 275 * Returns {@link RDB_E_ERROR} database common error. 276 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 277 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 278 * Returns {@link RDB_E_STEP_RESULT_CLOSED} the result set has been closed. 279 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 280 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 281 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 282 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 283 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 284 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 285 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 286 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 287 * @since 18 288 */ 289 int OH_Cursor_GetFloatVectorCount(OH_Cursor *cursor, int32_t columnIndex, size_t *length); 290 291 /** 292 * @brief Obtains the value of the requested column as a float array. 293 * 294 * @param cursor Represents a pointer to an instance of OH_Cursor. 295 * @param columnIndex Indicates the zero-based column index. 296 * @param val Represents a pointer to float array. The caller needs to apply for data memory. 297 * This function only fills data. Otherwise, the execution fails. 298 * @param inLen Represents the size of val. It can be obtained through the OH_Cursor_GetFloatVectorCount function. 299 * @param outLen Represents the actual amount of data obtained. It is an output parameter. 300 * @return Returns the status code of the execution. 301 * Returns {@link RDB_OK} if the execution is successful. 302 * Returns {@link RDB_E_ERROR} database common error. 303 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 304 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 305 * Returns {@link RDB_E_STEP_RESULT_CLOSED} the result set has been closed. 306 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 307 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 308 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 309 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 310 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 311 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 312 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 313 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 314 * @see OH_Cursor_GetFloatVectorCount. 315 * @since 18 316 */ 317 int OH_Cursor_GetFloatVector(OH_Cursor *cursor, int32_t columnIndex, float *val, size_t inLen, size_t *outLen); 318 319 #ifdef __cplusplus 320 }; 321 #endif 322 323 /** @} */ 324 325 #endif // OH_CURSOR_H 326