[tracker/data-provider-monitor-interface: 1/3] libtracker-miner: Added interface for monitor signals to TrackerDataProvider

[Martyn James Russell <mr src gnome org>]

commit fbe4cf3d74081a515c928136159b40283f75004e
Author: Martyn Russell <martyn lanedo com>
Date:   Mon Dec 22 14:45:20 2014 +0000

    libtracker-miner: Added interface for monitor signals to TrackerDataProvider

 src/libtracker-miner/tracker-data-provider.c |   11 ++++--
 src/libtracker-miner/tracker-data-provider.h |   49 +++++++++++++++++++++----
 src/libtracker-miner/tracker-enumerator.c    |    4 +-
 3 files changed, 51 insertions(+), 13 deletions(-)
---
diff --git a/src/libtracker-miner/tracker-data-provider.c b/src/libtracker-miner/tracker-data-provider.c
index f101f1b..b9fe97d 100644
--- a/src/libtracker-miner/tracker-data-provider.c
+++ b/src/libtracker-miner/tracker-data-provider.c
@@ -77,9 +77,14 @@ tracker_data_provider_default_init (TrackerDataProviderInterface *iface)
  * a wildcard like "standard::*" means all attributes in the standard
  * namespace. An example attribute query be "standard::*,owner::user".
  * The standard attributes are available as defines, like
- * G_FILE_ATTRIBUTE_STANDARD_NAME. See g_file_enumerate_children() for
+ * %G_FILE_ATTRIBUTE_STANDARD_NAME. See g_file_enumerate_children() for
  * more details.
  *
+ * The @flags provided will affect whether the @data_provider
+ * implementation should be setting up data monitors for changes under
+ * @url. Changes <emphasis>MUST NOT</emphasis> be signalled unless
+ * #TRACKER_DIRECTORY_FLAG_MONITOR is provided in @flags for @url.
+ *
  * Returns: (transfer full): a #TrackerEnumerator or %NULL on failure.
  * This must be freed with g_object_unref().
  *
@@ -139,10 +144,10 @@ tracker_data_provider_begin (TrackerDataProvider    *data_provider,
  * In case of a partial error the callback will be called with any
  * succeeding items and no error, and on the next request the error
  * will be reported. If a request is cancelled the callback will be
- * called with %G_IO_ERROR_CANCELLED.
+ * called with #G_IO_ERROR_CANCELLED.
  *
  * During an async request no other sync and async calls are allowed,
- * and will result in %G_IO_ERROR_PENDING errors.
+ * and will result in #G_IO_ERROR_PENDING errors.
  *
  * Any outstanding i/o request with higher priority (lower numerical
  * value) will be executed before an outstanding request with lower
diff --git a/src/libtracker-miner/tracker-data-provider.h b/src/libtracker-miner/tracker-data-provider.h
index 4b7a308..deab933 100644
--- a/src/libtracker-miner/tracker-data-provider.h
+++ b/src/libtracker-miner/tracker-data-provider.h
@@ -63,15 +63,35 @@ typedef struct _TrackerDataProviderIface TrackerDataProviderIface;
  * Completed using @end_finish.
  * @end_finish: Called when the data_provider is completing the
  * asynchronous operation provided by @end_async.
+ * @item_created: Signalled when an item is created in a monitored
+ * container. This can be another container or object itself. A
+ * container could be a directory and an object could be a file in
+ * a directory.
+ * @item_updated: Signalled when an item is updated, this includes
+ * both containers and objects. For example, the contents of an item
+ * have changed.
+ * @item_attribute_updated: Signalled when metadata changes are
+ * made to a container or object. Example of this would be include
+ * chmod, timestamps (utimensat), extended attributes (setxattr), link
+ * counts and user/group ID (chown) updates.
+ * @item_deleted: Signalled when a container or object is deleted.
+ * @item_moved: Signalled when a container or object is moved. The
+ * parameters provided give indication about what is known of source
+ * and target items.
  *
- * Virtual methods left to implement.
+ * Virtual methods to be implemented.
+ *
+ * The @item_created, @item_updated, @item_attribute_updated,
+ * @item_deleted and @item_moved signals <emphasis>MUST NOT</emphasis>
+ * be emitted unless the #TrackerDirectoryFlags used with the @begin
+ * and @begin_async APIs include #TRACKER_DIRECTORY_FLAG_MONITOR.
  **/
 struct _TrackerDataProviderIface {
        GTypeInterface g_iface;
 
        /* Virtual Table */
 
-       /* Start the data_provider for a given location, attributes and flags */
+       /* Crawling API - for container/object traversal */
        TrackerEnumerator *   (* begin)              (TrackerDataProvider    *data_provider,
                                                      GFile                  *url,
                                                      const gchar            *attributes,
@@ -90,7 +110,6 @@ struct _TrackerDataProviderIface {
                                                      GAsyncResult           *result,
                                                      GError                **error);
 
-       /* Close the given location */
        gboolean              (* end)                (TrackerDataProvider    *data_provider,
                                                      TrackerEnumerator      *enumerator,
                                                      GCancellable           *cancellable,
@@ -105,16 +124,30 @@ struct _TrackerDataProviderIface {
                                                      GAsyncResult           *result,
                                                      GError                **error);
 
+       /* Monitoring Signals - for container/object change notification */
+       void                  (* item_created)       (TrackerDataProvider    *data_provider,
+                                                     GFile                  *file,
+                                                     gboolean                is_container);
+       void                  (* item_updated)       (TrackerDataProvider    *data_provider,
+                                                     GFile                  *file,
+                                                     gboolean                is_container);
+       void                  (* item_attribute_updated)
+                                                     (TrackerDataProvider    *data_provider,
+                                                     GFile                  *file,
+                                                     gboolean                is_container);
+       void                  (* item_deleted)       (TrackerDataProvider    *data_provider,
+                                                     GFile                  *file,
+                                                     gboolean                is_container);
+       void                  (* item_moved)         (TrackerDataProvider    *data_provider,
+                                                     GFile                  *file,
+                                                     GFile                  *other_file,
+                                                     gboolean                is_container);
+
        /*< private >*/
        /* Padding for future expansion */
        void (*_tracker_reserved1) (void);
        void (*_tracker_reserved2) (void);
        void (*_tracker_reserved3) (void);
-       void (*_tracker_reserved4) (void);
-       void (*_tracker_reserved5) (void);
-       void (*_tracker_reserved6) (void);
-       void (*_tracker_reserved7) (void);
-       void (*_tracker_reserved8) (void);
 };
 
 GType              tracker_data_provider_get_type        (void) G_GNUC_CONST;
diff --git a/src/libtracker-miner/tracker-enumerator.c b/src/libtracker-miner/tracker-enumerator.c
index 1eddd8e..5a5f798 100644
--- a/src/libtracker-miner/tracker-enumerator.c
+++ b/src/libtracker-miner/tracker-enumerator.c
@@ -137,10 +137,10 @@ tracker_enumerator_next (TrackerEnumerator  *enumerator,
  * In case of a partial error the callback will be called with any
  * succeeding items and no error, and on the next request the error
  * will be reported. If a request is cancelled the callback will be
- * called with %G_IO_ERROR_CANCELLED.
+ * called with #G_IO_ERROR_CANCELLED.
  *
  * During an async request no other sync and async calls are allowed,
- * and will result in %G_IO_ERROR_PENDING errors.
+ * and will result in #G_IO_ERROR_PENDING errors.
  *
  * Any outstanding i/o request with higher priority (lower numerical
  * value) will be executed before an outstanding request with lower