• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# OH_Cursor
2
3## Overview
4
5Defines a struct for a result set. Provides APIs to access the result set obtained by querying the RDB store.
6
7**Since**: 10
8
9**Related module**: [RDB](capi-rdb.md)
10
11**Header file**: [oh_cursor.h](capi-oh-cursor-h.md)
12
13### Member Variables
14
15| Name      | Description                         |
16| ---------- | ----------------------------- |
17| int64_t id | Unique identifier of the **OH_Cursor** struct.|
18
19
20### Member Functions
21
22| Name                                                        | Description                                                        |
23| ------------------------------------------------------------ | ------------------------------------------------------------ |
24| [int (*getColumnCount)(OH_Cursor *cursor, int *count)](#getcolumncount) | Pointer to the function used to obtain the number of columns in the result set.                              |
25| [int (*getColumnType)(OH_Cursor *cursor, int32_t columnIndex, OH_ColumnType *columnType)](#getcolumntype) | Pointer to the function used to obtain the column type based on the specified column index.                      |
26| [int (*getColumnIndex)(OH_Cursor *cursor, const char *name, int *columnIndex)](#getcolumnindex) | Pointer to the function used to obtain the column index based on the specified column name.                        |
27| [int (*getColumnName)(OH_Cursor *cursor, int32_t columnIndex, char *name, int length)](#getcolumnname) | Pointer to the function used to obtain the column name based on the specified column index.                        |
28| [int (*getRowCount)(OH_Cursor *cursor, int *count)](#getrowcount) | Pointer to the function used to obtain the number of rows in the result set.                              |
29| [int (*goToNextRow)(OH_Cursor *cursor)](#gotonextrow)        | Pointer to the function used to go to the next row of the result set.                              |
30| [int (*getSize)(OH_Cursor *cursor, int32_t columnIndex, size_t *size)](#getsize) | Pointer to the function used to obtain information about the memory required when the column data type in the result set is **BLOB** or **TEXT**.|
31| [int (*getText)(OH_Cursor *cursor, int32_t columnIndex, char *value, int length)](#gettext) | Pointer to the function used to obtain the value of the string type based on the specified column and the current row.              |
32| [int (*getInt64)(OH_Cursor *cursor, int32_t columnIndex, int64_t *value)](#getint64) | Pointer to the function used to obtain the value of the int64_t type based on the specified column and the current row.             |
33| [int (*getReal)(OH_Cursor *cursor, int32_t columnIndex, double *value)](#getreal) | Pointer to the function used to obtain the value of the double type based on the specified column and the current row.              |
34| [int (*getBlob)(OH_Cursor *cursor, int32_t columnIndex, unsigned char *value, int length)](#getblob) | Pointer to the function used to obtain the values in the form of a byte array based on the specified column and the current row.          |
35| [int (*isNull)(OH_Cursor *cursor, int32_t columnIndex, bool *isNull)](#isnull) | Pointer to the function used to check whether the value in the specified column is null.                |
36| [int (*destroy)(OH_Cursor *cursor)](#destroy)                | Pointer to the function used to destroy a result set.                                      |
37| [int (*getAsset)(OH_Cursor *cursor, int32_t columnIndex, Data_Asset *value)](#getasset) | Pointer to the function used to obtain the value of the asset type based on the specified column and the current row.              |
38| [int (*getAssets)(OH_Cursor *cursor, int32_t columnIndex, Data_Asset **value, uint32_t length)](#getassets) | Pointer to the function used to obtain the values in the form of an asset array based on the specified column and the current row.          |
39
40
41## Member Function Description
42
43### getColumnCount()
44
45```
46int (*getColumnCount)(OH_Cursor *cursor, int *count)
47```
48
49**Description**
50
51Pointer to the function used to obtain the number of columns in the result set.
52
53**Since**: 10
54
55
56**Parameters**
57
58| Name           | Description                                        |
59| ----------------- | -------------------------------------------- |
60| OH_Cursor *cursor | Pointer to the **OH_Cursor** instance.                 |
61| int *count        | Pointer to the number of columns in the result set obtained.|
62
63**Returns**
64
65| Type| Description                                      |
66| ---- | ------------------------------------------ |
67| int  | Returns **RDB_OK** if the operation is successful; returns an error code otherwise.|
68
69### getColumnType()
70
71```
72int (*getColumnType)(OH_Cursor *cursor, int32_t columnIndex, OH_ColumnType *columnType)
73```
74
75**Description**
76
77Pointer to the function used to obtain the column type based on the specified column index.
78
79**Since**: 10
80
81
82**Parameters**
83
84| Name                                                      | Description                                                        |
85| ------------------------------------------------------------ | ------------------------------------------------------------ |
86| OH_Cursor *cursor                                            | Pointer to the **OH_Cursor** instance.                                 |
87| int32_t columnIndex                                          | Index of the column, which starts from **0**.                   |
88| [OH_ColumnType](capi-oh-data-value-h.md#oh_columntype) *columnType | Pointer to [OH_ColumnType](capi-oh-data-value-h.md#oh_columntype) of columns in the result set obtained.|
89
90**Returns**
91
92| Type| Description                                      |
93| ---- | ------------------------------------------ |
94| int  | Returns **RDB_OK** if the operation is successful; returns an error code otherwise.|
95
96### getColumnIndex()
97
98```
99int (*getColumnIndex)(OH_Cursor *cursor, const char *name, int *columnIndex)
100```
101
102**Description**
103
104Pointer to the function used to obtain the column index based on the specified column name.
105
106**Since**: 10
107
108
109**Parameters**
110
111| Name           | Description                                                |
112| ----------------- | ---------------------------------------------------- |
113| OH_Cursor *cursor | Pointer to the **OH_Cursor** instance.                         |
114| const char *name  | Column name.                          |
115| int *columnIndex  | Pointer to the column index obtained.|
116
117**Returns**
118
119| Type| Description                                      |
120| ---- | ------------------------------------------ |
121| int  | Returns **RDB_OK** if the operation is successful; returns an error code otherwise.|
122
123### getColumnName()
124
125```
126 int (*getColumnName)(OH_Cursor *cursor, int32_t columnIndex, char *name, int length)
127```
128
129**Description**
130
131Pointer to the function used to obtain the column name based on the specified column index.
132
133**Since**: 10
134
135
136**Parameters**
137
138| Name             | Description                                                        |
139| ------------------- | ------------------------------------------------------------ |
140| OH_Cursor *cursor   | Pointer to the **OH_Cursor** instance.                                 |
141| int32_t columnIndex | Index of the column, which starts from **0**.                   |
142| char *name          | Pointer to the column name obtained.        |
143| int length          | Total length of the column name obtained, including the terminator.|
144
145**Returns**
146
147| Type| Description                                      |
148| ---- | ------------------------------------------ |
149| int  | Returns **RDB_OK** if the operation is successful; returns an error code otherwise.|
150
151### getRowCount()
152
153```
154int (*getRowCount)(OH_Cursor *cursor, int *count)
155```
156
157**Description**
158
159Pointer to the function used to obtain the number of rows in the result set.
160
161**Since**: 10
162
163
164**Parameters**
165
166| Name           | Description                                        |
167| ----------------- | -------------------------------------------- |
168| OH_Cursor *cursor | Pointer to the **OH_Cursor** instance.                 |
169| int *count        | Pointer to the number of columns in the result set obtained.|
170
171**Returns**
172
173| Type| Description                                      |
174| ---- | ------------------------------------------ |
175| int  | Returns **RDB_OK** if the operation is successful; returns an error code otherwise.|
176
177### goToNextRow()
178
179```
180 int (*goToNextRow)(OH_Cursor *cursor)
181```
182
183**Description**
184
185Pointer to the function used to go to the next row of the result set.
186
187**Since**: 10
188
189
190**Parameters**
191
192| Name           | Description                       |
193| ----------------- | --------------------------- |
194| OH_Cursor *cursor | Pointer to the **OH_Cursor** instance.|
195
196**Returns**
197
198| Type| Description                                      |
199| ---- | ------------------------------------------ |
200| int  | Returns **RDB_OK** if the operation is successful; returns an error code otherwise.|
201
202### getSize()
203
204```
205int (*getSize)(OH_Cursor *cursor, int32_t columnIndex, size_t *size)
206```
207
208**Description**
209
210Pointer to the function used to obtain information about the memory required when the column data type in the result set is **BLOB** or **TEXT**.
211
212**Since**: 10
213
214
215**Parameters**
216
217| Name             | Description                                                        |
218| ------------------- | ------------------------------------------------------------ |
219| OH_Cursor *cursor   | Pointer to the **OH_Cursor** instance.                               |
220| int32_t columnIndex | Index of the column, which starts from **0**.                   |
221| int32_t columnIndex | Pointer to the memory size obtained.|
222
223**Returns**
224
225| Type| Description                                      |
226| ---- | ------------------------------------------ |
227| int  | Returns **RDB_OK** if the operation is successful; returns an error code otherwise.|
228
229### getText()
230
231```
232int (*getText)(OH_Cursor *cursor, int32_t columnIndex, char *value, int length)
233```
234
235**Description**
236
237Pointer to the function used to obtain the value of the string type based on the specified column and the current row.
238
239**Since**: 10
240
241
242**Parameters**
243
244| Name             | Description                                                        |
245| ------------------- | ------------------------------------------------------------ |
246| OH_Cursor *cursor   | Pointer to the **OH_Cursor** instance.                                 |
247| int32_t columnIndex | Index of the column, which starts from **0**.                 |
248| char *value         | Pointer to the value of the string type obtained.|
249| int length          | Length of **value**, obtained by using **getSize**.  |
250
251**Returns**
252
253| Type| Description                                      |
254| ---- | ------------------------------------------ |
255| int  | Returns **RDB_OK** if the operation is successful; returns an error code otherwise.|
256
257### getInt64()
258
259```
260int (*getInt64)(OH_Cursor *cursor, int32_t columnIndex, int64_t *value)
261```
262
263**Description**
264
265Pointer to the function used to obtain the value of the int64_t type based on the specified column and the current row.
266
267**Since**: 10
268
269
270**Parameters**
271
272| Name             | Description                                                        |
273| ------------------- | ------------------------------------------------------------ |
274| OH_Cursor *cursor   | Pointer to the **OH_Cursor** instance.                                 |
275| int32_t columnIndex | Index of the column, which starts from **0**.                   |
276| int64_t *value      | Pointer to the value obtained.|
277
278**Returns**
279
280| Type| Description                                      |
281| ---- | ------------------------------------------ |
282| int  | Returns **RDB_OK** if the operation is successful; returns an error code otherwise.|
283
284### getReal()
285
286```
287int (*getReal)(OH_Cursor *cursor, int32_t columnIndex, double *value)
288```
289
290**Description**
291
292Pointer to the function used to obtain the value of the double type based on the specified column and the current row.
293
294**Since**: 10
295
296
297**Parameters**
298
299| Name             | Description                                                        |
300| ------------------- | ------------------------------------------------------------ |
301| OH_Cursor *cursor   | Pointer to the **OH_Cursor** instance.                                 |
302| int32_t columnIndex | Index of the column, which starts from **0**.                   |
303| double *value       | Pointer to the value obtained.|
304
305**Returns**
306
307| Type| Description                                      |
308| ---- | ------------------------------------------ |
309| int  | Returns **RDB_OK** if the operation is successful; returns an error code otherwise.|
310
311### getBlob()
312
313```
314int (*getBlob)(OH_Cursor *cursor, int32_t columnIndex, unsigned char *value, int length)
315```
316
317**Description**
318
319Pointer to the function used to obtain the values in the form of a byte array based on the specified column and the current row.
320
321**Since**: 10
322
323
324**Parameters**
325
326| Name              | Description                                                        |
327| -------------------- | ------------------------------------------------------------ |
328| OH_Cursor *cursor    | Pointer to the **OH_Cursor** instance.                                 |
329| int32_t columnIndex  | Index of the column, which starts from **0**.                   |
330| unsigned char *value | Pointer to the values in the form of a byte array obtained.|
331| int length           | Length of **value**, obtained by using **getSize**.|
332
333**Returns**
334
335| Type| Description                                      |
336| ---- | ------------------------------------------ |
337| int  | Returns **RDB_OK** if the operation is successful; returns an error code otherwise.|
338
339### isNull()
340
341```
342int (*isNull)(OH_Cursor *cursor, int32_t columnIndex, bool *isNull)
343```
344
345**Description**
346
347Pointer to the function used to check whether the value in the specified column is null.
348
349**Since**: 10
350
351
352**Parameters**
353
354| Name             | Description                                                        |
355| ------------------- | ------------------------------------------------------------ |
356| OH_Cursor *cursor   | Pointer to the **OH_Cursor** instance.                                 |
357| int32_t columnIndex | Index of the column, which starts from **0**.                   |
358| bool *isNull        | Pointer to the value returned. The value **true** means the value is null; the value **false** means the opposite.|
359
360**Returns**
361
362| Type| Description                                      |
363| ---- | ------------------------------------------ |
364| int  | Returns **RDB_OK** if the operation is successful; returns an error code otherwise.|
365
366### destroy()
367
368```
369int (*destroy)(OH_Cursor *cursor)
370```
371
372**Description**
373
374Pointer to the function used to destroy a result set.
375
376**Since**: 10
377
378
379**Parameters**
380
381| Name           | Description                       |
382| ----------------- | --------------------------- |
383| OH_Cursor *cursor | Pointer to the **OH_Cursor** instance.|
384
385**Returns**
386
387| Type| Description                                      |
388| ---- | ------------------------------------------ |
389| int  | Returns **RDB_OK** if the operation is successful; returns an error code otherwise.|
390
391### getAsset()
392
393```
394int (*getAsset)(OH_Cursor *cursor, int32_t columnIndex, Data_Asset *value)
395```
396
397**Description**
398
399Pointer to the function used to obtain the value of the asset type based on the specified column and the current row.
400
401**Since**: 10
402
403
404**Parameters**
405
406| Name             | Description                                                        |
407| ------------------- | ------------------------------------------------------------ |
408| OH_Cursor *cursor   | Pointer to the **OH_Cursor** instance.                                 |
409| int32_t columnIndex | Index of the column, which starts from **0**.                   |
410| Data_Asset *value   | Pointer to the value obtained.|
411
412**Returns**
413
414| Type| Description                                      |
415| ---- | ------------------------------------------ |
416| int  | Returns **RDB_OK** if the operation is successful; returns an error code otherwise.|
417
418### getAssets()
419
420```
421int (*getAssets)(OH_Cursor *cursor, int32_t columnIndex, Data_Asset **value, uint32_t length)
422```
423
424**Description**
425
426Pointer to the function used to obtain the values in the form of an asset array based on the specified column and the current row.
427
428**Since**: 10
429
430
431**Parameters**
432
433| Name             | Description                                                        |
434| ------------------- | ------------------------------------------------------------ |
435| OH_Cursor *cursor   | Pointer to the **OH_Cursor** instance.                                 |
436| int32_t columnIndex | Index of the column, which starts from **0**.                   |
437| Data_Asset **value  | Double pointer to the value obtained.|
438| uint32_t length     | Length of the buffer, which is a variable of the uint32_t type passed in. After the API is executed, the variable is updated to the length of the returned asset array.|
439
440
441**Returns**
442
443| Type| Description                                      |
444| ---- | ------------------------------------------ |
445| int  | Returns **RDB_OK** if the operation is successful; returns an error code otherwise.|
446