## tracker-miner-manager

tracker-miner-manager — External control and monitoring of miners

## Synopsis

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

                        TrackerMinerManager;
                        TrackerMinerManagerClass;
    TrackerMinerManager * tracker_miner_manager_new         (void);
    GSList *            tracker_miner_manager_get_running   (TrackerMinerManager *manager);
    GSList *            tracker_miner_manager_get_available (TrackerMinerManager *manager);
    gboolean            tracker_miner_manager_pause         (TrackerMinerManager *manager,
                                                             const gchar *miner,
                                                             const gchar *reason,
                                                             guint32 *cookie);
    gboolean            tracker_miner_manager_resume        (TrackerMinerManager *manager,
                                                             const gchar *miner,
                                                             guint32 cookie);
    gboolean            tracker_miner_manager_is_active     (TrackerMinerManager *manager,
                                                             const gchar *miner);
    gboolean            tracker_miner_manager_is_paused     (TrackerMinerManager *manager,
                                                             const gchar *miner,
                                                             GStrv *applications,
                                                             GStrv *reasons);
    gboolean            tracker_miner_manager_get_status    (TrackerMinerManager *manager,
                                                             const gchar *miner,
                                                             gchar **status,
                                                             gdouble *progress);
    gboolean            tracker_miner_manager_ignore_next_update
                                                            (TrackerMinerManager *manager,
                                                             const gchar *miner,
                                                             const gchar **urls);
    const gchar *       tracker_miner_manager_get_display_name
                                                            (TrackerMinerManager *manager,
                                                             const gchar *miner);
    const gchar *       tracker_miner_manager_get_description
                                                            (TrackerMinerManager *manager,
                                                             const gchar *miner);

## Object Hierarchy

      GObject
       +----TrackerMinerManager

## Signals

      "miner-activated"                                : Run Last
      "miner-deactivated"                              : Run Last
      "miner-paused"                                   : Run Last
      "miner-progress"                                 : Run Last
      "miner-resumed"                                  : Run Last

## Description

TrackerMinerManager keeps track of available miners, their current progress/status, and also allows basic external control on them, such as pausing or resuming data processing.

## Details

### TrackerMinerManager

    typedef struct _TrackerMinerManager TrackerMinerManager;

Object to query and control miners.

### TrackerMinerManagerClass

    typedef struct {
    	GObjectClass parent_class;

    	void (* miner_progress)    (TrackerMinerManager *manager,
    	                            const gchar         *miner_name,
    	                            const gchar         *status,
    	                            gdouble              progress);
    	void (* miner_paused)      (TrackerMinerManager *manager,
    	                            const gchar         *miner_name);
    	void (* miner_resumed)     (TrackerMinerManager *manager,
    	                            const gchar         *miner_name);
    	void (* miner_activated)   (TrackerMinerManager *manager,
    	                            const gchar         *miner_name);
    	void (* miner_deactivated) (TrackerMinerManager *manager,
    	                            const gchar         *miner_name);
    } TrackerMinerManagerClass;

TrackerMinerManager class.

### tracker_miner_manager_new ()

    TrackerMinerManager * tracker_miner_manager_new         (void);

Creates a new TrackerMinerManager instance.

Returns : | a TrackerMinerManager.

### tracker_miner_manager_get_running ()

    GSList *            tracker_miner_manager_get_running   (TrackerMinerManager *manager);

Returns a list of references for all active miners.

`manager` : | a trackerMinerManager
Returns : | a GSList of miner references. This list must be freed through `g_slist_free()`, and all contained data with `g_free()`.

### tracker_miner_manager_get_available ()

    GSList *            tracker_miner_manager_get_available (TrackerMinerManager *manager);

Returns a list of references for all available miners.

`manager` : | a TrackerMinerManager
Returns : | a GSList of miner references. This list must be freed through `g_slist_free()`, and all contained data with `g_free()`.

### tracker_miner_manager_pause ()

    gboolean            tracker_miner_manager_pause         (TrackerMinerManager *manager,
                                                             const gchar *miner,
                                                             const gchar *reason,
                                                             guint32 *cookie);

Asks `miner` to pause. a miner could be paused by several reasons, and its activity won't be resumed until all pause requests have been resumed.

`manager` : | a TrackerMinerManager.
`miner` : | miner reference
`reason` : | reason to pause
`cookie` : | return location for the pause cookie ID
Returns : | `TRUE` if the miner was paused successfully.

### tracker_miner_manager_resume ()

    gboolean            tracker_miner_manager_resume        (TrackerMinerManager *manager,
                                                             const gchar *miner,
                                                             guint32 cookie);

Tells `miner` to resume activity. The miner won't actually resume operations until all pause requests have been resumed.

`manager` : | a TrackerMinerManager
`miner` : | miner reference
`cookie` : | pause cookie
Returns : | `TRUE` if the miner was successfully resumed.

### tracker_miner_manager_is_active ()

    gboolean            tracker_miner_manager_is_active     (TrackerMinerManager *manager,
                                                             const gchar *miner);

Returns `TRUE` if `miner` is currently active.

`manager` : | a TrackerMinerManager
`miner` : | miner reference
Returns : | `TRUE` if `miner` is active.

### tracker_miner_manager_is_paused ()

    gboolean            tracker_miner_manager_is_paused     (TrackerMinerManager *manager,
                                                             const gchar *miner,
                                                             GStrv *applications,
                                                             GStrv *reasons);

This function either returns `FALSE` if the miner is not paused, or returns `TRUE` and fills in `applications` and `reasons` with the pause reasons and the applications that asked for it. Both arrays will have the same lengh, and will be sorted so the application/pause reason pairs have the same index.

`manager` : | a TrackerMinerManager
`miner` : | miner reference
`applications` : | return location for application names.
`reasons` : | return location for pause reasons.
Returns : | `TRUE` if `miner` is paused.

### tracker_miner_manager_get_status ()

    gboolean            tracker_miner_manager_get_status    (TrackerMinerManager *manager,
                                                             const gchar *miner,
                                                             gchar **status,
                                                             gdouble *progress);

Returns the current status and progress for `miner`.

`manager` : | a TrackerMinerManager
`miner` : | miner reference
`status` : | return location for status
`progress` : | return location for progress
Returns : | `TRUE` if the status could be retrieved successfully.

### tracker_miner_manager_ignore_next_update ()

    gboolean            tracker_miner_manager_ignore_next_update
                                                            (TrackerMinerManager *manager,
                                                             const gchar *miner,
                                                             const gchar **urls);

Asks `miner` to mark `subjects` as writeback

`manager` : | a TrackerMinerManager.
`miner` : | miner reference
`urls` : | subjects to mark as writeback
Returns : | `TRUE` if the miner was asked to ignore on next update successfully.

### tracker_miner_manager_get_display_name ()

    const gchar *       tracker_miner_manager_get_display_name
                                                            (TrackerMinerManager *manager,
                                                             const gchar *miner);

Returns a translated display name for `miner`.

`manager` : | a TrackerMinerManager
`miner` : | miner reference
Returns : | The miner display name.

### tracker_miner_manager_get_description ()

    const gchar *       tracker_miner_manager_get_description
                                                            (TrackerMinerManager *manager,
                                                             const gchar *miner);

Returns the description for `miner`, or `NULL` if none is specified.

`manager` : | a TrackerMinerManager
`miner` : | miner reference
Returns : | The miner description.

## Signal Details

### The `"miner-activated"` signal

    void                user_function                      (TrackerMinerManager *manager,
                                                            gchar               *miner,
                                                            gpointer             user_data)      : Run Last

The ::miner-activated signal will be emitted whenever a miner (referenced by `miner`) is activated (technically, this means the miner has appeared in the session bus).

`manager` : | the TrackerMinerManager
`miner` : | miner reference
`user_data` : | user data set when the signal handler was connected.

### The `"miner-deactivated"` signal

    void                user_function                      (TrackerMinerManager *manager,
                                                            gchar               *miner,
                                                            gpointer             user_data)      : Run Last

The ::miner-deactivated signal will be emitted whenever a miner (referenced by `miner`) is deactivated (technically, this means the miner has disappeared from the session bus).

`manager` : | the TrackerMinerManager
`miner` : | miner reference
`user_data` : | user data set when the signal handler was connected.

### The `"miner-paused"` signal

    void                user_function                      (TrackerMinerManager *manager,
                                                            gchar               *miner,
                                                            gpointer             user_data)      : Run Last

The ::miner-paused signal will be emitted whenever a miner (referenced by `miner`) is paused.

`manager` : | the TrackerMinerManager
`miner` : | miner reference
`user_data` : | user data set when the signal handler was connected.

### The `"miner-progress"` signal

    void                user_function                      (TrackerMinerManager *manager,
                                                            gchar               *miner,
                                                            gchar               *status,
                                                            gdouble              progress,
                                                            gpointer             user_data)      : Run Last

The ::miner-progress signal is meant to report status/progress changes in any tracked miner.

`manager` : | the TrackerMinerManager
`miner` : | miner reference
`status` : | miner status
`progress` : | miner progress, from 0 to 1
`user_data` : | user data set when the signal handler was connected.

### The `"miner-resumed"` signal

    void                user_function                      (TrackerMinerManager *manager,
                                                            gchar               *miner,
                                                            gpointer             user_data)      : Run Last

The ::miner-resumed signal will be emitted whenever a miner (referenced by `miner`) is resumed.

`manager` : | the TrackerMinerManager
`miner` : | miner reference
`user_data` : | user data set when the signal handler was connected.