Tracker Miner Library Reference Manual: TrackerMinerManager

## TrackerMinerManager TrackerMinerManager — External control and monitoring of miners |

## Synopsis

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

    #define             TRACKER_MINER_MANAGER_ERROR
    struct              TrackerMinerManager;
                        TrackerMinerManagerClass;
    enum                TrackerMinerManagerError;
    GQuark              tracker_miner_manager_error_quark   (void);
    GSList *            tracker_miner_manager_get_available (TrackerMinerManager *manager);
    const gchar *       tracker_miner_manager_get_description
                                                            (TrackerMinerManager *manager,
                                                             const gchar *miner);
    const gchar *       tracker_miner_manager_get_display_name
                                                            (TrackerMinerManager *manager,
                                                             const gchar *miner);
    GSList *            tracker_miner_manager_get_running   (TrackerMinerManager *manager);
    gboolean            tracker_miner_manager_get_status    (TrackerMinerManager *manager,
                                                             const gchar *miner,
                                                             gchar **status,
                                                             gdouble *progress,
                                                             gint *remaining_time);
    gboolean            tracker_miner_manager_ignore_next_update
                                                            (TrackerMinerManager *manager,
                                                             const gchar *miner,
                                                             const gchar **urls);
    gboolean            tracker_miner_manager_index_file    (TrackerMinerManager *manager,
                                                             GFile *file,
                                                             GError **error);
    void                tracker_miner_manager_index_file_async
                                                            (TrackerMinerManager *manager,
                                                             GFile *file,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tracker_miner_manager_index_file_finish
                                                            (TrackerMinerManager *manager,
                                                             GAsyncResult *result,
                                                             GError **error);
    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);
    TrackerMinerManager * tracker_miner_manager_new         (void);
    TrackerMinerManager * tracker_miner_manager_new_full    (gboolean auto_start,
                                                             GError **error);
    gboolean            tracker_miner_manager_pause         (TrackerMinerManager *manager,
                                                             const gchar *miner,
                                                             const gchar *reason,
                                                             guint32 *cookie);
    gboolean            tracker_miner_manager_pause_for_process
                                                            (TrackerMinerManager *manager,
                                                             const gchar *miner,
                                                             const gchar *reason,
                                                             guint32 *cookie);
    gboolean            tracker_miner_manager_reindex_by_mimetype
                                                            (TrackerMinerManager *manager,
                                                             const GStrv mimetypes,
                                                             GError **error);
    gboolean            tracker_miner_manager_resume        (TrackerMinerManager *manager,
                                                             const gchar *miner,
                                                             guint32 cookie);

## Object Hierarchy

      GObject
       +----TrackerMinerManager

## Implemented Interfaces

TrackerMinerManager implements GInitable.

## Properties

      "auto-start"               gboolean              : Read / Write / Construct Only

## 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

### TRACKER_MINER_MANAGER_ERROR

    #define TRACKER_MINER_MANAGER_ERROR tracker_miner_manager_error_quark ()

### struct TrackerMinerManager

    struct 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;

GObjectClass `parent_class`; |
`miner_progress` () | The progress signal for all miners including name, status and progress as a percentage between 0 and 1.
`miner_paused` () | The paused signal for all miners known about.
`miner_resumed` () | The resumed signal for all miners known about.
`miner_activated` () | The activated signal for all miners which indicates the miner is available on d-bus.
`miner_deactivated` () | The deactivate for all miners which indicates the miner is no longer available on d-bus.

### enum TrackerMinerManagerError

    typedef enum {
    	TRACKER_MINER_MANAGER_ERROR_NOT_AVAILABLE,
    	TRACKER_MINER_MANAGER_ERROR_NOENT
    } TrackerMinerManagerError;

Enumeration values used in errors returned by the TrackerMinerManager API.

`TRACKER_MINER_MANAGER_ERROR_NOT_AVAILABLE` | The miner in question is not active and can so can not be used.
`TRACKER_MINER_MANAGER_ERROR_NOENT` | The resource that the miner is handling (for example a file or URI) does not exist.

Since 0.8

### tracker_miner_manager_error_quark ()

    GQuark              tracker_miner_manager_error_quark   (void);

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

Since 0.8

### tracker_miner_manager_get_available ()

    GSList *            tracker_miner_manager_get_available (TrackerMinerManager *manager);

Returns a list of references for all available miners. Available miners are miners which may or may not be running in a process at the current time.

`manager` : | a TrackerMinerManager
Returns : | a GSList which must be freed with `g_slist_free()` and all contained data with `g_free()`. Otherwise `NULL` is returned if there are no miners. [transfer full][element-type utf8]

Since 0.8

### tracker_miner_manager_get_description ()

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

Returns the description for the given `miner`.

`manager` : | a TrackerMinerManager
`miner` : | miner reference
Returns : | A string which should not be freed or `NULL` if none is specified. [transfer none]

Since 0.8

### 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 : | A string which should not be freed or `NULL`. [transfer none]

Since 0.8

### tracker_miner_manager_get_running ()

    GSList *            tracker_miner_manager_get_running   (TrackerMinerManager *manager);

Returns a list of references for all active miners. Active miners are miners which are running within a process.

`manager` : | a trackerMinerManager
Returns : | a GSList which must be freed with `g_slist_free()` and all contained data with `g_free()`. Otherwise `NULL` is returned if there are no miners. [transfer full][element-type utf8]

Since 0.8

### tracker_miner_manager_get_status ()

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

Returns the current status, progress and remaining time for `miner`. `remaining_time` will be 0 if not possible to compute it yet, and less than zero if it is not applicable.

`manager` : | a TrackerMinerManager
`miner` : | miner reference
`status` : | return location for status. [out][allow-none]
`progress` : | return location for progress. [out][allow-none]
`remaining_time` : | return location for remaining time. [out][allow-none]
Returns : | `TRUE` if the status could be retrieved successfully, otherwise `FALSE`

Since 0.12

### tracker_miner_manager_ignore_next_update ()

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

### Warning

`tracker_miner_manager_ignore_next_update` is deprecated and should not be used in newly-written code. 0.12

Tells the `miner` to ignore any events for the next `urls`. This is used for cases where a file is updated by Tracker by the tracker-writeback service. This API is used to avoid signalling up the stack the changes to `urls`.

`manager` : | a TrackerMinerManager
`miner` : | miner reference
`urls` : | the subjects to ignore the next updates of. [in]
Returns : | `TRUE` on success, otherwise `FALSE`.

Since 0.8

### tracker_miner_manager_index_file ()

    gboolean            tracker_miner_manager_index_file    (TrackerMinerManager *manager,
                                                             GFile *file,
                                                             GError **error);

Tells the filesystem miner to index the `file`.

On failure `error` will be set.

`manager` : | a TrackerMinerManager
`file` : | a URL valid in GIO of a file to give to the miner for processing
`error` : | return location for errors. [out callee-allocates][transfer full][allow-none]
Returns : | `TRUE` on success, otherwise `FALSE`.

Since 0.10

### tracker_miner_manager_index_file_async ()

    void                tracker_miner_manager_index_file_async
                                                            (TrackerMinerManager *manager,
                                                             GFile *file,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Tells the filesystem miner to index the `file`. When the operation is called, `callback` will be called. You can then call `tracker_miner_manager_index_file_finish()` to get the result of the operation.

`manager` : | a TrackerMinerManager
`file` : | a URL valid in GIO of a file to give to the miner for processing
`cancellable` : | a GCancellable, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | the data to pass to the callback function

Since 0.16

### tracker_miner_manager_index_file_finish ()

    gboolean            tracker_miner_manager_index_file_finish
                                                            (TrackerMinerManager *manager,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes a request to index a file. See `tracker_miner_manager_index_file_async()`

On failure `error` will be set.

`manager` : | a TrackerMinerManager
`result` : | a GAsyncResult
`error` : | return location for errors. [out callee-allocates][transfer full][allow-none]
Returns : | `TRUE` on success, otherwise `FALSE`.

Since 0.16

### tracker_miner_manager_is_active ()

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

Returns the miner's current activity.

`manager` : | a TrackerMinerManager
`miner` : | miner reference
Returns : | `TRUE` if the `miner` is active, otherwise `FALSE`.

Since 0.8

### 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. [out callee-allocates][allow-none][transfer full]
`reasons` : | return location for pause reasons. [out callee-allocates][allow-none][transfer full]
Returns : | `TRUE` if `miner` is paused, otherwise `FALSE`.

Since 0.8

### tracker_miner_manager_new ()

    TrackerMinerManager * tracker_miner_manager_new         (void);

Creates a new TrackerMinerManager instance.

Note: Auto-starting miners when querying status will be enabled.

Returns : | a TrackerMinerManager or NULL if an error happened.

Since 0.8

### tracker_miner_manager_new_full ()

    TrackerMinerManager * tracker_miner_manager_new_full    (gboolean auto_start,
                                                             GError **error);

Creates a new TrackerMinerManager.

`auto_start` : | Flag to disable auto-starting the miners when querying status
`error` : | a GError to report errors.
Returns : | a TrackerMinerManager. On error, NULL is returned and `error` is set accordingly.

Since 0.10.5

### 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. [out][allow-none]
Returns : | `TRUE` if the miner was paused successfully, otherwise `FALSE`.

Since 0.8

### tracker_miner_manager_pause_for_process ()

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

This function operates exactly the same way as `tracker_miner_manager_pause()` with the exception that if the calling process dies, the pause is resumed. This API is useful for cases where the calling process has a risk of crashing without resuming the pause.

NOTE: If you call `g_object_unref()` on the `manager` before you intend to resume the pause and it finalizes, it will automatically resume.

`manager` : | a TrackerMinerManager.
`miner` : | miner reference
`reason` : | reason to pause
`cookie` : | return location for the pause cookie ID. [out][allow-none]
Returns : | `TRUE` if the miner was paused successfully, otherwise `FALSE`.

Since 0.10.15

### tracker_miner_manager_reindex_by_mimetype ()

    gboolean            tracker_miner_manager_reindex_by_mimetype
                                                            (TrackerMinerManager *manager,
                                                             const GStrv mimetypes,
                                                             GError **error);

Tells the filesystem miner to reindex any file with a mimetype in the `mimetypes` list.

On failure `error` will be set.

`manager` : | a TrackerMinerManager
`mimetypes` : | an array of mimetypes (E.G. "text/plain"). All items with a mimetype in that list will be reindexed. [in]
`error` : | return location for errors. [out callee-allocates][transfer full][allow-none]
Returns : | `TRUE` on success, otherwise `FALSE`.

Since 0.10

### 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, otherwise `FALSE`.

Since 0.8

## Property Details

### The `"auto-start"` property

      "auto-start"               gboolean              : Read / Write / Construct Only

If set, auto starts miners when querying their status.

Default value: TRUE

## 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.

Since 0.8

### 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.

Since 0.8

### 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.

Since 0.8

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

    void                user_function                      (TrackerMinerManager *manager,
                                                            gchar               *miner,
                                                            gchar               *status,
                                                            gdouble              progress,
                                                            gint                 remaining_time,
                                                            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
`remaining_time` : | remaining processing time
`user_data` : | user data set when the signal handler was connected.

Since 0.12

### 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.

Since 0.8