[tracker/wip/carlosg/serialize-api: 17/36] libtracker-sparql: Add tracker_sparql_connection_serialize_async() API

[Carlos Garnacho <carlosg src gnome org>]

commit 812086d9e144b57846b83ef384a12fac82231c1e
Author: Carlos Garnacho <carlosg gnome org>
Date:   Sat Nov 13 16:58:42 2021 +0100

    libtracker-sparql: Add tracker_sparql_connection_serialize_async() API
    
    This new call serializes a DESCRIBE or CONSTRUCT query into one of the
    supported RDF formats. This may be useful in a number of situations,
    such as data exporting, and bulk migrations.

 src/libtracker-sparql/tracker-connection.c | 67 ++++++++++++++++++++++++++++++
 src/libtracker-sparql/tracker-connection.h | 17 ++++++++
 src/libtracker-sparql/tracker-private.h    | 10 +++++
 3 files changed, 94 insertions(+)
---
diff --git a/src/libtracker-sparql/tracker-connection.c b/src/libtracker-sparql/tracker-connection.c
index 25009234c..e2fb32578 100644
--- a/src/libtracker-sparql/tracker-connection.c
+++ b/src/libtracker-sparql/tracker-connection.c
@@ -870,3 +870,70 @@ tracker_sparql_connection_load_statement_from_gresource (TrackerSparqlConnection
 
        return stmt;
 }
+
+/**
+ * tracker_sparql_connection_serialize_async:
+ * @connection: a #TrackerSparqlConnection
+ * @format: output RDF format
+ * @query: SPARQL query
+ * @cancellable: a #GCancellable
+ * @callback: the #GAsyncReadyCallback called when the operation completes
+ * @user_data: data 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.
+ *
+ * The SPARQL endpoint may not support the specified format, in that case
+ * an error will be raised.
+ *
+ * Since: 3.3
+ **/
+void
+tracker_sparql_connection_serialize_async (TrackerSparqlConnection *connection,
+                                           TrackerRdfFormat         format,
+                                           const gchar             *query,
+                                           GCancellable            *cancellable,
+                                           GAsyncReadyCallback      callback,
+                                           gpointer                 user_data)
+{
+       g_return_if_fail (TRACKER_IS_SPARQL_CONNECTION (connection));
+       g_return_if_fail (format < TRACKER_N_RDF_FORMATS);
+       g_return_if_fail (query != NULL);
+       g_return_if_fail (!cancellable || G_IS_CANCELLABLE (cancellable));
+       g_return_if_fail (callback != NULL);
+
+       TRACKER_SPARQL_CONNECTION_GET_CLASS (connection)->serialize_async (connection,
+                                                                          format,
+                                                                          query,
+                                                                          cancellable,
+                                                                          callback,
+                                                                          user_data);
+}
+
+/**
+ * tracker_sparql_connection_serialize_finish:
+ * @connection: a #TrackerSparqlConnection
+ * @result: the #GAsyncResult
+ * @error: location for returned errors, or %NULL
+ *
+ * Finishes a tracker_sparql_connection_serialize_async() operation.
+ * In case of error, %NULL will be returned and @error will be set.
+ *
+ * Returns: (transfer full): a #GInputStream to read RDF content.
+ *
+ * Since: 3.3
+ **/
+GInputStream *
+tracker_sparql_connection_serialize_finish (TrackerSparqlConnection  *connection,
+                                            GAsyncResult             *result,
+                                            GError                  **error)
+{
+       g_return_val_if_fail (TRACKER_IS_SPARQL_CONNECTION (connection), NULL);
+       g_return_val_if_fail (G_IS_ASYNC_RESULT (result), NULL);
+       g_return_val_if_fail (!error || !*error, NULL);
+
+       return TRACKER_SPARQL_CONNECTION_GET_CLASS (connection)->serialize_finish (connection,
+                                                                                  result,
+                                                                                  error);
+}
diff --git a/src/libtracker-sparql/tracker-connection.h b/src/libtracker-sparql/tracker-connection.h
index b8ea4715a..d05e37f2a 100644
--- a/src/libtracker-sparql/tracker-connection.h
+++ b/src/libtracker-sparql/tracker-connection.h
@@ -54,6 +54,11 @@ typedef enum {
        TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES      = 1 << 5,
 } TrackerSparqlConnectionFlags;
 
+typedef enum {
+       TRACKER_RDF_FORMAT_TURTLE,
+       TRACKER_N_RDF_FORMATS
+} TrackerRdfFormat;
+
 /**
  * TrackerSparqlConnection:
  *
@@ -204,6 +209,18 @@ TrackerNotifier * tracker_sparql_connection_create_notifier (TrackerSparqlConnec
 TRACKER_AVAILABLE_IN_ALL
 void tracker_sparql_connection_close (TrackerSparqlConnection *connection);
 
+TRACKER_AVAILABLE_IN_3_3
+void tracker_sparql_connection_serialize_async (TrackerSparqlConnection  *connection,
+                                                TrackerRdfFormat          format,
+                                                const gchar              *query,
+                                                GCancellable             *cancellable,
+                                                GAsyncReadyCallback      callback,
+                                                gpointer                 user_data);
+TRACKER_AVAILABLE_IN_3_3
+GInputStream * tracker_sparql_connection_serialize_finish (TrackerSparqlConnection  *connection,
+                                                           GAsyncResult             *result,
+                                                           GError                  **error);
+
 TRACKER_AVAILABLE_IN_ALL
 void tracker_sparql_connection_close_async (TrackerSparqlConnection *connection,
                                             GCancellable            *cancellable,
diff --git a/src/libtracker-sparql/tracker-private.h b/src/libtracker-sparql/tracker-private.h
index 448581acd..e5be247f4 100644
--- a/src/libtracker-sparql/tracker-private.h
+++ b/src/libtracker-sparql/tracker-private.h
@@ -110,6 +110,16 @@ struct _TrackerSparqlConnectionClass
                                          const gchar              *dbus_path,
                                          gchar                   **name,
                                          gchar                   **path);
+
+       void (* serialize_async) (TrackerSparqlConnection  *connection,
+                                 TrackerRdfFormat          format,
+                                 const gchar              *query,
+                                 GCancellable             *cancellable,
+                                 GAsyncReadyCallback      callback,
+                                 gpointer                 user_data);
+       GInputStream * (* serialize_finish) (TrackerSparqlConnection  *connection,
+                                            GAsyncResult             *res,
+                                            GError                  **error);
 };
 
 struct _TrackerSparqlCursorClass