Tracker Miner
3
LIBTRACKER-MINER Library

# Tracker Miner

Abstract base class for data miners

## Synopsis

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

    typedef             TrackerMiner;
                        TrackerMinerClass;
    GQuark              tracker_miner_error_quark           (void);
    void                tracker_miner_start                 (TrackerMiner *miner);
    void                tracker_miner_stop                  (TrackerMiner *miner);
    gboolean            tracker_miner_is_started            (TrackerMiner *miner);
    gboolean            tracker_miner_execute_update        (TrackerMiner *miner,
                                                             const gchar *sparql,
                                                             GError **error);
    GPtrArray *         tracker_miner_execute_sparql        (TrackerMiner *miner,
                                                             const gchar *sparql,
                                                             GError **error);
    gboolean            tracker_miner_execute_batch_update  (TrackerMiner *miner,
                                                             const gchar *sparql,
                                                             GError **error);
    gboolean            tracker_miner_commit                (TrackerMiner *miner);
    gint                tracker_miner_pause                 (TrackerMiner *miner,
                                                             const gchar *reason,
                                                             GError **error);
    gboolean            tracker_miner_resume                (TrackerMiner *miner,
                                                             gint cookie,
                                                             GError **error);

## Object Hierarchy

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

## Properties

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

## Signals

      "error"                                          : Run Last
      "paused"                                         : Run Last
      "progress"                                       : Run Last
      "resumed"                                        : Run Last
      "started"                                        : Run Last
      "stopped"                                        : Run Last
      "terminated"                                     : 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

### 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 (* terminated) (TrackerMiner *miner);

    	void (* progress)   (TrackerMiner *miner,
    			     const gchar  *status,
    			     gdouble       progress);

    	void (* error)      (TrackerMiner *miner,
    			     GError       *error);
    } 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.

terminated ()

  terminated.

progress ()

  progress.

error ()

  error.

### 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_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_execute_update ()

    gboolean            tracker_miner_execute_update        (TrackerMiner *miner,
                                                             const gchar *sparql,
                                                             GError **error);

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

`miner` :

  a TrackerMiner

`sparql` :

  a SPARQL query

`error` :

  return location for errors

Returns :

  TRUE if the SPARQL query was executed successfully.

### tracker_miner_execute_sparql ()

    GPtrArray *         tracker_miner_execute_sparql        (TrackerMiner *miner,
                                                             const gchar *sparql,
                                                             GError **error);

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

`miner` :

  a TrackerMiner

`sparql` :

  a SPARQL query

`error` :

  return location for errors

Returns :

  a GPtrArray with the returned data.

### tracker_miner_execute_batch_update ()

    gboolean            tracker_miner_execute_batch_update  (TrackerMiner *miner,
                                                             const gchar *sparql,
                                                             GError **error);

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

`miner` :

  a TrackerMiner

`sparql` :

  a set of SPARQL updates

`error` :

  return location for errors

Returns :

  TRUE if the SPARQL query was executed successfully.

### tracker_miner_commit ()

    gboolean            tracker_miner_commit                (TrackerMiner *miner);

Commits all pending batch updates. see `tracker_miner_execute_batch_update()`

`miner` :

  a TrackerMiner

Returns :

  TRUE if the data was committed successfully.

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

## Property Details

### The `"name"` property

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

Miner name.

Default value: NULL

### The `"progress"` property

      "progress"                 gdouble               : Read / Write

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 *trackerminer,
                                                            gpointer      arg1,
                                                            gpointer      user_data)         : Run Last

`trackerminer` :

  the object which received the signal.

`arg1` :

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

### The `"terminated"` signal

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

`trackerminer` :

  the object which received the signal.

`user_data` :

  user data set when the signal handler was connected.