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 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 55 /** 56 * @brief Indicates the column type. 57 * 58 * @since 10 59 */ 60 typedef enum OH_ColumnType { 61 /** 62 * Indicates the column type is NULL. 63 */ 64 TYPE_NULL = 0, 65 /** 66 * Indicates the column type is INT64. 67 */ 68 TYPE_INT64, 69 /** 70 * Indicates the column type is REAL. 71 */ 72 TYPE_REAL, 73 /** 74 * Indicates the column type is TEXT. 75 */ 76 TYPE_TEXT, 77 /** 78 * Indicates the column type is BLOB. 79 */ 80 TYPE_BLOB, 81 /** 82 * Indicates the column type is {@link Data_Asset}. 83 * 84 * @since 11 85 */ 86 TYPE_ASSET, 87 /** 88 * Indicates the column type is array of {@link Data_Asset}. 89 * 90 * @since 11 91 */ 92 TYPE_ASSETS 93 } OH_ColumnType; 94 95 /** 96 * @brief Define the OH_Cursor structure type. 97 * 98 * Provides methods for accessing a database result set generated by query the database. 99 * 100 * @since 10 101 */ 102 typedef struct OH_Cursor OH_Cursor; 103 104 /** 105 * @brief Define the OH_Cursor structure type. 106 * 107 * Provides methods for accessing a database result set generated by query the database. 108 * 109 * @since 10 110 */ 111 struct OH_Cursor { 112 /** 113 * The id used to uniquely identify the OH_Cursor struct. 114 */ 115 int64_t id; 116 /** 117 * @brief Function pointer. Obtains the total number of columns. 118 * 119 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 120 * @param count This parameter is the output parameter, and the number of columns is written to this variable. 121 * @return Returns the status code of the execution. 122 * @see OH_Cursor. 123 * @since 10 124 */ 125 int (*getColumnCount)(OH_Cursor *cursor, int *count); 126 127 /** 128 * @brief Function pointer. Obtains data type of the given column's value. 129 * 130 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 131 * @param columnIndex Indicates the zero-based index of the target column. 132 * @param columnType This parameter is the output parameter, and the column value type is written to this variable. 133 * @return Returns the status code of the execution. 134 * @see OH_Cursor, OH_ColumnType. 135 * @since 10 136 */ 137 int (*getColumnType)(OH_Cursor *cursor, int32_t columnIndex, OH_ColumnType *columnType); 138 139 /** 140 * @brief Function pointer. Obtains the zero-based index for the given column name. 141 * 142 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 143 * @param name Indicates the name of the column. 144 * @param columnIndex This parameter is the output parameter, 145 * and the column index for the given column is written to this variable. 146 * @return Returns the status code of the execution. 147 * @see OH_Cursor. 148 * @since 10 149 */ 150 int (*getColumnIndex)(OH_Cursor *cursor, const char *name, int *columnIndex); 151 152 /** 153 * @brief Function pointer. Obtains the column name at the given column index. 154 * 155 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 156 * @param columnIndex Indicates the zero-based column index. 157 * @param name This parameter is the output parameter, 158 * and the column name for the given index is written to this variable. 159 * @param length Indicates the length of the name. 160 * @return Returns the status code of the execution. 161 * @see OH_Cursor. 162 * @since 10 163 */ 164 int (*getColumnName)(OH_Cursor *cursor, int32_t columnIndex, char *name, int length); 165 166 /** 167 * @brief Function pointer. Obtains the numbers of rows in the result set. 168 * 169 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 170 * @param count This parameter is the output parameter, 171 * and the numbers of rows in the result set is written to this variable. 172 * @return Returns the status code of the execution. 173 * @see OH_Cursor. 174 * @since 10 175 */ 176 int (*getRowCount)(OH_Cursor *cursor, int *count); 177 178 /** 179 * @brief Function pointer. Move the cursor to the next row. 180 * 181 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 182 * @return Returns the status code of the execution. 183 * @see OH_Cursor. 184 * @since 10 185 */ 186 int (*goToNextRow)(OH_Cursor *cursor); 187 188 /** 189 * @brief Function pointer. Obtains the size of blob or text. 190 * 191 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 192 * @param columnIndex Indicates the zero-based column index. 193 * @param size This parameter is the output parameter, 194 * and the value size of the requested column is written to this variable. 195 * @return Returns the status code of the execution. 196 * @see OH_Cursor. 197 * @since 10 198 */ 199 int (*getSize)(OH_Cursor *cursor, int32_t columnIndex, size_t *size); 200 201 /** 202 * @brief Function pointer. Obtains the value of the requested column as a string. 203 * 204 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 205 * @param columnIndex Indicates the zero-based column index. 206 * @param value This parameter is the output parameter, 207 * and the value of the requested column as a char * is written to this variable. 208 * @param length Indicates the length of the value, it can be obtained through the OH_Cursor_GetSize function. 209 * @return Returns the status code of the execution. 210 * @see OH_Cursor. 211 * @since 10 212 */ 213 int (*getText)(OH_Cursor *cursor, int32_t columnIndex, char *value, int length); 214 215 /** 216 * @brief Function pointer. Obtains the value of the requested column as a int64_t. 217 * 218 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 219 * @param columnIndex Indicates the zero-based column index. 220 * @param value This parameter is the output parameter, 221 * and the value of the requested column as a int64_t is written to this variable. 222 * @return Returns the status code of the execution. 223 * @see OH_Cursor. 224 * @since 10 225 */ 226 int (*getInt64)(OH_Cursor *cursor, int32_t columnIndex, int64_t *value); 227 228 /** 229 * @brief Function pointer. Obtains the value of the requested column as a double. 230 * 231 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 232 * @param columnIndex Indicates the zero-based column index. 233 * @param value This parameter is the output parameter, 234 * and the value of the requested column as a double is written to this variable. 235 * @return Returns the status code of the execution. 236 * @see OH_Cursor. 237 * @since 10 238 */ 239 int (*getReal)(OH_Cursor *cursor, int32_t columnIndex, double *value); 240 241 /** 242 * @brief Function pointer. Obtains the value of the requested column as a byte array. 243 * 244 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 245 * @param columnIndex Indicates the zero-based column index. 246 * @param value This parameter is the output parameter, 247 * and the value of the requested column as a byte array is written to this variable. 248 * @param length Indicates the length of the value, it can be obtained through the OH_Cursor_GetSize function. 249 * @return Returns the status code of the execution. 250 * @see OH_Cursor. 251 * @since 10 252 */ 253 int (*getBlob)(OH_Cursor *cursor, int32_t columnIndex, unsigned char *value, int length); 254 255 /** 256 * @brief Function pointer. Obtains Whether the value of the requested column is null. 257 * 258 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 259 * @param columnIndex Indicates the zero-based column index. 260 * @param isNull This parameter is the output parameter, 261 * and the value whether the column value is null is written to this variable. 262 * @return Returns the status code of the execution. 263 * @see OH_Cursor. 264 * @since 10 265 */ 266 int (*isNull)(OH_Cursor *cursor, int32_t columnIndex, bool *isNull); 267 268 /** 269 * @brief Function pointer. Destroy the result set, releasing all of its resources and making it completely invalid. 270 * 271 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 272 * @return Returns the status code of the execution. 273 * @see OH_Cursor. 274 * @since 10 275 */ 276 int (*destroy)(OH_Cursor *cursor); 277 278 /** 279 * @brief Function pointer. Obtains the value of the requested column as an {@link Data_Asset} instance. 280 * 281 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 282 * @param columnIndex Indicates the zero-based column index. 283 * @param value This parameter is the output parameter, 284 * and the value of the requested column as an {@link Data_Asset} instance is written to this variable. 285 * @return Returns the status code of the execution. 286 * @see OH_Cursor. 287 * @since 11 288 */ 289 int (*getAsset)(OH_Cursor *cursor, int32_t columnIndex, Data_Asset *value); 290 291 /** 292 * @brief Function pointer. Obtains the value of the requested column as an {@link Data_Asset} instance. 293 * 294 * @param cursor Represents a pointer to an {@link OH_Cursor} instance. 295 * @param columnIndex Indicates the zero-based column index. 296 * @param value This parameter is the output parameter, 297 * and the value of the requested column as an {@link Data_Asset} instance is written to this variable. 298 * @param length Indicates the length of the value. 299 * @return Returns the status code of the execution. 300 * @see OH_Cursor. 301 * @since 11 302 */ 303 int (*getAssets)(OH_Cursor *cursor, int32_t columnIndex, Data_Asset **value, uint32_t *length); 304 }; 305 306 #ifdef __cplusplus 307 }; 308 #endif 309 310 /** @} */ 311 312 #endif // OH_CURSOR_H