TrackerMinerManager: Tracker Control Library Reference Manual

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

## Functions

GQuark | tracker_miner_manager_error_quark ()
TrackerMinerManager * | tracker_miner_manager_new ()
TrackerMinerManager * | tracker_miner_manager_new_full ()
GSList * | tracker_miner_manager_get_running ()
GSList * | tracker_miner_manager_get_available ()
gboolean | tracker_miner_manager_pause ()
gboolean | tracker_miner_manager_pause_for_process ()
gboolean | tracker_miner_manager_resume ()
gboolean | tracker_miner_manager_is_active ()
gboolean | tracker_miner_manager_is_paused ()
gboolean | tracker_miner_manager_get_status ()
const gchar * | tracker_miner_manager_get_display_name ()
const gchar * | tracker_miner_manager_get_description ()
gboolean | tracker_miner_manager_reindex_by_mimetype ()
gboolean | tracker_miner_manager_index_file ()
void | tracker_miner_manager_index_file_async ()
gboolean | tracker_miner_manager_index_file_finish ()
gboolean | tracker_miner_manager_ignore_next_update ()

## Properties

gboolean | auto-start | Read / Write / Construct Only

## Signals

void | miner-activated | Run Last
void | miner-deactivated | Run Last
void | miner-paused | Run Last
void | miner-progress | Run Last
void | miner-resumed | Run Last

## Types and Values

#define | TRACKER_MINER_MANAGER_ERROR
enum | TrackerMinerManagerError
struct | TrackerMinerManager
| TrackerMinerManagerClass

## Object Hierarchy

        GObject
        ╰── TrackerMinerManager

## Implemented Interfaces

TrackerMinerManager implements GInitable.

## Includes

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

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

## Functions

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

#### Parameters

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

#### Parameters

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][nullable]

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.

#### Parameters

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][nullable]

Since: 0.8

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

#### Parameters

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.

#### Parameters

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

#### Parameters

manager | a TrackerMinerManager |
miner | miner reference |
cookie | pause cookie |

#### Returns

`TRUE` if the miner was successfully resumed, otherwise `FALSE`.

Since: 0.8

### tracker_miner_manager_is_active ()

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

Returns the miner's current activity.

#### Parameters

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.

#### Parameters

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

#### Parameters

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_get_display_name ()

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

Returns a translated display name for `miner` .

#### Parameters

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_description ()

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

Returns the description for the given `miner` .

#### Parameters

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

#### Parameters

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_index_file ()

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

Tells the filesystem miner to start indexing the `file` .

On failure `error` will be set.

#### Parameters

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 start indexing the `file` . Once the message has been sent, `callback` will be called. You can then call `tracker_miner_manager_index_file_finish()` to get the result.

#### Parameters

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.

#### Parameters

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_ignore_next_update ()

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

`tracker_miner_manager_ignore_next_update` has been deprecated since version 0.12 and should not be used in newly-written code.

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

#### Parameters

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

## Types and Values

### TRACKER_MINER_MANAGER_ERROR

    #define TRACKER_MINER_MANAGER_ERROR tracker_miner_manager_error_quark ()

### enum TrackerMinerManagerError

Enumeration values used in errors returned by the TrackerMinerManager API.

#### Members

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

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

#### Members

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

## Property Details

### The `“auto-start”` property

      “auto-start”               gboolean

If set, auto starts miners when querying their status.

Flags: Read / Write / Construct Only

Default value: TRUE

## Signal Details

### The `“miner-activated”` signal

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

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

#### Parameters

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

Flags: Run Last

Since: 0.8

### The `“miner-deactivated”` signal

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

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

#### Parameters

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

Flags: Run Last

Since: 0.8

### The `“miner-paused”` signal

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

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

#### Parameters

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

Flags: Run Last

Since: 0.8

### The `“miner-progress”` signal

    void
    user_function (TrackerMinerManager *manager,
                   gchar               *miner,
                   gchar               *status,
                   gdouble              progress,
                   gint                 remaining_time,
                   gpointer             user_data)

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

#### Parameters

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

Flags: Run Last

Since: 0.12

### The `“miner-resumed”` signal

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

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

#### Parameters

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

Flags: Run Last

Since: 0.8