Tracker SPARQL Library Reference Manual: TrackerSparqlCursor

## TrackerSparqlCursor TrackerSparqlCursor — Iteration of the query results |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <tracker-sparql.h>

    struct              TrackerSparqlCursor;
    enum                TrackerSparqlValueType;
    TrackerSparqlConnection * tracker_sparql_cursor_get_connection
                                                            (TrackerSparqlCursor *self);
    gint                tracker_sparql_cursor_get_n_columns (TrackerSparqlCursor *self);
    const gchar *       tracker_sparql_cursor_get_string    (TrackerSparqlCursor *self,
                                                             gint column,
                                                             glong *length);
    gboolean            tracker_sparql_cursor_get_boolean   (TrackerSparqlCursor *self,
                                                             gint column);
    gdouble             tracker_sparql_cursor_get_double    (TrackerSparqlCursor *self,
                                                             gint column);
    gint64              tracker_sparql_cursor_get_integer   (TrackerSparqlCursor *self,
                                                             gint column);
    TrackerSparqlValueType tracker_sparql_cursor_get_value_type
                                                            (TrackerSparqlCursor *self,
                                                             gint column);
    const gchar *       tracker_sparql_cursor_get_variable_name
                                                            (TrackerSparqlCursor *self,
                                                             gint column);
    void                tracker_sparql_cursor_close         (TrackerSparqlCursor *self);
    gboolean            tracker_sparql_cursor_is_bound      (TrackerSparqlCursor *self,
                                                             gint column);
    gboolean            tracker_sparql_cursor_next          (TrackerSparqlCursor *self,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                tracker_sparql_cursor_next_async    (TrackerSparqlCursor *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);
    gboolean            tracker_sparql_cursor_next_finish   (TrackerSparqlCursor *self,
                                                             GAsyncResult *_res_,
                                                             GError **error);
    void                tracker_sparql_cursor_rewind        (TrackerSparqlCursor *self);

## Object Hierarchy

      GObject
       +----TrackerSparqlCursor

## Properties

      "connection"               TrackerSparqlConnection*  : Read / Write
      "n-columns"                gint                  : Read

## Description

TrackerSparqlCursor is an object which provides methods to iterate the results of a query to the Tracker Store.

## Details

### struct TrackerSparqlCursor

    struct TrackerSparqlCursor;

The TrackerSparqlCursor object represents an iterator of results.

### enum TrackerSparqlValueType

    typedef enum {
    	TRACKER_SPARQL_VALUE_TYPE_UNBOUND,
    	TRACKER_SPARQL_VALUE_TYPE_URI,
    	TRACKER_SPARQL_VALUE_TYPE_STRING,
    	TRACKER_SPARQL_VALUE_TYPE_INTEGER,
    	TRACKER_SPARQL_VALUE_TYPE_DOUBLE,
    	TRACKER_SPARQL_VALUE_TYPE_DATETIME,
    	TRACKER_SPARQL_VALUE_TYPE_BLANK_NODE,
    	TRACKER_SPARQL_VALUE_TYPE_BOOLEAN
    } TrackerSparqlValueType;

Enumeration with the possible types of the cursor's cells

`TRACKER_SPARQL_VALUE_TYPE_UNBOUND` | Unbound value type
`TRACKER_SPARQL_VALUE_TYPE_URI` | Uri value type, rdfs:Resource
`TRACKER_SPARQL_VALUE_TYPE_STRING` | String value type, xsd:string
`TRACKER_SPARQL_VALUE_TYPE_INTEGER` | Integer value type, xsd:integer
`TRACKER_SPARQL_VALUE_TYPE_DOUBLE` | Double value type, xsd:double
`TRACKER_SPARQL_VALUE_TYPE_DATETIME` | Datetime value type, xsd:dateTime
`TRACKER_SPARQL_VALUE_TYPE_BLANK_NODE` | Blank node value type
`TRACKER_SPARQL_VALUE_TYPE_BOOLEAN` | Boolean value type, xsd:boolean

Since 0.10

### tracker_sparql_cursor_get_connection ()

    TrackerSparqlConnection * tracker_sparql_cursor_get_connection
                                                            (TrackerSparqlCursor *self);

`self` : | a TrackerSparqlCursor
Returns : | the TrackerSparqlConnection associated with this TrackerSparqlCursor. The returned object must not be unreferenced by the caller.

Since 0.10

### tracker_sparql_cursor_get_n_columns ()

    gint                tracker_sparql_cursor_get_n_columns (TrackerSparqlCursor *self);

This method should only be called after a successful `tracker_sparql_cursor_next()`; otherwise its return value will be undefined.

`self` : | a TrackerSparqlCursor
Returns : | a gint representing the number of columns available in the results to iterate.

Since 0.10

### tracker_sparql_cursor_get_string ()

    const gchar *       tracker_sparql_cursor_get_string    (TrackerSparqlCursor *self,
                                                             gint column,
                                                             glong *length);

Retrieves a string representation of the data in the current row in `column`.

`self` : | a TrackerSparqlCursor
`column` : | column number to retrieve (first one is 0)
`length` : | length of the returned string
Returns : | a string which must not be freed. `NULL` is returned if the column is not in the [0,n_columns] range.

Since 0.10

### tracker_sparql_cursor_get_boolean ()

    gboolean            tracker_sparql_cursor_get_boolean   (TrackerSparqlCursor *self,
                                                             gint column);

Retrieve a boolean for the current row in `column`.

`self` : | a TrackerSparqlCursor
`column` : | column number to retrieve (first one is 0)
Returns : | a gboolean.

Since 0.10

### tracker_sparql_cursor_get_double ()

    gdouble             tracker_sparql_cursor_get_double    (TrackerSparqlCursor *self,
                                                             gint column);

Retrieve a double for the current row in `column`.

`self` : | a TrackerSparqlCursor
`column` : | column number to retrieve (first one is 0)
Returns : | a double.

Since 0.10

### tracker_sparql_cursor_get_integer ()

    gint64              tracker_sparql_cursor_get_integer   (TrackerSparqlCursor *self,
                                                             gint column);

Retrieve an integer for the current row in `column`.

`self` : | a TrackerSparqlCursor
`column` : | column number to retrieve (first one is 0)
Returns : | a gint64.

Since 0.10

### tracker_sparql_cursor_get_value_type ()

    TrackerSparqlValueType tracker_sparql_cursor_get_value_type
                                                            (TrackerSparqlCursor *self,
                                                             gint column);

The data type bound to the current row in `column` is returned.

`self` : | a TrackerSparqlCursor
`column` : | column number to retrieve (first one is 0)
Returns : | a TrackerSparqlValueType.

Since 0.10

### tracker_sparql_cursor_get_variable_name ()

    const gchar *       tracker_sparql_cursor_get_variable_name
                                                            (TrackerSparqlCursor *self,
                                                             gint column);

Retrieves the variable name for the current row in `column`.

`self` : | a TrackerSparqlCursor
`column` : | column number to retrieve (first one is 0)
Returns : | a string which must not be freed.

Since 0.10

### tracker_sparql_cursor_close ()

    void                tracker_sparql_cursor_close         (TrackerSparqlCursor *self);

Closes the iterator, making it invalid.

`self` : | a TrackerSparqlCursor

Since 0.12

### tracker_sparql_cursor_is_bound ()

    gboolean            tracker_sparql_cursor_is_bound      (TrackerSparqlCursor *self,
                                                             gint column);

If the current row and `column` are bound to a value, `TRUE` is returned.

`self` : | a TrackerSparqlCursor
`column` : | column number to retrieve (first one is 0)
Returns : | a `TRUE` or `FALSE`.

Since 0.10

### tracker_sparql_cursor_next ()

    gboolean            tracker_sparql_cursor_next          (TrackerSparqlCursor *self,
                                                             GCancellable *cancellable,
                                                             GError **error);

Iterates to the next result. This is completely synchronous and it may block.

`self` : | a TrackerSparqlCursor
`cancellable` : | a GCancellable used to cancel the operation
`error` : | GError for error reporting.
Returns : | `FALSE` if no more results found, otherwise `TRUE`.

Since 0.10

### tracker_sparql_cursor_next_async ()

    void                tracker_sparql_cursor_next_async    (TrackerSparqlCursor *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);

### tracker_sparql_cursor_next_finish ()

    gboolean            tracker_sparql_cursor_next_finish   (TrackerSparqlCursor *self,
                                                             GAsyncResult *_res_,
                                                             GError **error);

Finishes the asynchronous iteration to the next result.

`self` : | a TrackerSparqlCursor
`_res_` : | a GAsyncResult with the result of the operation
`error` : | GError for error reporting.
Returns : | `FALSE` if no more results found, otherwise `TRUE`.

Since 0.10

### tracker_sparql_cursor_rewind ()

    void                tracker_sparql_cursor_rewind        (TrackerSparqlCursor *self);

Resets the iterator to point back to the first result.

`self` : | a TrackerSparqlCursor

Since 0.10

## Property Details

### The `"connection"` property

      "connection"               TrackerSparqlConnection*  : Read / Write

The TrackerSparqlConnection used to retrieve the results.

Since 0.10

### The `"n-columns"` property

      "n-columns"                gint                  : Read

n-columns.

Default value: 0