TrackerDecorator

TrackerDecorator — A miner tasked with listening for DB resource changes and extracting metadata

Synopsis

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

struct              TrackerDecorator;
struct              TrackerDecoratorClass;
enum                TrackerDecoratorError;
GQuark              tracker_decorator_error_quark       (void);
const gchar *       tracker_decorator_get_data_source   (TrackerDecorator *decorator);
const gchar **      tracker_decorator_get_class_names   (TrackerDecorator *decorator);
guint               tracker_decorator_get_n_items       (TrackerDecorator *decorator);
void                tracker_decorator_prepend_id        (TrackerDecorator *decorator,
                                                         gint id,
                                                         gint class_name_id);
void                tracker_decorator_delete_id         (TrackerDecorator *decorator,
                                                         gint id);
void                tracker_decorator_next              (TrackerDecorator *decorator,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
TrackerDecoratorInfo * tracker_decorator_next_finish    (TrackerDecorator *decorator,
                                                         GAsyncResult *result,
                                                         GError **error);
void                tracker_decorator_set_priority_rdf_types
                                                        (TrackerDecorator *decorator,
                                                         const gchar * const *rdf_types);
TrackerDecoratorInfo * tracker_decorator_info_ref       (TrackerDecoratorInfo *info);
void                tracker_decorator_info_unref        (TrackerDecoratorInfo *info);
const gchar *       tracker_decorator_info_get_urn      (TrackerDecoratorInfo *info);
const gchar *       tracker_decorator_info_get_url      (TrackerDecoratorInfo *info);
const gchar *       tracker_decorator_info_get_mimetype (TrackerDecoratorInfo *info);
GTask *             tracker_decorator_info_get_task     (TrackerDecoratorInfo *info);
TrackerSparqlBuilder * tracker_decorator_info_get_sparql
                                                        (TrackerDecoratorInfo *info);

Object Hierarchy

  GObject
   +----TrackerMiner
         +----TrackerDecorator
               +----TrackerDecoratorFS

Implemented Interfaces

TrackerDecorator implements GInitable.

Properties

  "class-names"              GStrv                 : Read / Write
  "commit-batch-size"        gint                  : Read / Write
  "data-source"              gchar*                : Read / Write / Construct Only
  "priority-rdf-types"       GStrv                 : Write

Signals

  "finished"                                       : Run Last
  "items-available"                                : Run Last

Description

TrackerDecorator watches for signal updates based on content changes in the database. When new files are added initially, only simple metadata exists, for example, name, size, mtime, etc. The TrackerDecorator queues files for extended metadata extraction (i.e. for tracker-extract to fetch metadata specific to the file type) for example 'nmm:whiteBalance' for a picture.

Details

struct TrackerDecorator

struct TrackerDecorator;

Abstract miner object for passive extended metadata indexing, i.e. data past the basic information such as file name, size, etc.


struct TrackerDecoratorClass

struct TrackerDecoratorClass {
	TrackerMinerClass parent_class;

	void (* items_available) (TrackerDecorator *decorator);
	void (* finished)        (TrackerDecorator *decorator);

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

An implementation that takes care of extracting extra metadata specific to file types by talking to tracker-extract.

Based on TrackerMinerClass.

TrackerMinerClass parent_class;

parent object class.

items_available ()

Called when there are resources to be processed.

finished ()

Called when all resources have been processed.

gpointer padding[10];

Reserved for future API improvements.

enum TrackerDecoratorError

typedef enum {
	TRACKER_DECORATOR_ERROR_EMPTY,
	TRACKER_DECORATOR_ERROR_PAUSED
} TrackerDecoratorError;

Possible errors returned when calling tracker_decorator_next_finish().

TRACKER_DECORATOR_ERROR_EMPTY

There is no item to be processed next. It is entirely possible to have a ::items_available signal emitted and then have this error when calling tracker_decorator_next_finish() because the signal may apply to a class which we're not interested in. For example, a new nmo:Email might have been added to Tracker, but we might only be interested in nfo:Document. This case would give this error.

TRACKER_DECORATOR_ERROR_PAUSED

No work was done or will be done because the miner is currently paused.

tracker_decorator_error_quark ()

GQuark              tracker_decorator_error_quark       (void);

Gives the caller the GQuark used to identify TrackerDecorator 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.18.


tracker_decorator_get_data_source ()

const gchar *       tracker_decorator_get_data_source   (TrackerDecorator *decorator);

The unique string identifying this TrackerDecorator that has extracted the extended metadata. This is essentially an identifier so it's clear WHO has extracted this extended metadata.

decorator :

a TrackerDecorator.

Returns :

a const gchar* or NULL if an error happened.

Since 0.18.


tracker_decorator_get_class_names ()

const gchar **      tracker_decorator_get_class_names   (TrackerDecorator *decorator);

This function returns a string list of class names which are being updated with extended metadata. An example would be 'nfo:Document'.

decorator :

a TrackerDecorator.

Returns :

a const gchar** or NULL. [transfer none]

Since 0.18.


tracker_decorator_get_n_items ()

guint               tracker_decorator_get_n_items       (TrackerDecorator *decorator);

Get the number of items left in the queue to be processed. This indicates content that may already exist in Tracker but is waiting to be further flurished with metadata with a 2nd pass extraction or index.

decorator :

a TrackerDecorator

Returns :

the number of items queued to be processed, always >= 0.

Since 0.18.


tracker_decorator_prepend_id ()

void                tracker_decorator_prepend_id        (TrackerDecorator *decorator,
                                                         gint id,
                                                         gint class_name_id);

Adds resource needing extended metadata extraction to the queue. id is the same IDs emitted by tracker-store when the database is updated for consistency. For details, see the GraphUpdated signal.

decorator :

a TrackerDecorator.

id :

the ID of the resource ID.

class_name_id :

the ID of the resource's class.

Since 0.18.


tracker_decorator_delete_id ()

void                tracker_decorator_delete_id         (TrackerDecorator *decorator,
                                                         gint id);

Deletes resource needing extended metadata extraction from the queue. id is the same IDs emitted by tracker-store when the database is updated for consistency. For details, see the GraphUpdated signal.

decorator :

a TrackerDecorator.

id :

an ID.

Since 0.18.


tracker_decorator_next ()

void                tracker_decorator_next              (TrackerDecorator *decorator,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Processes the next resource in the queue to have extended metadata extracted. If the item in the queue has been completed already, it signals it's completion instead.

This function will give a GError if the miner is paused at the time it is called.

decorator :

a TrackerDecorator.

cancellable :

a GCancellable.

callback :

a GAsyncReadyCallback.

user_data :

user_data for callback.

Since 0.18.


tracker_decorator_next_finish ()

TrackerDecoratorInfo * tracker_decorator_next_finish    (TrackerDecorator *decorator,
                                                         GAsyncResult *result,
                                                         GError **error);

Should be called in the callback function provided to tracker_decorator_next() to return the result of the task be it an error or not.

decorator :

a TrackerDecorator.

result :

a GAsyncResult.

error :

return location for a GError, or NULL.

Returns :

a TrackerDecoratorInfo on success or NULL on error. Free with tracker_decorator_info_unref(). [transfer full]

Since 0.18.


tracker_decorator_set_priority_rdf_types ()

void                tracker_decorator_set_priority_rdf_types
                                                        (TrackerDecorator *decorator,
                                                         const gchar * const *rdf_types);

Re-evaluate the priority queues internally to ensure that rdf_types are handled before all other content. This is useful for applications that need their content available sooner than the standard time it would take to index content.

decorator :

a TrackerDecorator

rdf_types :

a string array of rdf types

Since 0.18.


tracker_decorator_info_ref ()

TrackerDecoratorInfo * tracker_decorator_info_ref       (TrackerDecoratorInfo *info);

Increases the reference count of info by 1.

info :

a TrackerDecoratorInfo

Returns :

the same info passed in, or NULL on error.

Since 0.18.


tracker_decorator_info_unref ()

void                tracker_decorator_info_unref        (TrackerDecoratorInfo *info);

Decreases the reference count of info by 1 and frees it when the reference count reaches 0.

info :

a TrackerDecoratorInfo

Since 0.18.


tracker_decorator_info_get_urn ()

const gchar *       tracker_decorator_info_get_urn      (TrackerDecoratorInfo *info);

A URN is a Uniform Resource Name and should be a unique identifier for a resource in the database.

info :

a TrackerDecoratorInfo.

Returns :

the URN for TrackerDecoratorInfo on success or NULL on error.

Since 0.18.


tracker_decorator_info_get_url ()

const gchar *       tracker_decorator_info_get_url      (TrackerDecoratorInfo *info);

A URL is a Uniform Resource Locator and should be a location associated with a resource in the database. For example, 'file:///tmp/foo.txt'.

info :

a TrackerDecoratorInfo.

Returns :

the URL for TrackerDecoratorInfo on success or NULL on error.

Since 0.18.


tracker_decorator_info_get_mimetype ()

const gchar *       tracker_decorator_info_get_mimetype (TrackerDecoratorInfo *info);

A MIME¹ type is a way of describing the content type of a file or set of data. An example would be 'text/plain' for a clear text document or file.

¹: http://en.wikipedia.org/wiki/MIME

info :

a TrackerDecoratorInfo.

Returns :

the MIME type for TrackerDecoratorInfo on success or NULL on error.

Since 0.18.


tracker_decorator_info_get_task ()

GTask *             tracker_decorator_info_get_task     (TrackerDecoratorInfo *info);

Get the GTask associated with retrieving extended metadata and information for a URN in Tracker.

info :

a TrackerDecoratorInfo.

Returns :

the GTask for TrackerDecoratorInfo on success or NULL if there is no existing GTask. [transfer none]

Since 0.18.


tracker_decorator_info_get_sparql ()

TrackerSparqlBuilder * tracker_decorator_info_get_sparql
                                                        (TrackerDecoratorInfo *info);

A TrackerSparqlBuilder allows the caller to extract the final SPARQL used to insert the extracted metadata into the database for the resource being processed.

This function calls g_task_get_task_data() on the return value of tracker_decorator_info_get_task().

info :

a TrackerDecoratorInfo.

Returns :

a TrackerSparqlBuilder on success or NULL on error. [transfer none]

Since 0.18.

Property Details

The "class-names" property

  "class-names"              GStrv                 : Read / Write

rdfs:Class objects to listen to for changes.


The "commit-batch-size" property

  "commit-batch-size"        gint                  : Read / Write

Number of items per update batch.

Allowed values: >= 0

Default value: 200


The "data-source" property

  "data-source"              gchar*                : Read / Write / Construct Only

nie:DataSource to use in this decorator.

Default value: NULL


The "priority-rdf-types" property

  "priority-rdf-types"       GStrv                 : Write

rdf:type that needs to be extracted first.

Signal Details

The "finished" signal

void                user_function                      (TrackerDecorator *decorator,
                                                        gpointer          user_data)      : Run Last

The ::finished signal will be emitted whenever the TrackerDecorator has finished extracted extended metadata for resources in the database.

decorator :

the TrackerDecorator

user_data :

user data set when the signal handler was connected.

Since 0.18.


The "items-available" signal

void                user_function                      (TrackerDecorator *decorator,
                                                        gpointer          user_data)      : Run Last

The ::items-available signal will be emitted whenever the TrackerDecorator sees resources that are available for extended metadata extraction.

decorator :

the TrackerDecorator

user_data :

user data set when the signal handler was connected.

Since 0.18.

See Also

TrackerDecoratorFS