TrackerMiner: Tracker Miner Library Reference Manual

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

## Functions

GQuark | tracker_miner_error_quark ()
void | tracker_miner_start ()
void | tracker_miner_stop ()
void | tracker_miner_ignore_next_update ()
gboolean | tracker_miner_is_started ()
gboolean | tracker_miner_is_paused ()
guint | tracker_miner_get_n_pause_reasons ()
gint | tracker_miner_pause ()
gboolean | tracker_miner_resume ()
TrackerSparqlConnection * | tracker_miner_get_connection ()
GDBusConnection * | tracker_miner_get_dbus_connection ()
const gchar * | tracker_miner_get_dbus_full_name ()
const gchar * | tracker_miner_get_dbus_full_path ()

## Properties

gpointer | introspection-handler | Read / Write / Construct
gchar * | introspection-xml | Read / Write / Construct
gchar * | name | Read / Write / Construct Only
gdouble | progress | Read / Write / Construct
gint | remaining-time | Read / Write / Construct
gchar * | status | Read / Write / Construct

## Signals

void | ignore-next-update | Run Last
void | paused | Run Last
void | progress | Run Last
void | resumed | Run Last
void | started | Run Last
void | stopped | Run Last

## Types and Values

#define | TRACKER_MINER_DBUS_INTERFACE
#define | TRACKER_MINER_DBUS_NAME_PREFIX
#define | TRACKER_MINER_DBUS_PATH_PREFIX
#define | TRACKER_MINER_ERROR_DOMAIN
#define | TRACKER_MINER_ERROR
struct | TrackerMiner
| TrackerMinerClass
enum | TrackerMinerError

## Object Hierarchy

        GObject
        ╰── TrackerMiner
            ├── TrackerDecorator
            ├── TrackerMinerFS
            ╰── TrackerMinerOnline

## Implemented Interfaces

TrackerMiner implements GInitable.

## Includes

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

## 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()`).

## Functions

### tracker_miner_error_quark ()

    GQuark
    tracker_miner_error_quark (void);

Gives the caller the GQuark used to identify TrackerMiner errors in GError structures. The GQuark is used as the domain for the error.

#### Returns

the GQuark used for the domain of a GError.

Since: 0.8

### tracker_miner_start ()

    void
    tracker_miner_start (TrackerMiner *miner);

Tells the miner to start processing data.

#### Parameters

miner | a TrackerMiner |

Since: 0.8

### tracker_miner_stop ()

    void
    tracker_miner_stop (TrackerMiner *miner);

Tells the miner to stop processing data.

#### Parameters

miner | a TrackerMiner |

Since: 0.8

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

#### Parameters

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

Since: 0.8

### tracker_miner_is_started ()

    gboolean
    tracker_miner_is_started (TrackerMiner *miner);

Returns TRUE if the miner has been started.

#### Parameters

miner | a TrackerMiner |

#### Returns

TRUE if the miner is already started.

Since: 0.8

### tracker_miner_is_paused ()

    gboolean
    tracker_miner_is_paused (TrackerMiner *miner);

Returns TRUE if the miner is paused.

#### Parameters

miner | a TrackerMiner |

#### Returns

TRUE if the miner is paused.

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.

#### Parameters

miner | a TrackerMiner |

#### Returns

The number of current pause reasons

Since: 0.10.5

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

#### Parameters

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.

#### Parameters

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

    TrackerSparqlConnection *
    tracker_miner_get_connection (TrackerMiner *miner);

Gets the TrackerSparqlConnection initialized by `miner`

#### Parameters

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`

#### Parameters

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`

#### Parameters

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`

#### Parameters

miner | a TrackerMiner |

#### Returns

a constant string which should not be modified by the caller.

Since: 0.10

## Types and Values

### TRACKER_MINER_DBUS_INTERFACE

    #define TRACKER_MINER_DBUS_INTERFACE   "org.freedesktop.Tracker1.Miner"

The name of the D-Bus interface to use for all data miners that inter-operate with Tracker.

Since: 0.8.

### TRACKER_MINER_DBUS_NAME_PREFIX

    #define TRACKER_MINER_DBUS_NAME_PREFIX "org.freedesktop.Tracker1.Miner."

D-Bus name prefix to use for all data miners. This allows custom miners to be written using `TRACKER_MINER_DBUS_NAME_PREFIX` + "Files" for example and would show up on D-Bus under "org.freedesktop.Tracker1.Miner.Files".

Since: 0.8.

### TRACKER_MINER_DBUS_PATH_PREFIX

    #define TRACKER_MINER_DBUS_PATH_PREFIX "/org/freedesktop/Tracker1/Miner/"

D-Bus path prefix to use for all data miners. This allows custom miners to be written using `TRACKER_MINER_DBUS_PATH_PREFIX` + "Files" for example and would show up on D-Bus under "/org/freedesktop/Tracker1/Miner/Files".

Since: 0.8.

### TRACKER_MINER_ERROR_DOMAIN

    #define TRACKER_MINER_ERROR_DOMAIN "TrackerMiner"

Used as the domain for any GErrors reported by `TrackerMiner` objects.

Since: 0.8.

### TRACKER_MINER_ERROR

    #define TRACKER_MINER_ERROR        tracker_miner_error_quark()

Returns the `GQuark` used for GErrors and for `TrackerMiner` implementations. This calls `tracker_miner_error_quark()`.

Since: 0.8.

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

    	/* <Private> */
    	gpointer padding[10];
    } TrackerMinerClass;

Virtual methods left to implement.

#### Members

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. |
gpointer `padding`[10]; | Reserved for future API improvements. |

### enum TrackerMinerError

Possible errors returned when calling TrackerMiner APIs or subclassed miners where the error is generic to all miners.

#### Members

TRACKER_MINER_ERROR_NAME_MISSING | No name was given when creating the miner. The name is crucial for D-Bus presence and a host of other things. |
TRACKER_MINER_ERROR_NAME_UNAVAILABLE | The name trying to be used for the miner was not available, possibly because the miner is already running with the same name in another process. |
TRACKER_MINER_ERROR_PAUSED | Given by miners when an API is used at the time the miner itself is paused and such actions should be avoided. |
TRACKER_MINER_ERROR_PAUSED_ALREADY | The pause request has already been given by the same application with the same reason. Duplicate pause calls with the same reason by the same application can not be carried out. |
TRACKER_MINER_ERROR_INVALID_COOKIE | When pausing a miner, a cookie (or `gint` based ID) is given. That cookie must be used to resume a previous pause request. If the cookie is unrecognised, this error is given. |

## Property Details

### The `“introspection-handler”` property

      “introspection-handler”    gpointer

Introspection Method Handler function, expected to be a pointer to GDBusInterfaceVTable.

Flags: Read / Write / Construct

### The `“introspection-xml”` property

      “introspection-xml”        gchar *

Introspection XML to *append* to the standard miner interface provided.

Flags: Read / Write / Construct

Default value: NULL

### The `“name”` property

      “name”                     gchar *

Miner name.

Flags: Read / Write / Construct Only

Default value: NULL

### The `“progress”` property

      “progress”                 gdouble

Miner progress.

Flags: Read / Write / Construct

Allowed values: [0,1]

Default value: 0

### The `“remaining-time”` property

      “remaining-time”           gint

Estimated remaining time to finish processing.

Flags: Read / Write / Construct

Allowed values: >= -1

Default value: -1

### The `“status”` property

      “status”                   gchar *

Translatable string with status description.

Flags: Read / Write / Construct

Default value: "Idle"

## Signal Details

### The `“ignore-next-update”` signal

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

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

#### Parameters

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

Flags: Run Last

Since: 0.8

### The `“paused”` signal

    void
    user_function (TrackerMiner *miner,
                   gpointer      user_data)

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

#### Parameters

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

Flags: Run Last

Since: 0.8

### The `“progress”` signal

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

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.

#### Parameters

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

Flags: Run Last

Since: 0.12

### The `“resumed”` signal

    void
    user_function (TrackerMiner *miner,
                   gpointer      user_data)

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

#### Parameters

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

Flags: Run Last

Since: 0.8

### The `“started”` signal

    void
    user_function (TrackerMiner *miner,
                   gpointer      user_data)

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

#### Parameters

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

Flags: Run Last

Since: 0.8

### The `“stopped”` signal

    void
    user_function (TrackerMiner *miner,
                   gpointer      user_data)

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

#### Parameters

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

Flags: Run Last

Since: 0.8