[tracker/libtracker-sparql-porting: 3/45] libtracker-client: Marked entire API as deprecated and updated documentation



commit c055443343883a03c960cc1bd8c1fe0d8b0821eb
Author: Martyn Russell <martyn lanedo com>
Date:   Mon Jul 19 12:17:57 2010 +0100

    libtracker-client: Marked entire API as deprecated and updated documentation

 src/libtracker-client/tracker.c |  131 ++++++++++++++++++++++++++++++++++++---
 src/libtracker-client/tracker.h |   80 +++++++++++++-----------
 2 files changed, 167 insertions(+), 44 deletions(-)
---
diff --git a/src/libtracker-client/tracker.c b/src/libtracker-client/tracker.c
index 753b7ad..2196593 100644
--- a/src/libtracker-client/tracker.c
+++ b/src/libtracker-client/tracker.c
@@ -21,6 +21,8 @@
 
 #include "config.h"
 
+#ifndef TRACKER_DISABLE_DEPRECATED
+
 #include <string.h>
 #include <errno.h>
 #include <sys/types.h>
@@ -56,6 +58,13 @@
  * either by storing their data or by querying it. They are also not
  * limited to their application's data. Other data mined by other
  * applications is also available in some cases.
+ *
+ * Deprecated: 0.10: This whole library has been replaced by libtracker-sparql
+ * in its entirity to provide a cleaner and much more usable API using GLib's
+ * asynchronous and cancellable APIS and a foundation Cursor API shared by both
+ * a direct and d-bus approach. Additionally all escaping and SPARQL building
+ * functionality has moved to this new library and is shared across the Tracker
+ * platform.
  **/
 
 /**
@@ -804,6 +813,8 @@ is_service_available (void)
  * Escapes a string so it can be passed as a SPARQL parameter in
  * any query/update.
  *
+ * Deprecated: 0.10: For tracker_sparql_escape_string() in libtracker-sparql
+ *
  * Returns: the newly allocated escaped string which must be freed
  * using g_free().
  *
@@ -1257,6 +1268,8 @@ sparql_update_fast_async (TrackerClient  *client,
  *
  * The result is escaped using g_uri_escape_string().
  *
+ * Deprecated: 0.10: For tracker_sparql_escape_uri_vprintf() in libtracker-sparql
+ *
  * Returns: a newly-allocated string holding the result which should
  * be freed with g_free() when finished with.
  *
@@ -1360,7 +1373,9 @@ cleanup:
  * @Varargs: the parameters to insert into the format string
  *
  * Calls tracker_uri_vprintf_escaped() with the @Varargs supplied.
-
+ *
+ * Deprecated: 0.10: For tracker_sparql_escape_uri_printf() in libtracker-sparql
+ *
  * Returns: a newly-allocated string holding the result which should
  * be freed with g_free() when finished with.
  *
@@ -1390,6 +1405,8 @@ tracker_uri_printf_escaped (const gchar *format, ...)
  * The @timeout is only used if it is > 0. If it is, then it is used
  * with dbus_g_proxy_set_default_timeout().
  *
+ * Deprecated: 0.10: For tracker_bus_connection_new() or tracker_direct_connection_new() in libtracker-sparql
+ *
  * Returns: the #TrackerClient which should be freed with
  * g_object_unref() when finished with.
  **/
@@ -1422,6 +1439,8 @@ tracker_client_new (TrackerClientFlags flags,
  * API call made using libtracker-client. For synchronous API calls,
  * see tracker_cancel_last_call() which is more useful.
  *
+ * Deprecated: 0.10: There is no replacement for this in libtracker-sparql
+ *
  * Returns: A @gboolean indicating if the call was cancelled or not.
  **/
 gboolean
@@ -1505,6 +1524,8 @@ tracker_cancel_call (TrackerClient *client,
  * last API call ID is always tracked so you don't have to provide it
  * with this API.
  *
+ * Deprecated: 0.10: There is no replacement for this in libtracker-sparql
+ *
  * Returns: A #gboolean indicating if the call was cancelled or not.
  **/
 gboolean
@@ -1540,6 +1561,8 @@ tracker_cancel_last_call (TrackerClient *client)
  *
  * This API call is completely synchronous so it may block.
  *
+ * Deprecated: 0.10: For tracker_sparql_stats() in libtracker-sparql
+ *
  * Returns: A #GPtrArray with the statistics which must be freed using
  * g_ptr_array_free().
  *
@@ -1565,6 +1588,18 @@ tracker_statistics_get (TrackerClient  *client,
 	return table;
 }
 
+/**
+ * tracker_resources_load:
+ * @client: a #TrackerClient.
+ * @uri: a string representing a Turtle file
+ * @error: a #GError.
+ *
+ * Imports SPARQL into the database from a file specified by @uri
+ *
+ * Deprecated: 0.10: For tracker_sparql_import() in libtracker-sparql
+ *
+ * Since: 0.8
+ **/
 void
 tracker_resources_load (TrackerClient  *client,
                         const gchar    *uri,
@@ -1632,6 +1667,8 @@ tracker_resources_load (TrackerClient  *client,
  *
  * This API call is completely synchronous so it may block.
  *
+ * Deprecated: 0.10: For tracker_sparql_query() in libtracker-sparql
+ *
  * Returns: A #GPtrArray with the query results which must be freed
  * using g_ptr_array_free().
  *
@@ -1720,10 +1757,12 @@ tracker_resources_sparql_query (TrackerClient  *client,
  * </programlisting>
  * </example>
  *
+ * Deprecated: 0.10: For tracker_sparql_query() in libtracker-sparql
+ *
  * Returns: A #TrackerResultIterator pointing before the first result row. This
  * iterator must be disposed when done using tracker_result_iterator_free().
  *
- * Since: 0.9
+ * Since: 0.10
  **/
 TrackerResultIterator *
 tracker_resources_sparql_query_iterate (TrackerClient  *client,
@@ -1811,7 +1850,9 @@ tracker_resources_sparql_query_iterate (TrackerClient  *client,
  *
  * Frees a TrackerResultIterator and its associated resources
  *
- * Since: 0.9
+ * Deprecated: 0.10: For g_object_unref() in libtracker-sparql
+ *
+ * Since: 0.10
  **/
 void
 tracker_result_iterator_free (TrackerResultIterator *iterator)
@@ -1831,9 +1872,11 @@ tracker_result_iterator_free (TrackerResultIterator *iterator)
  * tracker_result_iterator_n_columns:
  * @iterator: A TrackerResultIterator
  *
+ * Deprecated: 0.10: For tracker_cursor_n_columns() in libtracker-sparql
+ *
  * Returns: the number of columns in the row pointed by @iterator
  *
- * Since: 0.9
+ * Since: 0.10
  **/
 guint
 tracker_result_iterator_n_columns (TrackerResultIterator *iterator)
@@ -1868,9 +1911,11 @@ tracker_result_iterator_n_columns (TrackerResultIterator *iterator)
  *
  * Fetches the next row for the results.
  *
+ * Deprecated: 0.10: For tracker_cursor_next() in libtracker-sparql
+ *
  * Returns: %TRUE if a rows was fetched, otherwise %FALSE.
  *
- * Since: 0.9
+ * Since: 0.10
  **/
 gboolean
 tracker_result_iterator_next (TrackerResultIterator *iterator)
@@ -1918,7 +1963,9 @@ tracker_result_iterator_next (TrackerResultIterator *iterator)
  * Returns: the value of the column as a string. The returned string belongs to
  * the iterator and should not be freed.
  *
- * Since: 0.9
+ * Deprecated: 0.10: For tracker_cursor_get_string() in libtracker-sparql
+ *
+ * Since: 0.10
  **/
 const gchar *
 tracker_result_iterator_value (TrackerResultIterator *iterator,
@@ -1965,6 +2012,8 @@ tracker_result_iterator_value (TrackerResultIterator *iterator,
  *
  * This API call is completely synchronous so it may block.
  *
+ * Deprecated: 0.10: For tracker_sparql_update() in libtracker-sparql
+ *
  * Since: 0.8
  **/
 void
@@ -1999,6 +2048,16 @@ tracker_resources_sparql_update (TrackerClient  *client,
 #endif /* HAVE_DBUS_FD_PASSING */
 }
 
+/**
+ * tracker_resources_sparql_update_blank:
+ * @client: a #TrackerClient.
+ * @query: a string representing SPARQL.
+ * @error: return location for errors.
+ *
+ * Deprecated: 0.10: There is no replacement for this in libtracker-sparql
+ *
+ * Since: 0.8
+ **/
 GPtrArray *
 tracker_resources_sparql_update_blank (TrackerClient  *client,
                                        const gchar    *query,
@@ -2080,6 +2139,8 @@ tracker_resources_sparql_update_blank (TrackerClient  *client,
  * tracker_resources_batch_commit_async(). This API call is synchronous so it may
  * block.
  *
+ * Deprecated: 0.10: For tracker_sparql_update() in libtracker-sparql
+ *
  * Since: 0.8
  **/
 void
@@ -2119,6 +2180,8 @@ tracker_resources_batch_sparql_update (TrackerClient  *client,
  * Commits a batch of already issued SPARQL updates. This API call is
  * synchronous so it may block.
  *
+ * Deprecated: 0.10: For tracker_sparql_update_commit() in libtracker-sparql
+ *
  * Since: 0.8
  **/
 void
@@ -2144,6 +2207,8 @@ tracker_resources_batch_commit (TrackerClient  *client,
  *
  * This behaves exactly as tracker_statistics_get() but asynchronously.
  *
+ * Deprecated: 0.10: For tracker_sparql_stats_async() in libtracker-sparql
+ *
  * Returns: A #guint representing the operation ID. See
  * tracker_cancel_call(). In the event of failure, 0 is returned.
  *
@@ -2218,6 +2283,8 @@ tracker_resources_load_async (TrackerClient    *client,
  * Does an asynchronous SPARQL query. See tracker_resources_sparql_query()
  * to see how an SPARLQL query should be like.
  *
+ * Deprecated: 0.10: For tracker_sparql_query_async() in libtracker-sparql
+ *
  * Returns: A #guint representing the operation ID. See
  * tracker_cancel_call(). In the event of failure, 0 is returned.
  *
@@ -2254,6 +2321,20 @@ tracker_resources_sparql_query_async (TrackerClient         *client,
 	return cb->id;
 }
 
+/**
+ * tracker_resources_sparql_query_iterate_async
+ * @client: a #TrackerClient.
+ * @query: a string representing SPARQL.
+ * @callback: function to be called when the blank update has been performed.
+ * @user_data: user data to pass to @callback.
+ *
+ * Deprecated: 0.10: For tracker_sparql_query_async() in libtracker-sparql
+ *
+ * Returns: A #guint representing the operation ID. See
+ * tracker_cancel_call(). In the event of failure, 0 is returned.
+ *
+ * Since: 0.10
+ **/
 guint
 tracker_resources_sparql_query_iterate_async (TrackerClient         *client,
                                               const gchar           *query,
@@ -2336,6 +2417,20 @@ tracker_resources_sparql_query_iterate_async (TrackerClient         *client,
 #endif /* HAVE_DBUS_FD_PASSING */
 }
 
+/**
+ * tracker_resources_sparql_update_async
+ * @client: a #TrackerClient.
+ * @query: a string representing SPARQL.
+ * @callback: function to be called when the blank update has been performed.
+ * @user_data: user data to pass to @callback.
+ *
+ * Deprecated: 0.10: For tracker_sparql_update_async() in libtracker-sparql
+ *
+ * Returns: A #guint representing the operation ID. See
+ * tracker_cancel_call(). In the event of failure, 0 is returned.
+ *
+ * Since: 0.8
+ **/
 guint
 tracker_resources_sparql_update_async (TrackerClient    *client,
                                        const gchar      *query,
@@ -2395,6 +2490,20 @@ tracker_resources_sparql_update_async (TrackerClient    *client,
 #endif /* HAVE_DBUS_FD_PASSING */
 }
 
+/**
+ * tracker_resources_sparql_update_blank_async
+ * @client: a #TrackerClient.
+ * @query: a string representing SPARQL.
+ * @callback: function to be called when the blank update has been performed.
+ * @user_data: user data to pass to @callback.
+ *
+ * Deprecated: 0.10: There is no replacement for this in libtracker-sparql
+ *
+ * Returns: A #guint representing the operation ID. See
+ * tracker_cancel_call(). In the event of failure, 0 is returned.
+ *
+ * Since: 0.8
+ **/
 guint
 tracker_resources_sparql_update_blank_async (TrackerClient         *client,
                                              const gchar           *query,
@@ -2463,6 +2572,8 @@ tracker_resources_sparql_update_blank_async (TrackerClient         *client,
  *
  * Updates the database using SPARQL. see tracker_resources_batch_sparql_update().
  *
+ * Deprecated: 0.10: For tracker_sparql_update_async() in libtracker-sparql
+ *
  * Returns: A #guint representing the operation ID. See
  * tracker_cancel_call(). In the event of failure, 0 is returned.
  *
@@ -2535,6 +2646,8 @@ tracker_resources_batch_sparql_update_async (TrackerClient    *client,
  *
  * Commits a batch of already issued SPARQL updates.
  *
+ * Deprecated: 0.10: For tracker_sparql_update_commit_async() in libtracker-sparql
+ *
  * Returns: A #guint representing the operation ID. See
  * tracker_cancel_call(). In the event of failure, 0 is returned.
  *
@@ -2583,6 +2696,8 @@ tracker_resources_batch_commit_async (TrackerClient    *client,
  * possible the changes in the RDF store should be reflected in the metadata of
  * the original file.
  *
+ * Deprecated: 0.10: There is no replacement for this in libtracker-sparql
+ *
  * Returns: a handle that can be used to disconnect the signal later using
  *          tracker_resources_writeback_disconnect. The handle will always be
  *          greater than 0 on success.
@@ -2625,6 +2740,8 @@ tracker_resources_writeback_connect (TrackerClient            *client,
  * @client: a #TrackerClient
  * @handle: a handle identifying a callback
  *
+ * Deprecated: 0.10: There is no replacement for this in libtracker-sparql
+ *
  * Removes the callback identified by @handle from the writeback callbacks.
  **/
 void
@@ -2695,8 +2812,6 @@ sparql_append_string_literal (GString     *sparql,
 	g_string_append_c (sparql, '"');
 }
 
-#ifndef TRACKER_DISABLE_DEPRECATED
-
 /**
  * tracker_connect:
  * @enable_warnings: a #gboolean to determine if warnings are issued in
diff --git a/src/libtracker-client/tracker.h b/src/libtracker-client/tracker.h
index a3dea6e..9ea31f8 100644
--- a/src/libtracker-client/tracker.h
+++ b/src/libtracker-client/tracker.h
@@ -31,6 +31,13 @@
 
 G_BEGIN_DECLS
 
+#ifndef TRACKER_DISABLE_DEPRECATED
+
+/*
+ * Now, libtracker-sparql is to be used instead of libtracker-client. All these
+ * APIS are now marked as deprecated.
+ */
+
 #define TRACKER_DBUS_SERVICE              "org.freedesktop.Tracker1"
 #define TRACKER_DBUS_OBJECT               "/org/freedesktop/Tracker1"
 #define TRACKER_DBUS_INTERFACE_RESOURCES  "org.freedesktop.Tracker1.Resources"
@@ -84,7 +91,7 @@ typedef enum {
  **/
 typedef void (*TrackerReplyGPtrArray) (GPtrArray *result,
                                        GError    *error,
-                                       gpointer   user_data);
+                                       gpointer   user_data)                                      G_GNUC_DEPRECATED;
 
 /**
  * TrackerReplyVoid:
@@ -95,11 +102,11 @@ typedef void (*TrackerReplyGPtrArray) (GPtrArray *result,
  * is an error the @error is populated with the details.
  **/
 typedef void (*TrackerReplyVoid)      (GError    *error,
-                                       gpointer   user_data);
+                                       gpointer   user_data)                                      G_GNUC_DEPRECATED;
 
 typedef void (*TrackerReplyIterator)  (TrackerResultIterator *iterator,
                                        GError                *error,
-                                       gpointer               user_data);
+                                       gpointer               user_data)                          G_GNUC_DEPRECATED;
 
 /**
  * TrackerWritebackCallback:
@@ -111,96 +118,97 @@ typedef void (*TrackerReplyIterator)  (TrackerResultIterator *iterator,
  * is modified in the store.
  */
 typedef void (*TrackerWritebackCallback) (const GHashTable *resources,
-                                          gpointer          user_data);
+                                          gpointer          user_data)                            G_GNUC_DEPRECATED;
 
-GType          tracker_client_get_type                     (void) G_GNUC_CONST;
-GQuark         tracker_client_error_quark                  (void);
+GType          tracker_client_get_type                     (void) G_GNUC_CONST                    G_GNUC_DEPRECATED;
+GQuark         tracker_client_error_quark                  (void)                                 G_GNUC_DEPRECATED;
 TrackerClient *tracker_client_new                          (TrackerClientFlags      flags,
-                                                            gint                    timeout);
+                                                            gint                    timeout)      G_GNUC_DEPRECATED;
 
 gboolean       tracker_cancel_call                         (TrackerClient          *client,
-                                                            guint                   call_id);
-gboolean       tracker_cancel_last_call                    (TrackerClient          *client);
+                                                            guint                   call_id)      G_GNUC_DEPRECATED;
+gboolean       tracker_cancel_last_call                    (TrackerClient          *client)       G_GNUC_DEPRECATED;
 
 /* Utilities */
-gchar *        tracker_sparql_escape                       (const gchar            *str);
+gchar *        tracker_sparql_escape                       (const gchar            *str)          G_GNUC_DEPRECATED;
 
 gchar *        tracker_uri_vprintf_escaped                 (const gchar            *format,
-                                                            va_list                 args);
+                                                            va_list                 args)         G_GNUC_DEPRECATED;
 gchar *        tracker_uri_printf_escaped                  (const gchar            *format, 
-                                                            ...);
+                                                            ...)                                  G_GNUC_DEPRECATED;
 
 /* Synchronous API */
 GPtrArray *    tracker_statistics_get                      (TrackerClient          *client,
-                                                            GError                **error);
+                                                            GError                **error)        G_GNUC_DEPRECATED;
 void           tracker_resources_load                      (TrackerClient          *client,
                                                             const gchar            *uri,
-                                                            GError                **error);
+                                                            GError                **error)        G_GNUC_DEPRECATED;
 GPtrArray *    tracker_resources_sparql_query              (TrackerClient          *client,
                                                             const gchar            *query,
-                                                            GError                **error);
+                                                            GError                **error)        G_GNUC_DEPRECATED;
 TrackerResultIterator *
                tracker_resources_sparql_query_iterate      (TrackerClient          *client,
                                                             const gchar            *query,
-                                                            GError                **error);
-void           tracker_result_iterator_free                (TrackerResultIterator  *iterator);
-guint          tracker_result_iterator_n_columns           (TrackerResultIterator  *iterator);
-gboolean       tracker_result_iterator_next                (TrackerResultIterator  *iterator);
+                                                            GError                **error)        G_GNUC_DEPRECATED;
+void           tracker_result_iterator_free                (TrackerResultIterator  *iterator)     G_GNUC_DEPRECATED;
+guint          tracker_result_iterator_n_columns           (TrackerResultIterator  *iterator)     G_GNUC_DEPRECATED;
+gboolean       tracker_result_iterator_next                (TrackerResultIterator  *iterator)     G_GNUC_DEPRECATED;
 const gchar *  tracker_result_iterator_value               (TrackerResultIterator  *iterator,
-                                                            guint                   column);
+                                                            guint                   column)       G_GNUC_DEPRECATED;
 void           tracker_resources_sparql_update             (TrackerClient          *client,
                                                             const gchar            *query,
-                                                            GError                **error);
+                                                            GError                **error)        G_GNUC_DEPRECATED;
 GPtrArray *    tracker_resources_sparql_update_blank       (TrackerClient          *client,
                                                             const gchar            *query,
-                                                            GError                **error);
+                                                            GError                **error)        G_GNUC_DEPRECATED;
 void           tracker_resources_batch_sparql_update       (TrackerClient          *client,
                                                             const gchar            *query,
-                                                            GError                **error);
+                                                            GError                **error)        G_GNUC_DEPRECATED;
 void           tracker_resources_batch_commit              (TrackerClient          *client,
-                                                            GError                **error);
+                                                            GError                **error)        G_GNUC_DEPRECATED;
 /* Asynchronous API */
 guint          tracker_statistics_get_async                (TrackerClient          *client,
                                                             TrackerReplyGPtrArray   callback,
-                                                            gpointer                user_data);
+                                                            gpointer                user_data)    G_GNUC_DEPRECATED;
 guint          tracker_resources_load_async                (TrackerClient          *client,
                                                             const gchar            *uri,
                                                             TrackerReplyVoid        callback,
-                                                            gpointer                user_data);
+                                                            gpointer                user_data)    G_GNUC_DEPRECATED;
 guint          tracker_resources_sparql_query_async        (TrackerClient          *client,
                                                             const gchar            *query,
                                                             TrackerReplyGPtrArray   callback,
-                                                            gpointer                user_data);
+                                                            gpointer                user_data)    G_GNUC_DEPRECATED;
 guint         tracker_resources_sparql_query_iterate_async (TrackerClient          *client,
                                                             const gchar            *query,
                                                             TrackerReplyIterator    callback,
-                                                            gpointer                user_data);
+                                                            gpointer                user_data)    G_GNUC_DEPRECATED;
 guint          tracker_resources_sparql_update_async       (TrackerClient          *client,
                                                             const gchar            *query,
                                                             TrackerReplyVoid        callback,
-                                                            gpointer                user_data);
+                                                            gpointer                user_data)    G_GNUC_DEPRECATED;
 guint          tracker_resources_sparql_update_blank_async (TrackerClient          *client,
                                                             const gchar            *query,
                                                             TrackerReplyGPtrArray   callback,
-                                                            gpointer                user_data);
+                                                            gpointer                user_data)    G_GNUC_DEPRECATED;
 guint          tracker_resources_batch_sparql_update_async (TrackerClient          *client,
                                                             const gchar            *query,
                                                             TrackerReplyVoid        callback,
-                                                            gpointer                user_data);
+                                                            gpointer                user_data)    G_GNUC_DEPRECATED;
 guint          tracker_resources_batch_commit_async        (TrackerClient          *client,
                                                             TrackerReplyVoid        callback,
-                                                            gpointer                user_data);
+                                                            gpointer                user_data)    G_GNUC_DEPRECATED;
 
 /* Store signals */
 guint          tracker_resources_writeback_connect         (TrackerClient            *client,
                                                             TrackerWritebackCallback  callback,
-                                                            gpointer                  user_data);
+                                                            gpointer                  user_data)  G_GNUC_DEPRECATED;
 void           tracker_resources_writeback_disconnect      (TrackerClient            *client,
-                                                            guint handle);
+                                                            guint handle)                         G_GNUC_DEPRECATED;
 
-#ifndef TRACKER_DISABLE_DEPRECATED
+/*
+ * REALLY OLD and Deprecated APIs, since 0.6.x APIs
+ */
 
-/* Deprecated APIs */
 /**
  * TrackerReplyArray:
  * @result: a gchar ** with the results of the query.



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]