[tracker/external-crawler: 8/31] libtracker-miner: Miner now uses a proper MinerError API

[Martyn James Russell <mr src gnome org>]

commit 956ad8bcc623b80a2f33c381c3a8618239763e84
Author: Martyn Russell <martyn lanedo com>
Date:   Wed May 7 12:15:44 2014 +0100

    libtracker-miner: Miner now uses a proper MinerError API
    
    Previously, the error code was always 0. Now we have an enum people can refer
    to.
    
    This is particularly important for miner implementations and cases where
    classes want to return an error due to an API being used *while* being paused.
    This is the case in TrackerMinerFS.

 src/libtracker-miner/tracker-miner-fs.c     |   41 ++++++++++++++++++++---
 src/libtracker-miner/tracker-miner-fs.h     |   13 ++++++--
 src/libtracker-miner/tracker-miner-object.c |   47 ++++++++++++--------------
 src/libtracker-miner/tracker-miner-object.h |   31 +++++++++++++++++
 4 files changed, 99 insertions(+), 33 deletions(-)
---
diff --git a/src/libtracker-miner/tracker-miner-fs.c b/src/libtracker-miner/tracker-miner-fs.c
index 40bb2bf..9e1e9fb 100644
--- a/src/libtracker-miner/tracker-miner-fs.c
+++ b/src/libtracker-miner/tracker-miner-fs.c
@@ -3943,20 +3943,51 @@ tracker_miner_fs_get_indexing_tree (TrackerMinerFS *fs)
  * tracker_miner_fs_manually_notify_file:
  * @fs: a #TrackerMinerFS
  * @file: a #GFile
+ * @error: a #GError
  *
- * Returns: %TRUE if successful, %FALSE otherwise.
+ * This API is only useful where the @fs was created using the
+ * #TrackerMinerFS:external-crawler property set to %TRUE. By default
+ * this is %FALSE. This allows 3rd party developers to 'push' their
+ * data into Tracker to be processed, rather than requiring Tracker to
+ * index the content itself by crawling the file system and monitoring
+ * changes.
+ *
+ * This is also very helpful for cases where @file is not based on the
+ * local file system (for example a cloud implementation) and you want
+ * to tell Tracker about content to index more directly.
+ *
+ * Returns: %TRUE if successful, otherwise %FALSE and @error will be
+ * set if a pointer is supplied.
  *
  * Since: 1.2.
  **/
 gboolean
-tracker_miner_fs_manually_notify_file (TrackerMinerFS *fs,
-                                       GFile          *file)
+tracker_miner_fs_manually_notify_file (TrackerMinerFS  *fs,
+                                       GFile           *file,
+                                       GError         **error)
 {
+       TrackerMinerFSPrivate *priv;
+
        g_return_val_if_fail (TRACKER_IS_MINER_FS (fs), FALSE);
        g_return_val_if_fail (G_IS_FILE (file), FALSE);
 
-       /* FIXME: Add checks to disable this API unless crawling is disabled. */
-       /* FIXME: Add checks for paused, etc. */
+       priv = fs->priv;
+
+       if (!priv->external_crawler) {
+               g_set_error (error,
+                            tracker_miner_fs_error_quark (),
+                            TRACKER_MINER_FS_ERROR_HAVE_CRAWLER,
+                            "API can not be used with the internal crawler provided by Tracker");
+               return FALSE;
+       }
+
+       if (!priv->external_crawler) {
+               g_set_error (error,
+                            tracker_miner_error_quark (),
+                            TRACKER_MINER_ERROR_PAUSED,
+                            "API can not be used when paused");
+               return FALSE;
+       }
 
        /* FIXME: We need to know if this was created, updated, etc. */
        return tracker_file_notifier_add_file (fs->priv->file_notifier, file);
diff --git a/src/libtracker-miner/tracker-miner-fs.h b/src/libtracker-miner/tracker-miner-fs.h
index e907553..54c53ca 100644
--- a/src/libtracker-miner/tracker-miner-fs.h
+++ b/src/libtracker-miner/tracker-miner-fs.h
@@ -102,6 +102,11 @@ typedef struct {
  * @TRACKER_MINER_FS_ERROR_INIT: There was an error during
  * initialization of the object. The specific details are in the
  * message.
+ * @TRACKER_MINER_FS_ERROR_HAVE_CRAWLER: This error is given when
+ * trying to use an API that is only useful when
+ * #TrackerMinerFS:external-crawler is set to %TRUE. By default it is
+ * set to %FALSE. An example of such API is the
+ * tracker_miner_fs_manually_notify_file().
  *
  * Possible errors returned when calling creating new objects based on
  * the #TrackerMinerFS type and other APIs available with this class.
@@ -109,7 +114,8 @@ typedef struct {
  * Since: 1.2.
  **/
 typedef enum {
-       TRACKER_MINER_FS_ERROR_INIT
+       TRACKER_MINER_FS_ERROR_INIT,
+       TRACKER_MINER_FS_ERROR_HAVE_CRAWLER,
 } TrackerMinerFSError;
 
 
@@ -173,8 +179,9 @@ void                  tracker_miner_fs_force_mtime_checking (TrackerMinerFS *fs,
                                                              GFile          *directory);
 
 TrackerIndexingTree * tracker_miner_fs_get_indexing_tree    (TrackerMinerFS *fs);
-gboolean tracker_miner_fs_manually_notify_file (TrackerMinerFS *fs,
-                                                GFile          *file);
+gboolean tracker_miner_fs_manually_notify_file (TrackerMinerFS  *fs,
+                                                GFile           *file,
+                                                GError         **error);
 
 G_END_DECLS
 
diff --git a/src/libtracker-miner/tracker-miner-object.c b/src/libtracker-miner/tracker-miner-object.c
index 8889887..61f15ed 100644
--- a/src/libtracker-miner/tracker-miner-object.c
+++ b/src/libtracker-miner/tracker-miner-object.c
@@ -65,8 +65,6 @@
 
 #define TRACKER_MINER_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), TRACKER_TYPE_MINER, 
TrackerMinerPrivate))
 
-static GQuark miner_error_quark = 0;
-
 /* Introspection data for the service we are exporting */
 static const gchar introspection_xml[] =
   "<node>"
@@ -207,6 +205,18 @@ static void       on_tracker_store_disappeared (GDBusConnection        *connecti
                                                 const gchar            *name,
                                                 gpointer                user_data);
 
+/**
+ * tracker_miner_error_quark:
+ *
+ * Gives the caller the #GQuark used to identify miner errors in
+ * GError structures.
+ *
+ * Returns: the error #GQuark
+ *
+ * Since: 0.8
+ **/
+G_DEFINE_QUARK (TrackerMinerError, tracker_miner_error)
+
 G_DEFINE_ABSTRACT_TYPE_WITH_CODE (TrackerMiner, tracker_miner, G_TYPE_OBJECT,
                                   G_IMPLEMENT_INTERFACE (G_TYPE_INITABLE,
                                                          miner_initable_iface_init));
@@ -378,8 +388,6 @@ tracker_miner_class_init (TrackerMinerClass *klass)
                                                           G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
 
        g_type_class_add_private (object_class, sizeof (TrackerMinerPrivate));
-
-       miner_error_quark = g_quark_from_static_string ("TrackerMiner");
 }
 
 static void
@@ -427,8 +435,8 @@ miner_initable_init (GInitable     *initable,
        /* Check miner has a proper name */
        if (!miner->priv->name) {
                g_set_error (error,
-                            TRACKER_MINER_ERROR,
-                            0,
+                            tracker_miner_error_quark (),
+                            TRACKER_MINER_ERROR_NAME_MISSING,
                             "Miner '%s' should have been given a name, bailing out",
                             G_OBJECT_TYPE_NAME (miner));
                return FALSE;
@@ -488,8 +496,8 @@ miner_initable_init (GInitable     *initable,
 
        if (rval != 1 /* DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER */) {
                g_set_error (error,
-                            TRACKER_MINER_ERROR,
-                            0,
+                            tracker_miner_error_quark (),
+                            TRACKER_MINER_ERROR_NAME_UNAVAILABLE,
                             "D-Bus service name:'%s' is already taken, "
                             "perhaps the application is already running?",
                             miner->priv->full_name);
@@ -747,21 +755,6 @@ pause_data_destroy (gpointer data)
 }
 
 /**
- * tracker_miner_error_quark:
- *
- * Returns the #GQuark used to identify miner errors in GError structures.
- *
- * Returns: the error #GQuark
- *
- * Since: 0.8
- **/
-GQuark
-tracker_miner_error_quark (void)
-{
-       return g_quark_from_static_string (TRACKER_MINER_ERROR_DOMAIN);
-}
-
-/**
  * tracker_miner_start:
  * @miner: a #TrackerMiner
  *
@@ -953,7 +946,9 @@ miner_pause_internal (TrackerMiner  *miner,
                if (g_strcmp0 (application, pd->application) == 0 &&
                    g_strcmp0 (reason, pd->reason) == 0) {
                        /* Can't use duplicate pauses */
-                       g_set_error_literal (error, TRACKER_MINER_ERROR, 0,
+                       g_set_error_literal (error,
+                                            tracker_miner_error_quark (),
+                                            TRACKER_MINER_ERROR_PAUSED_ALREADY,
                                             _("Pause application and reason match an already existing pause 
request"));
                        return -1;
                }
@@ -1050,7 +1045,9 @@ tracker_miner_resume (TrackerMiner  *miner,
        g_return_val_if_fail (TRACKER_IS_MINER (miner), FALSE);
 
        if (!g_hash_table_remove (miner->priv->pauses, GINT_TO_POINTER (cookie))) {
-               g_set_error_literal (error, TRACKER_MINER_ERROR, 0,
+               g_set_error_literal (error,
+                                    tracker_miner_error_quark (),
+                                    TRACKER_MINER_ERROR_INVALID_COOKIE,
                                     _("Cookie not recognized to resume paused miner"));
                return FALSE;
        }
diff --git a/src/libtracker-miner/tracker-miner-object.h b/src/libtracker-miner/tracker-miner-object.h
index 7fa9e70..a85786e 100644
--- a/src/libtracker-miner/tracker-miner-object.h
+++ b/src/libtracker-miner/tracker-miner-object.h
@@ -88,6 +88,37 @@ typedef struct {
        gpointer padding[10];
 } TrackerMinerClass;
 
+/**
+ * TrackerMinerError:
+ * @TRACKER_MINER_ERROR_NAME_MISSING: No name was given when creating
+ * the miner. The name is crucial for D-Bus presence and a host of
+ * other things.
+ * @TRACKER_MINER_ERROR_NAME_UNAVAILABLE: The name trying to be used
+ * for the miner was not available, possibly because the miner is
+ * already running with the same name in another process.
+ * @TRACKER_MINER_ERROR_PAUSED: Given by miners when an API is used at
+ * the time the miner itself is paused and such actions should be avoided.
+ * @TRACKER_MINER_ERROR_PAUSED_ALREADY: The pause request has already
+ * been given by the same application with the same reason. Duplicate
+ * pause calls with the same reason by the same application can not
+ * be carried out.
+ * @TRACKER_MINER_ERROR_INVALID_COOKIE: When pausing a miner, a cookie
+ * (or @gint based ID) is given. That cookie must be used to resume a
+ * previous pause request. If the cookie is unrecognised, this error
+ * is given.
+ *
+ * Possible errors returned when calling #TrackerMiner APIs or
+ * subclassed miners where the error is generic to all miners.
+ **/
+typedef enum {
+       TRACKER_MINER_ERROR_NAME_MISSING,
+       TRACKER_MINER_ERROR_NAME_UNAVAILABLE,
+       TRACKER_MINER_ERROR_PAUSED,
+       TRACKER_MINER_ERROR_PAUSED_ALREADY,
+       TRACKER_MINER_ERROR_INVALID_COOKIE
+} TrackerMinerError;
+
+
 GType                    tracker_miner_get_type            (void) G_GNUC_CONST;
 GQuark                   tracker_miner_error_quark         (void);