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