TrackerMiner

TrackerMiner — Abstract base class for data miners

Synopsis

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

#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;
GQuark              tracker_miner_error_quark           (void);
void                tracker_miner_start                 (TrackerMiner *miner);
void                tracker_miner_stop                  (TrackerMiner *miner);
void                tracker_miner_ignore_next_update    (TrackerMiner *miner,
                                                         const GStrv urls);
gboolean            tracker_miner_is_started            (TrackerMiner *miner);
gboolean            tracker_miner_is_paused             (TrackerMiner *miner);
guint               tracker_miner_get_n_pause_reasons   (TrackerMiner *miner);
gint                tracker_miner_pause                 (TrackerMiner *miner,
                                                         const gchar *reason,
                                                         GError **error);
gboolean            tracker_miner_resume                (TrackerMiner *miner,
                                                         gint cookie,
                                                         GError **error);
TrackerSparqlConnection * tracker_miner_get_connection  (TrackerMiner *miner);
GDBusConnection *   tracker_miner_get_dbus_connection   (TrackerMiner *miner);
const gchar *       tracker_miner_get_dbus_full_name    (TrackerMiner *miner);
const gchar *       tracker_miner_get_dbus_full_path    (TrackerMiner *miner);

Object Hierarchy

  GObject
   +----TrackerMiner
         +----TrackerDecorator
         +----TrackerMinerFS
         +----TrackerMinerOnline

Implemented Interfaces

TrackerMiner implements GInitable.

Properties

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

Signals

  "ignore-next-update"                             : Run Last
  "paused"                                         : Run Last
  "progress"                                       : Run Last
  "resumed"                                        : Run Last
  "started"                                        : Run Last
  "stopped"                                        : Run Last

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

Details

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.

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

typedef enum {
	TRACKER_MINER_ERROR_NAME_MISSING,
	TRACKER_MINER_ERROR_NAME_UNAVAILABLE,
	TRACKER_MINER_ERROR_PAUSED,
	TRACKER_MINER_ERROR_PAUSED_ALREADY,
	TRACKER_MINER_ERROR_INVALID_COOKIE
} TrackerMinerError;

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

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.

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.

miner :

a TrackerMiner

Since 0.8


tracker_miner_stop ()

void                tracker_miner_stop                  (TrackerMiner *miner);

Tells the miner to stop processing data.

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.

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.

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.

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.

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.

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.

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

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

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

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

miner :

a TrackerMiner

Returns :

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

Since 0.10

Property Details

The "introspection-handler" property

  "introspection-handler"    gpointer              : Read / Write / Construct

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


The "introspection-xml" property

  "introspection-xml"        gchar*                : Read / Write / Construct

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

Default value: NULL


The "name" property

  "name"                     gchar*                : Read / Write / Construct Only

Miner name.

Default value: NULL


The "progress" property

  "progress"                 gdouble               : Read / Write / Construct

Miner progress.

Allowed values: [0,1]

Default value: 0


The "remaining-time" property

  "remaining-time"           gint                  : Read / Write / Construct

Estimated remaining time to finish processing.

Allowed values: >= -1

Default value: -1


The "status" property

  "status"                   gchar*                : Read / Write / Construct

Translatable string with status description.

Default value: "Idle"

Signal Details

The "ignore-next-update" signal

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

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

miner :

the TrackerMiner

urls :

the urls to mark as ignore on next update

user_data :

user data set when the signal handler was connected.

Since 0.8


The "paused" signal

void                user_function                      (TrackerMiner *miner,
                                                        gpointer      user_data)      : Run Last

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

miner :

the TrackerMiner

user_data :

user data set when the signal handler was connected.

Since 0.8


The "progress" signal

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

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.

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.

Since 0.12


The "resumed" signal

void                user_function                      (TrackerMiner *miner,
                                                        gpointer      user_data)      : Run Last

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

miner :

the TrackerMiner

user_data :

user data set when the signal handler was connected.

Since 0.8


The "started" signal

void                user_function                      (TrackerMiner *miner,
                                                        gpointer      user_data)      : Run Last

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

miner :

the TrackerMiner

user_data :

user data set when the signal handler was connected.

Since 0.8


The "stopped" signal

void                user_function                      (TrackerMiner *miner,
                                                        gpointer      user_data)      : Run Last

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

miner :

the TrackerMiner

user_data :

user data set when the signal handler was connected.

Since 0.8