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