[tracker/wip/carlosg/deserialize-api: 4/17] libtracker-sparql: Add public deserialization API

[Carlos Garnacho <carlosg src gnome org>]

commit 9ddc56dfeb93df1cd296691b3ced4f9159930930
Author: Carlos Garnacho <carlosg gnome org>
Date:   Sat May 7 23:59:24 2022 +0200

    libtracker-sparql: Add public deserialization API
    
    This API takes a GInputStream containing RDF data (loaded from a
    file, obtained from tracker_sparql_connection_serialize on another
    connection, ...) and loads it into the TrackerSparqlConnection.
    
    So far it's an empty stub, implementations will be added in direct
    and dbus connections.

 src/libtracker-sparql/tracker-connection.c | 80 ++++++++++++++++++++++++++++++
 src/libtracker-sparql/tracker-connection.h | 24 +++++++++
 src/libtracker-sparql/tracker-private.h    | 11 ++++
 3 files changed, 115 insertions(+)
---
diff --git a/src/libtracker-sparql/tracker-connection.c b/src/libtracker-sparql/tracker-connection.c
index c52e6c7c4..398d9ae52 100644
--- a/src/libtracker-sparql/tracker-connection.c
+++ b/src/libtracker-sparql/tracker-connection.c
@@ -940,6 +940,86 @@ tracker_sparql_connection_serialize_finish (TrackerSparqlConnection  *connection
                                                                                   error);
 }
 
+/**
+ * tracker_sparql_connection_deserialize_async:
+ * @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
+ * graph specified (e.g. using the `GRAPH` clause in the Trig format) will
+ * be inserted in the specified graph instead of @default_graph.
+ *
+ * The @flags argument is reserved for future expansions, currently
+ * %TRACKER_DESERIALIZE_FLAGS_NONE must be passed.
+ *
+ * Since: 3.4
+ **/
+void
+tracker_sparql_connection_deserialize_async (TrackerSparqlConnection *connection,
+                                             TrackerDeserializeFlags  flags,
+                                             TrackerRdfFormat         format,
+                                             const gchar             *default_graph,
+                                             GInputStream            *stream,
+                                             GCancellable            *cancellable,
+                                             GAsyncReadyCallback      callback,
+                                             gpointer                 user_data)
+{
+       g_return_if_fail (TRACKER_IS_SPARQL_CONNECTION (connection));
+       g_return_if_fail (flags == TRACKER_DESERIALIZE_FLAGS_NONE);
+       g_return_if_fail (format < TRACKER_N_RDF_FORMATS);
+       g_return_if_fail (G_IS_INPUT_STREAM (stream));
+       g_return_if_fail (!cancellable || G_IS_CANCELLABLE (cancellable));
+       g_return_if_fail (callback != NULL);
+
+       TRACKER_SPARQL_CONNECTION_GET_CLASS (connection)->deserialize_async (connection,
+                                                                            flags,
+                                                                            format,
+                                                                            default_graph,
+                                                                            stream,
+                                                                            cancellable,
+                                                                            callback,
+                                                                            user_data);
+}
+
+/**
+ * tracker_sparql_connection_deserialize_finish:
+ * @connection: a #TrackerSparqlConnection
+ * @result: the #GAsyncResult
+ * @error: location for returned errors, or %NULL
+ *
+ * Finishes a tracker_sparql_connection_deserialize_async() operation.
+ * In case of error, %NULL will be returned and @error will be set.
+ *
+ * Returns: %TRUE if all data was inserted successfully.
+ *
+ * Since: 3.4
+ **/
+gboolean
+tracker_sparql_connection_deserialize_finish (TrackerSparqlConnection  *connection,
+                                              GAsyncResult             *result,
+                                              GError                  **error)
+{
+       g_return_val_if_fail (TRACKER_IS_SPARQL_CONNECTION (connection), FALSE);
+       g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
+       g_return_val_if_fail (!error || !*error, FALSE);
+
+       return TRACKER_SPARQL_CONNECTION_GET_CLASS (connection)->deserialize_finish (connection,
+                                                                                    result,
+                                                                                    error);
+}
+
 /**
  * tracker_sparql_connection_map_connection:
  * @connection: a #TrackerSparqlConnection
diff --git a/src/libtracker-sparql/tracker-connection.h b/src/libtracker-sparql/tracker-connection.h
index 86e4339ee..41aede1ff 100644
--- a/src/libtracker-sparql/tracker-connection.h
+++ b/src/libtracker-sparql/tracker-connection.h
@@ -64,6 +64,16 @@ typedef enum {
        TRACKER_SERIALIZE_FLAGS_NONE = 0,
 } TrackerSerializeFlags;
 
+/**
+ * TrackerDeserializeFlags:
+ * @TRACKER_DESERIALIZE_FLAGS_NONE: No flags.
+ *
+ * Flags affecting deserialization of RDF.
+ */
+typedef enum {
+       TRACKER_DESERIALIZE_FLAGS_NONE = 0,
+} TrackerDeserializeFlags;
+
 /**
  * TrackerSparqlConnection:
  *
@@ -227,6 +237,20 @@ GInputStream * tracker_sparql_connection_serialize_finish (TrackerSparqlConnecti
                                                            GAsyncResult             *result,
                                                            GError                  **error);
 
+TRACKER_AVAILABLE_IN_3_4
+void tracker_sparql_connection_deserialize_async (TrackerSparqlConnection *connection,
+                                                  TrackerDeserializeFlags  flags,
+                                                  TrackerRdfFormat         format,
+                                                  const gchar             *default_graph,
+                                                  GInputStream            *stream,
+                                                  GCancellable            *cancellable,
+                                                  GAsyncReadyCallback      callback,
+                                                  gpointer                 user_data);
+TRACKER_AVAILABLE_IN_3_4
+gboolean tracker_sparql_connection_deserialize_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 39b893757..0e309e48e 100644
--- a/src/libtracker-sparql/tracker-private.h
+++ b/src/libtracker-sparql/tracker-private.h
@@ -123,6 +123,17 @@ struct _TrackerSparqlConnectionClass
        GInputStream * (* serialize_finish) (TrackerSparqlConnection  *connection,
                                             GAsyncResult             *res,
                                             GError                  **error);
+       void (* deserialize_async) (TrackerSparqlConnection *connection,
+                                   TrackerDeserializeFlags  flags,
+                                   TrackerRdfFormat         format,
+                                   const gchar             *default_graph,
+                                   GInputStream            *stream,
+                                   GCancellable            *cancellable,
+                                   GAsyncReadyCallback      callback,
+                                   gpointer                 user_data);
+       gboolean (* deserialize_finish) (TrackerSparqlConnection  *connection,
+                                        GAsyncResult             *res,
+                                        GError                  **error);
        void (* map_connection) (TrackerSparqlConnection  *connection,
                                 const gchar              *handle_name,
                                 TrackerSparqlConnection  *service_connection);