TrackerMiner

TrackerMiner — Abstract base class for data miners

Synopsis

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

#define             TRACKER_MINER_ERROR_DOMAIN
#define             TRACKER_MINER_ERROR
typedef             TrackerMinerPrivate;
typedef             TrackerMiner;
                    TrackerMinerClass;
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);
gint                tracker_miner_pause                 (TrackerMiner *miner,
                                                         const gchar *reason,
                                                         GError **error);
gboolean            tracker_miner_resume                (TrackerMiner *miner,
                                                         gint cookie,
                                                         GError **error);
void                tracker_miner_execute_update        (TrackerMiner *miner,
                                                         const gchar *sparql,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
void                tracker_miner_execute_update_finish (TrackerMiner *miner,
                                                         GAsyncResult *result,
                                                         GError **error);
void                tracker_miner_execute_sparql        (TrackerMiner *miner,
                                                         const gchar *sparql,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
const GPtrArray*    tracker_miner_execute_sparql_finish (TrackerMiner *miner,
                                                         GAsyncResult *result,
                                                         GError **error);
void                tracker_miner_execute_batch_update  (TrackerMiner *miner,
                                                         const gchar *sparql,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
void                tracker_miner_execute_batch_update_finish
                                                        (TrackerMiner *miner,
                                                         GAsyncResult *result,
                                                         GError **error);
void                tracker_miner_commit                (TrackerMiner *miner,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
void                tracker_miner_commit_finish         (TrackerMiner *miner,
                                                         GAsyncResult *result,
                                                         GError **error);

Object Hierarchy

  GObject
   +----TrackerMiner
         +----TrackerMinerFS

Properties

  "name"                     gchar*                : Read / Write / Construct Only
  "progress"                 gdouble               : Read / Write / Construct
  "status"                   gchar*                : Read / Write

Signals

  "error"                                          : Run Last
  "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.

Details

TRACKER_MINER_ERROR_DOMAIN

#define TRACKER_MINER_ERROR_DOMAIN "TrackerMiner"

TRACKER_MINER_ERROR

#define TRACKER_MINER_ERROR        tracker_miner_error_quark()

TrackerMinerPrivate

typedef struct TrackerMinerPrivate TrackerMinerPrivate;

TrackerMiner

typedef struct TrackerMiner 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 (* error)              (TrackerMiner *miner,
	                             GError       *error);

	void (* ignore_next_update) (TrackerMiner *miner,
	                             const GStrv   urls);
} 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.

error ()

 error.

ignore_next_update ()

 Called after ignore on next update event happens.

tracker_miner_error_quark ()

GQuark              tracker_miner_error_quark           (void);

Returns the GQuark used to identify miner errors in GError structures.

Returns :

 the error GQuark

tracker_miner_start ()

void                tracker_miner_start                 (TrackerMiner *miner);

Tells the miner to start processing data.

miner :

 a TrackerMiner

tracker_miner_stop ()

void                tracker_miner_stop                  (TrackerMiner *miner);

Tells the miner to stop processing data.

miner :

 a TrackerMiner

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

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.

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

Returns :

 The pause cookie ID.

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

Returns :

 TRUE if the cookie was valid.

tracker_miner_execute_update ()

void                tracker_miner_execute_update        (TrackerMiner *miner,
                                                         const gchar *sparql,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Executes an update SPARQL query on tracker-store, use this whenever you want to perform data insertions or modifications.

When the operation is finished, callback will be called, providing a GAsyncResult object. Call tracker_miner_execute_sparql_finish on it to get the returned GError, if there is one.

If the operation is cancelled, callback will be called anyway, with the GAsyncResult object containing an error.

miner :

 a TrackerMiner

sparql :

 a SPARQL query

cancellable :

 a GCancellable to control the operation

callback :

 a GAsyncReadyCallback to call when the operation is finished

user_data :

 data to pass to callback

tracker_miner_execute_update_finish ()

void                tracker_miner_execute_update_finish (TrackerMiner *miner,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the async update operation. If an error occured during the update, error will be set.

miner :

 a TrackerMiner

result :

 a GAsyncResult

error :

 a GError

tracker_miner_execute_sparql ()

void                tracker_miner_execute_sparql        (TrackerMiner *miner,
                                                         const gchar *sparql,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Executes the SPARQL query on tracker-store and returns asynchronously the queried data. Use this whenever you need to get data from already stored information.

When the operation is finished, callback will be called, providing a GAsyncResult object. Call tracker_miner_execute_sparql_finish on it to get the query results, or the GError object if an error occured.

If the operation is cancelled, callback will be called anyway, with the GAsyncResult object containing an error.

miner :

 a TrackerMiner

sparql :

 a SPARQL query

cancellable :

 a GCancellable to control the operation

callback :

 a GAsyncReadyCallback to call when the operation is finished

user_data :

 data to pass to callback

tracker_miner_execute_sparql_finish ()

const GPtrArray*    tracker_miner_execute_sparql_finish (TrackerMiner *miner,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the async operation and returns the query results. If an error occured during the query, error will be set.

miner :

 a TrackerMiner

result :

 a GAsyncResult object holding the result of the query

error :

 a GError

Returns :

 a GPtrArray with the sparql results which should not be freed.

tracker_miner_execute_batch_update ()

void                tracker_miner_execute_batch_update  (TrackerMiner *miner,
                                                         const gchar *sparql,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Executes a batch of update SPARQL queries on tracker-store, use this whenever you want to perform data insertions or modifications in batches.

When the operation is finished, callback will be called, providing a GAsyncResult object. Call tracker_miner_execute_batch_update_finish on it to get the returned GError, if there is one.

If the operation is cancelled, callback will be called anyway, with the GAsyncResult object containing an error.

miner :

 a TrackerMiner

sparql :

 a set of SPARQL updates

cancellable :

 a GCancellable to control the operation

callback :

 a GAsyncReadyCallback to call when the operation is finished

user_data :

 data to pass to callback

tracker_miner_execute_batch_update_finish ()

void                tracker_miner_execute_batch_update_finish
                                                        (TrackerMiner *miner,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the async batch update operation. If an error occured during the update, error will be set.

miner :

 a TrackerMiner

result :

 a GAsyncResult

error :

 a GError

tracker_miner_commit ()

void                tracker_miner_commit                (TrackerMiner *miner,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Commits all pending batch updates. See tracker_miner_execute_batch_update().

When the operation is finished, callback will be called, providing a GAsyncResult object. Call tracker_miner_commit_finish on it to get the returned GError, if there is one.

If the operation is cancelled, callback will be called anyway, with the GAsyncResult object containing an error.

miner :

 a TrackerMiner

cancellable :

 a GCancellable to control the operation

callback :

 a GAsyncReadyCallback to call when the operation is finished

user_data :

 data to pass to callback

tracker_miner_commit_finish ()

void                tracker_miner_commit_finish         (TrackerMiner *miner,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the async comit operation. If an error occured during the commit, error will be set.

miner :

 a TrackerMiner

result :

 a GAsyncResult

error :

 a GError

Property Details

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 "status" property

  "status"                   gchar*                : Read / Write

Translatable string with status description.

Default value: NULL

Signal Details

The "error" signal

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

The ::error signal will be emitted by TrackerMiner implementations to indicate some error in the data mining process.

miner :

 the TrackerMiner

error :

 the error that happened

user_data :

 user data set when the signal handler was connected.

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.

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.

The "progress" signal

void                user_function                      (TrackerMiner *miner,
                                                        gchar        *status,
                                                        gdouble       progress,
                                                        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.

miner :

 the TrackerMiner

status :

 miner status

progress :

 a gdouble indicating miner progress, from 0 to 1.

user_data :

 user data set when the signal handler was connected.

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.

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.

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.
Generated by GTK-Doc V1.14