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