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