GNOME.org
 

[tracker/wip/carlosg/tracker-3.0-api-breaks: 61/63] docs: Some updates for Tracker 3.0

commit c45ab5d6f3dfc67de159e7cdacb159ef64e084bb
Author: Sam Thursfield <sam afuera me uk>
Date:   Fri Jan 17 01:18:53 2020 +0100

    docs: Some updates for Tracker 3.0
    
    This updates the overview, adds the tracker_endpoint API,
    documents the tracker_sparql_connection() constructors,
    and removes the 'compiling' section which was way out of date.

 .../libtracker-sparql/libtracker-sparql-docs.xml   |  1 +
 .../libtracker-sparql-sections.txt                 | 20 ++++++
 docs/reference/libtracker-sparql/overview.xml      | 72 +++++++--------------
 src/libtracker-sparql/tracker-connection.c         | 73 ++++++++++++++++++++++
 src/libtracker-sparql/tracker-endpoint.c           | 19 ++++++
 5 files changed, 135 insertions(+), 50 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml 
b/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml
index 78f6d3b8a..12a9c16ce 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml
@@ -35,6 +35,7 @@
     <xi:include href="xml/tracker-sparql-statement.xml"/>
     <xi:include href="xml/tracker-sparql-cursor.xml"/>
     <xi:include href="xml/tracker-notifier.xml"/>
+    <xi:include href="xml/tracker-endpoint.xml"/>
     <xi:include href="xml/tracker-misc.xml"/>
     <xi:include href="xml/tracker-version.xml"/>
   </part>
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt 
b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
index 948b63253..996b6316c 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
@@ -234,6 +234,26 @@ TRACKER_TYPE_NOTIFIER_FLAGS
 tracker_notifier_flags_get_type
 </SECTION>
 
+<SECTION>
+<FILE>tracker-endpoint</FILE>
+<TITLE>TrackerEndpoint</TITLE>
+TrackerEndpoint
+TrackerEndpointClass
+TrackerEndpointDBus
+TrackerEndpointDBusClass
+tracker_endpoint_dbus_get_type
+tracker_endpoint_dbus_new
+tracker_endpoint_get_sparql_connection
+<SUBSECTION Standard>
+TRACKER_TYPE_ENDPOINT
+TRACKER_TYPE_ENDPOINT_DBUS
+TRACKER_TYPE_SPARQL_CONNECTION
+TRACKER_TYPE_SPARQL_CONNECTION_FLAGS
+TRACKER_TYPE_SPARQL_CURSOR
+TRACKER_TYPE_SPARQL_ERROR
+TRACKER_TYPE_SPARQL_STATEMENT
+</SECTION>
+
 <SECTION>
 <TITLE>Version Information</TITLE>
 <FILE>tracker-version</FILE>
diff --git a/docs/reference/libtracker-sparql/overview.xml b/docs/reference/libtracker-sparql/overview.xml
index 81b1729da..02a164218 100644
--- a/docs/reference/libtracker-sparql/overview.xml
+++ b/docs/reference/libtracker-sparql/overview.xml
@@ -4,10 +4,21 @@
   <title>Overview</title>
   <partintro>
     <para>
-      The libtracker-sparql library is the foundation for Tracker
-      querying and inserting into the data store. The data store
-      allows both querying and inserting using SPARQL based on the
-      Nepomuk ontology.
+      The libtracker-sparql library allows creating and connecting to
+      one or more "triplestore" databases.
+    </para>
+    <para>
+      Data queries and updates are done using the SPARQL graph query
+      language. The <type><link linkend="TrackerResource">TrackerResource</link></type>
+      API provides helpers for updating data.
+    </para>
+    <para>
+      You can share a database over D-Bus using the
+      <type><link linkend="TrackerEndpoint">TrackerEndpoint</link></type> API,
+      allowing other libtracker-sparql users to query from it, either
+      by referencing it in a <userinput>SELECT { SERVICE ... }</userinput>
+      query, or by connecting directly with
+      <function><link 
linkend="tracker-sparql-connection-bus-new">tracker_sparql_connection_bus_new</link></function>.
     </para>
   </partintro>
 
@@ -15,48 +26,19 @@
   <chapter id="tracker-overview-connection-methods">
     <title>Connection methods</title>
 
-    <para>
-        To access the session-wide Tracker store, you should call
-        <function><link 
linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function>.
-    </para>
     <para>
         You can create and access a private store using
-        <function><link 
linkend="tracker-sparql-connection-local-new">tracker_sparql_connection_local_new</link></function>.
+        <function><link 
linkend="tracker-sparql-connection-new">tracker_sparql_connection_new</link></function>.
     </para>
-  </chapter>
-
-  <chapter id="tracker-overview-compiling">
-    <title>Compiling applications</title>
-
     <para>
-      To compile applications using libtracker-sparql, you
-      need to tell the compiler where to find the proper header files
-      and libraries. This is done with the
-      <application>pkg-config</application> utility.
+        To connect to another database on the same local machine, such as the
+        one exposed by the Tracker filesystem miner, use
+        <function><link 
linkend="tracker-sparql-connection-bus-new">tracker_sparql_connection_bus_new</link></function>.
     </para>
-
     <para>
-      The following interactive shell session demonstrates how
-      <application>pkg-config</application> is used (the actual output on
-      your system may be different):
-<programlisting>
-$ pkg-config --cflags tracker-sparql-0.12
--pthread -I/usr/include/tracker-0.12 -I/usr/include/tracker-0.12/libtracker-sparql -I/usr/include/glib-2.0 
-I/usr/lib/glib-2.0/include
-
-$ pkg-config --libs tracker-sparql-0.12
--Wl,--export-dynamic -pthread -ltracker-sparql-0.12 -lgio-2.0 -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt 
-lglib-2.0
-</programlisting>
+        To connect to another a database on a remote machine, use
+        <function><link 
linkend="tracker-sparql-connection-remote-new">tracker_sparql_connection_remote_new</link></function>.
     </para>
-    <para>
-      The simplest way to compile a program is to use the "backticks"
-      feature of the shell. If you enclose a command in backticks
-      (<emphasis>not single quotes</emphasis>), then its output will be
-      substituted into the command line before execution:
-<programlisting>
- $ cc `pkg-config --cflags --libs tracker-sparql-0.12` hello.c -o hello
-</programlisting>
-    </para>
-
   </chapter>
 
   <chapter id="tracker-overview-environment-variables">
@@ -90,16 +72,7 @@ $ pkg-config --libs tracker-sparql-0.12
        <listitem>
          <emphasis>TRACKER_VERBOSITY</emphasis>
          <para>
-           Historically, all queries would go
-           through <emphasis>tracker-store</emphasis> and all
-           requests would be logged according to the verbosity set
-           in <emphasis>tracker-store.cfg</emphasis> (see manual
-           pages for <emphasis>tracker-store.cfg</emphasis>). Since
-           libtracker-sparql may
-           circumvent <emphasis>tracker-store</emphasis> if using the
-           direct access backend, this environment variable was added
-           to let clients choose the log level. The same values apply
-           to all other processes which have logging and a
+           Lets you choose the log level for libtracker-sparql.
            configuration to control it. Values range
            from <emphasis>0</emphasis> to <emphasis>3</emphasis>,
            0=errors, 1=minimal, 2=detailed, 3=debug. By default it
@@ -112,4 +85,3 @@ $ pkg-config --libs tracker-sparql-0.12
   </chapter>
 
 </part>
-
diff --git a/src/libtracker-sparql/tracker-connection.c b/src/libtracker-sparql/tracker-connection.c
index 50783c6e4..efc3135e4 100644
--- a/src/libtracker-sparql/tracker-connection.c
+++ b/src/libtracker-sparql/tracker-connection.c
@@ -36,6 +36,79 @@ tracker_sparql_connection_class_init (TrackerSparqlConnectionClass *klass)
 {
 }
 
+/* The constructor functions are defined in the libtracker-sparql-backend, but
+ * documented here. */
+
+/**
+ * tracker_sparql_connection_new:
+ * @flags: values from #TrackerSparqlConnectionFlags
+ * @store: the directory that contains the database, as a #GFile
+ * @ontology: the directory that contains the database schemas, as a #GFile
+ * @cancellable: a #GCancellable, or %NULL
+ *
+ * Opens a database. Use this for data managed by the current process.
+ *
+ * To connect to databases managed by other processes, use
+ * tracker_sparql_connection_bus_new().
+ *
+ * Returns: a new #TrackerSparqlConnection. Call g_object_unref() on the
+ * object when no longer used.
+ *
+ * Since: 3.0
+ */
+
+/**
+ * tracker_sparql_connection_new_async:
+ * @flags: values from #TrackerSparqlConnectionFlags
+ * @store: the directory that contains the database, as a #GFile
+ * @ontology: the directory that contains the database schemas, as a #GFile
+ * @cancellable: a #GCancellable, or %NULL
+ * @callback: the #GAsyncReadyCallback called when the operation completes
+ * @user_data: data passed to @callback
+ *
+ * Asynchronous version of tracker_sparql_connection_new().
+ *
+ * Since: 3.0
+ */
+
+/**
+ * tracker_sparql_connection_new_finish:
+ * @result: the #GAsyncResult
+ * @error: pointer to a #GError
+ *
+ * Completion function for tracker_sparql_connection_new_async().
+ *
+ * Since: 3.0
+ */
+
+/**
+ * tracker_sparql_connection_bus_new:
+ * @service: The name of the D-Bus service to connect to.
+ * @object_path: The path to the object, or %NULL to use the default.
+ * @conn: The #GDBusConnection to use, or %NULL to use the session bus.
+ *
+ * Connects to a database owned by another process on the
+ * local machine.
+ *
+ * Returns: a new #TrackerSparqlConnection. Call g_object_unref() on the
+ * object when no longer used.
+ *
+ * Since: 3.0
+ */
+
+/**
+ * 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.
+ *
+ * Returns: a new remote #TrackerSparqlConnection. Call g_object_unref() on the
+ * object when no longer used.
+ *
+ * Since: 1.12
+ */
+
 /**
  * tracker_sparql_connection_query:
  * @connection: a #TrackerSparqlConnection
diff --git a/src/libtracker-sparql/tracker-endpoint.c b/src/libtracker-sparql/tracker-endpoint.c
index 4539eae63..ddf537af5 100644
--- a/src/libtracker-sparql/tracker-endpoint.c
+++ b/src/libtracker-sparql/tracker-endpoint.c
@@ -38,6 +38,25 @@ typedef struct {
 
 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (TrackerEndpoint, tracker_endpoint, G_TYPE_OBJECT)
 
+/**
+ * SECTION: tracker-endpoint
+ * @short_description: Expose a database to other processes
+ * @title: TrackerEndpoint
+ * @stability: Stable
+ * @include: tracker-endpoint.h
+ *
+ * <para>
+ * #TrackerEndpoint allows sharing data with other processes on the system,
+ * using a Tracker-specific D-Bus API.
+ * </para>
+ * <para>
+ * When it is shared in this way, processes can connect to your database using
+ * tracker_sparql_connection_bus_new() and can also fetch data directly from
+ * SPARQL queries using the <userinput>SELECT { SERVICE ... }</userinput>
+ * syntax.
+ * </para>
+ */
+
 static void
 tracker_endpoint_finalize (GObject *object)
 {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]