1# OH_Cursor 2<!--Kit: ArkData--> 3<!--Subsystem: DistributedDataManager--> 4<!--Owner: @baijidong--> 5<!--Designer: @widecode; @htt1997--> 6<!--Tester: @yippo; @logic42--> 7<!--Adviser: @ge-yafang--> 8 9## 概述 10 11表示结果集。提供通过查询数据库生成的数据库结果集的访问方法。 12 13**起始版本：** 10 14 15**相关模块：** [RDB](capi-rdb.md) 16 17**所在头文件：** [oh_cursor.h](capi-oh-cursor-h.md) 18 19### 成员变量 20 21| 名称 | 描述 | 22| ---------- | ----------------------------- | 23| int64_t id | OH_Cursor结构体的唯一标识符。 | 24 25 26### 成员函数 27 28| 名称 | 描述 | 29| ------------------------------------------------------------ | ------------------------------------------------------------ | 30| [int (*getColumnCount)(OH_Cursor *cursor, int *count)](#getcolumncount) | 函数指针，获取结果集中的列数。 | 31| [int (*getColumnType)(OH_Cursor *cursor, int32_t columnIndex, OH_ColumnType *columnType)](#getcolumntype) | 函数指针，根据指定的列索引获取列类型。 | 32| [int (*getColumnIndex)(OH_Cursor *cursor, const char *name, int *columnIndex)](#getcolumnindex) | 函数指针，根据指定的列名获取列索引。 | 33| [int (*getColumnName)(OH_Cursor *cursor, int32_t columnIndex, char *name, int length)](#getcolumnname) | 函数指针，根据指定的列索引获取列名。 | 34| [int (*getRowCount)(OH_Cursor *cursor, int *count)](#getrowcount) | 函数指针，获取结果集中的行数。 | 35| [int (*goToNextRow)(OH_Cursor *cursor)](#gotonextrow) | 函数指针，转到结果集的下一行。 | 36| [int (*getSize)(OH_Cursor *cursor, int32_t columnIndex, size_t *size)](#getsize) | 函数指针，当结果集中列的数据类型是BLOB或者TEXT时，获取其值所需的内存。 | 37| [int (*getText)(OH_Cursor *cursor, int32_t columnIndex, char *value, int length)](#gettext) | 函数指针，以字符串形式获取当前行中指定列的值。 | 38| [int (*getInt64)(OH_Cursor *cursor, int32_t columnIndex, int64_t *value)](#getint64) | 函数指针，以int64_t形式获取当前行中指定列的值。 | 39| [int (*getReal)(OH_Cursor *cursor, int32_t columnIndex, double *value)](#getreal) | 函数指针，以double形式获取当前行中指定列的值。 | 40| [int (*getBlob)(OH_Cursor *cursor, int32_t columnIndex, unsigned char *value, int length)](#getblob) | 函数指针，以字节数组的形式获取当前行中指定列的值。 | 41| [int (*isNull)(OH_Cursor *cursor, int32_t columnIndex, bool *isNull)](#isnull) | 函数指针，检查当前行中指定列的值是否为null。 | 42| [int (*destroy)(OH_Cursor *cursor)](#destroy) | 函数指针，关闭结果集。 | 43| [int (*getAsset)(OH_Cursor *cursor, int32_t columnIndex, Data_Asset *value)](#getasset) | 函数指针，以资产的形式获取当前行中指定列的值。 | 44| [int (*getAssets)(OH_Cursor *cursor, int32_t columnIndex, Data_Asset **value, uint32_t length)](#getassets) | 函数指针，以资产数组的形式获取当前行中指定列的值。 | 45 46 47## 成员函数说明 48 49### getColumnCount() 50 51``` 52int (*getColumnCount)(OH_Cursor *cursor, int *count) 53``` 54 55**描述** 56 57函数指针，获取结果集中的列数。 58 59**起始版本：** 10 60 61 62**参数：** 63 64| 参数项 | 描述 | 65| ----------------- | -------------------------------------------- | 66| OH_Cursor *cursor | 表示指向OH_Cursor实例的指针 | 67| int *count | 该参数是输出参数，结果集中的列数会写入该变量 | 68 69**返回：** 70 71| 类型 | 说明 | 72| ---- | ------------------------------------------ | 73| int | 返回操作是否成功，出错时返回对应的错误码。 | 74 75### getColumnType() 76 77``` 78int (*getColumnType)(OH_Cursor *cursor, int32_t columnIndex, OH_ColumnType *columnType) 79``` 80 81**描述** 82 83函数指针，根据指定的列索引获取列类型。 84 85**起始版本：** 10 86 87 88**参数：** 89 90| 参数项 | 描述 | 91| ------------------------------------------------------------ | ------------------------------------------------------------ | 92| OH_Cursor *cursor | 表示指向OH_Cursor实例的指针 | 93| int32_t columnIndex | 表示结果集中指定列的索引，索引值从0开始。 | 94| [OH_ColumnType](capi-oh-data-value-h.md#oh_columntype) *columnType | 该参数是输出参数，结果集中指定列的数据类型[OH_ColumnType](capi-oh-data-value-h.md#oh_columntype)会写入该变量。 | 95 96**返回：** 97 98| 类型 | 说明 | 99| ---- | ------------------------------------------ | 100| int | 返回操作是否成功，出错时返回对应的错误码。 | 101 102### getColumnIndex() 103 104``` 105int (*getColumnIndex)(OH_Cursor *cursor, const char *name, int *columnIndex) 106``` 107 108**描述** 109 110函数指针，根据指定的列名获取列索引。 111 112**起始版本：** 10 113 114 115**参数：** 116 117| 参数项 | 描述 | 118| ----------------- | ---------------------------------------------------- | 119| OH_Cursor *cursor | 表示指向OH_Cursor实例的指针 | 120| const char *name | 表示结果集中指定列的名称。 | 121| int *columnIndex | 该参数是输出参数，结果集中指定列的索引会写入该变量。 | 122 123**返回：** 124 125| 类型 | 说明 | 126| ---- | ------------------------------------------ | 127| int | 返回操作是否成功，出错时返回对应的错误码。 | 128 129### getColumnName() 130 131``` 132 int (*getColumnName)(OH_Cursor *cursor, int32_t columnIndex, char *name, int length) 133``` 134 135**描述** 136 137函数指针，根据指定的列索引获取列名。 138 139**起始版本：** 10 140 141 142**参数：** 143 144| 参数项 | 描述 | 145| ------------------- | ------------------------------------------------------------ | 146| OH_Cursor *cursor | 表示指向OH_Cursor实例的指针 | 147| int32_t columnIndex | 表示结果集中指定列的索引，索引值从0开始。 | 148| char *name | 该参数是输出参数，结果集中指定列的名称会写入该变量。 | 149| int length | 该参数为输入参数，表示开发者传入的包括终止符在内的列名字符串的总长度。 | 150 151**返回：** 152 153| 类型 | 说明 | 154| ---- | ------------------------------------------ | 155| int | 返回操作是否成功，出错时返回对应的错误码。 | 156 157### getRowCount() 158 159``` 160int (*getRowCount)(OH_Cursor *cursor, int *count) 161``` 162 163**描述** 164 165函数指针，获取结果集中的行数。 166 167**起始版本：** 10 168 169 170**参数：** 171 172| 参数项 | 描述 | 173| ----------------- | -------------------------------------------- | 174| OH_Cursor *cursor | 表示指向OH_Cursor实例的指针 | 175| int *count | 该参数是输出参数，结果集中的列数会写入该变量 | 176 177**返回：** 178 179| 类型 | 说明 | 180| ---- | ------------------------------------------ | 181| int | 返回操作是否成功，出错时返回对应的错误码。 | 182 183### goToNextRow() 184 185``` 186 int (*goToNextRow)(OH_Cursor *cursor) 187``` 188 189**描述** 190 191函数指针，转到结果集的下一行。 192 193**起始版本：** 10 194 195 196**参数：** 197 198| 参数项 | 描述 | 199| ----------------- | --------------------------- | 200| OH_Cursor *cursor | 表示指向OH_Cursor实例的指针 | 201 202**返回：** 203 204| 类型 | 说明 | 205| ---- | ------------------------------------------ | 206| int | 返回操作是否成功，出错时返回对应的错误码。 | 207 208### getSize() 209 210``` 211int (*getSize)(OH_Cursor *cursor, int32_t columnIndex, size_t *size) 212``` 213 214**描述** 215 216函数指针，当结果集中列的数据类型是BLOB或者TEXT时，获取其值所需的内存。 217 218**起始版本：** 10 219 220 221**参数：** 222 223| 参数项 | 描述 | 224| ------------------- | ------------------------------------------------------------ | 225| OH_Cursor *cursor | 表示指向OH_Cursor实例的指针。 | 226| int32_t columnIndex | 表示结果集中指定列的索引，索引值从0开始。 | 227| size_t *size | 该参数是输出参数，BLOB或者TEXT数据所需内存大小会写入该变量。 | 228 229**返回：** 230 231| 类型 | 说明 | 232| ---- | ------------------------------------------ | 233| int | 返回操作是否成功，出错时返回对应的错误码。 | 234 235### getText() 236 237``` 238int (*getText)(OH_Cursor *cursor, int32_t columnIndex, char *value, int length) 239``` 240 241**描述** 242 243函数指针，以字符串形式获取当前行中指定列的值。 244 245**起始版本：** 10 246 247 248**参数：** 249 250| 参数项 | 描述 | 251| ------------------- | ------------------------------------------------------------ | 252| OH_Cursor *cursor | 表示指向OH_Cursor实例的指针 | 253| int32_t columnIndex | 该表示结果集中指定列的索引，索引值从0开始。 | 254| char *value | 该参数是输出参数，结果集中指定列的值会以字符串形式写入该变量。 | 255| int length | 该参数是输入参数，表示value的长度，该值可通过getSize获取。 | 256 257**返回：** 258 259| 类型 | 说明 | 260| ---- | ------------------------------------------ | 261| int | 返回操作是否成功，出错时返回对应的错误码。 | 262 263### getInt64() 264 265``` 266int (*getInt64)(OH_Cursor *cursor, int32_t columnIndex, int64_t *value) 267``` 268 269**描述** 270 271函数指针，以int64_t形式获取当前行中指定列的值。 272 273**起始版本：** 10 274 275 276**参数：** 277 278| 参数项 | 描述 | 279| ------------------- | ------------------------------------------------------------ | 280| OH_Cursor *cursor | 表示指向OH_Cursor实例的指针 | 281| int32_t columnIndex | 表示结果集中指定列的索引，索引值从0开始。 | 282| int64_t *value | 该参数是输出参数，结果集中指定列的值会以int64_t形式写入该变量。 | 283 284**返回：** 285 286| 类型 | 说明 | 287| ---- | ------------------------------------------ | 288| int | 返回操作是否成功，出错时返回对应的错误码。 | 289 290### getReal() 291 292``` 293int (*getReal)(OH_Cursor *cursor, int32_t columnIndex, double *value) 294``` 295 296**描述** 297 298函数指针，以double形式获取当前行中指定列的值。 299 300**起始版本：** 10 301 302 303**参数：** 304 305| 参数项 | 描述 | 306| ------------------- | ------------------------------------------------------------ | 307| OH_Cursor *cursor | 表示指向OH_Cursor实例的指针 | 308| int32_t columnIndex | 表示结果集中指定列的索引，索引值从0开始。 | 309| double *value | 该参数是输出参数，结果集中指定列的值会以double形式写入该变量。 | 310 311**返回：** 312 313| 类型 | 说明 | 314| ---- | ------------------------------------------ | 315| int | 返回操作是否成功，出错时返回对应的错误码。 | 316 317### getBlob() 318 319``` 320int (*getBlob)(OH_Cursor *cursor, int32_t columnIndex, unsigned char *value, int length) 321``` 322 323**描述** 324 325函数指针，以字节数组的形式获取当前行中指定列的值。 326 327**起始版本：** 10 328 329 330**参数：** 331 332| 参数项 | 描述 | 333| -------------------- | ------------------------------------------------------------ | 334| OH_Cursor *cursor | 表示指向OH_Cursor实例的指针 | 335| int32_t columnIndex | 表示结果集中指定列的索引，索引值从0开始。 | 336| unsigned char *value | 该参数是输出参数，结果集中指定列的值会以字节数组形式写入该变量。 | 337| int length | 该参数为输入参数，表示传入的value的长度，该值可通过getSize获取。 | 338 339**返回：** 340 341| 类型 | 说明 | 342| ---- | ------------------------------------------ | 343| int | 返回操作是否成功，出错时返回对应的错误码。 | 344 345### isNull() 346 347``` 348int (*isNull)(OH_Cursor *cursor, int32_t columnIndex, bool *isNull) 349``` 350 351**描述** 352 353函数指针，检查当前行中指定列的值是否为null。 354 355**起始版本：** 10 356 357 358**参数：** 359 360| 参数项 | 描述 | 361| ------------------- | ------------------------------------------------------------ | 362| OH_Cursor *cursor | 表示指向OH_Cursor实例的指针 | 363| int32_t columnIndex | 表示结果集中指定列的索引，索引值从0开始。 | 364| bool *isNull | 该参数是输出参数，如果当前行中指定列的值为null，该值为true，否则为false。 | 365 366**返回：** 367 368| 类型 | 说明 | 369| ---- | ------------------------------------------ | 370| int | 返回操作是否成功，出错时返回对应的错误码。 | 371 372### destroy() 373 374``` 375int (*destroy)(OH_Cursor *cursor) 376``` 377 378**描述** 379 380函数指针，关闭结果集。 381 382**起始版本：** 10 383 384 385**参数：** 386 387| 参数项 | 描述 | 388| ----------------- | --------------------------- | 389| OH_Cursor *cursor | 表示指向OH_Cursor实例的指针 | 390 391**返回：** 392 393| 类型 | 说明 | 394| ---- | ------------------------------------------ | 395| int | 返回操作是否成功，出错时返回对应的错误码。 | 396 397### getAsset() 398 399``` 400int (*getAsset)(OH_Cursor *cursor, int32_t columnIndex, Data_Asset *value) 401``` 402 403**描述** 404 405函数指针，以资产的形式获取当前行中指定列的值。 406 407**起始版本：** 10 408 409 410**参数：** 411 412| 参数项 | 描述 | 413| ------------------- | ------------------------------------------------------------ | 414| OH_Cursor *cursor | 表示指向OH_Cursor实例的指针 | 415| int32_t columnIndex | 表示结果集中指定列的索引，索引值从0开始。 | 416| Data_Asset *value | 该参数是输出参数，结果集中指定列的值会以资产形式写入该变量。 | 417 418**返回：** 419 420| 类型 | 说明 | 421| ---- | ------------------------------------------ | 422| int | 返回操作是否成功，出错时返回对应的错误码。 | 423 424### getAssets() 425 426``` 427int (*getAssets)(OH_Cursor *cursor, int32_t columnIndex, Data_Asset **value, uint32_t length) 428``` 429 430**描述** 431 432函数指针，以资产数组的形式获取当前行中指定列的值。 433 434**起始版本：** 10 435 436 437**参数：** 438 439| 参数项 | 描述 | 440| ------------------- | ------------------------------------------------------------ | 441| OH_Cursor *cursor | 表示指向OH_Cursor实例的指针 | 442| int32_t columnIndex | 表示结果集中指定列的索引，索引值从0开始。 | 443| Data_Asset **value | 该参数是输出参数，结果集中指定列的值会以资产数组形式写入该变量。 | 444| uint32_t length | 既是入参又是出参：作为入参，需要开发者传入一个uint32_t类型的变量，表示输入缓冲区的大小；作为出参，表示函数执行后，length指向的变量会被更新为实际返回的资产数组的长度。 | 445 446 447**返回：** 448 449| 类型 | 说明 | 450| ---- | ------------------------------------------ | 451| int | 返回操作是否成功，出错时返回对应的错误码。 |