TrackerSparqlConnection

TrackerSparqlConnection

Synopsis

enum                TrackerSparqlError;
struct              TrackerSparqlConnection;
TrackerSparqlConnection * tracker_sparql_connection_get (GCancellable *cancellable,
                                                         GError **error);
void                tracker_sparql_connection_get_async (GCancellable *cancellable,
                                                         GAsyncReadyCallback _callback_,
                                                         gpointer _user_data_);
TrackerSparqlConnection * tracker_sparql_connection_get_finish
                                                        (GAsyncResult *_res_,
                                                         GError **error);
TrackerSparqlConnection * tracker_sparql_connection_get_direct
                                                        (GCancellable *cancellable,
                                                         GError **error);
void                tracker_sparql_connection_get_direct_async
                                                        (GCancellable *cancellable,
                                                         GAsyncReadyCallback _callback_,
                                                         gpointer _user_data_);
TrackerSparqlConnection * tracker_sparql_connection_get_direct_finish
                                                        (GAsyncResult *_res_,
                                                         GError **error);
TrackerSparqlCursor * tracker_sparql_connection_query   (TrackerSparqlConnection *self,
                                                         const gchar *sparql,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                tracker_sparql_connection_query_async
                                                        (TrackerSparqlConnection *self,
                                                         const gchar *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 gchar *sparql,
                                                         gint priority,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                tracker_sparql_connection_update_async
                                                        (TrackerSparqlConnection *self,
                                                         const gchar *sparql,
                                                         gint priority,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback _callback_,
                                                         gpointer _user_data_);
void                tracker_sparql_connection_update_finish
                                                        (TrackerSparqlConnection *self,
                                                         GAsyncResult *_res_,
                                                         GError **error);
void                tracker_sparql_connection_update_array_async
                                                        (TrackerSparqlConnection *self,
                                                         gchar **sparql,
                                                         int sparql_length1,
                                                         gint priority,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback _callback_,
                                                         gpointer _user_data_);
GPtrArray *         tracker_sparql_connection_update_array_finish
                                                        (TrackerSparqlConnection *self,
                                                         GAsyncResult *_res_,
                                                         GError **error);
GVariant *          tracker_sparql_connection_update_blank
                                                        (TrackerSparqlConnection *self,
                                                         const gchar *sparql,
                                                         gint priority,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                tracker_sparql_connection_update_blank_async
                                                        (TrackerSparqlConnection *self,
                                                         const gchar *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;


struct TrackerSparqlConnection

struct TrackerSparqlConnection;

The TrackerSparqlConnection object represents a connection with the Tracker store or databases depending on direct or non-direct requests.


tracker_sparql_connection_get ()

TrackerSparqlConnection * tracker_sparql_connection_get (GCancellable *cancellable,
                                                         GError **error);

This function is used to give the caller a connection to Tracker they can use for future requests. The best backend available to connect to Tracker is returned. These backends include direct-access (for read-only queries) and D-Bus (for both read and write queries).

You can use environment variables to influence how backends are used. If no environment variables are provided, both backends are loaded and chosen based on their merits. If you try to force a backend for a query which it won't support (i.e. an update for a read-only backend), you will see critical warnings.

When calling either tracker_sparql_connection_get(), tracker_sparql_connection_get_direct() or the asynchronous variants of these functions, a mutex is used to protect the loading of backends against potential race conditions. For synchronous calls, this function will always block if a previous connection get method has been called.

All backends will call the D-Bus tracker-store API Wait() to make sure the store and databases are in the right state before any user based requests can proceed. There may be a small delay during this call if the databases weren't shutdown cleanly and need to be checked on start up. If the journal needs to be replayed in such an event, the delay may be substantial while data is restored as best as possible.

cancellable :

a GCancellable used to cancel the operation

error :

GError for error reporting.

Returns :

a new TrackerSparqlConnection. Call g_object_unref() on the object when no longer used.

Since 0.10


tracker_sparql_connection_get_async ()

void                tracker_sparql_connection_get_async (GCancellable *cancellable,
                                                         GAsyncReadyCallback _callback_,
                                                         gpointer _user_data_);


tracker_sparql_connection_get_finish ()

TrackerSparqlConnection * tracker_sparql_connection_get_finish
                                                        (GAsyncResult *_res_,
                                                         GError **error);

This function is called from the callback provided for tracker_sparql_connection_get_async() to return the connection requested or an error in cases of failure.

_res_ :

The GAsyncResult from the callback used to return the TrackerSparqlConnection

error :

The error which occurred or NULL

Returns :

a new TrackerSparqlConnection. Call g_object_unref() on the object when no longer used.

Since 0.10


tracker_sparql_connection_get_direct ()

TrackerSparqlConnection * tracker_sparql_connection_get_direct
                                                        (GCancellable *cancellable,
                                                         GError **error);

Warning

tracker_sparql_connection_get_direct has been deprecated since version 0.12 and should not be used in newly-written code. Use tracker_sparql_connection_get instead.

This behaves the same way tracker_sparql_connection_get() does, however, the TrackerSparqlConnection can only be used for read-only requests. The advantage to this API over the tracker_sparql_connection_get() function is that it will use direct-access. This is faster than using D-Bus which may be the case with tracker_sparql_connection_get().

cancellable :

a GCancellable used to cancel the operation

error :

GError for error reporting.

Returns :

a new TrackerSparqlConnection. Call g_object_unref() on the object when no longer used.

Since 0.10


tracker_sparql_connection_get_direct_async ()

void                tracker_sparql_connection_get_direct_async
                                                        (GCancellable *cancellable,
                                                         GAsyncReadyCallback _callback_,
                                                         gpointer _user_data_);


tracker_sparql_connection_get_direct_finish ()

TrackerSparqlConnection * tracker_sparql_connection_get_direct_finish
                                                        (GAsyncResult *_res_,
                                                         GError **error);

Warning

tracker_sparql_connection_get_direct_finish has been deprecated since version 0.12 and should not be used in newly-written code. Use tracker_sparql_connection_get_finish instead.

This function is called from the callback provided for tracker_sparql_connection_get_direct_async() to return the connection requested or an error in cases of failure.

_res_ :

The GAsyncResult from the callback used to return the TrackerSparqlConnection

error :

The error which occurred or NULL

Returns :

a new TrackerSparqlConnection. Call g_object_unref() on the object when no longer used.

Since 0.10


tracker_sparql_connection_query ()

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

Executes a SPARQL query on. 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.

Since 0.10


tracker_sparql_connection_query_async ()

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


tracker_sparql_connection_query_finish ()

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

Finishes the asynchronous SPARQL query operation.

self :

a TrackerSparqlConnection

_res_ :

a GAsyncResult with the result of 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.

Since 0.10


tracker_sparql_connection_update ()

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

Executes a SPARQL update. 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.

Since 0.10


tracker_sparql_connection_update_async ()

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

Executes asynchronously a SPARQL update.

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_

Since 0.10


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.

Since 0.10


tracker_sparql_connection_update_array_async ()

void                tracker_sparql_connection_update_array_async
                                                        (TrackerSparqlConnection *self,
                                                         gchar **sparql,
                                                         int sparql_length1,
                                                         gint priority,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback _callback_,
                                                         gpointer _user_data_);

Executes asynchronously an array of SPARQL updates. Each update in the array is its own transaction. This means that update n+1 is not halted due to an error in update n.

self :

a TrackerSparqlConnection

sparql :

an array of strings containing the SPARQL update queries

sparql_length1 :

the amount of strings you pass as sparql

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_

Since 0.10


tracker_sparql_connection_update_array_finish ()

GPtrArray *         tracker_sparql_connection_update_array_finish
                                                        (TrackerSparqlConnection *self,
                                                         GAsyncResult *_res_,
                                                         GError **error);

Finishes the asynchronous SPARQL update_array operation.

Example 1. 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
static void
async_update_array_callback (GObject      *source_object,
                             GAsyncResult *result,
                             gpointer      user_data)
{
    GError *error = NULL;
    GPtrArray *errors;
    guint i;

    errors = tracker_sparql_connection_update_array_finish (connection, result, &error);
    g_assert_no_error (error);

    for (i = 0; i < errors->len; i++) {
        const GError *e = g_ptr_array_index (errors, i);

        ...
    }

    g_ptr_array_unref (errors);
}


self :

a TrackerSparqlConnection

_res_ :

a GAsyncResult with the result of the operation

error :

GError for error reporting.

Returns :

a GPtrArray of size sparql_length1 with elements that are either NULL or a GError instance. The returned array should be freed with g_ptr_array_unref when no longer used, not with g_ptr_array_free. When you use errors of the array, you must g_error_copy them. Errors inside of the array must be considered as const data and not freed. The index of the error corresponds to the index of the update query in the array that you passed to tracker_sparql_connection_update_array_async.

Since 0.10


tracker_sparql_connection_update_blank ()

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

Executes a SPARQL update 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.

Since 0.10


tracker_sparql_connection_update_blank_async ()

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

Executes asynchronously a SPARQL update.

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_

Since 0.10


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.

Since 0.10


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.

Since 0.10


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_

Since 0.10


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.

Since 0.10


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.

Since 0.10


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_

Since 0.10


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.

Since 0.10