From ce75f4a8b79d476bacd2ed91611a403d2642d616 Mon Sep 17 00:00:00 2001 From: Carlos Garnacho Date: Fri, 24 Feb 2023 19:01:53 +0100 Subject: libtracker-sparql: Do not use volatile to register DBus errors The documentation of g_dbus_error_register_error_domain() says we should not use one. --- src/libtracker-sparql/tracker-error.c | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'src/libtracker-sparql') diff --git a/src/libtracker-sparql/tracker-error.c b/src/libtracker-sparql/tracker-error.c index 600427433..e2d1aa374 100644 --- a/src/libtracker-sparql/tracker-error.c +++ b/src/libtracker-sparql/tracker-error.c @@ -51,12 +51,13 @@ G_STATIC_ASSERT (G_N_ELEMENTS (tracker_sparql_error_entries) == TRACKER_SPARQL_N GQuark tracker_sparql_error_quark (void) { - static volatile gsize quark_volatile = 0; - g_dbus_error_register_error_domain ("tracker-sparql-error-quark", - &quark_volatile, - tracker_sparql_error_entries, - G_N_ELEMENTS (tracker_sparql_error_entries)); - return (GQuark) quark_volatile; + static gsize quark = 0; + + g_dbus_error_register_error_domain ("tracker-sparql-error-quark", + &quark, + tracker_sparql_error_entries, + G_N_ELEMENTS (tracker_sparql_error_entries)); + return (GQuark) quark; } /* Converts internal error codes into public -- cgit v1.2.1 From 712abcc5f1690b223ead8df57c9cc2fdf66752dd Mon Sep 17 00:00:00 2001 From: Carlos Garnacho Date: Fri, 24 Feb 2023 19:06:20 +0100 Subject: build: Ensure to generate enum types for the error domain This is required for correct introspection of our error domain. --- src/libtracker-sparql/meson.build | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'src/libtracker-sparql') diff --git a/src/libtracker-sparql/meson.build b/src/libtracker-sparql/meson.build index 157ebccd2..cc236806e 100644 --- a/src/libtracker-sparql/meson.build +++ b/src/libtracker-sparql/meson.build @@ -11,7 +11,7 @@ version_header = configure_file( configuration: conf) enum_types = gnome.mkenums('tracker-sparql-enum-types', - sources: ['tracker-notifier.h', 'tracker-connection.h', 'tracker-enums.h'], + sources: ['tracker-notifier.h', 'tracker-connection.h', 'tracker-enums.h', 'tracker-error.h'], c_template: 'tracker-sparql-enum-types.c.template', h_template: 'tracker-sparql-enum-types.h.template', install_dir: join_paths(get_option('prefix'), get_option('includedir'), 'tracker-@0@'.format(tracker_api_version), 'libtracker-sparql'), @@ -169,6 +169,8 @@ if get_option('introspection').enabled() libtracker_sparql_sources, libtracker_sparql_public_headers, introspection_extra_sources, + version_header, + enum_types, ], dependencies: introspection_extra_deps, nsversion: tracker_api_version, -- cgit v1.2.1 From f76af4e5c00b8edb041e70d01320c9a363dd4b3b Mon Sep 17 00:00:00 2001 From: Carlos Garnacho Date: Fri, 24 Feb 2023 19:08:04 +0100 Subject: libtracker-sparql: Update library API documentation Port references and links to the gi-docgen format, and while at it flesh out some more documentation and adjust formatting to look better with the gi-docgen templates. --- src/libtracker-sparql/tracker-batch.c | 138 ++-- src/libtracker-sparql/tracker-connection.c | 712 ++++++++++++--------- src/libtracker-sparql/tracker-connection.h | 14 +- src/libtracker-sparql/tracker-cursor.c | 177 +++-- src/libtracker-sparql/tracker-cursor.h | 6 - src/libtracker-sparql/tracker-endpoint-dbus.c | 63 +- src/libtracker-sparql/tracker-endpoint-dbus.h | 6 - src/libtracker-sparql/tracker-endpoint-http.c | 72 ++- src/libtracker-sparql/tracker-endpoint-http.h | 9 - src/libtracker-sparql/tracker-endpoint.c | 35 +- src/libtracker-sparql/tracker-endpoint.h | 6 - src/libtracker-sparql/tracker-error.c | 5 - src/libtracker-sparql/tracker-error.h | 12 +- src/libtracker-sparql/tracker-namespace-manager.c | 67 +- src/libtracker-sparql/tracker-namespace-manager.h | 6 - src/libtracker-sparql/tracker-notifier.c | 90 +-- src/libtracker-sparql/tracker-notifier.h | 6 - src/libtracker-sparql/tracker-ontologies.h | 11 - src/libtracker-sparql/tracker-resource.c | 340 ++++++---- .../tracker-sparql-enum-types.h.template | 9 +- src/libtracker-sparql/tracker-statement.c | 208 +++--- src/libtracker-sparql/tracker-statement.h | 6 - src/libtracker-sparql/tracker-uri.c | 24 +- src/libtracker-sparql/tracker-utils.c | 16 +- src/libtracker-sparql/tracker-version.c | 24 +- 25 files changed, 1152 insertions(+), 910 deletions(-) (limited to 'src/libtracker-sparql') diff --git a/src/libtracker-sparql/tracker-batch.c b/src/libtracker-sparql/tracker-batch.c index 3a20e27a5..38c074fd2 100644 --- a/src/libtracker-sparql/tracker-batch.c +++ b/src/libtracker-sparql/tracker-batch.c @@ -19,30 +19,27 @@ * Author: Carlos Garnacho */ /** - * SECTION: tracker-batch - * @short_description: Update batches - * @title: TrackerBatch - * @stability: Stable - * @include: tracker-sparql.h - * - * #TrackerBatch is an object containing a series of SPARQL updates, - * in either SPARQL string or #TrackerResource form. This object has - * a single use, after the batch is executed, it can only be finished - * and freed. - * - * A batch is created with tracker_sparql_connection_create_batch(). - * To add resources use tracker_batch_add_resource() or - * tracker_batch_add_sparql(). - * - * When a batch is ready for execution, use tracker_batch_execute() - * or tracker_batch_execute_async(). The batch is executed as a single + * TrackerBatch: + * + * `TrackerBatch` executes a series of SPARQL updates and RDF data + * insertions within a transaction. + * + * A batch is created with [method@Tracker.SparqlConnection.create_batch]. + * To add resources use [method@Tracker.Batch.add_resource], + * [method@Tracker.Batch.add_sparql] or [method@Batch.add_statement]. + * + * When a batch is ready for execution, use [method@Tracker.Batch.execute] + * or [method@Tracker.Batch.execute_async]. The batch is executed as a single * transaction, it will succeed or fail entirely. * - * The mapping of blank node labels is global in a #TrackerBatch, + * This object has a single use, after the batch is executed it can + * only be finished and freed. + * + * The mapping of blank node labels is global in a `TrackerBatch`, * referencing the same blank node label in different operations in * a batch will resolve to the same resource. * - * This object was added in Tracker 3.1. + * Since: 3.1 */ #include "config.h" @@ -133,7 +130,7 @@ tracker_batch_class_init (TrackerBatchClass *klass) /** * TrackerBatch:connection: * - * The #TrackerSparqlConnection the batch belongs to. + * The [class@Tracker.SparqlConnection] the batch belongs to. */ props[PROP_CONNECTION] = g_param_spec_object ("connection", @@ -150,9 +147,10 @@ tracker_batch_class_init (TrackerBatchClass *klass) /** * tracker_batch_get_connection: - * @batch: a #TrackerBatch + * @batch: A `TrackerBatch` * - * Returns the #TrackerSparqlConnection that this batch was created from. + * Returns the [class@Tracker.SparqlConnection] that this batch was created + * from. * * Returns: (transfer none): The SPARQL connection of this batch. **/ @@ -168,8 +166,8 @@ tracker_batch_get_connection (TrackerBatch *batch) /** * tracker_batch_add_sparql: - * @batch: a #TrackerBatch - * @sparql: a SPARQL update string + * @batch: A `TrackerBatch` + * @sparql: A SPARQL update string * * Adds an SPARQL update string to @batch. * @@ -190,9 +188,9 @@ tracker_batch_add_sparql (TrackerBatch *batch, /** * tracker_batch_add_resource: - * @batch: a #TrackerBatch + * @batch: A `TrackerBatch` * @graph: (nullable): RDF graph to insert the resource to - * @resource: a #TrackerResource + * @resource: A [class@Tracker.Resource] * * Adds the RDF represented by @resource to @batch. * @@ -214,17 +212,18 @@ tracker_batch_add_resource (TrackerBatch *batch, /** * tracker_batch_add_statement: (skip): - * @batch: a #TrackerBatch - * @stmt: a #TrackerSparqlStatement containing a SPARQL update - * @...: parameters bound to @stmt, in triples of name/type/value + * @batch: a `TrackerBatch` + * @stmt: a [class@Tracker.SparqlStatement] containing a SPARQL update + * @...: NULL-terminated list of parameters bound to @stmt, in triplets of name, type and value. * - * Adds a #TrackerSparqlStatement containing an SPARQL update. The statement will + * Adds a [class@Tracker.SparqlStatement] containing an SPARQL update. The statement will * be executed once in the batch, with the parameters bound as specified in the * variable arguments. * - * The variable arguments are a NULL terminated set of variable name, value GType, - * and actual value. For example, for a statement that has a single `~name` parameter, - * it could be given a value for execution with the given code: + * The variable arguments are a NULL terminated set of variable name, type [type@GObject.Type], + * and value. The value C type must correspond to the given [type@GObject.Type]. For example, for + * a statement that has a single `~name` parameter, it could be given a value for execution + * with the following code: * * ```c * tracker_batch_add_statement (batch, stmt, @@ -232,13 +231,13 @@ tracker_batch_add_resource (TrackerBatch *batch, * NULL); * ``` * - * The #TrackerSparqlStatement may be used on multiple tracker_batch_add_statement() - * calls with the same or different values, on the same or different #TrackerBatch + * A [class@Tracker.SparqlStatement] may be used on multiple [method@Tracker.Batch.add_statement] + * calls with the same or different values, on the same or different `TrackerBatch` * objects. * - * This function should only be called on #TrackerSparqlStatement objects - * obtained through tracker_sparql_connection_update_statement() or - * update statements loaded through tracker_sparql_connection_load_statement_from_gresource(). + * This function should only be called on [class@Tracker.SparqlStatement] objects + * obtained through [method@Tracker.SparqlConnection.update_statement] or + * update statements loaded through [method@Tracker.SparqlConnection.load_statement_from_gresource]. * * Since: 3.5 **/ @@ -295,22 +294,20 @@ tracker_batch_add_statement (TrackerBatch *batch, /** * tracker_batch_add_statementv: (rename-to tracker_batch_add_statement) - * @batch: a #TrackerBatch - * @stmt: a #TrackerSparqlStatement containing a SPARQL update - * @n_values: the number of bound parameters - * @variable_names: (array length=n_values): the names of each bound parameter - * @values: (array length=n_values): the values of each bound parameter + * @batch: A `TrackerBatch` + * @stmt: A [class@Tracker.SparqlStatement] containing a SPARQL update + * @n_values: The number of bound parameters + * @variable_names: (array length=n_values): The names of each bound parameter + * @values: (array length=n_values): The values of each bound parameter * - * Adds a #TrackerSparqlStatement containing an SPARQL update. The statement will + * Adds a [class@Tracker.SparqlStatement] containing an SPARQL update. The statement will * be executed once in the batch, with the values bound as specified by @variable_names * and @values. * * For example, for a statement that has a single `~name` parameter, * it could be given a value for execution with the given code: * - * 

- *
- * ```
+ * ```c
  * const char *names = { "name" };
  * const GValue values[G_N_ELEMENTS (names)] = { 0, };
  *
@@ -320,29 +317,20 @@ tracker_batch_add_statement (TrackerBatch           *batch,
  *                               G_N_ELEMENTS (names),
  *                               names, values);
  * ```
- *
- * - * 

- *
- * ```
+ * ```python
  * batch.add_statement(stmt, ['name'], ['John Smith']);
  * ```
- *
- * - * 

- *
- * ```
+ * ```js
  * batch.add_statement(stmt, ['name'], ['John Smith']);
  * ```
- *
* - * The #TrackerSparqlStatement may be used on multiple tracker_batch_add_statement() - * calls with the same or different values, on the same or different #TrackerBatch + * A [class@Tracker.SparqlStatement] may be used on multiple [method@Tracker.Batch.add_statement] + * calls with the same or different values, on the same or different `TrackerBatch` * objects. * - * This function should only be called on #TrackerSparqlStatement objects - * obtained through tracker_sparql_connection_update_statement() or - * update statements loaded through tracker_sparql_connection_load_statement_from_gresource(). + * This function should only be called on [class@Tracker.SparqlStatement] objects + * obtained through [method@Tracker.SparqlConnection.update_statement] or + * update statements loaded through [method@Tracker.SparqlConnection.load_statement_from_gresource]. * * Since: 3.5 **/ @@ -366,9 +354,9 @@ tracker_batch_add_statementv (TrackerBatch *batch, /** * tracker_batch_execute: - * @batch: a #TrackerBatch - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: location for a #GError, or %NULL + * @batch: a `TrackerBatch` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * * Executes the batch. This operations happens synchronously. * @@ -394,11 +382,11 @@ tracker_batch_execute (TrackerBatch *batch, /** * tracker_batch_execute_async: - * @batch: a #TrackerBatch - * @cancellable: (nullable): 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 + * @batch: A `TrackerBatch` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback * * Executes the batch. This operation happens asynchronously, when * finished @callback will be executed. @@ -424,11 +412,11 @@ tracker_batch_execute_async (TrackerBatch *batch, /** * tracker_batch_execute_finish: - * @batch: a #TrackerBatch - * @res: a #GAsyncResult with the result of the operation - * @error: location for a #GError, or %NULL + * @batch: A `TrackerBatch` + * @res: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes the operation started with tracker_batch_execute_async(). + * Finishes the operation started with [method@Tracker.Batch.execute_async]. * * Returns: %TRUE of there were no errors, %FALSE otherwise * diff --git a/src/libtracker-sparql/tracker-connection.c b/src/libtracker-sparql/tracker-connection.c index fcc4ba3b3..76f57b636 100644 --- a/src/libtracker-sparql/tracker-connection.c +++ b/src/libtracker-sparql/tracker-connection.c @@ -18,43 +18,67 @@ */ /** - * SECTION: tracker-sparql-connection - * @short_description: Connection to SPARQL triple store - * @title: TrackerSparqlConnection - * @stability: Stable - * @include: tracker-sparql.h - * - * #TrackerSparqlConnection is an object that represents a connection to a - * SPARQL triple store. This store may be local and private (see - * tracker_sparql_connection_new()), or it may be a remote connection to a - * public endpoint (See tracker_sparql_connection_bus_new() and - * tracker_sparql_connection_remote_new()). - * - * A #TrackerSparqlConnection is private to the calling process, it can be - * exposed publicly via a #TrackerEndpoint, see tracker_endpoint_dbus_new(). - * - * Updates on a connection are performed via the tracker_sparql_connection_update() - * family of calls. tracker_sparql_connection_update_array() may be used for batched - * updates. All functions have asynchronous variants. - * - * Queries on a connection are performed via tracker_sparql_connection_query() - * and tracker_sparql_connection_query_statement(). The first call receives a - * query string and returns a #TrackerSparqlCursor to iterate the results. The - * second call returns a #TrackerSparqlStatement object that may be reused for - * repeatable queries with variable parameters. tracker_sparql_statement_execute() - * will returns a #TrackerSparqlCursor. - * - * Depending on the ontology definition, #TrackerSparqlConnection may emit - * notifications whenever changes happen in the stored data. These notifications - * can be processed via a #TrackerNotifier obtained with - * tracker_sparql_connection_create_notifier(). - * - * After use, a #TrackerSparqlConnection should be closed. See - * tracker_sparql_connection_close() and tracker_sparql_connection_close_async(). - * - * A #TrackerSparqlConnection may be used from multiple threads, asynchronous - * database updates are executed sequentially on arrival order, asynchronous - * queries are executed in a thread pool. + * TrackerSparqlConnection: + * + * `TrackerSparqlConnection` holds a connection to a RDF triple store. + * + * This triple store may be of three types: + * + * - Local to the process, created through [ctor@Tracker.SparqlConnection.new]. + * - A HTTP SPARQL endpoint over the network, created through + * [ctor@Tracker.SparqlConnection.remote_new] + * - A DBus SPARQL endpoint owned by another process in the same machine, created + * through [ctor@Tracker.SparqlConnection.bus_new] + * + * When creating a local triple store, it is required to give details about its + * structure. This is done by passing a location to an ontology, see more + * on how are [ontologies defined](ontologies.html). A local database may be + * stored in a filesystem location, or it may reside in memory. + * + * A `TrackerSparqlConnection` is private to the calling process, it can be + * exposed to other hosts/processes via a [class@Tracker.Endpoint], see + * [ctor@Tracker.EndpointDBus.new] and [ctor@Tracker.EndpointHttp.new]. + * + * When issuing SPARQL queries and updates, it is recommended that these are + * created through [class@Tracker.SparqlStatement] to avoid the SPARQL + * injection class of bugs, see [method@Tracker.SparqlConnection.query_statement] + * and [method@Tracker.SparqlConnection.update_statement]. For SPARQL updates + * it is also possible to use a "builder" approach to generate RDF data, see + * [class@Tracker.Resource]. It is also possible to create [class@Tracker.SparqlStatement] + * objects for SPARQL queries and updates from SPARQL strings embedded in a + * [struct@Gio.Resource], see [method@Tracker.SparqlConnection.load_statement_from_gresource]. + * + * To get the best performance, it is recommended that SPARQL updates are clustered + * through [class@Tracker.Batch]. + * + * `TrackerSparqlConnection` also offers a number of methods for the simple cases, + * [method@Tracker.SparqlConnection.query] may be used when there is a SPARQL + * query string directly available, and the [method@Tracker.SparqlConnection.update] + * family of functions may be used for one-off updates. All functions have asynchronous + * variants. + * + * When a SPARQL query is executed, a [class@Tracker.SparqlCursor] will be obtained + * to iterate over the query results. + * + * Depending on the ontology definition, `TrackerSparqlConnection` may emit + * notifications whenever resources of certain types get insert, modified or + * deleted from the triple store (see [nrl:notify](nrl-ontology.html#nrl:notify). + * These notifications can be handled via a [class@Tracker.Notifier] obtained with + * [method@Tracker.SparqlConnection.create_notifier]. + * + * After done with a connection, it is recommended to call [method@Tracker.SparqlConnection.close] + * or [method@Tracker.SparqlConnection.close_async] explicitly to cleanly close the + * connection and prevent consistency checks on future runs. The triple store + * connection will be implicitly closed when the `TrackerSparqlConnection` object + * is disposed. + * + * A `TrackerSparqlConnection` may be used from multiple threads, asynchronous + * updates are executed sequentially on arrival order, asynchronous + * queries are dispatched in a thread pool. + * + * If you ever have the need to procedurally compose SPARQL query strings, consider + * the use of [func@Tracker.sparql_escape_string] for literal strings and + * the [func@Tracker.sparql_escape_uri] family of functions for URIs. */ #include "config.h" @@ -118,21 +142,25 @@ tracker_sparql_connection_lookup_dbus_service (TrackerSparqlConnection *connect /** * tracker_sparql_connection_query: - * @connection: a #TrackerSparqlConnection - * @sparql: string containing the SPARQL query - * @cancellable: a #GCancellable used to cancel the operation - * @error: #GError for error reporting. + * @connection: A `TrackerSparqlConnection` + * @sparql: String containing the SPARQL query + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * - * Executes a SPARQL query on. The API call is completely synchronous, so - * it may block. + * Executes a SPARQL query on @connection. * - * The @sparql query should be built with #TrackerResource, or - * its parts correctly escaped using tracker_sparql_escape_string(), - * otherwise SPARQL injection is possible. + * This method is synchronous and will block until the query + * is executed. See [method@Tracker.SparqlConnection.query_async] + * for an asynchronous variant. + * + * If the query is partially built from user input or other + * untrusted sources, special care is required about possible + * SPARQL injection. In order to avoid it entirely, it is recommended + * to use [class@Tracker.SparqlStatement]. The function + * [func@Tracker.sparql_escape_string] exists as a last resort, + * but its use is not recommended. * - * Returns: (transfer full): 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. + * Returns: (transfer full): a [class@Tracker.SparqlCursor] with the results. */ TrackerSparqlCursor * tracker_sparql_connection_query (TrackerSparqlConnection *connection, @@ -159,14 +187,21 @@ tracker_sparql_connection_query (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_query_async: - * @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 - * - * Executes asynchronously a SPARQL query. + * @connection: A `TrackerSparqlConnection` + * @sparql: String containing the SPARQL query + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback + * + * Executes asynchronously a SPARQL query on @connection + * + * If the query is partially built from user input or other + * untrusted sources, special care is required about possible + * SPARQL injection. In order to avoid it entirely, it is recommended + * to use [class@Tracker.SparqlStatement]. The function + * [func@Tracker.sparql_escape_string] exists as a last resort, + * but its use is not recommended. */ void tracker_sparql_connection_query_async (TrackerSparqlConnection *connection, @@ -188,15 +223,13 @@ tracker_sparql_connection_query_async (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_query_finish: - * @connection: a #TrackerSparqlConnection - * @res: a #GAsyncResult with the result of the operation - * @error: #GError for error reporting. + * @connection: A `TrackerSparqlConnection` + * @res: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes the asynchronous SPARQL query operation. + * Finishes the operation started with [method@Tracker.SparqlConnection.query_async]. * - * Returns: (transfer full): 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. + * Returns: (transfer full): a [class@Tracker.SparqlCursor] with the results. */ TrackerSparqlCursor * tracker_sparql_connection_query_finish (TrackerSparqlConnection *connection, @@ -220,17 +253,28 @@ tracker_sparql_connection_query_finish (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_update: - * @connection: a #TrackerSparqlConnection - * @sparql: string containing the SPARQL update query - * @cancellable: a #GCancellable used to cancel the operation - * @error: #GError for error reporting. - * - * 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. + * @connection: A `TrackerSparqlConnection` + * @sparql: String containing the SPARQL update query + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location + * + * Executes a SPARQL update on @connection. + * + * This method is synchronous and will block until the update + * is finished. See [method@Tracker.SparqlConnection.update_async] + * for an asynchronous variant. + * + * It is recommented to consider the usage of [class@Tracker.Batch] + * to cluster database updates. Frequent isolated SPARQL updates + * through this method will have a degraded performance in comparison. + * + * If the query is partially built from user input or other + * untrusted sources, special care is required about possible + * SPARQL injection. In order to avoid it entirely, it is recommended + * to use [class@Tracker.SparqlStatement], or to build the SPARQL + * input through [class@Tracker.Resource]. The function + * [func@Tracker.sparql_escape_string] exists as a last resort, + * but its use is not recommended. */ void tracker_sparql_connection_update (TrackerSparqlConnection *connection, @@ -251,14 +295,26 @@ tracker_sparql_connection_update (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_update_async: - * @connection: a #TrackerSparqlConnection - * @sparql: string containing the SPARQL update 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 + * @connection: A `TrackerSparqlConnection` + * @sparql: String containing the SPARQL update query + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback * * Executes asynchronously a SPARQL update. + * + * It is recommented to consider the usage of [class@Tracker.Batch] + * to cluster database updates. Frequent isolated SPARQL updates + * through this method will have a degraded performance in comparison. + * + * If the query is partially built from user input or other + * untrusted sources, special care is required about possible + * SPARQL injection. In order to avoid it entirely, it is recommended + * to use [class@Tracker.SparqlStatement], or to build the SPARQL + * input through [class@Tracker.Resource]. The function + * [func@Tracker.sparql_escape_string] exists as a last resort, + * but its use is not recommended. */ void tracker_sparql_connection_update_async (TrackerSparqlConnection *connection, @@ -280,11 +336,11 @@ tracker_sparql_connection_update_async (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_update_finish: - * @connection: a #TrackerSparqlConnection - * @res: a #GAsyncResult with the result of the operation - * @error: #GError for error reporting. + * @connection: A `TrackerSparqlConnection` + * @res: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes the asynchronous SPARQL update operation. + * Finishes the operation started with [method@Tracker.SparqlConnection.update_async]. */ void tracker_sparql_connection_update_finish (TrackerSparqlConnection *connection, @@ -302,16 +358,24 @@ tracker_sparql_connection_update_finish (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_update_array_async: - * @connection: a #TrackerSparqlConnection - * @sparql: an array of strings containing the SPARQL update queries - * @sparql_length: the amount of strings you pass as @sparql - * @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 + * @connection: A `TrackerSparqlConnection` + * @sparql: An array of strings containing the SPARQL update queries + * @sparql_length: The amount of strings you pass as @sparql + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback * * Executes asynchronously an array of SPARQL updates. All updates in the * array are handled within a single transaction. + * + * If the query is partially built from user input or other + * untrusted sources, special care is required about possible + * SPARQL injection. In order to avoid it entirely, it is recommended + * to use [class@Tracker.SparqlStatement], or to build the SPARQL + * input through [class@Tracker.Resource]. The function + * [func@Tracker.sparql_escape_string] exists as a last resort, + * but its use is not recommended. */ void tracker_sparql_connection_update_array_async (TrackerSparqlConnection *connection, @@ -335,11 +399,11 @@ tracker_sparql_connection_update_array_async (TrackerSparqlConnection *connecti /** * tracker_sparql_connection_update_array_finish: - * @connection: a #TrackerSparqlConnection - * @res: a #GAsyncResult with the result of the operation - * @error: #GError for error reporting. + * @connection: A `TrackerSparqlConnection` + * @res: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes the asynchronous SPARQL update_array operation. + * Finishes the operation started with [method@Tracker.SparqlConnection.update_array_async]. * * Returns: #TRUE if there were no errors. */ @@ -360,16 +424,19 @@ tracker_sparql_connection_update_array_finish (TrackerSparqlConnection *connect /** * tracker_sparql_connection_update_blank: - * @connection: a #TrackerSparqlConnection - * @sparql: string containing the SPARQL update query - * @cancellable: a #GCancellable used to cancel the operation - * @error: #GError for error reporting. + * @connection: A `TrackerSparqlConnection` + * @sparql: String containing the SPARQL update query + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location + * + * Executes a SPARQL update and returns the names of the generated blank nodes. * - * Executes a SPARQL update and returns the URNs of the generated nodes, - * if any. The API call is completely synchronous, so it may block. + * This method is synchronous and will block until the update + * is finished. See [method@Tracker.SparqlConnection.update_blank_async] + * for an asynchronous variant. * - * The @sparql query should be built with #TrackerResource, or - * its parts correctly escaped using tracker_sparql_escape_string(), + * The @sparql query should be built with [class@Tracker.Resource], or + * its parts correctly escaped using [func@Tracker.sparql_escape_string], * otherwise SPARQL injection is possible. * * The format string of the `GVariant` is `aaa{ss}` (an array of an array @@ -379,14 +446,13 @@ tracker_sparql_connection_update_array_finish (TrackerSparqlConnection *connect * (e.g. `foo` for the blank node `_:foo`) and the URN that was generated for * it. For most updates the first two outer arrays will only contain one item. * - * Returns: a #GVariant with the generated URNs, which should be freed with - * g_variant_unref() when no longer used. + * Returns: a [type@GLib.Variant] with the generated URNs. * * Deprecated: 3.5: This function makes the expectation that blank nodes have * a durable name that persist. The SPARQL and RDF specs define a much more * reduced scope for blank node labels. This function advises a behavior that * goes against that reduced scope, and will directly make the returned values - * meaningless if the %TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES flag + * meaningless if the #TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES flag * is defined in the connection. * * Users that want names generated for them, should look for other methods @@ -411,18 +477,20 @@ tracker_sparql_connection_update_blank (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_update_blank_async: - * @connection: a #TrackerSparqlConnection - * @sparql: string containing the SPARQL update 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 - * - * Executes asynchronously a SPARQL update with blank nodes. See - * the tracker_sparql_connection_update_blank() documentation to - * see the differences with tracker_sparql_connection_update(). - * - * Deprecated: 3.5: See tracker_sparql_connection_update_blank(). + * @connection: A `TrackerSparqlConnection` + * @sparql: String containing the SPARQL update query + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback + * + * + * Executes asynchronously a SPARQL update and returns the names of the generated blank nodes. + * + * See the [method@Tracker.SparqlConnection.update_blank] documentation to + * learn the differences with [method@Tracker.SparqlConnection.update]. + * + * Deprecated: 3.5: See [method@Tracker.SparqlConnection.update_blank]. */ void tracker_sparql_connection_update_blank_async (TrackerSparqlConnection *connection, @@ -444,19 +512,19 @@ tracker_sparql_connection_update_blank_async (TrackerSparqlConnection *connectio /** * tracker_sparql_connection_update_blank_finish: - * @connection: a #TrackerSparqlConnection - * @res: a #GAsyncResult with the result of the operation - * @error: #GError for error reporting. + * @connection: A `TrackerSparqlConnection` + * @res: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location + * + * Finishes the operation started with [method@Tracker.SparqlConnection.update_blank_async]. * - * Finishes the asynchronous SPARQL update operation, and returns - * the URNs of the generated nodes, if any. See the - * tracker_sparql_connection_update_blank() documentation for the interpretation - * of the returned #GVariant. + * This method returns the URNs of the generated nodes, if any. See the + * [method@Tracker.SparqlConnection.update_blank] documentation for the interpretation + * of the returned [type@GLib.Variant]. * - * Returns: a #GVariant with the generated URNs, which should be freed with - * g_variant_unref() when no longer used. + * Returns: a [type@GLib.Variant] with the generated URNs. * - * Deprecated: 3.5: See tracker_sparql_connection_update_blank(). + * Deprecated: 3.5: See [method@Tracker.SparqlConnection.update_blank]. */ GVariant * tracker_sparql_connection_update_blank_finish (TrackerSparqlConnection *connection, @@ -474,14 +542,21 @@ tracker_sparql_connection_update_blank_finish (TrackerSparqlConnection *connect /** * tracker_sparql_connection_update_resource: - * @connection: a #TrackerSparqlConnection + * @connection: A `TrackerSparqlConnection` * @graph: (nullable): RDF graph where the resource should be inserted/updated, or %NULL for the default graph - * @resource: a #TrackerResource - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: pointer to a #GError, or %NULL + * @resource: A [class@Tracker.Resource] + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location + * + * Inserts a resource as described by @resource on the given @graph. * - * Inserts a resource as described by @resource, on the graph described by @graph. - * This operation blocks until done. + * This method is synchronous and will block until the update + * is finished. See [method@Tracker.SparqlConnection.update_resource_async] + * for an asynchronous variant. + * + * It is recommented to consider the usage of [class@Tracker.Batch] + * to cluster database updates. Frequent isolated SPARQL updates + * through this method will have a degraded performance in comparison. * * Returns: #TRUE if there were no errors. * @@ -508,16 +583,19 @@ tracker_sparql_connection_update_resource (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_update_resource_async: - * @connection: a #TrackerSparqlConnection + * @connection: A `TrackerSparqlConnection` * @graph: (nullable): RDF graph where the resource should be inserted/updated, or %NULL for the default graph - * @resource: a #TrackerResource - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: the #GAsyncReadyCallback called when the operation completes - * @user_data: data passed to @callback + * @resource: A [class@Tracker.Resource] + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback + * + * Inserts asynchronously a resource as described by @resource on the given @graph. * - * Inserts a resource as described by @resource, on the graph described by @graph. - * This operation is executed asynchronously, when finished @callback will be - * executed. + * It is recommented to consider the usage of [class@Tracker.Batch] + * to cluster database updates. Frequent isolated SPARQL updates + * through this method will have a degraded performance in comparison. * * Since: 3.1 **/ @@ -544,11 +622,11 @@ tracker_sparql_connection_update_resource_async (TrackerSparqlConnection *connec /** * tracker_sparql_connection_update_resource_finish: - * @connection: a #TrackerSparqlConnection - * @res: a #GAsyncResult with the result of the operation - * @error: pointer to a #GError, or %NULL + * @connection: A `TrackerSparqlConnection` + * @res: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes a tracker_sparql_connection_update_resource_async() operation. + * Finishes the operation started with [method@Tracker.SparqlConnection.update_resource_async]. * * Returns: #TRUE if there were no errors. * @@ -570,13 +648,12 @@ tracker_sparql_connection_update_resource_finish (TrackerSparqlConnection *conn /** * tracker_sparql_connection_get_namespace_manager: - * @connection: a #TrackerSparqlConnection + * @connection: A `TrackerSparqlConnection` * - * Retrieves a #TrackerNamespaceManager that contains all + * Returns a [class@Tracker.NamespaceManager] that contains all * prefixes in the ontology of @connection. * - * Returns: (transfer none): a #TrackerNamespaceManager for this - * connection. This object is owned by @connection and must not be freed. + * Returns: (transfer none): a [class@Tracker.NamespaceManager] with the prefixes of @connection. */ TrackerNamespaceManager * tracker_sparql_connection_get_namespace_manager (TrackerSparqlConnection *connection) @@ -593,16 +670,18 @@ tracker_sparql_connection_get_namespace_manager (TrackerSparqlConnection *connec /** * tracker_sparql_connection_query_statement: - * @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 + * @connection: A `TrackerSparqlConnection` + * @sparql: The SPARQL query + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * - * Prepares the given SELECT/DESCRIBE/CONSTRUCT @sparql as a #TrackerSparqlStatement. - * This prepared statement can be executed through tracker_sparql_statement_execute() - * or tracker_sparql_statement_serialize_async() families of functions. + * Prepares the given `SELECT`/`ASK`/`DESCRIBE`/`CONSTRUCT` SPARQL query as a + * [class@Tracker.SparqlStatement]. * - * Returns: (transfer full) (nullable): a prepared statement + * This prepared statement can be executed through [method@Tracker.SparqlStatement.execute] + * or [method@Tracker.SparqlStatement.serialize_async] families of functions. + * + * Returns: (transfer full) (nullable): A prepared statement */ TrackerSparqlStatement * tracker_sparql_connection_query_statement (TrackerSparqlConnection *connection, @@ -623,16 +702,17 @@ tracker_sparql_connection_query_statement (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_update_statement: - * @connection: a #TrackerSparqlConnection - * @sparql: the SPARQL update - * @cancellable: a #GCancellable used to cancel the operation, or %NULL - * @error: a #TrackerSparqlError or %NULL if no error occured + * @connection: A `TrackerSparqlConnection` + * @sparql: The SPARQL update + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location + * + * Prepares the given `INSERT`/`DELETE` SPARQL as a [class@Tracker.SparqlStatement]. * - * Prepares the given INSERT/DELETE/LOAD/CLEAR/DROP/ADD/MOVE/COPY/CREATE @sparql - * as a #TrackerSparqlStatement. This prepared statement can be executed through - * the tracker_sparql_statement_update() family of functions. + * This prepared statement can be executed through + * the [method@Tracker.SparqlStatement.update] family of functions. * - * Returns: (transfer full) (nullable): a prepared statement + * Returns: (transfer full) (nullable): A prepared statement * * Since: 3.5 */ @@ -658,35 +738,39 @@ tracker_sparql_connection_update_statement (TrackerSparqlConnection *connection /** * tracker_sparql_connection_create_notifier: - * @connection: a #TrackerSparqlConnection + * @connection: A `TrackerSparqlConnection` + * + * Creates a new [class@Tracker.Notifier] to receive notifications about changes in @connection. * - * Creates a new #TrackerNotifier to notify about changes in @connection. - * See #TrackerNotifier documentation for information about how to use this + * See [class@Tracker.Notifier] documentation for information about how to use this * object. * - * Returns: (transfer full): a newly created notifier. Free with g_object_unref() - * when no longer needed. + * Connections to HTTP endpoints will return %NULL. + * + * Returns: (transfer full) (nullable): A newly created notifier. **/ TrackerNotifier * tracker_sparql_connection_create_notifier (TrackerSparqlConnection *connection) { g_return_val_if_fail (TRACKER_IS_SPARQL_CONNECTION (connection), NULL); + if (!TRACKER_SPARQL_CONNECTION_GET_CLASS (connection)->create_notifier) + return NULL; + return TRACKER_SPARQL_CONNECTION_GET_CLASS (connection)->create_notifier (connection); } /** * tracker_sparql_connection_close: - * @connection: a #TrackerSparqlConnection + * @connection: A `TrackerSparqlConnection` + * + * Closes a SPARQL connection. * - * Closes a SPARQL connection. No other API calls than g_object_unref() - * should happen after this call. + * 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. - * - * Since: 3.0 */ void tracker_sparql_connection_close (TrackerSparqlConnection *connection) @@ -698,17 +782,15 @@ tracker_sparql_connection_close (TrackerSparqlConnection *connection) /** * tracker_sparql_connection_close_async: - * @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 + * @connection: A `TrackerSparqlConnection` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback * - * 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. + * Closes a SPARQL connection asynchronously. * - * Since: 3.0 + * No other API calls than g_object_unref() should happen after this call. **/ void tracker_sparql_connection_close_async (TrackerSparqlConnection *connection, @@ -726,15 +808,13 @@ tracker_sparql_connection_close_async (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_close_finish: - * @connection: a #TrackerSparqlConnection - * @res: the #GAsyncResult - * @error: pointer to a #GError + * @connection: A `TrackerSparqlConnection` + * @res: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes the asynchronous connection close. + * Finishes the operation started with [method@Tracker.SparqlConnection.close_async]. * * Returns: %FALSE if some error occurred, %TRUE otherwise - * - * Since: 3.0 **/ gboolean tracker_sparql_connection_close_finish (TrackerSparqlConnection *connection, @@ -749,12 +829,13 @@ tracker_sparql_connection_close_finish (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_create_batch: - * @connection: a #TrackerSparqlConnection + * @connection: a `TrackerSparqlConnection` + * + * Creates a new [class@Tracker.Batch] to store and execute SPARQL updates. * - * Creates a new batch to store and execute update commands. If the connection - * is readonly or cannot issue SPARQL updates, %NULL will be returned. + * If the connection is readonly or cannot issue SPARQL updates, %NULL will be returned. * - * Returns: (transfer full): (nullable): A new #TrackerBatch + * Returns: (transfer full): (nullable): A new [class@Tracker.Batch] **/ TrackerBatch * tracker_sparql_connection_create_batch (TrackerSparqlConnection *connection) @@ -769,15 +850,19 @@ tracker_sparql_connection_create_batch (TrackerSparqlConnection *connection) /** * tracker_sparql_connection_load_statement_from_gresource: - * @connection: a #TrackerSparqlConnection - * @resource_path: the resource path of the file to parse. - * @cancellable: a #GCancellable, or %NULL - * @error: return location for an error, or %NULL + * @connection: A `TrackerSparqlConnection` + * @resource_path: The resource path of the file to parse. + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location + * + * Prepares a [class@Tracker.SparqlStatement] for the SPARQL contained as a [struct@Gio.Resource] + * file at @resource_path. * - * Prepares a #TrackerSparqlStatement for the SPARQL query contained as a resource - * file at @resource_path. SPARQL Query files typically have the .rq extension. + * SPARQL Query files typically have the .rq extension. This will use + * [method@Tracker.SparqlConnection.query_statement] or [method@Tracker.SparqlConnection.update_statement] + * underneath to indistinctly return SPARQL query or update statements. * - * Returns: (transfer full) (nullable): a prepared statement + * Returns: (transfer full) (nullable): A prepared statement * * Since: 3.3 **/ @@ -828,17 +913,19 @@ tracker_sparql_connection_load_statement_from_gresource (TrackerSparqlConnection /** * tracker_sparql_connection_serialize_async: - * @connection: a #TrackerSparqlConnection - * @flags: serialization flags - * @format: output RDF format + * @connection: A `TrackerSparqlConnection` + * @flags: Serialization flags + * @format: Output RDF format * @query: SPARQL query - * @cancellable: a #GCancellable - * @callback: the #GAsyncReadyCallback called when the operation completes - * @user_data: data passed to @callback + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback * - * Serializes data into the specified RDF format. @query must be either a - * `DESCRIBE` or `CONSTRUCT` query. This is an asynchronous operation, - * @callback will be invoked when the data is available for reading. + * Serializes a `DESCRIBE` or `CONSTRUCT` query into the specified RDF format. + * + * This is an asynchronous operation, @callback will be invoked when + * the data is available for reading. * * The SPARQL endpoint may not support the specified format, in that case * an error will be raised. @@ -875,14 +962,13 @@ tracker_sparql_connection_serialize_async (TrackerSparqlConnection *connection, /** * tracker_sparql_connection_serialize_finish: - * @connection: a #TrackerSparqlConnection - * @result: the #GAsyncResult - * @error: location for returned errors, or %NULL + * @connection: A `TrackerSparqlConnection` + * @result: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes a tracker_sparql_connection_serialize_async() operation. - * In case of error, %NULL will be returned and @error will be set. + * Finishes the operation started with [method@Tracker.SparqlConnection.serialize_async]. * - * Returns: (transfer full): a #GInputStream to read RDF content. + * Returns: (transfer full): A [class@Gio.InputStream] to read RDF content. * * Since: 3.3 **/ @@ -902,22 +988,23 @@ tracker_sparql_connection_serialize_finish (TrackerSparqlConnection *connection /** * tracker_sparql_connection_deserialize_async: - * @connection: a #TrackerSparqlConnection - * @flags: deserialization flags + * @connection: A `TrackerSparqlConnection` + * @flags: Deserialization flags * @format: RDF format of data in stream - * @default_graph: default graph that will receive the RDF data - * @stream: input stream with RDF data - * @cancellable: a #GCancellable - * @callback: the #GAsyncReadyCallback called when the operation completes - * @user_data: data passed to @callback - * - * Incorporates the contents of the RDF data contained in @stream into the - * data stored by @connection. This is an asynchronous operation, - * @callback will be invoked when the data has been fully inserted to - * @connection. - * - * RDF data will be inserted in the given @default_graph if one is provided, - * or the default graph if @default_graph is %NULL. Any RDF data that has a + * @default_graph: Default graph that will receive the RDF data + * @stream: Input stream with RDF data + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback + * + * Loads the RDF data contained in @stream into the given @connection. + + * This is an asynchronous operation, @callback will be invoked when the + * data has been fully inserted to @connection. + * + * The RDF data will be inserted in the given @default_graph if one is provided, + * or the anonymous graph if @default_graph is %NULL. Any RDF data that has a * graph specified (e.g. using the `GRAPH` clause in the Trig format) will * be inserted in the specified graph instead of @default_graph. * @@ -955,12 +1042,11 @@ tracker_sparql_connection_deserialize_async (TrackerSparqlConnection *connection /** * tracker_sparql_connection_deserialize_finish: - * @connection: a #TrackerSparqlConnection - * @result: the #GAsyncResult - * @error: location for returned errors, or %NULL + * @connection: A `TrackerSparqlConnection` + * @result: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes a tracker_sparql_connection_deserialize_async() operation. - * In case of error, %NULL will be returned and @error will be set. + * Finishes the operation started with [method@Tracker.SparqlConnection.deserialize_async]. * * Returns: %TRUE if all data was inserted successfully. * @@ -982,14 +1068,21 @@ tracker_sparql_connection_deserialize_finish (TrackerSparqlConnection *connecti /** * tracker_sparql_connection_map_connection: - * @connection: a #TrackerSparqlConnection - * @handle_name: handle name for @service_connection - * @service_connection: a #TrackerSparqlConnection to use from @connection + * @connection: A `TrackerSparqlConnection` + * @handle_name: Handle name for @service_connection + * @service_connection: a `TrackerSparqlConnection` to use from @connection + * + * Maps a `TrackerSparqlConnection` onto another through a `private:@handle_name` URI. * - * Maps @service_connection so it is available as a "private:@handle_name" URI - * in @connection. This can be accessed via the SERVICE SPARQL syntax in + * This can be accessed via the SERVICE SPARQL syntax in * queries from @connection. E.g.: * + * ```c + * tracker_sparql_connection_map_connection (connection, + * "other-connection", + * other_connection); + * ``` + * * ```sparql * SELECT ?u { * SERVICE { @@ -999,11 +1092,11 @@ tracker_sparql_connection_deserialize_finish (TrackerSparqlConnection *connecti * ``` * * This is useful to interrelate data from multiple - * #TrackerSparqlConnection instances maintained by the same process, + * `TrackerSparqlConnection` instances maintained by the same process, * without creating a public endpoint for @service_connection. * - * @connection may only be a #TrackerSparqlConnection created via - * tracker_sparql_connection_new() and tracker_sparql_connection_new_async(). + * @connection may only be a `TrackerSparqlConnection` created via + * [ctor@Tracker.SparqlConnection.new] and [func@Tracker.SparqlConnection.new_async]. * * Since: 3.3 **/ @@ -1028,11 +1121,12 @@ tracker_sparql_connection_map_connection (TrackerSparqlConnection *connection, * tracker_sparql_connection_remote_new: * @uri_base: Base URI of the remote connection * - * 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. + * Creates a connection to a remote HTTP SPARQL endpoint. + * + * The connection is made using the libsoup HTTP library. The connection will + * normally use the `https://` or `http://` protocols. * - * Returns: (transfer full): a new remote #TrackerSparqlConnection. Call - * g_object_unref() on the object when no longer used. + * Returns: (transfer full): a new remote `TrackerSparqlConnection`. */ TrackerSparqlConnection * tracker_sparql_connection_remote_new (const gchar *uri_base) @@ -1042,39 +1136,47 @@ tracker_sparql_connection_remote_new (const gchar *uri_base) /** * tracker_sparql_connection_new: - * @flags: values from #TrackerSparqlConnectionFlags - * @store: (nullable): the directory that contains the database as a #GFile, or %NULL - * @ontology: (nullable): the directory that contains the database schemas as a #GFile, or %NULL - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: pointer to a #GError + * @flags: Connection flags to define the SPARQL connection behavior + * @store: (nullable): The directory that contains the database as a [iface@Gio.File], or %NULL + * @ontology: (nullable): The directory that contains the database schemas as a [iface@Gio.File], or %NULL + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * - * Creates or opens a database. + * Creates or opens a process-local 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(). + * [ctor@Tracker.SparqlConnection.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. - * - * Returns: (transfer full): a new #TrackerSparqlConnection. Call - * g_object_unref() on the object when no longer used. - * - * Since: 3.0 + * If defined, the @ontology argument must point to a location containing + * suitable `.ontology` files in Turtle format. These define the structure of + * the triple store. You can learn more about [ontologies](ontologies.html), + * or you can use the stock Nepomuk ontologies by calling + * [func@Tracker.sparql_get_ontology_nepomuk]. + * + * If opening an existing database, it is possible to pass %NULL as the + * @ontology location, the ontology will be introspected from the database. + * Passing a %NULL @ontology will raise an error if the database does not exist. + * + * If a database is opened without the #TRACKER_SPARQL_CONNECTION_FLAG_READONLY + * flag enabled, and the given @ontology holds differences with the current + * data layout, migration to the new structure will be attempted. This operation + * 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. + * The database is always left in a consistent state, either prior or posterior + * to migration. + * + * It is considered a developer error to ship ontologies that contain format + * errors, or that fail at migrations. + * + * It is encouraged to use `resource:///` URI locations for @ontology wherever + * possible, so the triple store structure is tied to the executable binary, + * and in order to minimize disk seeks during `TrackerSparqlConnection` + * initialization. + * + * Returns: (transfer full): a new `TrackerSparqlConnection`. */ TrackerSparqlConnection * tracker_sparql_connection_new (TrackerSparqlConnectionFlags flags, @@ -1110,16 +1212,17 @@ new_async_cb (GObject *source, /** * tracker_sparql_connection_new_async: - * @flags: values from #TrackerSparqlConnectionFlags - * @store: (nullable): the directory that contains the database as a #GFile, or %NULL - * @ontology: (nullable): the directory that contains the database schemas as a #GFile, or %NULL - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: the #GAsyncReadyCallback called when the operation completes - * @user_data: data passed to @callback + * @flags: Connection flags to define the SPARQL connection behavior + * @store: (nullable): The directory that contains the database as a [iface@Gio.File], or %NULL + * @ontology: (nullable): The directory that contains the database schemas as a [iface@Gio.File], or %NULL + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback * - * Asynchronous version of tracker_sparql_connection_new(). + * Creates or opens a process-local database asynchronously. * - * Since: 3.0 + * See [ctor@Tracker.SparqlConnection.new] for more information. */ void @@ -1145,12 +1248,10 @@ tracker_sparql_connection_new_async (TrackerSparqlConnectionFlags flags, /** * tracker_sparql_connection_new_finish: - * @result: the #GAsyncResult - * @error: pointer to a #GError - * - * Completion function for tracker_sparql_connection_new_async(). + * @result: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Since: 3.0 + * Finishes the operation started with [func@Tracker.SparqlConnection.new_async]. */ TrackerSparqlConnection * tracker_sparql_connection_new_finish (GAsyncResult *res, @@ -1168,16 +1269,13 @@ tracker_sparql_connection_new_finish (GAsyncResult *res, * tracker_sparql_connection_bus_new: * @service_name: The name of the D-Bus service to connect to. * @object_path: (nullable): The path to the object, or %NULL to use the default. - * @dbus_connection: (nullable): The #GDBusConnection to use, or %NULL to use the session bus - * @error: pointer to a #GError + * @dbus_connection: (nullable): The [type@Gio.DBusConnection] to use, or %NULL to use the session bus + * @error: Error location * * Connects to a database owned by another process on the - * local machine. + * local machine via DBus. * - * Returns: (transfer full): a new #TrackerSparqlConnection. Call g_object_unref() on the - * object when no longer used. - * - * Since: 3.0 + * Returns: (transfer full): a new `TrackerSparqlConnection`. */ TrackerSparqlConnection * tracker_sparql_connection_bus_new (const gchar *service, @@ -1218,13 +1316,14 @@ bus_new_cb (GObject *source, * tracker_sparql_connection_bus_new_async: * @service_name: The name of the D-Bus service to connect to. * @object_path: (nullable): The path to the object, or %NULL to use the default. - * @dbus_connection: (nullable): The #GDBusConnection to use, or %NULL to use the session bus - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: the #GAsyncReadyCallback called when the operation completes - * @user_data: data passed to @callback + * @dbus_connection: (nullable): The [class@Gio.DBusConnection] to use, or %NULL to use the session bus + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. + * @user_data: User-defined data to be passed to @callback * - * Connects to a database owned by another process on the - * local machine. This is an asynchronous operation. + * Connects asynchronously to a database owned by another process on the + * local machine via DBus. * * Since: 3.1 */ @@ -1255,13 +1354,12 @@ tracker_sparql_connection_bus_new_async (const gchar *service, /** * tracker_sparql_connection_bus_new_finish: - * @result: the #GAsyncResult - * @error: pointer to a #GError + * @result: A [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Completion function for tracker_sparql_connection_bus_new_async(). + * Finishes the operation started with [func@Tracker.SparqlConnection.bus_new_async]. * - * Returns: (transfer full): a new #TrackerSparqlConnection. Call g_object_unref() on the - * object when no longer used. + * Returns: (transfer full): a new `TrackerSparqlConnection`. * * Since: 3.1 */ diff --git a/src/libtracker-sparql/tracker-connection.h b/src/libtracker-sparql/tracker-connection.h index d0923c9cd..f31c37890 100644 --- a/src/libtracker-sparql/tracker-connection.h +++ b/src/libtracker-sparql/tracker-connection.h @@ -55,6 +55,12 @@ typedef enum { TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES = 1 << 5, } TrackerSparqlConnectionFlags; +/** + * TrackerSerializeFlags: + * @TRACKER_SERIALIZE_FLAGS_NONE: No flags. + * + * Flags affecting serialization into a RDF data format. + */ typedef enum { TRACKER_SERIALIZE_FLAGS_NONE = 0, } TrackerSerializeFlags; @@ -63,18 +69,12 @@ typedef enum { * TrackerDeserializeFlags: * @TRACKER_DESERIALIZE_FLAGS_NONE: No flags. * - * Flags affecting deserialization of RDF. + * Flags affecting deserialization from a RDF data format. */ typedef enum { TRACKER_DESERIALIZE_FLAGS_NONE = 0, } TrackerDeserializeFlags; -/** - * TrackerSparqlConnection: - * - * The TrackerSparqlConnection object represents a - * SPARQL connection. - */ #define TRACKER_TYPE_SPARQL_CONNECTION tracker_sparql_connection_get_type () #define TRACKER_SPARQL_TYPE_CONNECTION TRACKER_TYPE_SPARQL_CONNECTION diff --git a/src/libtracker-sparql/tracker-cursor.c b/src/libtracker-sparql/tracker-cursor.c index d7eb83685..42a531aeb 100644 --- a/src/libtracker-sparql/tracker-cursor.c +++ b/src/libtracker-sparql/tracker-cursor.c @@ -17,16 +17,31 @@ * Boston, MA 02110-1301, USA. */ /** - * SECTION: tracker-sparql-cursor - * @short_description: Iteration of the query results - * @title: TrackerSparqlCursor - * @stability: Stable - * @include: tracker-sparql.h + * TrackerSparqlCursor: * - * #TrackerSparqlCursor is an object which provides methods to iterate the - * results of a query to the Tracker Store. + * `TrackerSparqlCursor` provides the methods to iterate the results of a SPARQL query. * - * It is possible to use a given #TrackerSparqlCursor in other threads than + * Cursors are obtained through e.g. [method@Tracker.SparqlStatement.execute] + * or [method@Tracker.SparqlConnection.query] after the SPARQL query has been + * executed. + * + * When created, a cursor does not point to any element, [method@Tracker.SparqlCursor.next] + * is necessary to iterate one by one to the first (and following) results. + * When the cursor iterated across all rows in the result set, [method@Tracker.SparqlCursor.next] + * will return %FALSE with no error set. + * + * On each row, it is possible to extract the result values through the + * [method@Tracker.SparqlCursor.get_integer], [method@Tracker.SparqlCursor.get_string], etc... family + * of methods. The column index of those functions starts at 0. The number of columns is + * dependent on the SPARQL query issued, but may be checked at runtime through the + * [method@Tracker.SparqlCursor.get_n_columns] method. + * + * After a cursor is iterated, it is recommended to call [method@Tracker.SparqlCursor.close] + * explicitly to free up resources for other users of the same [class@Tracker.SparqlConnection], + * this is especially important in garbage collected languages. These resources + * will be also implicitly freed on cursor object finalization. + * + * It is possible to use a given `TrackerSparqlCursor` in other threads than * the one it was created from. It must be however used from just one thread * at any given time. */ @@ -187,7 +202,7 @@ tracker_sparql_cursor_class_init (TrackerSparqlCursorClass *klass) /** * TrackerSparqlCursor:connection: * - * The #TrackerSparqlConnection used to retrieve the results. + * The [class@Tracker.SparqlConnection] used to retrieve the results. */ props[PROP_CONNECTION] = g_param_spec_object ("connection", @@ -199,9 +214,9 @@ tracker_sparql_cursor_class_init (TrackerSparqlCursorClass *klass) G_PARAM_READABLE | G_PARAM_WRITABLE); /** - * TrackerSparqlCursor:n_columns: + * TrackerSparqlCursor:n-columns: * - * Number of columns available in the results to iterate. + * Number of columns available in the result set. */ props[PROP_N_COLUMNS] = g_param_spec_int ("n-columns", @@ -216,12 +231,12 @@ tracker_sparql_cursor_class_init (TrackerSparqlCursorClass *klass) /** * tracker_sparql_cursor_get_connection: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * - * Returns the #TrackerSparqlConnection associated with this - * #TrackerSparqlCursor. + * Returns the [class@Tracker.SparqlConnection] associated with this + * `TrackerSparqlCursor`. * - * Returns: (transfer none): the cursor #TrackerSparqlConnection. The + * Returns: (transfer none): the cursor [class@Tracker.SparqlConnection]. The * returned object must not be unreferenced by the caller. */ TrackerSparqlConnection * @@ -248,14 +263,15 @@ tracker_sparql_cursor_set_connection (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_get_n_columns: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` + * + * Retrieves the number of columns available in the result set. * * This method should only be called after a successful - * tracker_sparql_cursor_next(); otherwise its return value + * [method@Tracker.SparqlCursor.next], otherwise its return value * will be undefined. * - * Returns: a #gint representing the number of columns available in the - * results to iterate. + * Returns: The number of columns returned in the result set. */ gint tracker_sparql_cursor_get_n_columns (TrackerSparqlCursor *cursor) @@ -267,15 +283,19 @@ tracker_sparql_cursor_get_n_columns (TrackerSparqlCursor *cursor) /** * tracker_sparql_cursor_get_string: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * @column: column number to retrieve (first one is 0) * @length: (out) (nullable): length of the returned string, or %NULL * * Retrieves a string representation of the data in the current * row in @column. * + * Any type may be converted to a string. If the value is not bound + * (See [method@Tracker.SparqlCursor.is_bound]) this method will return %NULL. + * * Returns: (nullable): a string which must not be freed. %NULL is returned if - * the column is not in the [0,#n_columns] range. + * the column is not in the `[0, n_columns]` range, or if the row/column + * refer to a nullable optional value in the result set. */ const gchar * tracker_sparql_cursor_get_string (TrackerSparqlCursor *cursor, @@ -291,12 +311,15 @@ tracker_sparql_cursor_get_string (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_get_boolean: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * @column: column number to retrieve (first one is 0) * * Retrieve a boolean for the current row in @column. * - * Returns: a #gboolean. + * If the row/column do not have a boolean value, the result is + * undefined, see [method@Tracker.SparqlCursor.get_value_type]. + * + * Returns: a boolean value. */ gboolean tracker_sparql_cursor_get_boolean (TrackerSparqlCursor *cursor, @@ -310,12 +333,15 @@ tracker_sparql_cursor_get_boolean (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_get_double: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * @column: column number to retrieve (first one is 0) * * Retrieve a double for the current row in @column. * - * Returns: a double. + * If the row/column do not have a integer or double value, the result is + * undefined, see [method@Tracker.SparqlCursor.get_value_type]. + * + * Returns: a double value. */ gdouble tracker_sparql_cursor_get_double (TrackerSparqlCursor *cursor, @@ -329,12 +355,15 @@ tracker_sparql_cursor_get_double (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_get_integer: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * @column: column number to retrieve (first one is 0) * * Retrieve an integer for the current row in @column. * - * Returns: a #gint64. + * If the row/column do not have an integer value, the result is + * undefined, see [method@Tracker.SparqlCursor.get_value_type]. + * + * Returns: a 64-bit integer value. */ gint64 tracker_sparql_cursor_get_integer (TrackerSparqlCursor *cursor, @@ -348,12 +377,23 @@ tracker_sparql_cursor_get_integer (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_get_value_type: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * @column: column number to retrieve (first one is 0) * - * The data type bound to the current row in @column is returned. + * Returns the data type bound to the current row and the given @column. + * + * If the column is unbound, the value will be %TRACKER_SPARQL_VALUE_TYPE_UNBOUND. + * See also [method@Tracker.SparqlCursor.is_bound]. * - * Returns: a #TrackerSparqlValueType. + * Values of type #TRACKER_SPARQL_VALUE_TYPE_RESOURCE and + * #TRACKER_SPARQL_VALUE_TYPE_BLANK_NODE can be considered equivalent, the + * difference is the resource being referenced as a named IRI or a blank + * node. + * + * All other [enum@Tracker.SparqlValueType] value types refer to literal values. + * + * Returns: a [enum@Tracker.SparqlValueType] expressing the content type of + * the given column for the current row. */ TrackerSparqlValueType tracker_sparql_cursor_get_value_type (TrackerSparqlCursor *cursor, @@ -368,12 +408,17 @@ tracker_sparql_cursor_get_value_type (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_get_variable_name: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * @column: column number to retrieve (first one is 0) * - * Retrieves the variable name for the current row in @column. + * Retrieves the name of the given @column. + * + * This name will be defined at the SPARQL query, either + * implicitly from the names of the variables returned in + * the resultset, or explicitly through the `AS ?var` SPARQL + * syntax. * - * Returns: a string which must not be freed. + * Returns: (nullable): The name of the given column. */ const gchar * tracker_sparql_cursor_get_variable_name (TrackerSparqlCursor *cursor, @@ -387,12 +432,14 @@ tracker_sparql_cursor_get_variable_name (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_get_datetime: - * @cursor: a #TrackerSparqlCursor - * @column: column number to retrieve (first one is 0) + * @cursor: a `TrackerSparqlCursor` + * @column: Column number to retrieve (first one is 0) + * + * Retrieves a [type@GLib.DateTime] pointer for the current row in @column. * - * Retrieve an GDateTime pointer for the current row in @column. + * Returns: (transfer full) (nullable): [type@GLib.DateTime] object, or %NULL if the given column does not + * contain a [xsd:date](xsd-ontology.html#xsd:date) or [xsd:dateTime](xsd-ontology.html#xsd:dateTime). * - * Returns: (transfer full) (nullable): #GDateTime object, or %NULL if the given column does not contain a xsd:date or xsd:dateTime * Since: 3.2 */ GDateTime * @@ -407,9 +454,9 @@ tracker_sparql_cursor_get_datetime (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_close: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * - * Closes the iterator, making it invalid. + * Closes the cursor. The object can only be freed after this call. */ void tracker_sparql_cursor_close (TrackerSparqlCursor *cursor) @@ -421,10 +468,12 @@ tracker_sparql_cursor_close (TrackerSparqlCursor *cursor) /** * tracker_sparql_cursor_is_bound: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * @column: column number to retrieve (first one is 0) * - * If the current row and @column are bound to a value, %TRUE is returned. + * Returns whether the given @column has a bound value in the current row. + * + * This may not be the case through e.g. the `OPTIONAL { }` SPARQL syntax. * * Returns: a %TRUE or %FALSE. */ @@ -439,14 +488,17 @@ tracker_sparql_cursor_is_bound (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_next: - * @cursor: a #TrackerSparqlCursor - * @cancellable: a #GCancellable used to cancel the operation - * @error: #GError for error reporting. + * @cursor: a `TrackerSparqlCursor` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location + * + * Iterates the cursor to the next result. * - * Iterates to the next result. This is completely synchronous and - * it may block. + * If the cursor was not started, it will point to the first result after + * this call. This operation is completely synchronous and it may block, + * see [method@Tracker.SparqlCursor.next_async] for an asynchronous variant. * - * Returns: %FALSE if no more results found, otherwise %TRUE. + * Returns: %FALSE if there are no more results or if an error is found, otherwise %TRUE. */ gboolean tracker_sparql_cursor_next (TrackerSparqlCursor *cursor, @@ -472,13 +524,21 @@ tracker_sparql_cursor_next (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_next_async: - * @cursor: a #TrackerSparqlCursor - * @cancellable: a #GCancellable used to cancel the operation - * @callback: user-defined #GAsyncReadyCallback to be called when + * @cursor: a `TrackerSparqlCursor` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: user-defined [type@Gio.AsyncReadyCallback] to be called when * asynchronous operation is finished. * @user_data: user-defined data to be passed to @callback * - * Iterates, asynchronously, to the next result. + * Iterates the cursor asyncronously to the next result. + * + * If the cursor was not started, it will point to the first result after + * this operation completes. + * + * In the period between this call and the corresponding + * [method@Tracker.SparqlCursor.next_finish] call, the other cursor methods + * should not be used, nor their results trusted. The cursor should only + * be iterated once at a time. */ void tracker_sparql_cursor_next_async (TrackerSparqlCursor *cursor, @@ -497,13 +557,14 @@ tracker_sparql_cursor_next_async (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_next_finish: - * @cursor: a #TrackerSparqlCursor - * @res: a #GAsyncResult with the result of the operation - * @error: #GError for error reporting. + * @cursor: a `TrackerSparqlCursor` + * @res: a [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes the asynchronous iteration to the next result. + * Finishes the asynchronous iteration to the next result started with + * [method@Tracker.SparqlCursor.next_async]. * - * Returns: %FALSE if no more results found, otherwise %TRUE. + * Returns: %FALSE if there are no more results or if an error is found, otherwise %TRUE. */ gboolean tracker_sparql_cursor_next_finish (TrackerSparqlCursor *cursor, @@ -529,12 +590,12 @@ tracker_sparql_cursor_next_finish (TrackerSparqlCursor *cursor, /** * tracker_sparql_cursor_rewind: - * @cursor: a #TrackerSparqlCursor + * @cursor: a `TrackerSparqlCursor` * * Resets the iterator to point back to the first result. * * Deprecated: 3.5: This function only works on cursors - * from direct #TrackerSparqlConnection objects and cannot work + * from direct [class@Tracker.SparqlConnection] objects and cannot work * reliably across all cursor types. Issue a different query to * obtain a new cursor. */ diff --git a/src/libtracker-sparql/tracker-cursor.h b/src/libtracker-sparql/tracker-cursor.h index 2316202e4..f96c44129 100644 --- a/src/libtracker-sparql/tracker-cursor.h +++ b/src/libtracker-sparql/tracker-cursor.h @@ -28,12 +28,6 @@ G_BEGIN_DECLS -/** - * TrackerSparqlCursor: - * - * The TrackerSparqlCursor object represents an - * iterator of results. - */ #define TRACKER_TYPE_SPARQL_CURSOR tracker_sparql_cursor_get_type () #define TRACKER_SPARQL_TYPE_CURSOR TRACKER_TYPE_SPARQL_CURSOR TRACKER_AVAILABLE_IN_ALL diff --git a/src/libtracker-sparql/tracker-endpoint-dbus.c b/src/libtracker-sparql/tracker-endpoint-dbus.c index fab046622..542765c78 100644 --- a/src/libtracker-sparql/tracker-endpoint-dbus.c +++ b/src/libtracker-sparql/tracker-endpoint-dbus.c @@ -20,23 +20,42 @@ */ /** - * SECTION: tracker-endpoint-dbus - * @short_description: DBus endpoint - * @title: TrackerEndpointDBus - * @stability: Stable - * @include: libtracker-sparql/tracker-sparql.h + * TrackerEndpointDBus: * - * #TrackerEndpointDBus is an endpoint implementation that exports - * a local #TrackerSparqlConnection so it is accessible in the given - * bus connection. + * `TrackerEndpointDBus` makes the RDF data in a [class@Tracker.SparqlConnection] + * accessible to other processes via DBus. + * + * This object is a [class@Tracker.Endpoint] subclass that exports + * a [class@Tracker.SparqlConnection] so its RDF data is accessible to other + * processes through the given [class@Gio.DBusConnection]. + * + * ```c + * // This process already has org.example.Endpoint bus name + * endpoint = tracker_endpoint_dbus_new (sparql_connection, + * dbus_connection, + * NULL, + * NULL, + * &error); + * + * // From another process + * connection = tracker_sparql_connection_bus_new ("org.example.Endpoint", + * NULL, + * dbus_connection, + * &error); + * ``` + * + * The `TrackerEndpointDBus` will manage a DBus object at the given path + * with the `org.freedesktop.Tracker3.Endpoint` interface, if no path is + * given the object will be at the default `/org/freedesktop/Tracker3/Endpoint` + * location. * * Access to these endpoints may be transparently managed through * the Tracker portal service for applications sandboxed via Flatpak, and * access to data constrained to the graphs defined in the applications * manifest. * - * A #TrackerEndpointDBus may be created on a different thread/main - * context than the one creating the #TrackerSparqlConnection. + * A `TrackerEndpointDBus` may be created on a different thread/main + * context from the one that created [class@Tracker.SparqlConnection]. */ #include "config.h" @@ -1375,12 +1394,22 @@ tracker_endpoint_dbus_class_init (TrackerEndpointDBusClass *klass) object_class->set_property = tracker_endpoint_dbus_set_property; object_class->get_property = tracker_endpoint_dbus_get_property; + /** + * TrackerEndpointDBus:dbus-connection: + * + * The [class@Gio.DBusConnection] where the connection is proxied through. + */ props[PROP_DBUS_CONNECTION] = g_param_spec_object ("dbus-connection", "DBus connection", "DBus connection", G_TYPE_DBUS_CONNECTION, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY); + /** + * TrackerEndpointDBus:object-path: + * + * The DBus object path that this endpoint manages. + */ props[PROP_OBJECT_PATH] = g_param_spec_string ("object-path", "DBus object path", @@ -1399,16 +1428,16 @@ tracker_endpoint_dbus_init (TrackerEndpointDBus *endpoint) /** * tracker_endpoint_dbus_new: - * @sparql_connection: a #TrackerSparqlConnection - * @dbus_connection: a #GDBusConnection - * @object_path: (nullable): the object path to use, or %NULL for the default - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: pointer to a #GError + * @sparql_connection: The [class@Tracker.SparqlConnection] being made public + * @dbus_connection: #GDBusConnection to expose the DBus object over + * @object_path: (nullable): The object path to use, or %NULL to use the default + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * * Registers a Tracker endpoint object at @object_path on @dbus_connection. - * The default object path is "/org/freedesktop/Tracker3/Endpoint". + * The default object path is `/org/freedesktop/Tracker3/Endpoint`. * - * Returns: (transfer full): a #TrackerEndpointDBus object. + * Returns: (transfer full): a `TrackerEndpointDBus` object. */ TrackerEndpointDBus * tracker_endpoint_dbus_new (TrackerSparqlConnection *sparql_connection, diff --git a/src/libtracker-sparql/tracker-endpoint-dbus.h b/src/libtracker-sparql/tracker-endpoint-dbus.h index 8c999f3ec..5f47eac9a 100644 --- a/src/libtracker-sparql/tracker-endpoint-dbus.h +++ b/src/libtracker-sparql/tracker-endpoint-dbus.h @@ -38,12 +38,6 @@ G_BEGIN_DECLS #define TRACKER_IS_ENDPOINT_DBUS_CLASS(c) (G_TYPE_CHECK_CLASS_TYPE ((c), TRACKER_TYPE_ENDPOINT_DBUS)) #define TRACKER_ENDPOINT_DBUS_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), TRACKER_TYPE_ENDPOINT_DBUS, TrackerEndpointDBusClass)) -/** - * TrackerEndpointDBus: - * - * The TrackerEndpointDBus object represents a public - * connection to a #TrackerSparqlConnection on a DBus object path. - */ typedef struct _TrackerEndpointDBus TrackerEndpointDBus; G_DEFINE_AUTOPTR_CLEANUP_FUNC (TrackerEndpointDBus, g_object_unref) diff --git a/src/libtracker-sparql/tracker-endpoint-http.c b/src/libtracker-sparql/tracker-endpoint-http.c index e38bb78bb..6ae2340ae 100644 --- a/src/libtracker-sparql/tracker-endpoint-http.c +++ b/src/libtracker-sparql/tracker-endpoint-http.c @@ -20,33 +20,49 @@ */ /** - * SECTION: tracker-endpoint-http - * @short_description: HTTP endpoint - * @title: TrackerEndpointHttp - * @stability: Stable - * @include: libtracker-sparql/tracker-sparql.h + * TrackerEndpointHttp: * - * #TrackerEndpointHttp is an endpoint implementation that exports - * a local #TrackerSparqlConnection so it is accessible via HTTP - * requests. + * `TrackerEndpointHttp` makes the RDF data in a [class@Tracker.SparqlConnection] + * accessible to other hosts via HTTP. * - * Access to these endpoints may be managed via the - * #TrackerEndpointHttp::block-remote-address signal, the boolean + * This object is a [class@Tracker.Endpoint] subclass that exports + * a [class@Tracker.SparqlConnection] so its RDF data is accessible via HTTP + * requests on the given port. This endpoint implementation is compliant + * with the [SPARQL protocol specifications](https://www.w3.org/TR/2013/REC-sparql11-protocol-20130321/) + * and may interoperate with other implementations. + * + * ```c + * // This host has "example.local" hostname + * endpoint = tracker_endpoint_http_new (sparql_connection, + * 8080, + * tls_certificate, + * NULL, + * &error); + * + * // From another host + * connection = tracker_sparql_connection_remote_new ("http://example.local:8080/sparql"); + * ``` + * + * Access to HTTP endpoints may be managed via the + * [signal@Tracker.EndpointHttp::block-remote-address] signal, the boolean * return value expressing whether the connection is blocked or not. * Inspection of the requester address is left up to the user. The * default value allows all requests independently of their provenance, * users are encouraged to add a handler. * - * If the provided #GTlsCertificate is %NULL, the endpoint will allow + * If the provided [class@Gio.TlsCertificate] is %NULL, the endpoint will allow * plain HTTP connections. Users are encouraged to provide a certificate * in order to use HTTPS. * - * As a security measure, and in compliance with the SPARQL 1.1 specifications, - * the HTTP endpoint does not support database updates or modifications in any - * way. The database is completely owned by the host. + * As a security measure, and in compliance specifications, + * the HTTP endpoint does not handle database updates or modifications in any + * way. The database content is considered to be entirely managed by the + * process that creates the HTTP endpoint and owns the [class@Tracker.SparqlConnection]. * - * A #TrackerEndpointHttp may be created on a different thread/main - * context than the one creating the #TrackerSparqlConnection. + * A `TrackerEndpointHttp` may be created on a different thread/main + * context from the one that created [class@Tracker.SparqlConnection]. + * + * Since: 3.1 */ #include "config.h" @@ -388,7 +404,7 @@ tracker_endpoint_http_class_init (TrackerEndpointHttpClass *klass) /** * TrackerEndpointHttp::block-remote-address: - * @self: The #TrackerNotifier + * @self: The `TrackerEndpointHttp` * @address: The socket address of the remote connection * * Allows control over the connections stablished. The given @@ -404,6 +420,11 @@ tracker_endpoint_http_class_init (TrackerEndpointHttpClass *klass) g_signal_accumulator_first_wins, NULL, NULL, G_TYPE_BOOLEAN, 1, G_TYPE_SOCKET_ADDRESS); + /** + * TrackerEndpointHttp:http-port: + * + * HTTP port used to listen requests. + */ props[PROP_HTTP_PORT] = g_param_spec_uint ("http-port", "HTTP Port", @@ -411,6 +432,11 @@ tracker_endpoint_http_class_init (TrackerEndpointHttpClass *klass) 0, G_MAXUINT, 8080, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY); + /** + * TrackerEndpointHttp:http-certificate: + * + * [class@Gio.TlsCertificate] to encrypt the communication. + */ props[PROP_HTTP_CERTIFICATE] = g_param_spec_object ("http-certificate", "HTTP certificate", @@ -429,17 +455,17 @@ tracker_endpoint_http_init (TrackerEndpointHttp *endpoint) /** * tracker_endpoint_http_new: - * @sparql_connection: a #TrackerSparqlConnection - * @port: HTTP port to listen to - * @certificate: (nullable): certificate to use for encription, or %NULL - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: pointer to a #GError + * @sparql_connection: The [class@Tracker.SparqlConnection] being made public + * @port: HTTP port to handle incoming requests + * @certificate: (nullable): Optional [type@Gio.TlsCertificate] to use for encription + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * * Sets up a Tracker endpoint to listen via HTTP, in the given @port. * If @certificate is not %NULL, HTTPS may be used to connect to the * endpoint. * - * Returns: (transfer full): a #TrackerEndpointDBus object. + * Returns: (transfer full): a `TrackerEndpointHttp` object. * * Since: 3.1 **/ diff --git a/src/libtracker-sparql/tracker-endpoint-http.h b/src/libtracker-sparql/tracker-endpoint-http.h index be6e6f408..a3c5a9dfa 100644 --- a/src/libtracker-sparql/tracker-endpoint-http.h +++ b/src/libtracker-sparql/tracker-endpoint-http.h @@ -33,17 +33,8 @@ G_BEGIN_DECLS #define TRACKER_TYPE_ENDPOINT_HTTP (tracker_endpoint_http_get_type()) #define TRACKER_ENDPOINT_HTTP(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), TRACKER_TYPE_ENDPOINT_HTTP, TrackerEndpointHttp)) -#define TRACKER_ENDPOINT_HTTP_CLASS(c) (G_TYPE_CHECK_CLASS_CAST ((c), TRACKER_TYPE_ENDPOINT_HTTP, TrackerEndpointHttpClass)) #define TRACKER_IS_ENDPOINT_HTTP(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), TRACKER_TYPE_ENDPOINT_HTTP)) -#define TRACKER_IS_ENDPOINT_HTTP_CLASS(c) (G_TYPE_CHECK_CLASS_TYPE ((c), TRACKER_TYPE_ENDPOINT_HTTP)) -#define TRACKER_ENDPOINT_HTTP_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), TRACKER_TYPE_ENDPOINT_HTTP, TrackerEndpointHttpClass)) -/** - * TrackerEndpointHttp: - * - * The TrackerEndpointHttp object represents a public - * connection to a #TrackerSparqlConnection on a HTTP port. - */ typedef struct _TrackerEndpointHttp TrackerEndpointHttp; G_DEFINE_AUTOPTR_CLEANUP_FUNC (TrackerEndpointHttp, g_object_unref) diff --git a/src/libtracker-sparql/tracker-endpoint.c b/src/libtracker-sparql/tracker-endpoint.c index f404e3f0c..10f3cb8be 100644 --- a/src/libtracker-sparql/tracker-endpoint.c +++ b/src/libtracker-sparql/tracker-endpoint.c @@ -39,20 +39,21 @@ typedef struct { G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (TrackerEndpoint, tracker_endpoint, G_TYPE_OBJECT) /** - * SECTION: tracker-endpoint - * @short_description: Expose a database outside the process - * @title: TrackerEndpoint - * @stability: Stable - * @include: tracker-endpoint.h + * TrackerEndpoint: * - * #TrackerEndpoint allows sharing data, either with other processes on the - * system via a Tracker-specific D-Bus API, or remote peers via the HTTP - * SPARQL protocol. + * `TrackerEndpoint` is a helper object to make RDF triple stores represented + * by a [class@Tracker.SparqlConnection] publicly available to other processes/hosts. * - * When it is shared in this way, other peers can connect to your database using - * tracker_sparql_connection_bus_new() or tracker_sparql_connection_remote_new(), - * and can also fetch data directly from SPARQL queries using the - * SELECT { SERVICE ... } syntax. + * This is a base abstract object, see [class@Tracker.EndpointDBus] to make + * RDF triple stores available to other processes in the same machine, and + * [class@Tracker.EndpointHttp] to make it available to other hosts in the + * network. + * + * When the RDF triple store represented by a [class@Tracker.SparqlConnection] + * is made public this way, other peers may connect to the database using + * [ctor@Tracker.SparqlConnection.bus_new] or [ctor@Tracker.SparqlConnection.remote_new] + * to access this endpoint exclusively, or they may use the `SERVICE { ... }` SPARQL + * syntax from their own [class@Tracker.SparqlConnection]s to expand their data set. */ static void @@ -113,6 +114,11 @@ tracker_endpoint_class_init (TrackerEndpointClass *klass) object_class->set_property = tracker_endpoint_set_property; object_class->get_property = tracker_endpoint_get_property; + /** + * TrackerEndpoint:sparql-connection: + * + * The [class@Tracker.SparqlConnection] being proxied by this endpoint. + */ props[PROP_SPARQL_CONNECTION] = g_param_spec_object ("sparql-connection", "Sparql connection", @@ -129,9 +135,10 @@ tracker_endpoint_init (TrackerEndpoint *endpoint) /** * tracker_endpoint_get_sparql_connection: - * @endpoint: a #TrackerEndpoint + * @endpoint: a `TrackerEndpoint` * - * Returns the #TrackerSparqlConnection that this endpoint proxies. + * Returns the [class@Tracker.SparqlConnection] that this endpoint proxies + * to a wider audience. * * Returns: (transfer none): The proxied SPARQL connection **/ diff --git a/src/libtracker-sparql/tracker-endpoint.h b/src/libtracker-sparql/tracker-endpoint.h index b764f5e35..4bcddda84 100644 --- a/src/libtracker-sparql/tracker-endpoint.h +++ b/src/libtracker-sparql/tracker-endpoint.h @@ -32,12 +32,6 @@ G_BEGIN_DECLS -/** - * TrackerEndpoint: - * - * The TrackerEndpoint object represents a public - * connection to a #TrackerSparqlConnection. - */ #define TRACKER_TYPE_ENDPOINT tracker_endpoint_get_type() TRACKER_AVAILABLE_IN_ALL G_DECLARE_DERIVABLE_TYPE (TrackerEndpoint, tracker_endpoint, TRACKER, ENDPOINT, GObject) diff --git a/src/libtracker-sparql/tracker-error.c b/src/libtracker-sparql/tracker-error.c index e2d1aa374..c9964382b 100644 --- a/src/libtracker-sparql/tracker-error.c +++ b/src/libtracker-sparql/tracker-error.c @@ -43,11 +43,6 @@ static const GDBusErrorEntry tracker_sparql_error_entries[] = G_STATIC_ASSERT (G_N_ELEMENTS (tracker_sparql_error_entries) == TRACKER_SPARQL_N_ERRORS); -/** - * tracker_sparql_error_quark: - * - * Returns: The error domain quark used for Tracker errors. - **/ GQuark tracker_sparql_error_quark (void) { diff --git a/src/libtracker-sparql/tracker-error.h b/src/libtracker-sparql/tracker-error.h index 3ea9729a2..40ff3a709 100644 --- a/src/libtracker-sparql/tracker-error.h +++ b/src/libtracker-sparql/tracker-error.h @@ -26,14 +26,6 @@ G_BEGIN_DECLS -/** - * SECTION: tracker-sparql-error - * @short_description: Error codes - * @title: TrackerSparqlError - * @stability: Stable - * @include: tracker-sparql.h - */ - /** * TrackerSparqlError: * @TRACKER_SPARQL_ERROR_CONSTRAINT: Subject is not in the domain of a property or @@ -56,7 +48,7 @@ G_BEGIN_DECLS * @TRACKER_SPARQL_ERROR_LAST: The total number of error codes. * * Error domain for Tracker Sparql. Errors in this domain will be from the - * #TrackerSparqlError enumeration. See #GError for more information on error + * [error@Tracker.SparqlError] enumeration. See [struct@GLib.Error] for more information on error * domains. */ typedef enum { @@ -79,7 +71,7 @@ typedef enum { } TrackerSparqlError; #define TRACKER_SPARQL_N_ERRORS TRACKER_SPARQL_ERROR_LAST -#define TRACKER_SPARQL_ERROR tracker_sparql_error_quark () +#define TRACKER_SPARQL_ERROR (tracker_sparql_error_quark ()) TRACKER_AVAILABLE_IN_ALL GQuark tracker_sparql_error_quark (void); diff --git a/src/libtracker-sparql/tracker-namespace-manager.c b/src/libtracker-sparql/tracker-namespace-manager.c index f2eabdf00..2e13e3a8c 100644 --- a/src/libtracker-sparql/tracker-namespace-manager.c +++ b/src/libtracker-sparql/tracker-namespace-manager.c @@ -47,21 +47,19 @@ G_DEFINE_TYPE_WITH_PRIVATE (TrackerNamespaceManager, tracker_namespace_manager, #define GET_PRIVATE(object) (tracker_namespace_manager_get_instance_private (object)) /** - * SECTION: tracker-namespace-manager - * @short_description: A set of well-known namespaces, and known abbreviations for them - * @title: TrackerNamespaceManager - * @stability: Stable - * @include: libtracker-sparql/tracker-sparql.h + * TrackerNamespaceManager: * - * #TrackerNamespaceManager keeps track of namespaces. It allows you to assign - * short prefixes for them to avoid typing full URLs all the time. + * `TrackerNamespaceManager` object represents a mapping between namespaces and + * their shortened prefixes. * - * The syntax used is that of Compact URIs (CURIEs) as defined here: - * (https://www.w3.org/TR/2010/NOTE-curie-20101216) + * This object keeps track of namespaces, and allows you to assign + * short prefixes for them to avoid frequent use of full namespace IRIs. The syntax + * used is that of [Compact URIs (CURIEs)](https://www.w3.org/TR/2010/NOTE-curie-20101216). * - * Usually you will want to use the default namespace manager, as returned by - * tracker_namespace_manager_get_default(). This has a set of well-known - * prefixes predefined. + * Usually you will want to use a namespace manager obtained through + * [method@Tracker.SparqlConnection.get_namespace_manager] from the + * [class@Tracker.SparqlConnection] that manages the RDF data, as that will + * contain all prefixes and namespaces that are pre-defined by its ontology. */ static void finalize (GObject *object); @@ -101,9 +99,9 @@ finalize (GObject *object) /** * tracker_namespace_manager_new: * - * Creates a new #TrackerNamespaceManager instance. + * Creates a new, empty `TrackerNamespaceManager` instance. * - * Returns: a new #TrackerNamespaceManager instance + * Returns: a new `TrackerNamespaceManager` instance */ TrackerNamespaceManager * tracker_namespace_manager_new () @@ -118,16 +116,16 @@ tracker_namespace_manager_new () /** * tracker_namespace_manager_get_default: * - * Returns the global #TrackerNamespaceManager that contains a set of well-known - * namespaces and prefixes, such as rdf:, rdfs:, nie:, tracker:, etc. + * Returns the global `TrackerNamespaceManager` that contains a set of well-known + * namespaces and prefixes, such as `rdf:`, `rdfs:`, `nie:`, `tracker:`, etc. * * Note that the list of prefixes and namespaces is hardcoded in * libtracker-sparql. It may not correspond with the installed set of * ontologies, if they have been modified since they were installed. * - * Returns: (transfer none): a global, shared #TrackerNamespaceManager instance + * Returns: (transfer none): a global, shared `TrackerNamespaceManager` instance * - * Deprecated: 3.3: Use tracker_sparql_connection_get_namespace_manager() instead. + * Deprecated: 3.3: Use [method@Tracker.SparqlConnection.get_namespace_manager] instead. */ TrackerNamespaceManager * tracker_namespace_manager_get_default () @@ -164,12 +162,12 @@ tracker_namespace_manager_get_default () /** * tracker_namespace_manager_has_prefix: - * @self: a #TrackerNamespaceManager + * @self: a `TrackerNamespaceManager` * @prefix: a string * * Returns whether @prefix is known. * - * Returns: %TRUE if the #TrackerNamespaceManager knows about @prefix, %FALSE otherwise + * Returns: %TRUE if the `TrackerNamespaceManager` knows about @prefix, %FALSE otherwise */ gboolean tracker_namespace_manager_has_prefix (TrackerNamespaceManager *self, @@ -186,13 +184,13 @@ tracker_namespace_manager_has_prefix (TrackerNamespaceManager *self, /** * tracker_namespace_manager_lookup_prefix: - * @self: a #TrackerNamespaceManager + * @self: a `TrackerNamespaceManager` * @prefix: a string * * Looks up the namespace URI corresponding to @prefix, or %NULL if the prefix * is not known. * - * Returns: (nullable): a string owned by the #TrackerNamespaceManager, or %NULL + * Returns: (nullable): a string owned by the `TrackerNamespaceManager`, or %NULL */ const char * tracker_namespace_manager_lookup_prefix (TrackerNamespaceManager *self, @@ -209,7 +207,7 @@ tracker_namespace_manager_lookup_prefix (TrackerNamespaceManager *self, /** * tracker_namespace_manager_add_prefix: - * @self: a #TrackerNamespaceManager + * @self: A `TrackerNamespaceManager` * @prefix: a short, unique prefix to identify @namespace * @ns: the URL of the given namespace * @@ -218,9 +216,9 @@ tracker_namespace_manager_lookup_prefix (TrackerNamespaceManager *self, * Only one prefix is allowed for a given namespace, and all prefixes must * be unique. * - * Since 3.3, This function may not be used on #TrackerNamespaceManager - * instances that were obtained through - * tracker_sparql_connection_get_namespace_manager(). + * Since 3.3, The `TrackerNamespaceManager` instances obtained through + * [method@Tracker.SparqlConnection.get_namespace_manager] are "sealed", + * this API call should not performed on those. */ void tracker_namespace_manager_add_prefix (TrackerNamespaceManager *self, @@ -270,14 +268,14 @@ tracker_namespace_manager_add_prefix (TrackerNamespaceManager *self, /** * tracker_namespace_manager_expand_uri: - * @self: a #TrackerNamespaceManager + * @self: a `TrackerNamespaceManager` * @compact_uri: a URI or compact URI * * If @compact_uri begins with one of the prefixes known to this - * #TrackerNamespaceManager, then the return value will be the + * `TrackerNamespaceManager`, then the return value will be the * expanded URI. Otherwise, a copy of @compact_uri will be returned. * - * Returns: a newly-allocated string + * Returns: The possibly expanded URI in a newly-allocated string. */ char * tracker_namespace_manager_expand_uri (TrackerNamespaceManager *self, @@ -314,11 +312,11 @@ tracker_namespace_manager_expand_uri (TrackerNamespaceManager *self, /** * tracker_namespace_manager_compress_uri: - * @self: a #TrackerNamespaceManager + * @self: a `TrackerNamespaceManager` * @uri: a URI or compact URI * * If @uri begins with one of the namespaces known to this - * #TrackerNamespaceManager, then the return value will be the + * `TrackerNamespaceManager`, then the return value will be the * compressed URI. Otherwise, %NULL will be returned. * * Returns: (transfer full): (nullable): the compressed URI @@ -360,9 +358,10 @@ tracker_namespace_manager_compress_uri (TrackerNamespaceManager *self, /** * tracker_namespace_manager_print_turtle: - * @self: a #TrackerNamespaceManager + * @self: a `TrackerNamespaceManager` * - * Writes out all namespaces as Turtle @prefix statements. + * Writes out all namespaces as `@prefix` statements in + * the [Turtle](https://www.w3.org/TR/turtle/) RDF format. * * Returns: a newly-allocated string */ @@ -391,7 +390,7 @@ tracker_namespace_manager_print_turtle (TrackerNamespaceManager *self) /** * tracker_namespace_manager_foreach: - * @self: a #TrackerNamespaceManager + * @self: a `TrackerNamespaceManager` * @func: (scope call): the function to call for each prefix / URI pair * @user_data: user data to pass to the function * diff --git a/src/libtracker-sparql/tracker-namespace-manager.h b/src/libtracker-sparql/tracker-namespace-manager.h index 04e081356..f418cc71d 100644 --- a/src/libtracker-sparql/tracker-namespace-manager.h +++ b/src/libtracker-sparql/tracker-namespace-manager.h @@ -30,12 +30,6 @@ G_BEGIN_DECLS #include -/** - * TrackerNamespaceManager: - * - * The TrackerNamespaceManager object represents a - * mapping of prefixes and namespaces. - */ #define TRACKER_TYPE_NAMESPACE_MANAGER (tracker_namespace_manager_get_type()) TRACKER_AVAILABLE_IN_ALL G_DECLARE_FINAL_TYPE (TrackerNamespaceManager, tracker_namespace_manager, TRACKER, NAMESPACE_MANAGER, GObject) diff --git a/src/libtracker-sparql/tracker-notifier.c b/src/libtracker-sparql/tracker-notifier.c index 78056c2c0..1ac26e019 100644 --- a/src/libtracker-sparql/tracker-notifier.c +++ b/src/libtracker-sparql/tracker-notifier.c @@ -18,30 +18,36 @@ */ /** - * SECTION: tracker-notifier - * @title: TrackerNotifier - * @short_description: Listen to changes in the Tracker database - * @stability: Stable - * @include: libtracker-sparql/tracker-sparql.h + * TrackerNotifier: * - * #TrackerNotifier is an object that receives notifications about - * changes to the Tracker database. A #TrackerNotifier is created - * through tracker_sparql_connection_create_notifier(), after the notifier - * is created, events can be listened for by connecting to the - * #TrackerNotifier::events signal. + * `TrackerNotifier` allows receiving notification on changes + * in the data stored by a [class@Tracker.SparqlConnection]. * - * # Known caveats + * This object may be created through [method@Tracker.SparqlConnection.create_notifier], + * events can then be listened for by connecting to the + * [signal@Tracker.Notifier::events] signal. * - * * The %TRACKER_NOTIFIER_EVENT_DELETE events will be received after the - * resource has been deleted. At that time queries on those elements will - * not bring any metadata. Only the ID/URN obtained through the event - * remain meaningful. - * * Notifications of files being moved across indexed folders will - * appear as %TRACKER_NOTIFIER_EVENT_UPDATE events, containing - * the new location (if requested). The older location is no longer - * known to Tracker, this may make tracking of elements in specific - * folders hard using solely the #TrackerNotifier/Tracker data - * available at event notification time. + * Not every change is notified, only RDF resources with a + * class that has the [nrl:notify](nrl-ontology.html#nrl:notify) + * property defined by the ontology will be notified upon changes. + * + * Database changes are communicated through [struct@Tracker.NotifierEvent] events on + * individual graph/resource pairs. The event type obtained through + * [method@Tracker.NotifierEvent.get_event_type] will determine the type of event. + * Insertion of new resources is notified through + * %TRACKER_NOTIFIER_EVENT_CREATE events, deletion of + * resources is notified through %TRACKER_NOTIFIER_EVENT_DELETE + * events, and changes on any property of the resource is notified + * through %TRACKER_NOTIFIER_EVENT_UPDATE events. + * + * The events happen in reaction to database changes, after a `TrackerNotifier` + * received an event of type %TRACKER_NOTIFIER_EVENT_DELETE, the resource will + * not exist anymore and only the information in the [struct@Tracker.NotifierEvent] + * will remain. + * + * Similarly, when receiving an event of type %TRACKER_NOTIFIER_EVENT_UPDATE, + * the resource will have already changed, so the data previous to the update is + * no longer available. */ #include "config.h" @@ -745,10 +751,10 @@ tracker_notifier_class_init (TrackerNotifierClass *klass) /** * TrackerNotifier::events: - * @self: The #TrackerNotifier + * @self: The `TrackerNotifier` * @service: The SPARQL service that originated the events, %NULL for the local store * @graph: The graph where the events happened on, %NULL for the default anonymous graph - * @events: (element-type TrackerNotifierEvent): A #GPtrArray of #TrackerNotifierEvent + * @events: (transfer none) (type GLib.PtrArray) (element-type TrackerNotifierEvent): A [type@GLib.PtrArray] of [struct@Tracker.NotifierEvent] * * Notifies of changes in the Tracker database. */ @@ -793,23 +799,26 @@ tracker_notifier_init (TrackerNotifier *notifier) /** * tracker_notifier_signal_subscribe: - * @notifier: a #TrackerNotifier - * @connection: a #GDBusConnection + * @notifier: A `TrackerNotifier` + * @connection: A [class@Gio.DBusConnection] * @service: DBus service name to subscribe to events for * @object_path: (nullable): DBus object path to subscribe to events for, or %NULL - * @graph: (nullable): graph to listen events for, or %NULL + * @graph: (nullable): Graph to listen events for, or %NULL * - * Listens to notification events from a remote SPARQL endpoint as a DBus - * service (see #TrackerEndpointDBus). If the @object_path argument is - * %NULL, the default "/org/freedesktop/Tracker3/Endpoint" path will be + * Listens to notification events from a remote DBus SPARQL endpoint. + * + * If the @object_path argument is %NULL, the default + * `/org/freedesktop/Tracker3/Endpoint` path will be * used. If @graph is %NULL, all graphs will be listened for. * * The signal subscription can be removed with - * tracker_notifier_signal_unsubscribe(). + * [method@Tracker.Notifier.signal_unsubscribe]. * - * Returns: An ID for this subscription + * Note that this call is not necessary to receive notifications on + * a connection obtained through [ctor@Tracker.SparqlConnection.bus_new], + * only to listen to update notifications from additional DBus endpoints. * - * Since: 3.0 + * Returns: An ID for this subscription **/ guint tracker_notifier_signal_subscribe (TrackerNotifier *notifier, @@ -874,13 +883,12 @@ tracker_notifier_signal_subscribe (TrackerNotifier *notifier, /** * tracker_notifier_signal_unsubscribe: - * @notifier: a #TrackerNotifier - * @handler_id: a handler ID obtained with tracker_notifier_signal_subscribe() + * @notifier: A `TrackerNotifier` + * @handler_id: A signal subscription handler ID * - * Undoes a DBus signal subscription, the @handler_id argument was previously - * obtained with a tracker_notifier_signal_subscribe() call. + * Undoes a signal subscription done through [method@Tracker.Notifier.signal_subscribe]. * - * Since: 3.0 + * The @handler_id argument was previously obtained during signal subscription creation. **/ void tracker_notifier_signal_unsubscribe (TrackerNotifier *notifier, @@ -908,7 +916,7 @@ _tracker_notifier_get_connection (TrackerNotifier *notifier) /** * tracker_notifier_event_get_event_type: - * @event: A #TrackerNotifierEvent + * @event: A `TrackerNotifierEvent` * * Returns the event type. * @@ -923,7 +931,7 @@ tracker_notifier_event_get_event_type (TrackerNotifierEvent *event) /** * tracker_notifier_event_get_id: - * @event: A #TrackerNotifierEvent + * @event: A `TrackerNotifierEvent` * * Returns the tracker:id of the element being notified upon. This is a #gint64 * which is used as efficient internal identifier for the resource. @@ -939,13 +947,13 @@ tracker_notifier_event_get_id (TrackerNotifierEvent *event) /** * tracker_notifier_event_get_urn: - * @event: A #TrackerNotifierEvent + * @event: A `TrackerNotifierEvent` * * Returns the Uniform Resource Name of the element. This is Tracker's * public identifier for the resource. * * This URN is an unique string identifier for the resource being - * notified upon, typically of the form "urn:uuid:...". + * notified upon, typically of the form `urn:uuid:...`. * * Returns: The element URN **/ diff --git a/src/libtracker-sparql/tracker-notifier.h b/src/libtracker-sparql/tracker-notifier.h index 962d03198..aff34e3c4 100644 --- a/src/libtracker-sparql/tracker-notifier.h +++ b/src/libtracker-sparql/tracker-notifier.h @@ -32,12 +32,6 @@ G_BEGIN_DECLS #define TRACKER_TYPE_NOTIFIER (tracker_notifier_get_type ()) #define TRACKER_TYPE_NOTIFIER_EVENT (tracker_notifier_event_get_type ()) -/** - * TrackerNotifier: - * - * The TrackerNotifier object allows subscribing - * to changes in the stored data. - */ TRACKER_AVAILABLE_IN_ALL G_DECLARE_DERIVABLE_TYPE (TrackerNotifier, tracker_notifier, TRACKER, NOTIFIER, GObject) diff --git a/src/libtracker-sparql/tracker-ontologies.h b/src/libtracker-sparql/tracker-ontologies.h index 8713b4fb6..bb678b67f 100644 --- a/src/libtracker-sparql/tracker-ontologies.h +++ b/src/libtracker-sparql/tracker-ontologies.h @@ -18,17 +18,6 @@ * Boston, MA 02110-1301, USA. */ -/** - * SECTION: tracker-ontologies - * @short_description: Utility prefix definitions for common ontologies - * @title: Utility Ontology Defines - * @stability: Stable - * @include: libtracker-sparql/tracker-sparql.h - * - * Utility defines for the common namespace prefixes. - */ - - #ifndef __LIBTRACKER_SPARQL_ONTOLOGIES_H__ #define __LIBTRACKER_SPARQL_ONTOLOGIES_H__ diff --git a/src/libtracker-sparql/tracker-resource.c b/src/libtracker-sparql/tracker-resource.c index ab579135b..1d06d0841 100644 --- a/src/libtracker-sparql/tracker-resource.c +++ b/src/libtracker-sparql/tracker-resource.c @@ -47,14 +47,37 @@ G_DEFINE_TYPE_WITH_PRIVATE (TrackerResource, tracker_resource, G_TYPE_OBJECT) #define GET_PRIVATE(object) (tracker_resource_get_instance_private (object)) /** - * SECTION: tracker-resource - * @short_description: Represents a single Tracker resource - * @title: TrackerResource - * @stability: Stable - * @include: tracker-resource.h - * - * #TrackerResource keeps track of a set of properties for a given resource. - * The resulting data can be serialized in several ways. + * TrackerResource: + * + * `TrackerResource` is an in-memory representation of RDF data about a given resource. + * + * This object keeps track of a set of properties for a given resource, and can + * also link to other `TrackerResource` objects to form trees or graphs of RDF + * data. See [method@Tracker.Resource.set_relation] and [method@Tracker.Resource.set_uri] + * on how to link a `TrackerResource` to other RDF data. + * + * `TrackerResource` may also hold data about literal values, added through + * the specialized [method@Tracker.Resource.set_int64], [method@Tracker.Resource.set_string], + * etc family of functions, or the generic [method@Tracker.Resource.set_gvalue] method. + * + * Since RDF properties may be multi-valued, for every `set` call there exists + * another `add` call (e.g. [method@Tracker.Resource.add_int64], [method@Tracker.Resource.add_string] + * and so on). The `set` methods do also reset any previously value the + * property might hold for the given resource. + * + * Resources may have an IRI set at creation through [ctor@Tracker.Resource.new], + * or set afterwards through [method@Tracker.Resource.set_identifier]. Resources + * without a name will represent a blank node, and will be dealt with as such + * during database insertions. + * + * `TrackerResource` performs no validation on the data being coherent as per + * any ontology. Errors will be found out at the time of using the TrackerResource + * for e.g. database updates. + * + * Once the RDF data is built in memory, the (tree of) `TrackerResource` may be + * converted to a RDF format through [method@Tracker.Resource.print_rdf], or + * directly inserted into a database through [method@Tracker.Batch.add_resource] + * or [method@Tracker.SparqlConnection.update_resource]. */ static char * @@ -65,13 +88,6 @@ generate_blank_node_identifier (void) return g_strdup_printf("_:%" G_GINT64_FORMAT, counter++); } -/** - * TrackerResource: - * - * The TrackerResource object represents information - * about a given resource. - */ - enum { PROP_0, @@ -247,7 +263,7 @@ set_property (GObject *object, * * Creates a TrackerResource instance. * - * Returns: a newly created #TrackerResource. Free with g_object_unref() when done + * Returns: a newly created `TrackerResource`. */ TrackerResource * tracker_resource_new (const char *identifier) @@ -269,18 +285,17 @@ tracker_resource_new (const char *identifier) /** * tracker_resource_set_gvalue: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to set - * @value: an initialised #GValue + * @value: an initialised [struct@GObject.Value] * - * State that the only value for the given property is 'value'. Any existing - * values for 'property' will be removed. + * Replace any previously existing value for @property_uri with @value. * * When serialising to SPARQL, any properties that were set with this function * will get a corresponding DELETE statement to remove any existing values in * the database. * - * You can pass any kind of GValue for @value, but serialization functions will + * You can pass any kind of [struct@GObject.Value] for @value, but serialization functions will * normally only be able to serialize URIs/relationships and fundamental value * types (string, int, etc.). */ @@ -382,52 +397,65 @@ value_set_uri (GValue *value, /** * tracker_resource_set_boolean: - * @self: the #TrackerResource - * @property_uri: a string identifying the property to modify - * @value: the property object + * @self: The `TrackerResource` + * @property_uri: A string identifying the property to modify + * @value: The property boolean value * - * Sets a single-valued boolean object. + * Sets a boolean property. Replaces any previous value. + * + * This method corresponds to [xsd:boolean](xsd-ontology.html#xsd:boolean). */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_boolean, gboolean, G_TYPE_BOOLEAN, g_value_set_boolean, validate_boolean) /** * tracker_resource_set_double: - * @self: the #TrackerResource - * @property_uri: a string identifying the property to modify - * @value: the property object + * @self: The `TrackerResource` + * @property_uri: A string identifying the property to modify + * @value: The property object + * + * Sets a numeric property with double precision. Replaces any previous value. * - * Sets a single-valued double object. + * This method corresponds to [xsd:double](xsd-ontology.html#xsd:double). */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_double, double, G_TYPE_DOUBLE, g_value_set_double, validate_double) /** * tracker_resource_set_int: - * @self: the #TrackerResource - * @property_uri: a string identifying the property to modify - * @value: the property object + * @self: The `TrackerResource` + * @property_uri: A string identifying the property to modify + * @value: The property object * - * Sets a single-valued integer object. + * Sets a numeric property with integer precision. Replaces any previous value. + * + * This method corresponds to [xsd:integer](xsd-ontology.html#xsd:integer). */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_int, int, G_TYPE_INT, g_value_set_int, validate_int) /** * tracker_resource_set_int64: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Sets a single-valued integer object. + * Sets a numeric property with 64-bit integer precision. Replaces any previous value. + * + * This method corresponds to [xsd:integer](xsd-ontology.html#xsd:integer). */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_int64, gint64, G_TYPE_INT64, g_value_set_int64, validate_int64) /** * tracker_resource_set_relation: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @resource: the property object * - * Sets a single-valued resource object as a #TrackerResource. This - * function produces similar RDF to tracker_resource_set_uri(), + * Sets a resource property as a `TrackerResource`. Replaces any previous value. + * + * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range) + * that points to a non-literal class (i.e. a subclass of + * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)). + * + * This function produces similar RDF to [method@Tracker.Resource.set_uri], * although in this function the URI will depend on the identifier * set on @resource. */ @@ -435,59 +463,76 @@ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_relation, TrackerResource *, TRACKE /** * tracker_resource_set_take_relation: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @resource: (transfer full): the property object * - * Sets a single-valued resource object as a #TrackerResource. This - * function produces similar RDF to tracker_resource_set_uri(), + * Sets a resource property as a `TrackerResource`. Replaces any previous value. + * Takes ownership on the given @resource. + * + * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range) + * that points to a non-literal class (i.e. a subclass of + * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)). + * + * This function produces similar RDF to [method@Tracker.Resource.set_uri], * although in this function the URI will depend on the identifier - * set on @resource. This function takes ownership of @resource. + * set on @resource. */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_take_relation, TrackerResource *, TRACKER_TYPE_RESOURCE, g_value_take_object, validate_pointer) /** * tracker_resource_set_string: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Sets a single-valued string object. + * Sets a string property. Replaces any previous value. + * + * This method corresponds to [xsd:string](xsd-ontology.html#xsd:string). */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_string, const char *, G_TYPE_STRING, g_value_set_string, validate_pointer) /** * tracker_resource_set_uri: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Sets a single-valued resource object as a string URI. This function - * produces similar RDF to tracker_resource_set_relation(), although + * Sets a resource property as an URI string. Replaces any previous value. + * + * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range) + * that points to a non-literal class (i.e. a subclass of + * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)). + * + * This function produces similar RDF to [method@Tracker.Resource.set_relation], although * it requires that the URI is previously known. */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_uri, const char *, TRACKER_TYPE_URI, value_set_uri, validate_pointer) /** * tracker_resource_set_datetime: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Sets a single-valued GDateTime as a #TrackerResource + * Sets a date property as a [type@GLib.DateTime]. Replaces any previous value. + * + * This method corresponds to [xsd:date](xsd-ontology.html#xsd:date) and + * [xsd:dateTime](xsd-ontology.html#xsd:dateTime). + * * Since: 3.2 */ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_datetime, GDateTime *, G_TYPE_DATE_TIME, g_value_set_boxed, validate_pointer) /** * tracker_resource_add_gvalue: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to set - * @value: an initialised #GValue + * @value: an initialised [struct@GObject.Value] * - * Add 'value' to the list of values for given property. + * Add @value to the list of values for given property. * - * You can pass any kind of GValue for @value, but serialization functions will + * You can pass any kind of [struct@GObject.Value] for @value, but serialization functions will * normally only be able to serialize URIs/relationships and fundamental value * types (string, int, etc.). */ @@ -595,52 +640,80 @@ tracker_resource_add_gvalue (TrackerResource *self, /** * tracker_resource_add_boolean: - * @self: the #TrackerResource - * @property_uri: a string identifying the property to modify - * @value: the property object + * @self: The `TrackerResource` + * @property_uri: A string identifying the property to modify + * @value: The property boolean value + * + * Adds a boolean property. Previous values for the same property are kept. + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). * - * Adds a boolean object to a multi-valued property. + * This method corresponds to [xsd:boolean](xsd-ontology.html#xsd:boolean). */ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_boolean, gboolean, G_TYPE_BOOLEAN, g_value_set_boolean, validate_boolean) /** * tracker_resource_add_double: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Adds a double object to a multi-valued property. + * Adds a numeric property with double precision. Previous values for the same property are kept. + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This method corresponds to [xsd:double](xsd-ontology.html#xsd:double). */ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_double, double, G_TYPE_DOUBLE, g_value_set_double, validate_double) /** * tracker_resource_add_int: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Adds an integer object to a multi-valued property. + * Adds a numeric property with integer precision. Previous values for the same property are kept. + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This method corresponds to [xsd:integer](xsd-ontology.html#xsd:integer). */ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_int, int, G_TYPE_INT, g_value_set_int, validate_int) /** * tracker_resource_add_int64: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Adds an integer object to a multi-valued property. + * Adds a numeric property with 64-bit integer precision. Previous values for the same property are kept. + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This method corresponds to [xsd:integer](xsd-ontology.html#xsd:integer). */ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_int64, gint64, G_TYPE_INT64, g_value_set_int64, validate_int64) /** * tracker_resource_add_relation: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @resource: the property object * - * Adds a resource object to a multi-valued property. This - * function produces similar RDF to tracker_resource_add_uri(), + * Adds a resource property as a `TrackerResource`. Previous values for the same property are kept. + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range) + * that points to a non-literal class (i.e. a subclass of + * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)). + * + * This method produces similar RDF to [method@Tracker.Resource.add_uri], * although in this function the URI will depend on the identifier * set on @resource. */ @@ -648,12 +721,21 @@ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_relation, TrackerResource *, TRACKE /** * tracker_resource_add_take_relation: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @resource: (transfer full): the property object * - * Adds a resource object to a multi-valued property. This - * function produces similar RDF to tracker_resource_add_uri(), + * Adds a resource property as a `TrackerResource`. Previous values for the same property are kept. + * Takes ownership on the given @resource. + * + * This method is meant to RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range) + * that points to a non-literal class (i.e. a subclass of + * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)). + * + * This function produces similar RDF to [method@Tracker.Resource.add_uri], * although in this function the URI will depend on the identifier * set on @resource. This function takes ownership of @resource. */ @@ -662,46 +744,67 @@ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_take_relation, TrackerResource *, T /** * tracker_resource_add_string: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Adds a string object to a multi-valued property. + * Adds a string property. Previous values for the same property are kept. + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This method corresponds to [xsd:string](xsd-ontology.html#xsd:string). */ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_string, const char *, G_TYPE_STRING, g_value_set_string, validate_pointer) /** * tracker_resource_add_uri: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Adds a resource object to a multi-valued property. This function - * produces similar RDF to tracker_resource_add_relation(), although + * Adds a resource property as an URI string. Previous values for the same property are kept. + * + * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range) + * that points to a non-literal class (i.e. a subclass of + * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)). + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This function produces similar RDF to [method@Tracker.Resource.add_relation], although * it requires that the URI is previously known. */ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_uri, const char *, TRACKER_TYPE_URI, value_set_uri, validate_pointer) /** * tracker_resource_add_datetime: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to modify * @value: the property object * - * Adds GDateTime object to the multi-valued property. + * Adds a date property as a [type@GLib.DateTime]. Previous values for the + * same property are kept. + * + * This method is meant for RDF properties allowing multiple values, see + * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality). + * + * This method corresponds to [xsd:date](xsd-ontology.html#xsd:date) and + * [xsd:dateTime](xsd-ontology.html#xsd:dateTime). + * * Since: 3.2 */ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_datetime, GDateTime *, G_TYPE_DATE_TIME, g_value_set_boxed, validate_pointer) /** * tracker_resource_get_values: - * @self: the #TrackerResource + * @self: the `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the list of all known values of the given property. * - * Returns: (transfer container) (element-type GValue) (nullable): a #GList of - * #GValue instances. The list should be freed with g_list_free() + * Returns: (transfer container) (element-type GValue) (nullable): a [struct@GLib.List] of + * [struct@GObject.Value] instances. The list should be freed with [func@GLib.List.free] */ GList *tracker_resource_get_values (TrackerResource *self, const char *property_uri) @@ -771,7 +874,7 @@ GList *tracker_resource_get_values (TrackerResource *self, /** * tracker_resource_get_first_boolean: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the first boolean object previously assigned to a property. @@ -782,7 +885,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_boolean, gboolean, G_TYPE_BOO /** * tracker_resource_get_first_double: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the first double object previously assigned to a property. @@ -793,7 +896,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_double, double, G_TYPE_DOUBLE /** * tracker_resource_get_first_int: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the first integer object previously assigned to a property. @@ -804,7 +907,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_int, int, G_TYPE_INT, g_value /** * tracker_resource_get_first_int64: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the first integer object previously assigned to a property. @@ -815,7 +918,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_int64, gint64, G_TYPE_INT64, /** * tracker_resource_get_first_relation: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the first resource object previously assigned to a property. @@ -826,7 +929,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_relation, TrackerResource *, /** * tracker_resource_get_first_string: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the first string object previously assigned to a property. @@ -837,7 +940,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_string, const char *, G_TYPE_ /** * tracker_resource_get_first_uri: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * * Returns the first resource object previously assigned to a property. @@ -848,10 +951,10 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_uri, const char *, TRACKER_TY /** * tracker_resource_get_first_datetime: - * @self: A #TrackerResource + * @self: A `TrackerResource` * @property_uri: a string identifying the property to look up * - * Returns the first resource object previously assigned to a property. + * Returns the first [type@GLib.DateTime] previously assigned to a property. * * Returns: (transfer none) (nullable): the first GDateTime object * Since: 3.2 @@ -860,12 +963,12 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_datetime, GDateTime *, G_TYPE /** * tracker_resource_get_identifier: - * @self: A #TrackerResource + * @self: A `TrackerResource` * * Returns the identifier of a resource. * - * If the identifier was set to NULL, the identifier returned will be a unique - * SPARQL blank node identifier, such as "_:123". + * If the identifier was set to NULL, the identifier returned will be a locally + * unique SPARQL blank node identifier, such as `_:123`. * * Returns: (nullable): a string owned by the resource */ @@ -886,16 +989,16 @@ tracker_resource_get_identifier (TrackerResource *self) /** * tracker_resource_set_identifier: - * @self: a #TrackerResource + * @self: A `TrackerResource` * @identifier: (nullable): a string identifying the resource * - * Changes the identifier of a #TrackerResource. The identifier should be a + * Changes the identifier of a `TrackerResource`. The identifier should be a * URI or compact URI, but this is not necessarily enforced. Invalid * identifiers may cause errors when serializing the resource or trying to * insert the results in a database. * * If the identifier is set to %NULL, a SPARQL blank node identifier such as - * "_:123" is assigned to the resource. + * `_:123` is assigned to the resource. */ void tracker_resource_set_identifier (TrackerResource *self, @@ -913,10 +1016,10 @@ tracker_resource_set_identifier (TrackerResource *self, /** * tracker_resource_identifier_compare_func: - * @resource: a #TrackerResource + * @resource: a `TrackerResource` * @identifier: a string identifying the resource * - * A helper function that compares a #TrackerResource by its identifier + * A helper function that compares a `TrackerResource` by its identifier * string. * * Returns: an integer less than, equal to, or greater than zero, if the @@ -934,8 +1037,8 @@ tracker_resource_identifier_compare_func (TrackerResource *resource, /** * tracker_resource_compare: - * @a: A #TrackerResource - * @b: A second #TrackerResource to compare + * @a: A `TrackerResource` + * @b: A second `TrackerResource` to compare * * Compare the identifiers of two TrackerResource instances. The resources * are considered identical if they have the same identifier. @@ -959,14 +1062,11 @@ tracker_resource_compare (TrackerResource *a, /** * tracker_resource_get_properties: - * @resource: a #TrackerResource + * @resource: a `TrackerResource` * * Gets the list of properties defined in @resource * * Returns: (transfer container) (element-type utf8): The list of properties. - * The list should be freed with g_list_free(). - * - * Since: 3.0 **/ GList * tracker_resource_get_properties (TrackerResource *resource) @@ -1191,7 +1291,7 @@ generate_turtle_property (const char *property, /** * tracker_resource_print_turtle: - * @self: a #TrackerResource + * @self: a `TrackerResource` * @namespaces: (allow-none): a set of prefixed URLs, or %NULL to use the * Nepomuk set * @@ -1201,12 +1301,12 @@ generate_turtle_property (const char *property, * * * The @namespaces object is used to expand any compact URI values. In most - * cases you should pass the one returned by tracker_sparql_connection_get_namespace_manager() + * cases you should pass the one returned by [method@Tracker.SparqlConnection.get_namespace_manager] * from the connection that is the intended recipient of this data. * * Returns: a newly-allocated string * - * Deprecated: 3.4: Use tracker_resource_print_rdf() instead. + * Deprecated: 3.4: Use [method@Tracker.Resource.print_rdf] instead. */ char * tracker_resource_print_turtle (TrackerResource *self, @@ -1423,7 +1523,7 @@ generate_sparql_insert_pattern (TrackerResource *resource, /** * tracker_resource_print_sparql_update: - * @self: a #TrackerResource + * @self: a `TrackerResource` * @namespaces: (allow-none): a set of prefixed URLs, or %NULL to use the * Nepomuk set * @graph_id: (allow-none): the URN of the graph the data should be added to, @@ -1433,7 +1533,7 @@ generate_sparql_insert_pattern (TrackerResource *resource, * stored in @resource. * * The @namespaces object is used to expand any compact URI values. In most - * cases you should pass the one returned by tracker_sparql_connection_get_namespace_manager() + * cases you should pass the one returned by [method@Tracker.SparqlConnection.get_namespace_manager] * from the connection that is the intended recipient of this data. * * Returns: a newly-allocated string containing a SPARQL update command. @@ -1502,7 +1602,7 @@ tracker_resource_print_sparql_update (TrackerResource *resource, /** * tracker_resource_print_jsonld: - * @self: a #TrackerResource + * @self: a `TrackerResource` * @namespaces: (nullable): a set of prefixed URLs, or %NULL to use the * Nepomuk set * @@ -1512,12 +1612,12 @@ tracker_resource_print_sparql_update (TrackerResource *resource, * serialization format. * * The @namespaces object is used to expand any compact URI values. In most - * cases you should pass the one returned by tracker_sparql_connection_get_namespace_manager() + * cases you should pass the one returned by [method@Tracker.SparqlConnection.get_namespace_manager] * from the connection that is the intended recipient of this data. * * Returns: a newly-allocated string containing JSON-LD data. * - * Deprecated: 3.5: Use tracker_resource_print_rdf() + * Deprecated: 3.5: Use [method@Tracker.Resource.print_rdf] instead. */ char * tracker_resource_print_jsonld (TrackerResource *self, @@ -1553,7 +1653,7 @@ convert_format (TrackerRdfFormat format) /** * tracker_resource_print_rdf: - * @self: a #TrackerResource + * @self: a `TrackerResource` * @namespaces: a set of prefixed URLs * @format: RDF format of the printed string * @graph: (nullable): target graph of the resource RDF, or %NULL for the @@ -1562,7 +1662,7 @@ convert_format (TrackerRdfFormat format) * Serialize all the information in @resource into the selected RDF format. * * The @namespaces object is used to expand any compact URI values. In most - * cases you should pass the one returned by tracker_sparql_connection_get_namespace_manager() + * cases you should pass the one returned by [method@Tracker.SparqlConnection.get_namespace_manager] * from the connection that is the intended recipient of this data. * * Returns: a newly-allocated string containing RDF data in the requested format. @@ -1675,11 +1775,11 @@ tracker_serialize_single_value (TrackerResource *resource, /** * tracker_resource_serialize: - * @resource: A #TrackerResource + * @resource: A `TrackerResource` * - * Serializes a #TrackerResource to a #GVariant in a lossless way. + * Serializes a `TrackerResource` to a [type@GLib.Variant] in a lossless way. * All child resources are subsequently serialized. It is implied - * that both ends use a common #TrackerNamespaceManager. + * that both ends use a common [class@Tracker.NamespaceManager]. * * Returns: (transfer floating) (nullable): A variant describing the resource, * the reference is floating. @@ -1751,11 +1851,11 @@ tracker_resource_serialize (TrackerResource *resource) /** * tracker_resource_deserialize: - * @variant: a #GVariant + * @variant: a [type@GLib.Variant] * - * Deserializes a #TrackerResource previously serialized with - * tracker_resource_serialize(). It is implied that both ends - * use a common #TrackerNamespaceManager. + * Deserializes a `TrackerResource` previously serialized with + * [method@Tracker.Resource.serialize]. It is implied that both ends + * use a common [class@Tracker.NamespaceManager]. * * Returns: (transfer full) (nullable): A TrackerResource, or %NULL if * deserialization fails. @@ -1872,7 +1972,7 @@ tracker_resource_deserialize (GVariant *variant) /** * tracker_resource_get_property_overwrite: - * @resource: a #TrackerResource + * @resource: a `TrackerResource` * @property_uri: a string identifying the property to query * * Returns whether the prior values for this property would be deleted diff --git a/src/libtracker-sparql/tracker-sparql-enum-types.h.template b/src/libtracker-sparql/tracker-sparql-enum-types.h.template index c0afe7b37..a7aced5a8 100644 --- a/src/libtracker-sparql/tracker-sparql-enum-types.h.template +++ b/src/libtracker-sparql/tracker-sparql-enum-types.h.template @@ -1,10 +1,11 @@ /*** BEGIN file-header ***/ -#ifndef __TRACKER_NOTIFY_ENUM_TYPES_H__ -#define __TRACKER_NOTIFY_ENUM_TYPES_H__ +#ifndef __TRACKER_SPARQL_ENUM_TYPES_H__ +#define __TRACKER_SPARQL_ENUM_TYPES_H__ #include #include +#include G_BEGIN_DECLS /*** END file-header ***/ @@ -16,12 +17,12 @@ G_BEGIN_DECLS /*** BEGIN value-header ***/ TRACKER_AVAILABLE_IN_ALL -GType @enum_name@_get_type (void) G_GNUC_CONST; +GType @enum_name@_get_type (void); #define TRACKER_TYPE_@ENUMSHORT@ (@enum_name@_get_type ()) /*** END value-header ***/ /*** BEGIN file-tail ***/ G_END_DECLS -#endif /* __TRACKER_ENUMS_TYPES_H__ */ +#endif /* __TRACKER_SPARQL_ENUMS_TYPES_H__ */ /*** END file-tail ***/ diff --git a/src/libtracker-sparql/tracker-statement.c b/src/libtracker-sparql/tracker-statement.c index 7a6c26aaf..8497af779 100644 --- a/src/libtracker-sparql/tracker-statement.c +++ b/src/libtracker-sparql/tracker-statement.c @@ -17,30 +17,38 @@ * Boston, MA 02110-1301, USA. */ /** - * SECTION: tracker-sparql-statement - * @short_description: Prepared statements - * @title: TrackerSparqlStatement - * @stability: Stable - * @include: tracker-sparql.h - * - * The TrackerSparqlStatement object represents - * a SPARQL query. This query may contain parameterized variables - * (expressed as ~var in the syntax), which may be mapped to arbitrary - * values prior to execution. This statement may be reused for future + * TrackerSparqlStatement: + * + * `TrackerSparqlStatement` represents a prepared statement for a SPARQL query. + * + * The SPARQL query will be internally compiled into the format that is most + * optimal to execute the query many times. For connections created + * through [ctor@Tracker.SparqlConnection.new] that will be a + * SQLite compiled statement. + * + * The SPARQL query may contain parameterized variables expressed via the + * `~` prefix in the SPARQL syntax (e.g. `~var`), these may happen anywhere + * in the SPARQL where a literal or variable would typically happen. These + * parameterized variables may be mapped to arbitrary values prior to + * execution. The `TrackerSparqlStatement` may be reused for future * queries with different values. * - * The argument bindings may be changed through tracker_sparql_statement_bind_int(), - * tracker_sparql_statement_bind_boolean(), tracker_sparql_statement_bind_double() - * and tracker_sparql_statement_bind_string(). Those functions receive - * a @name argument corresponding for the variable name in the SPARQL query - * (eg. "var" for ~var) and a @value to map the variable to. + * The argument bindings may be changed through the [method@Tracker.SparqlStatement.bind_int], + * [method@Tracker.SparqlStatement.bind_int], etc... family of functions. Those functions + * receive a @name argument corresponding for the variable name in the SPARQL query + * (eg. `"var"` for `~var`) and a value to map the variable to. * * Once all arguments have a value, the query may be executed through - * tracker_sparql_statement_execute() or tracker_sparql_statement_execute_async(). + * [method@Tracker.SparqlStatement.execute_async] or [method@Tracker.SparqlStatement.execute]. * - * It is possible to use a given #TrackerSparqlStatement in other threads than - * the one it was created from. It must be however used from just one thread - * at any given time. + * It is possible to use any `TrackerSparqlStatement` from other threads than + * the one it was created from. However, binding values and executing the + * statement must only happen from one thread at a time. It is possible to reuse + * the `TrackerSparqlStatement` right after [method@Tracker.SparqlStatement.execute_async] + * was called, there is no need to wait for [method@Tracker.SparqlStatement.execute_finish]. + * + * In some circumstances, it is possible that the query needs to be recompiled + * from the SPARQL source. This will happen transparently. */ #include "config.h" @@ -135,7 +143,7 @@ tracker_sparql_statement_class_init (TrackerSparqlStatementClass *klass) /** * TrackerSparqlStatement:connection: * - * The #TrackerSparqlConnection used to perform the query. + * The [class@Tracker.SparqlConnection] the statement was created for. */ props[PROP_CONNECTION] = g_param_spec_object ("connection", @@ -166,9 +174,9 @@ tracker_sparql_statement_class_init (TrackerSparqlStatementClass *klass) /** * tracker_sparql_statement_get_connection: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * - * Returns the #TrackerSparqlConnection that this statement was created from. + * Returns the [class@Tracker.SparqlConnection] that this statement was created for. * * Returns: (transfer none): The SPARQL connection of this statement. **/ @@ -184,7 +192,7 @@ tracker_sparql_statement_get_connection (TrackerSparqlStatement *stmt) /** * tracker_sparql_statement_get_sparql: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * * Returns the SPARQL string that this prepared statement holds. * @@ -202,11 +210,11 @@ tracker_sparql_statement_get_sparql (TrackerSparqlStatement *stmt) /** * tracker_sparql_statement_bind_boolean: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * @name: variable name * @value: value * - * Binds the boolean @value to variable @name. + * Binds the boolean @value to the parameterized variable given by @name. */ void tracker_sparql_statement_bind_boolean (TrackerSparqlStatement *stmt, @@ -223,11 +231,11 @@ tracker_sparql_statement_bind_boolean (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_bind_int: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * @name: variable name * @value: value * - * Binds the integer @value to variable @name. + * Binds the integer @value to the parameterized variable given by @name. */ void tracker_sparql_statement_bind_int (TrackerSparqlStatement *stmt, @@ -244,11 +252,11 @@ tracker_sparql_statement_bind_int (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_bind_double: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * @name: variable name * @value: value * - * Binds the double @value to variable @name. + * Binds the double @value to the parameterized variable given by @name. */ void tracker_sparql_statement_bind_double (TrackerSparqlStatement *stmt, @@ -265,11 +273,11 @@ tracker_sparql_statement_bind_double (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_bind_string: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * @name: variable name * @value: value * - * Binds the string @value to variable @name. + * Binds the string @value to the parameterized variable given by @name. */ void tracker_sparql_statement_bind_string (TrackerSparqlStatement *stmt, @@ -287,11 +295,12 @@ tracker_sparql_statement_bind_string (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_bind_datetime: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * @name: variable name * @value: value * - * Binds the GDateTime @value to variable @name. + * Binds the [type@GLib.DateTime] @value to the parameterized variable given by @name. + * * Since: 3.2 */ @@ -311,18 +320,24 @@ tracker_sparql_statement_bind_datetime (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_execute: - * @stmt: a #TrackerSparqlStatement - * @cancellable: a #GCancellable used to cancel the operation - * @error: #GError for error reporting. + * @stmt: a `TrackerSparqlStatement` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * - * Executes the SPARQL query with the currently bound values. + * Executes the `SELECT` or `ASK` SPARQL query with the currently bound values. * - * This function should only be called on #TrackerSparqlStatement objects - * obtained through tracker_sparql_connection_query_statement() or + * This function also works for `DESCRIBE` and `CONSTRUCT` queries that + * retrieve data from the triple store. These query forms that return + * RDF data are however more useful together with [method@Tracker.SparqlStatement.serialize_async]. + * + * This function should only be called on `TrackerSparqlStatement` objects + * obtained through [method@Tracker.SparqlConnection.query_statement] or * SELECT/CONSTRUCT/DESCRIBE statements loaded through - * tracker_sparql_connection_load_statement_from_gresource(). + * [method@Tracker.SparqlConnection.load_statement_from_gresource]. + * An error will be raised if this method is called on a `INSERT` or `DELETE` + * SPARQL query. * - * Returns: (transfer full): A #TrackerSparqlCursor + * Returns: (transfer full): A `TrackerSparqlCursor` with the query results. */ TrackerSparqlCursor * tracker_sparql_statement_execute (TrackerSparqlStatement *stmt, @@ -348,18 +363,24 @@ tracker_sparql_statement_execute (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_execute_async: - * @stmt: a #TrackerSparqlStatement - * @cancellable: a #GCancellable used to cancel the operation - * @callback: user-defined #GAsyncReadyCallback to be called when - * asynchronous operation is finished. + * @stmt: a `TrackerSparqlStatement` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: user-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. * @user_data: user-defined data to be passed to @callback * - * Asynchronously executes the SPARQL query with the currently bound values. + * Executes asynchronously the `SELECT` or `ASK` SPARQL query with the currently bound values. + * + * This function also works for `DESCRIBE` and `CONSTRUCT` queries that + * retrieve data from the triple store. These query forms that return + * RDF data are however more useful together with [method@Tracker.SparqlStatement.serialize_async]. * - * This function should only be called on #TrackerSparqlStatement objects - * obtained through tracker_sparql_connection_query_statement() or + * This function should only be called on `TrackerSparqlStatement` objects + * obtained through [method@Tracker.SparqlConnection.query_statement] or * SELECT/CONSTRUCT/DESCRIBE statements loaded through - * tracker_sparql_connection_load_statement_from_gresource(). + * [method@Tracker.SparqlConnection.load_statement_from_gresource]. + * An error will be raised if this method is called on a `INSERT` or `DELETE` + * SPARQL query. */ void tracker_sparql_statement_execute_async (TrackerSparqlStatement *stmt, @@ -378,14 +399,14 @@ tracker_sparql_statement_execute_async (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_execute_finish: - * @stmt: a #TrackerSparqlStatement - * @res: The #GAsyncResult from the callback used to return the #TrackerSparqlCursor - * @error: The error which occurred or %NULL + * @stmt: a `TrackerSparqlStatement` + * @res: a [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * * Finishes the asynchronous operation started through - * tracker_sparql_statement_execute_async(). + * [method@Tracker.SparqlStatement.execute_async]. * - * Returns: (transfer full): A #TrackerSparqlCursor + * Returns: (transfer full): A `TrackerSparqlCursor` with the query results. */ TrackerSparqlCursor * tracker_sparql_statement_execute_finish (TrackerSparqlStatement *stmt, @@ -411,15 +432,18 @@ tracker_sparql_statement_execute_finish (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_update: - * @stmt: a #TrackerSparqlStatement - * @cancellable: a #GCancellable used to cancel the operation - * @error: #GError for error reporting. + * @stmt: a `TrackerSparqlStatement` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @error: Error location * - * Executes the SPARQL update with the currently bound values. + * Executes the `INSERT`/`DELETE` SPARQL query series with the currently bound values. * - * This function should only be called on #TrackerSparqlStatement objects - * obtained through tracker_sparql_connection_update_statement() or - * update statements loaded through tracker_sparql_connection_load_statement_from_gresource(). + * This function should only be called on `TrackerSparqlStatement` objects + * obtained through [method@Tracker.SparqlConnection.update_statement] or + * `INSERT`/`DELETE` statements loaded through + * [method@Tracker.SparqlConnection.load_statement_from_gresource]. + * An error will be raised if this method is called on + * `SELECT`/`ASK`/`DESCRIBE`/`CONSTRUCT` SPARQL queries. * * Returns: %TRUE if the update finished with no errors, %FALSE otherwise * @@ -441,17 +465,20 @@ tracker_sparql_statement_update (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_update_async: - * @stmt: a #TrackerSparqlStatement - * @cancellable: a #GCancellable used to cancel the operation - * @callback: user-defined #GAsyncReadyCallback to be called when - * asynchronous operation is finished. + * @stmt: a `TrackerSparqlStatement` + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: user-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. * @user_data: user-defined data to be passed to @callback * - * Asynchronously executes the SPARQL update query with the currently bound values. + * Executes asynchronously the `INSERT`/`DELETE` SPARQL query series with the currently bound values. * - * This function should only be called on #TrackerSparqlStatement objects - * obtained through tracker_sparql_connection_update_statement() or - * update statements loaded through tracker_sparql_connection_load_statement_from_gresource(). + * This function should only be called on `TrackerSparqlStatement` objects + * obtained through [method@Tracker.SparqlConnection.update_statement] or + * `INSERT`/`DELETE` statements loaded through + * [method@Tracker.SparqlConnection.load_statement_from_gresource]. + * An error will be raised if this method is called on + * `SELECT`/`ASK`/`DESCRIBE`/`CONSTRUCT` SPARQL queries. * * Since: 3.5 */ @@ -472,12 +499,12 @@ tracker_sparql_statement_update_async (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_update_finish: - * @stmt: a #TrackerSparqlStatement - * @result: The #GAsyncResult from the callback used to return the #TrackerSparqlCursor - * @error: The error which occurred or %NULL + * @stmt: a `TrackerSparqlStatement` + * @result: a [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * * Finishes the asynchronous update started through - * tracker_sparql_statement_update_async(). + * [method@Tracker.SparqlStatement.update_async]. * * Returns: %TRUE if the update finished with no errors, %FALSE otherwise * @@ -500,11 +527,9 @@ tracker_sparql_statement_update_finish (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_clear_bindings: - * @stmt: a #TrackerSparqlStatement - * - * Clears all boolean/string/integer/double bindings. + * @stmt: a `TrackerSparqlStatement` * - * Since: 3.0 + * Clears all bindings. */ void tracker_sparql_statement_clear_bindings (TrackerSparqlStatement *stmt) @@ -516,17 +541,18 @@ tracker_sparql_statement_clear_bindings (TrackerSparqlStatement *stmt) /** * tracker_sparql_statement_serialize_async: - * @stmt: a #TrackerSparqlStatement + * @stmt: a `TrackerSparqlStatement` * @flags: serialization flags * @format: RDF format of the serialized data - * @cancellable: (nullable): a #GCancellable used to cancel the operation - * @callback: user-defined #GAsyncReadyCallback to be called when - * asynchronous operation is finished. + * @cancellable: (nullable): Optional [type@Gio.Cancellable] + * @callback: user-defined [type@Gio.AsyncReadyCallback] to be called when + * the asynchronous operation is finished. * @user_data: user-defined data to be passed to @callback * - * Serializes data into the specified RDF format. The query @stmt was - * created from must be either a `DESCRIBE` or `CONSTRUCT` query, an - * error will be raised otherwise. + * Serializes a `DESCRIBE` or `CONSTRUCT` query into the given RDF @format. + * + * The query @stmt was created from must be either a `DESCRIBE` or `CONSTRUCT` + * query, an error will be raised otherwise. * * This is an asynchronous operation, @callback will be invoked when the * data is available for reading. @@ -535,7 +561,7 @@ tracker_sparql_statement_clear_bindings (TrackerSparqlStatement *stmt) * an error will be raised. * * The @flags argument is reserved for future expansions, currently - * %TRACKER_SERIALIZE_FLAGS_NONE must be passed. + * #TRACKER_SERIALIZE_FLAGS_NONE must be passed. * * Since: 3.3 **/ @@ -562,14 +588,14 @@ tracker_sparql_statement_serialize_async (TrackerSparqlStatement *stmt, /** * tracker_sparql_statement_serialize_finish: - * @stmt: a #TrackerSparqlStatement - * @result: the #GAsyncResult - * @error: location for returned errors, or %NULL + * @stmt: a `TrackerSparqlStatement` + * @result: a [type@Gio.AsyncResult] with the result of the operation + * @error: Error location * - * Finishes a tracker_sparql_statement_serialize_async() operation. - * In case of error, %NULL will be returned and @error will be set. + * Finishes the asynchronous operation started through + * [method@Tracker.SparqlStatement.serialize_async]. * - * Returns: (transfer full): a #GInputStream to read RDF content. + * Returns: (transfer full): a [class@Gio.InputStream] to read RDF content. * * Since: 3.3 **/ diff --git a/src/libtracker-sparql/tracker-statement.h b/src/libtracker-sparql/tracker-statement.h index fc551e89a..3de04f797 100644 --- a/src/libtracker-sparql/tracker-statement.h +++ b/src/libtracker-sparql/tracker-statement.h @@ -28,12 +28,6 @@ G_BEGIN_DECLS -/** - * TrackerSparqlStatement: - * - * The TrackerSparqlStatement object represents - * a prepared query statement. - */ #define TRACKER_TYPE_SPARQL_STATEMENT tracker_sparql_statement_get_type () #define TRACKER_SPARQL_TYPE_STATEMENT TRACKER_TYPE_SPARQL_STATEMENT TRACKER_AVAILABLE_IN_ALL diff --git a/src/libtracker-sparql/tracker-uri.c b/src/libtracker-sparql/tracker-uri.c index 9238c50cb..135f5ddf7 100644 --- a/src/libtracker-sparql/tracker-uri.c +++ b/src/libtracker-sparql/tracker-uri.c @@ -19,16 +19,6 @@ * Boston, MA 02110-1301, USA. */ -/** - * SECTION: tracker-uri - * @short_description: URI utility functions - * @title: URI Utilities - * @stability: Stable - * @include: libtracker-sparql/tracker-sparql.h - * - * Tracker defines some utility functions to deal with URI strings. - */ - #include "config.h" #include @@ -163,14 +153,13 @@ find_conversion (const char *format, * string precision pitfalls documented in g_strdup_printf() * @args: the list of parameters to insert into the format string * + * Formats and escapes a string for use as a URI. This function takes a `va_list`. + * * Similar to the standard C vsprintf() function but safer, since it * calculates the maximum space required and allocates memory to hold * the result. * - * The result is escaped using g_uri_escape_string(). - * - * Returns: (transfer full): a newly-allocated string holding the result. The returned string - * should be freed with g_free() when no longer needed. + * Returns: (transfer full): a newly-allocated string holding the result. */ gchar * tracker_sparql_escape_uri_vprintf (const gchar *format, @@ -269,7 +258,7 @@ cleanup: * string precision pitfalls documented in g_strdup_printf() * @...: the parameters to insert into the format string * - * Calls tracker_sparql_escape_uri_vprintf() with the @... supplied. + * Formats and escapes a string for use as a URI. This function takes variadic arguments. * * Returns: (transfer full): a newly-allocated string holding the result.The returned string * should be freed with g_free() when no longer needed. @@ -291,10 +280,9 @@ tracker_sparql_escape_uri_printf (const gchar *format, ...) * tracker_sparql_escape_uri: * @uri: a string to be escaped, following the tracker sparql rules * - * Calls tracker_sparql_escape_uri_printf(). + * Escapes a string for use as a URI. * - * Returns: (transfer full): a newly-allocated string holding the result. The returned string - * should be freed with g_free() when no longer needed. + * Returns: (transfer full): a newly-allocated string holding the result. */ gchar * tracker_sparql_escape_uri (const gchar *uri) diff --git a/src/libtracker-sparql/tracker-utils.c b/src/libtracker-sparql/tracker-utils.c index 063559793..1f4639a23 100644 --- a/src/libtracker-sparql/tracker-utils.c +++ b/src/libtracker-sparql/tracker-utils.c @@ -16,15 +16,6 @@ * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, * Boston, MA 02110-1301, USA. */ -/** - * SECTION: tracker-misc - * @short_description: miscellaneous functionality - * @title: Utility Functions - * @stability: Stable - * @include: tracker-sparql.h - * - * Collection of Tracker utility functions. - */ #include "config.h" @@ -37,9 +28,10 @@ * @literal: a string to escape * * Escapes @literal so it is suitable for insertion in - * SPARQL queries as string literals. Manual construction - * of query strings based user input is best avoided at - * all cost, use of #TrackerSparqlStatement is recommended + * SPARQL queries as string literals. + * + * Manual construction of query strings based user input is best + * avoided at all cost, use of #TrackerSparqlStatement is recommended * instead. * * Returns: (transfer full): the escaped string diff --git a/src/libtracker-sparql/tracker-version.c b/src/libtracker-sparql/tracker-version.c index 7fd829482..ce5f9bb0d 100644 --- a/src/libtracker-sparql/tracker-version.c +++ b/src/libtracker-sparql/tracker-version.c @@ -16,17 +16,6 @@ * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, * Boston, MA 02110-1301, USA. */ -/** - * SECTION: tracker-version - * @short_description: variables and functions to check Tracker version - * @title: Version Information - * @stability: Stable - * @include: tracker-sparql.h - * - * Tracker provides version information, primarily useful in configure checks - * for builds that have a configure script. Applications will not typically use - * the features described here. - */ #include "config.h" @@ -47,9 +36,10 @@ const guint tracker_binary_age = TRACKER_BINARY_AGE; * @required_minor: the required minor version. * @required_micro: the required micro version. * - * Checks that the Tracker library in use is compatible with the - * given version. Generally you would pass in the constants - * #TRACKER_MAJOR_VERSION, #TRACKER_MINOR_VERSION, #TRACKER_MICRO_VERSION + * Checks that the Tracker library in use is compatible with the given version. + * + * Generally you would pass in the constants + * [const@Tracker.MAJOR_VERSION], [const@Tracker.MINOR_VERSION], [const@Tracker.MICRO_VERSION] * as the three arguments to this function; that produces * a check that the library in use is compatible with * the version of Tracker the application or module was compiled @@ -57,15 +47,13 @@ const guint tracker_binary_age = TRACKER_BINARY_AGE; * * Compatibility is defined by two things: first the version * of the running library is newer than the version - * @required_major.required_minor.@required_micro. Second + * @required_major.@required_minor.@required_micro. Second * the running library must be binary compatible with the - * version @required_major.required_minor.@required_micro + * version @required_major.@required_minor.@required_micro * (same major version.) * * Return value: %NULL if the Tracker library is compatible with the * given version, or a string describing the version mismatch. - * The returned string is owned by Tracker and must not be modified - * or freed. **/ const gchar * tracker_check_version (guint required_major, -- cgit v1.2.1