TrackerMiner

TrackerMiner — Abstract base class for data miners

Functions

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

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