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