[tracker/wip/carlosg/local-connection-mapping: 2/2] libtracker-sparql: Add tracker_sparql_connection_map_connection()

[Carlos Garnacho <carlosg src gnome org>]

commit 36894431976e9681a512c3181fa0071e64d36f94
Author: Carlos Garnacho <carlosg gnome org>
Date:   Sat Apr 3 15:43:49 2021 +0200

    libtracker-sparql: Add tracker_sparql_connection_map_connection()
    
    This API call allows hooking up a local TrackerSparqlConnection into
    another, so it is possible to access other local connections from
    one of them. This happens via the SERVICE SPARQL syntax, using
    special local:$handle_name URIs.
    
    This may be useful if there is data with different relevance (e.g.
    cache vs persistent) that the application is interested in maintaining
    separately, but query altogether.

 .../libtracker-sparql-sections.txt                 |  1 +
 src/libtracker-sparql/direct/tracker-direct.c      | 17 ++++++++
 src/libtracker-sparql/tracker-connection.c         | 48 ++++++++++++++++++++++
 src/libtracker-sparql/tracker-connection.h         |  5 +++
 src/libtracker-sparql/tracker-private.h            |  3 ++
 5 files changed, 74 insertions(+)
---
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt 
b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
index 8dce837dd..3b7488962 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
@@ -129,6 +129,7 @@ tracker_sparql_connection_create_batch
 tracker_sparql_connection_close
 tracker_sparql_connection_close_async
 tracker_sparql_connection_close_finish
+tracker_sparql_connection_map_connection
 <SUBSECTION Standard>
 TrackerSparqlConnectionClass
 TRACKER_SPARQL_CONNECTION
diff --git a/src/libtracker-sparql/direct/tracker-direct.c b/src/libtracker-sparql/direct/tracker-direct.c
index 7f5131deb..8c9d21cc9 100644
--- a/src/libtracker-sparql/direct/tracker-direct.c
+++ b/src/libtracker-sparql/direct/tracker-direct.c
@@ -1226,6 +1226,22 @@ tracker_direct_connection_lookup_dbus_service (TrackerSparqlConnection  *connect
        return TRUE;
 }
 
+void
+tracker_direct_connection_map_connection (TrackerSparqlConnection *connection,
+                                         const gchar             *handle_name,
+                                         TrackerSparqlConnection *service_connection)
+{
+       TrackerDirectConnectionPrivate *priv;
+       TrackerDirectConnection *conn;
+
+       conn = TRACKER_DIRECT_CONNECTION (connection);
+       priv = tracker_direct_connection_get_instance_private (conn);
+
+       tracker_data_manager_map_local_connection (priv->data_manager,
+                                                  handle_name,
+                                                  service_connection);
+}
+
 static void
 tracker_direct_connection_class_init (TrackerDirectConnectionClass *klass)
 {
@@ -1261,6 +1277,7 @@ tracker_direct_connection_class_init (TrackerDirectConnectionClass *klass)
        sparql_connection_class->update_resource_finish = tracker_direct_connection_update_resource_finish;
        sparql_connection_class->create_batch = tracker_direct_connection_create_batch;
        sparql_connection_class->lookup_dbus_service = tracker_direct_connection_lookup_dbus_service;
+       sparql_connection_class->map_connection = tracker_direct_connection_map_connection;
 
        props[PROP_FLAGS] =
                g_param_spec_flags ("flags",
diff --git a/src/libtracker-sparql/tracker-connection.c b/src/libtracker-sparql/tracker-connection.c
index 2cacd7735..e31550498 100644
--- a/src/libtracker-sparql/tracker-connection.c
+++ b/src/libtracker-sparql/tracker-connection.c
@@ -69,6 +69,8 @@
 #include "tracker-connection.h"
 #include "tracker-private.h"
 
+#include "direct/tracker-direct.h"
+
 G_DEFINE_ABSTRACT_TYPE (TrackerSparqlConnection, tracker_sparql_connection,
                         G_TYPE_OBJECT)
 
@@ -806,3 +808,49 @@ tracker_sparql_connection_create_batch (TrackerSparqlConnection *connection)
 
        return TRACKER_SPARQL_CONNECTION_GET_CLASS (connection)->create_batch (connection);
 }
+
+/**
+ * tracker_sparql_connection_map_connection:
+ * @connection: a #TrackerSparqlConnection
+ * @handle_name: handle name for @service_connection
+ * @service_connection: a #TrackerSparqlConnection to use from @connection
+ *
+ * Maps @service_connection so it is available as a "local:@handle_name" URI
+ * in @connection. This can be accessed via the SERVICE SPARQL syntax in
+ * queries from @connection. E.g.:
+ *
+ * <example>
+ * <programlisting>
+ * SELECT ?u {
+ *   SERVICE &lt;local:other-connection&gt; {
+ *     ?u a rdfs:Resource
+ *   }
+ * }
+ * </programlisting>
+ * </example>
+ *
+ * This is useful to interrelate data from multiple
+ * #TrackerSparqlConnection<!-- -->s maintained by the same process,
+ * without creating a public endpoint for @service_connection.
+ *
+ * This call only applies to connections created via
+ * tracker_sparql_connection_new() and tracker_sparql_connection_new_async().
+ *
+ * Since: 3.2
+ **/
+void
+tracker_sparql_connection_map_connection (TrackerSparqlConnection *connection,
+                                         const gchar             *handle_name,
+                                         TrackerSparqlConnection *service_connection)
+{
+       g_return_if_fail (TRACKER_IS_DIRECT_CONNECTION (connection));
+       g_return_if_fail (TRACKER_IS_DIRECT_CONNECTION (service_connection));
+       g_return_if_fail (handle_name && *handle_name);
+
+       if (!TRACKER_SPARQL_CONNECTION_GET_CLASS (connection)->map_connection)
+               return;
+
+       return TRACKER_SPARQL_CONNECTION_GET_CLASS (connection)->map_connection (connection,
+                                                                                handle_name,
+                                                                                service_connection);
+}
diff --git a/src/libtracker-sparql/tracker-connection.h b/src/libtracker-sparql/tracker-connection.h
index d992adbcd..5a84bcf9c 100644
--- a/src/libtracker-sparql/tracker-connection.h
+++ b/src/libtracker-sparql/tracker-connection.h
@@ -210,4 +210,9 @@ gboolean tracker_sparql_connection_close_finish (TrackerSparqlConnection  *conne
                                                  GAsyncResult             *res,
                                                  GError                  **error);
 
+TRACKER_AVAILABLE_IN_ALL
+void tracker_sparql_connection_map_connection (TrackerSparqlConnection *connection,
+                                              const gchar             *handle_name,
+                                              TrackerSparqlConnection *service_connection);
+
 #endif /* __TRACKER_SPARQL_CONNECTION_H__ */
diff --git a/src/libtracker-sparql/tracker-private.h b/src/libtracker-sparql/tracker-private.h
index b8c6381ec..c3ed8741d 100644
--- a/src/libtracker-sparql/tracker-private.h
+++ b/src/libtracker-sparql/tracker-private.h
@@ -112,6 +112,9 @@ struct _TrackerSparqlConnectionClass
                                          const gchar              *dbus_path,
                                          gchar                   **name,
                                          gchar                   **path);
+       void (* map_connection) (TrackerSparqlConnection  *connection,
+                                const gchar              *handle_name,
+                                TrackerSparqlConnection  *service_connection);
 };
 
 typedef struct _TrackerSparqlCursorClass TrackerSparqlCursorClass;