## TrackerSparqlConnection

TrackerSparqlConnection

## Synopsis

    enum                TrackerSparqlError;
                        TrackerSparqlConnection;
    TrackerSparqlConnection* tracker_sparql_connection_get  (GError **error);
    TrackerSparqlConnection* tracker_sparql_connection_get_direct
                                                            (GError **error);
    TrackerSparqlCursor* tracker_sparql_connection_query    (TrackerSparqlConnection *self,
                                                             const char *sparql,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                tracker_sparql_connection_query_async
                                                            (TrackerSparqlConnection *self,
                                                             const char *sparql,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);
    TrackerSparqlCursor* tracker_sparql_connection_query_finish
                                                            (TrackerSparqlConnection *self,
                                                             GAsyncResult *_res_,
                                                             GError **error);
    void                tracker_sparql_connection_update    (TrackerSparqlConnection *self,
                                                             const char *sparql,
                                                             gint priority,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                tracker_sparql_connection_update_async
                                                            (TrackerSparqlConnection *self,
                                                             const char *sparql,
                                                             gint priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);
    void                tracker_sparql_connection_update_finish
                                                            (TrackerSparqlConnection *self,
                                                             GAsyncResult *_res_,
                                                             GError **error);
    GVariant*           tracker_sparql_connection_update_blank
                                                            (TrackerSparqlConnection *self,
                                                             const char *sparql,
                                                             gint priority,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                tracker_sparql_connection_update_blank_async
                                                            (TrackerSparqlConnection *self,
                                                             const char *sparql,
                                                             gint priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);
    GVariant*           tracker_sparql_connection_update_blank_finish
                                                            (TrackerSparqlConnection *self,
                                                             GAsyncResult *_res_,
                                                             GError **error);
    void                tracker_sparql_connection_load      (TrackerSparqlConnection *self,
                                                             GFile *file,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                tracker_sparql_connection_load_async
                                                            (TrackerSparqlConnection *self,
                                                             GFile *file,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);
    void                tracker_sparql_connection_load_finish
                                                            (TrackerSparqlConnection *self,
                                                             GAsyncResult *_res_,
                                                             GError **error);
    TrackerSparqlCursor* tracker_sparql_connection_statistics
                                                            (TrackerSparqlConnection *self,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                tracker_sparql_connection_statistics_async
                                                            (TrackerSparqlConnection *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);
    TrackerSparqlCursor* tracker_sparql_connection_statistics_finish
                                                            (TrackerSparqlConnection *self,
                                                             GAsyncResult *_res_,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----TrackerSparqlConnection

## Description

## Details

### enum TrackerSparqlError

    typedef enum  {
    	TRACKER_SPARQL_ERROR_PARSE,
    	TRACKER_SPARQL_ERROR_UNKNOWN_CLASS,
    	TRACKER_SPARQL_ERROR_UNKNOWN_PROPERTY,
    	TRACKER_SPARQL_ERROR_TYPE,
    	TRACKER_SPARQL_ERROR_CONSTRAINT,
    	TRACKER_SPARQL_ERROR_NO_SPACE,
    	TRACKER_SPARQL_ERROR_INTERNAL,
    	TRACKER_SPARQL_ERROR_UNSUPPORTED
    } TrackerSparqlError;

### TrackerSparqlConnection

    typedef struct _TrackerSparqlConnection TrackerSparqlConnection;

The TrackerSparqlConnection object represents a connection with the Tracker Store.

### tracker_sparql_connection_get ()

    TrackerSparqlConnection* tracker_sparql_connection_get  (GError **error);

Returns a new TrackerSparqlConnection, which will use the best method available to connect to the Tracker Store (direct-access for Read-Only queries, and D-Bus otherwise).

There are 2 environment variables which can be used to control which backends are used to set up the connection. If no environment variables are provided, then both backends are loaded and chosen based on their merits.

The TRACKER_BUS_BACKEND environment variable can be set to "dbus-glib" to force the D-Bus backend to use non-FD (File Descriptor) passing (the original communication method Tracker used).

The TRACKER_SPARQL_BACKEND environment variable also allows the caller to switch between "auto" (the default), "direct" (for direct access) and "bus" for D-Bus backends. If you force a backend which does not support what you're doing (for example, using the "direct" backend for a SPARQL update) then you will see critical warnings in your code.

`error` : | GError for error reporting.
Returns : | a new TrackerSparqlConnection. Call `g_object_unref()` on the object when no longer used.

### tracker_sparql_connection_get_direct ()

    TrackerSparqlConnection* tracker_sparql_connection_get_direct
                                                            (GError **error);

Returns a new TrackerSparqlConnection, which uses direct-access method to connect to the Tracker Store. Note that this connection will only be able to perform Read-Only queries in the store.

If the TRACKER_SPARQL_BACKEND environment variable is set, it may override the choice to use a direct access connection here, for more details, see `tracker_sparql_connection_get()`.

`error` : | GError for error reporting.
Returns : | a new TrackerSparqlConnection. Call `g_object_unref()` on the object when no longer used.

### tracker_sparql_connection_query ()

    TrackerSparqlCursor* tracker_sparql_connection_query    (TrackerSparqlConnection *self,
                                                             const char *sparql,
                                                             GCancellable *cancellable,
                                                             GError **error);

Executes a SPARQL query on the store. The API call is completely synchronous, so it may block.

`self` : | a TrackerSparqlConnection
`sparql` : | string containing the SPARQL query
`cancellable` : | a GCancellable used to cancel the operation
`error` : | GError for error reporting.
Returns : | a TrackerSparqlCursor if results were found, NULL otherwise. On error, NULL is returned and the `error` is set accordingly. Call `g_object_unref()` on the returned cursor when no longer needed.

### tracker_sparql_connection_query_async ()

    void                tracker_sparql_connection_query_async
                                                            (TrackerSparqlConnection *self,
                                                             const char *sparql,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);

Executes asynchronously a SPARQL query on the store.

`self` : | a TrackerSparqlConnection
`sparql` : | string containing the SPARQL query
`cancellable` : | a GCancellable used to cancel the operation
`_callback_` : | user-defined GAsyncReadyCallback to be called when asynchronous operation is finished.
`_user_data_` : | user-defined data to be passed to `_callback_`

### tracker_sparql_connection_query_finish ()

    TrackerSparqlCursor* tracker_sparql_connection_query_finish
                                                            (TrackerSparqlConnection *self,
                                                             GAsyncResult *_res_,
                                                             GError **error);

`self` : |
`_res_` : |
`error` : |
Returns : |

### tracker_sparql_connection_update ()

    void                tracker_sparql_connection_update    (TrackerSparqlConnection *self,
                                                             const char *sparql,
                                                             gint priority,
                                                             GCancellable *cancellable,
                                                             GError **error);

Executes a SPARQL update on the store. The API call is completely synchronous, so it may block.

`self` : | a TrackerSparqlConnection
`sparql` : | string containing the SPARQL update query
`priority` : | the priority for the operation
`cancellable` : | a GCancellable used to cancel the operation
`error` : | GError for error reporting.

### tracker_sparql_connection_update_async ()

    void                tracker_sparql_connection_update_async
                                                            (TrackerSparqlConnection *self,
                                                             const char *sparql,
                                                             gint priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);

Executes asynchronously a SPARQL update on the store.

`self` : | a TrackerSparqlConnection
`sparql` : | string containing the SPARQL update query
`priority` : | the priority for the asynchronous operation
`cancellable` : | a GCancellable used to cancel the operation
`_callback_` : | user-defined GAsyncReadyCallback to be called when asynchronous operation is finished.
`_user_data_` : | user-defined data to be passed to `_callback_`

### tracker_sparql_connection_update_finish ()

    void                tracker_sparql_connection_update_finish
                                                            (TrackerSparqlConnection *self,
                                                             GAsyncResult *_res_,
                                                             GError **error);

Finishes the asynchronous SPARQL update operation.

`self` : | a TrackerSparqlConnection
`_res_` : | a GAsyncResult with the result of the operation
`error` : | GError for error reporting.

### tracker_sparql_connection_update_blank ()

    GVariant*           tracker_sparql_connection_update_blank
                                                            (TrackerSparqlConnection *self,
                                                             const char *sparql,
                                                             gint priority,
                                                             GCancellable *cancellable,
                                                             GError **error);

Executes a SPARQL update on the store, and returns the URNs of the generated nodes, if any. The API call is completely synchronous, so it may block.

`self` : | a TrackerSparqlConnection
`sparql` : | string containing the SPARQL update query
`priority` : | the priority for the operation
`cancellable` : | a GCancellable used to cancel the operation
`error` : | GError for error reporting.
Returns : | a GVariant with the generated URNs, which should be freed with `g_variant_unref()` when no longer used.

### tracker_sparql_connection_update_blank_async ()

    void                tracker_sparql_connection_update_blank_async
                                                            (TrackerSparqlConnection *self,
                                                             const char *sparql,
                                                             gint priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);

Executes asynchronously a SPARQL update on the store.

`self` : | a TrackerSparqlConnection
`sparql` : | string containing the SPARQL update query
`priority` : | the priority for the asynchronous operation
`cancellable` : | a GCancellable used to cancel the operation
`_callback_` : | user-defined GAsyncReadyCallback to be called when asynchronous operation is finished.
`_user_data_` : | user-defined data to be passed to `_callback_`

### tracker_sparql_connection_update_blank_finish ()

    GVariant*           tracker_sparql_connection_update_blank_finish
                                                            (TrackerSparqlConnection *self,
                                                             GAsyncResult *_res_,
                                                             GError **error);

Finishes the asynchronous SPARQL update operation, and returns the URNs of the generated nodes, if any.

`self` : | a TrackerSparqlConnection
`_res_` : | a GAsyncResult with the result of the operation
`error` : | GError for error reporting.
Returns : | a GVariant with the generated URNs, which should be freed with `g_variant_unref()` when no longer used.

### tracker_sparql_connection_load ()

    void                tracker_sparql_connection_load      (TrackerSparqlConnection *self,
                                                             GFile *file,
                                                             GCancellable *cancellable,
                                                             GError **error);

Loads a Turtle file (TTL) into the store. The API call is completely synchronous, so it may block.

`self` : | a TrackerSparqlConnection
`file` : | a GFile
`cancellable` : | a GCancellable used to cancel the operation
`error` : | GError for error reporting.

### tracker_sparql_connection_load_async ()

    void                tracker_sparql_connection_load_async
                                                            (TrackerSparqlConnection *self,
                                                             GFile *file,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);

Loads, asynchronously, a Turtle file (TTL) into the store.

`self` : | a TrackerSparqlConnection
`file` : | a GFile
`cancellable` : | a GCancellable used to cancel the operation
`_callback_` : | user-defined GAsyncReadyCallback to be called when asynchronous operation is finished.
`_user_data_` : | user-defined data to be passed to `_callback_`

### tracker_sparql_connection_load_finish ()

    void                tracker_sparql_connection_load_finish
                                                            (TrackerSparqlConnection *self,
                                                             GAsyncResult *_res_,
                                                             GError **error);

Finishes the asynchronous load of the Turtle file.

`self` : | a TrackerSparqlConnection
`_res_` : | a GAsyncResult with the result of the operation
`error` : | GError for error reporting.

### tracker_sparql_connection_statistics ()

    TrackerSparqlCursor* tracker_sparql_connection_statistics
                                                            (TrackerSparqlConnection *self,
                                                             GCancellable *cancellable,
                                                             GError **error);

Retrieves the statistics from the Store. The API call is completely synchronous, so it may block.

`self` : | a TrackerSparqlConnection
`cancellable` : | a GCancellable used to cancel the operation
`error` : | GError for error reporting.
Returns : | a TrackerSparqlCursor to iterate the reply if successful, NULL on error. Call `g_object_unref()` on the returned cursor when no longer needed.

### tracker_sparql_connection_statistics_async ()

    void                tracker_sparql_connection_statistics_async
                                                            (TrackerSparqlConnection *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback _callback_,
                                                             gpointer _user_data_);

Retrieves, asynchronously, the statistics from the Store.

`self` : | a TrackerSparqlConnection
`cancellable` : | a GCancellable used to cancel the operation
`_callback_` : | user-defined GAsyncReadyCallback to be called when asynchronous operation is finished.
`_user_data_` : | user-defined data to be passed to `_callback_`

### tracker_sparql_connection_statistics_finish ()

    TrackerSparqlCursor* tracker_sparql_connection_statistics_finish
                                                            (TrackerSparqlConnection *self,
                                                             GAsyncResult *_res_,
                                                             GError **error);

Finishes the asynchronous retrieval of statistics from the Store.

`self` : | a TrackerSparqlConnection
`_res_` : | a GAsyncResult with the result of the operation
`error` : | GError for error reporting.
Returns : | a TrackerSparqlCursor to iterate the reply if successful, NULL on error. Call `g_object_unref()` on the returned cursor when no longer needed.