This is a documentation preview for the next version of Tracker, generated from tracker.git commit 18f8564.

See the Tracker website for more documentation.

TrackerSparqlConnection

TrackerSparqlConnection

Functions

Types and Values

Object Hierarchy

    GEnum
    ╰── TrackerSparqlError
    GFlags
    ╰── TrackerSparqlConnectionFlags
    GObject
    ╰── TrackerSparqlConnection

Description

Functions

tracker_sparql_connection_new ()

TrackerSparqlConnection *
tracker_sparql_connection_new (TrackerSparqlConnectionFlags flags,
                               GFile *store,
                               GFile *ontology,
                               GCancellable *cancellable,
                               GError **error);

Creates or opens a database.

This method should only be used for databases owned by the current process. To connect to databases managed by other processes, use tracker_sparql_connection_bus_new().

If store is NULL, the database will be created in memory.

The ontologies parameter must point to a location containing suitable .ontology files in Turtle format. These control the database schema that is used. You can use the default Nepomuk ontologies by calling tracker_sparql_get_ontology_nepomuk().

If you open an existing database using a different ontology to the one it was created with, Tracker will attempt to migrate the existing data to the new schema. This may raise an error. In particular, not all migrations are possible without causing data loss and Tracker will refuse to delete data during a migration.

You can also pass NULL for ontologies to mean "use the ontologies that the database was created with". This will fail if the database doesn't already exist.

Parameters

flags

values from TrackerSparqlConnectionFlags

 

store

the directory that contains the database as a GFile, or NULL

 

ontology

the directory that contains the database schemas as a GFile, or NULL

 

cancellable

a GCancellable, or NULL.

[nullable]

error

pointer to a GError

 

Returns

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

[transfer full]

Since: 3.0


tracker_sparql_connection_new_async ()

void
tracker_sparql_connection_new_async (TrackerSparqlConnectionFlags flags,
                                     GFile *store,
                                     GFile *ontology,
                                     GCancellable *cancellable,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

Asynchronous version of tracker_sparql_connection_new().

Parameters

flags

values from TrackerSparqlConnectionFlags

 

store

the directory that contains the database as a GFile, or NULL.

[nullable]

ontology

the directory that contains the database schemas as a GFile, or NULL.

[nullable]

cancellable

a GCancellable, or NULL.

[nullable]

callback

the GAsyncReadyCallback called when the operation completes

 

user_data

data passed to callback

 

Since: 3.0


tracker_sparql_connection_new_finish ()

TrackerSparqlConnection *
tracker_sparql_connection_new_finish (GAsyncResult *result,
                                      GError **error);

Completion function for tracker_sparql_connection_new_async().

Parameters

result

the GAsyncResult

 

error

pointer to a GError

 

Since: 3.0


tracker_sparql_connection_remote_new ()

TrackerSparqlConnection *
tracker_sparql_connection_remote_new (const gchar *uri_base);

Connects to a remote SPARQL endpoint. The connection is made using the libsoup HTTP library. The connection will normally use the http:// or https:// protocol.

Parameters

uri_base

Base URI of the remote connection

 

Returns

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

[transfer full]

Since: 1.12


tracker_sparql_connection_bus_new ()

TrackerSparqlConnection *
tracker_sparql_connection_bus_new (const gchar *service_name,
                                   const gchar *object_path,
                                   GDBusConnection *dbus_connection,
                                   GError **error);

Connects to a database owned by another process on the local machine.

Parameters

service_name

The name of the D-Bus service to connect to.

 

object_path

The path to the object, or NULL to use the default.

[nullable]

dbus_connection

The GDBusConnection to use, or NULL to use the session bus.

[nullable]

error

pointer to a GError

 

Returns

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

[transfer full]

Since: 3.0


tracker_sparql_connection_query ()

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

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

The sparql query should be built with TrackerResource, or its parts correctly escaped using tracker_sparql_escape_string(), otherwise SPARQL injection is possible.

Parameters

connection

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. On error, NULL is returned and the error is set accordingly. Call g_object_unref() on the returned cursor when no longer needed.

[transfer full]


tracker_sparql_connection_query_async ()

void
tracker_sparql_connection_query_async (TrackerSparqlConnection *connection,
                                       const gchar *sparql,
                                       GCancellable *cancellable,
                                       GAsyncReadyCallback callback,
                                       gpointer user_data);

Executes asynchronously a SPARQL query.

Parameters

connection

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 *connection,
                                GAsyncResult *res,
                                GError **error);

Finishes the asynchronous SPARQL query operation.

Parameters

connection

a TrackerSparqlConnection

 

res

a GAsyncResult with the result of the operation

 

error

GError for error reporting.

 

Returns

a TrackerSparqlCursor if results were found. On error, NULL is returned and the error is set accordingly. Call g_object_unref() on the returned cursor when no longer needed.

[transfer full]


tracker_sparql_connection_query_statement ()

TrackerSparqlStatement *
tracker_sparql_connection_query_statement
                               (TrackerSparqlConnection *connection,
                                const gchar *sparql,
                                GCancellable *cancellable,
                                GError **error);

Prepares the given sparql as a TrackerSparqlStatement.

Parameters

connection

a TrackerSparqlConnection

 

sparql

the SPARQL query

 

cancellable

a GCancellable used to cancel the operation, or NULL

 

error

a TrackerSparqlError or NULL if no error occured

 

Returns

a prepared statement.

[transfer full][nullable]


tracker_sparql_connection_update ()

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

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

The sparql query should be built with TrackerResource, or its parts correctly escaped using tracker_sparql_escape_string(), otherwise SPARQL injection is possible.

Parameters

connection

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 *connection,
                                const gchar *sparql,
                                gint priority,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Executes asynchronously a SPARQL update.

Parameters

connection

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 *connection,
                                GAsyncResult *res,
                                GError **error);

Finishes the asynchronous SPARQL update operation.

Parameters

connection

a TrackerSparqlConnection

 

res

a GAsyncResult with the result of the operation

 

error

GError for error reporting.

 

tracker_sparql_connection_update_array_async ()

void
tracker_sparql_connection_update_array_async
                               (TrackerSparqlConnection *connection,
                                gchar **sparql,
                                gint sparql_length,
                                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.

Parameters

connection

a TrackerSparqlConnection

 

sparql

an array of strings containing the SPARQL update queries

 

sparql_length

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

 

tracker_sparql_connection_update_array_finish ()

gboolean
tracker_sparql_connection_update_array_finish
                               (TrackerSparqlConnection *connection,
                                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);
}

Parameters

connection

a TrackerSparqlConnection

 

res

a GAsyncResult with the result of the operation

 

error

GError for error reporting.

 

Returns

a GPtrArray of size sparql_length 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.


tracker_sparql_connection_update_blank ()

GVariant *
tracker_sparql_connection_update_blank
                               (TrackerSparqlConnection *connection,
                                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.

The sparql query should be built with TrackerResource, or its parts correctly escaped using tracker_sparql_escape_string(), otherwise SPARQL injection is possible.

Parameters

connection

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 *connection,
                                const gchar *sparql,
                                gint priority,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Executes asynchronously a SPARQL update.

Parameters

connection

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 *connection,
                                GAsyncResult *res,
                                GError **error);

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

Parameters

connection

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_get_namespace_manager ()

TrackerNamespaceManager *
tracker_sparql_connection_get_namespace_manager
                               (TrackerSparqlConnection *connection);

Retrieves a TrackerNamespaceManager that contains all prefixes in the ontology of connection .

Parameters

connection

a TrackerSparqlConnection

 

Returns

a TrackerNamespaceManager for this connection. This object is owned by connection and must not be freed.

[transfer none]


tracker_sparql_connection_create_notifier ()

TrackerNotifier *
tracker_sparql_connection_create_notifier
                               (TrackerSparqlConnection *connection,
                                TrackerNotifierFlags flags);

Creates a new TrackerNotifier to notify about changes in connection . See TrackerNotifier documentation for information about how to use this object.

Parameters

connection

a TrackerSparqlConnection

 

flags

flags to modify notifier behavior

 

Returns

a newly created notifier. Free with g_object_unref() when no longer needed.

[transfer full]


tracker_sparql_connection_close ()

void
tracker_sparql_connection_close (TrackerSparqlConnection *connection);

Closes a SPARQL connection. No other API calls than g_object_unref() should happen after this call.

This call is blocking. All pending updates will be flushed, and the store databases will be closed orderly. All ongoing SELECT queries will be cancelled. Notifiers will no longer emit events.

Parameters

connection

a TrackerSparqlConnection

 

Since: 3.0


tracker_sparql_connection_close_async ()

void
tracker_sparql_connection_close_async (TrackerSparqlConnection *connection,
                                       GCancellable *cancellable,
                                       GAsyncReadyCallback callback,
                                       gpointer user_data);

Closes a connection asynchronously. No other API calls than g_object_unref() should happen after this call. See tracker_sparql_connection_close() for more information.

Parameters

connection

a TrackerSparqlConnection

 

cancellable

a GCancellable, or NULL

 

callback

user-defined GAsyncReadyCallback to be called when asynchronous operation is finished.

 

user_data

user-defined data to be passed to callback

 

Since: 3.0


tracker_sparql_connection_close_finish ()

gboolean
tracker_sparql_connection_close_finish
                               (TrackerSparqlConnection *connection,
                                GAsyncResult *res,
                                GError **error);

Finishes the asynchronous connection close.

Parameters

connection

a TrackerSparqlConnection

 

res

the GAsyncResult

 

error

pointer to a GError

 

Returns

FALSE if some error occurred, TRUE otherwise

Since: 3.0

Types and Values

enum TrackerSparqlError

Error domain for Tracker Sparql. Errors in this domain will be from the TrackerSparqlError enumeration. See GError for more information on error domains.

Members

TRACKER_SPARQL_ERROR_PARSE

Error parsing the SPARQL string.

 

TRACKER_SPARQL_ERROR_UNKNOWN_CLASS

Unknown class.

 

TRACKER_SPARQL_ERROR_UNKNOWN_PROPERTY

Unknown property.

 

TRACKER_SPARQL_ERROR_TYPE

Wrong type.

 

TRACKER_SPARQL_ERROR_CONSTRAINT

Subject is not in the domain of a property or trying to set multiple values for a single valued property.

 

TRACKER_SPARQL_ERROR_NO_SPACE

There was no disk space available to perform the request.

 

TRACKER_SPARQL_ERROR_INTERNAL

Internal error.

 

TRACKER_SPARQL_ERROR_UNSUPPORTED

Unsupported feature or method.

 

TRACKER_SPARQL_ERROR_UNKNOWN_GRAPH

Unknown graph.

 

TRACKER_SPARQL_ERROR_ONTOLOGY_NOT_FOUND

The specified ontology wasn't found.

 

TRACKER_SPARQL_N_ERRORS

The total number of error codes.

 

TrackerSparqlConnection

typedef struct _TrackerSparqlConnection TrackerSparqlConnection;

The TrackerSparqlConnection object represents a SPARQL connection.


enum TrackerSparqlConnectionFlags

Connection flags to modify TrackerSparqlConnection behavior.

Members

TRACKER_SPARQL_CONNECTION_FLAGS_NONE

No flags.

 

TRACKER_SPARQL_CONNECTION_FLAGS_READONLY

Connection is readonly.

 

TRACKER_SPARQL_CONNECTION_FLAGS_FTS_ENABLE_STEMMER

Word stemming is applied to FTS search terms.

 

TRACKER_SPARQL_CONNECTION_FLAGS_FTS_ENABLE_UNACCENT

Unaccenting is applied to FTS search terms.

 

TRACKER_SPARQL_CONNECTION_FLAGS_FTS_ENABLE_STOP_WORDS

FTS Search terms are filtered through a stop word list.

 

TRACKER_SPARQL_CONNECTION_FLAGS_FTS_IGNORE_NUMBERS

Ignore numbers in FTS search terms.