TrackerMiner

## TrackerMiner TrackerMiner — Abstract base class for data miners |

## Synopsis

    #include <libtracker-miner/tracker-miner.h>

    #define             TRACKER_MINER_ERROR
    #define             TRACKER_MINER_ERROR_DOMAIN
    struct              TrackerMiner;
                        TrackerMinerClass;
    GQuark              tracker_miner_error_quark           (void);
    TrackerSparqlConnection * tracker_miner_get_connection  (TrackerMiner *miner);
    GDBusConnection *   tracker_miner_get_dbus_connection   (TrackerMiner *miner);
    const gchar *       tracker_miner_get_dbus_full_name    (TrackerMiner *miner);
    const gchar *       tracker_miner_get_dbus_full_path    (TrackerMiner *miner);
    guint               tracker_miner_get_n_pause_reasons   (TrackerMiner *miner);
    void                tracker_miner_ignore_next_update    (TrackerMiner *miner,
                                                             const GStrv urls);
    gboolean            tracker_miner_is_paused             (TrackerMiner *miner);
    gboolean            tracker_miner_is_started            (TrackerMiner *miner);
    gint                tracker_miner_pause                 (TrackerMiner *miner,
                                                             const gchar *reason,
                                                             GError **error);
    gboolean            tracker_miner_resume                (TrackerMiner *miner,
                                                             gint cookie,
                                                             GError **error);
    void                tracker_miner_start                 (TrackerMiner *miner);
    void                tracker_miner_stop                  (TrackerMiner *miner);

## Object Hierarchy

      GObject
       +----TrackerMiner
             +----TrackerMinerFS

## Implemented Interfaces

TrackerMiner implements GInitable.

## Properties

      "name"                     gchar*                : Read / Write / Construct Only
      "progress"                 gdouble               : Read / Write / Construct
      "remaining-time"           gint                  : Read / Write / Construct
      "status"                   gchar*                : Read / Write / Construct

## Signals

      "ignore-next-update"                             : Run Last
      "paused"                                         : Run Last
      "progress"                                       : Run Last
      "resumed"                                        : Run Last
      "started"                                        : Run Last
      "stopped"                                        : Run Last

## Description

TrackerMiner is an abstract base class to help developing data miners for tracker-store, being an abstract class it doesn't do much by itself, but provides the basic signaling and operation control so the miners implementing this class are properly recognized by Tracker, and can be controlled properly by external means such as TrackerMinerManager.

TrackerMiner implements the GInitable interface, and thus, all objects of types inheriting from TrackerMiner must be initialized with `g_initable_init()` just after creation (or directly created with `g_initable_new()`).

## Details

### TRACKER_MINER_ERROR

    #define TRACKER_MINER_ERROR        tracker_miner_error_quark()

### TRACKER_MINER_ERROR_DOMAIN

    #define TRACKER_MINER_ERROR_DOMAIN "TrackerMiner"

### struct TrackerMiner

    struct TrackerMiner;

Abstract miner object.

### TrackerMinerClass

    typedef struct {
    	GObjectClass parent_class;

    	/* signals */
    	void (* started)            (TrackerMiner *miner);
    	void (* stopped)            (TrackerMiner *miner);

    	void (* paused)             (TrackerMiner *miner);
    	void (* resumed)            (TrackerMiner *miner);

    	void (* progress)           (TrackerMiner *miner,
    	                             const gchar  *status,
    	                             gdouble       progress);

    	void (* ignore_next_update) (TrackerMiner *miner,
    	                             const GStrv   urls);
    } TrackerMinerClass;

Virtual methods left to implement.

GObjectClass `parent_class`; | parent object class.
`started` () | Called when the miner is told to start collecting data.
`stopped` () | Called when the miner is told to stop collecting data.
`paused` () | Called when the miner is told to pause.
`resumed` () | Called when the miner is told to resume activity.
`progress` () | progress.
`ignore_next_update` () | Called after ignore on next update event happens.

### tracker_miner_error_quark ()

    GQuark              tracker_miner_error_quark           (void);

Returns the GQuark used to identify miner errors in GError structures.

Returns : | the error GQuark

Since 0.8

### tracker_miner_get_connection ()

    TrackerSparqlConnection * tracker_miner_get_connection  (TrackerMiner *miner);

Gets the TrackerSparqlConnection initialized by `miner`

`miner` : | a TrackerMiner
Returns : | a TrackerSparqlConnection. [transfer none]

Since 0.10

### tracker_miner_get_dbus_connection ()

    GDBusConnection *   tracker_miner_get_dbus_connection   (TrackerMiner *miner);

Gets the GDBusConnection initialized by `miner`

`miner` : | a TrackerMiner
Returns : | a GDBusConnection. [transfer none]

Since 0.10

### tracker_miner_get_dbus_full_name ()

    const gchar *       tracker_miner_get_dbus_full_name    (TrackerMiner *miner);

Gets the DBus name registered by `miner`

`miner` : | a TrackerMiner
Returns : | a constant string which should not be modified by the caller.

Since 0.10

### tracker_miner_get_dbus_full_path ()

    const gchar *       tracker_miner_get_dbus_full_path    (TrackerMiner *miner);

Gets the DBus path registered by `miner`

`miner` : | a TrackerMiner
Returns : | a constant string which should not be modified by the caller.

Since 0.10

### tracker_miner_get_n_pause_reasons ()

    guint               tracker_miner_get_n_pause_reasons   (TrackerMiner *miner);

Returns the number of pause reasons holding `miner` from indexing contents.

`miner` : | a TrackerMiner
Returns : | The number of current pause reasons

Since 0.10.5

### tracker_miner_ignore_next_update ()

    void                tracker_miner_ignore_next_update    (TrackerMiner *miner,
                                                             const GStrv urls);

Tells the miner to mark `urls` are to ignore on next update.

`miner` : | a TrackerMiner
`urls` : | the urls to mark as to ignore on next update. [in]

Since 0.8

### tracker_miner_is_paused ()

    gboolean            tracker_miner_is_paused             (TrackerMiner *miner);

Returns TRUE if the miner is paused.

`miner` : | a TrackerMiner
Returns : | TRUE if the miner is paused.

Since 0.10

### tracker_miner_is_started ()

    gboolean            tracker_miner_is_started            (TrackerMiner *miner);

Returns TRUE if the miner has been started.

`miner` : | a TrackerMiner
Returns : | TRUE if the miner is already started.

Since 0.8

### tracker_miner_pause ()

    gint                tracker_miner_pause                 (TrackerMiner *miner,
                                                             const gchar *reason,
                                                             GError **error);

Asks `miner` to pause. On success the cookie ID is returned, this is what must be used in `tracker_miner_resume()` to resume operations. On failure `error` will be set and -1 will be returned.

`miner` : | a TrackerMiner
`reason` : | reason to pause
`error` : | return location for errors. [out callee-allocates][transfer full][allow-none]
Returns : | The pause cookie ID.

Since 0.8

### tracker_miner_resume ()

    gboolean            tracker_miner_resume                (TrackerMiner *miner,
                                                             gint cookie,
                                                             GError **error);

Asks the miner to resume processing. The cookie must be something returned by `tracker_miner_pause()`. The miner won't actually resume operations until all pause requests have been resumed.

`miner` : | a TrackerMiner
`cookie` : | pause cookie
`error` : | return location for errors. [out][transfer full][allow-none]
Returns : | TRUE if the cookie was valid.

Since 0.8

### tracker_miner_start ()

    void                tracker_miner_start                 (TrackerMiner *miner);

Tells the miner to start processing data.

`miner` : | a TrackerMiner

Since 0.8

### tracker_miner_stop ()

    void                tracker_miner_stop                  (TrackerMiner *miner);

Tells the miner to stop processing data.

`miner` : | a TrackerMiner

Since 0.8

## Property Details

### The `"name"` property

      "name"                     gchar*                : Read / Write / Construct Only

Miner name.

Default value: NULL

### The `"progress"` property

      "progress"                 gdouble               : Read / Write / Construct

Miner progress.

Allowed values: [0,1]

Default value: 0

### The `"remaining-time"` property

      "remaining-time"           gint                  : Read / Write / Construct

Estimated remaining time to finish processing.

Allowed values: >= G_MAXULONG

Default value: -1

### The `"status"` property

      "status"                   gchar*                : Read / Write / Construct

Translatable string with status description.

Default value: "Idle"

## Signal Details

### The `"ignore-next-update"` signal

    void                user_function                      (TrackerMiner *miner,
                                                            GStrv         urls,
                                                            gpointer      user_data)      : Run Last

the ::ignore-next-update signal is emitted in the miner right after it has been asked to mark `urls` as to ignore on next update through `tracker_miner_ignore_next_update()`.

`miner` : | the TrackerMiner
`urls` : | the urls to mark as ignore on next update
`user_data` : | user data set when the signal handler was connected.

Since 0.8

### The `"paused"` signal

    void                user_function                      (TrackerMiner *miner,
                                                            gpointer      user_data)      : Run Last

the ::paused signal is emitted whenever there is any reason to pause, either internal (through `tracker_miner_pause()`) or external (through DBus, see TrackerMinerManager).

`miner` : | the TrackerMiner
`user_data` : | user data set when the signal handler was connected.

Since 0.8

### The `"progress"` signal

    void                user_function                      (TrackerMiner *miner,
                                                            gchar        *status,
                                                            gdouble       progress,
                                                            gint          remaining_time,
                                                            gpointer      user_data)           : Run Last

the ::progress signal will be emitted by TrackerMiner implementations to indicate progress about the data mining process. `status` will contain a translated string with the current miner status and `progress` will indicate how much has been processed so far. `remaining_time` will give the number expected of seconds to finish processing, 0 if the value cannot be estimated, and -1 if its not applicable.

`miner` : | the TrackerMiner
`status` : | miner status
`progress` : | a gdouble indicating miner progress, from 0 to 1.
`remaining_time` : | a gint indicating the reamaining processing time, in seconds.
`user_data` : | user data set when the signal handler was connected.

Since 0.12

### The `"resumed"` signal

    void                user_function                      (TrackerMiner *miner,
                                                            gpointer      user_data)      : Run Last

the ::resumed signal is emitted whenever all reasons to pause have disappeared, see `tracker_miner_resume()` and TrackerMinerManager.

`miner` : | the TrackerMiner
`user_data` : | user data set when the signal handler was connected.

Since 0.8

### The `"started"` signal

    void                user_function                      (TrackerMiner *miner,
                                                            gpointer      user_data)      : Run Last

the ::started signal is emitted in the miner right after it has been started through `tracker_miner_start()`.

`miner` : | the TrackerMiner
`user_data` : | user data set when the signal handler was connected.

Since 0.8

### The `"stopped"` signal

    void                user_function                      (TrackerMiner *miner,
                                                            gpointer      user_data)      : Run Last

the ::stopped signal is emitted in the miner right after it has been stopped through `tracker_miner_stop()`.

`miner` : | the TrackerMiner
`user_data` : | user data set when the signal handler was connected.

Since 0.8