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_index_file_for_process ()
void | tracker_miner_manager_index_file_for_process_async ()
gboolean | tracker_miner_manager_index_file_for_process_finish ()

## Properties

gboolean | auto-start | Read / Write / Construct Only
gchar * | domain-ontology | 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,
                                      GCancellable *cancellable,
                                      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 |
cancellable | a GCancellable, or `NULL`. | [allow-none]
error | return location for errors. | [out callee-allocates][transfer full][allow-none]

#### Returns

`TRUE` on success, otherwise `FALSE`.

Since: 2.0

### 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_index_file_for_process ()

    gboolean
    tracker_miner_manager_index_file_for_process
                                   (TrackerMinerManager *manager,
                                    GFile *file,
                                    GCancellable *cancellable,
                                    GError **error);

This function operates exactly the same way as `tracker_miner_manager_index_file()` with the exception that if the calling process dies, the indexing is cancelled. This API is useful for cases where the calling process wants to tie the indexing operation closely to its own lifetime.

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 |
cancellable | a GCancellable, or `NULL`. | [allow-none]
error | return location for errors. | [out callee-allocates][transfer full][allow-none]

#### Returns

`TRUE` on success, otherwise `FALSE`.

Since: 1.10

### tracker_miner_manager_index_file_for_process_async ()

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

This function operates exactly the same way as `tracker_miner_manager_index_file()` with the exception that if the calling process dies, the indexing is cancelled. This API is useful for cases where the calling process wants to tie the indexing operation closely to its own lifetime.

When the operation is finished, `callback` will be called. You can then call `tracker_miner_manager_index_file_for_process_finish()` to get the result of the operation.

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

### tracker_miner_manager_index_file_for_process_finish ()

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

Finishes a request to index a file. See `tracker_miner_manager_index_file_for_process_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: 1.10

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

`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

### The `“domain-ontology”` property

      “domain-ontology”          gchar *

The domain ontology this object controls.

Flags: Read / Write / Construct Only

Default value: NULL

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