TrackerNotifier: Tracker SPARQL Library Reference Manual

TrackerNotifier

TrackerNotifier — Listen to changes in the Tracker database

Functions

TrackerNotifier *	tracker_notifier_new ()
TrackerNotifierEventType	tracker_notifier_event_get_event_type ()
gint64	tracker_notifier_event_get_id ()
const gchar *	tracker_notifier_event_get_type ()
const gchar *	tracker_notifier_event_get_urn ()
const gchar *	tracker_notifier_event_get_location ()

Properties

GStrv	classes	Read / Write / Construct Only
TrackerNotifierFlags	flags	Read / Write / Construct Only

Signals

void

events

Types and Values

enum	TrackerNotifierFlags
	TrackerNotifier
struct	TrackerNotifierClass
enum	TrackerNotifierEventType
	TrackerNotifierEvent

Object Hierarchy

    GObject
    ╰── TrackerNotifier

Implemented Interfaces

TrackerNotifier implements GInitable.

Includes

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

Description

TrackerNotifier is an object that receives notifications about changes to the Tracker database. A TrackerNotifier is created through tracker_notifier_new(), passing the RDF types that are relevant to the caller, and possible different TrackerNotifierFlags to change TrackerNotifier behavior. After the notifier is created, events can be listened for by connecting to the “events” signal. This object was added in Tracker 1.12.

TrackerNotifier by default coalesces events so the user is only notified of changes after all metadata is extracted and inserted in the database, so the user is guaranteed that all relevant data will be available at the time of notification. If this is not desired, or when dealing with data not dealt with by tracker-extract, the TRACKER_NOTIFIER_FLAG_NOTIFY_UNEXTRACTED flag can be passed.

If the TRACKER_NOTIFIER_FLAG_NOTIFY_UNEXTRACTED flag is passed, created/updated elements may be notified in two steps, first a CREATED/UPDATED event will be emitted, and then a second UPDATED event might appear after further metadata is extracted.

TrackerNotifier is tracker:id centric, the ID can be obtained from every event through tracker_notifier_event_get_id(). The expected way to retrieving metadata is a query of the form:

SELECT ?urn …
WHERE {
  ?urn a rdfs:Resource .
  …
  FILTER (tracker:id(?urn) = …)
}

If the flags TRACKER_NOTIFIER_FLAG_QUERY_URN or TRACKER_NOTIFIER_FLAG_QUERY_LOCATION are passed, the extra metadata will be available through tracker_notifier_event_get_urn() and/or tracker_notifier_event_get_location(). Note that this metadata can't be obtained for every element and situation, most notably during TRACKER_NOTIFIER_EVENT_DELETE events.

Known caveats

If a resource is deleted, the TRACKER_NOTIFIER_EVENT_DELETE event emitted will have a NULL location, even if the notifier was created with the TRACKER_NOTIFIER_FLAG_QUERY_LOCATION flag enabled. At the time of notifying, the resource does not exist anymore, so no meatadata can be retrieved.
Notifications of files being moved across indexed folders will appear as TRACKER_NOTIFIER_EVENT_UPDATE events, containing the new location (if requested). The older location is no longer known to Tracker, this may make tracking of elements in specific folders hard using solely the TrackerNotifier/Tracker data available at event notification time.

The recommendation to fix those is making the caller aware of tracker:ids, querying those in the application SPARQL queries so the client can search the formerly queried data for matching IDs when TrackerNotifier events happen. URNs are just as effective as a matching mechanism, but more costly.

Functions

tracker_notifier_new ()

TrackerNotifier *
tracker_notifier_new (const gchar * const *classes,
                      TrackerNotifierFlags flags,
                      GCancellable *cancellable,
                      GError **error);

Creates a new notifier, events can be listened through the TrackerNotifier::events signal.

Parameters

classes	Array of RDF classes to receive notifications from, or `NULL` for all.	[array zero-terminated=1][allow-none]
flags	flags affecting the notifier behavior
cancellable	Cancellable for the operation
error	location for the possible resulting error.

Returns

a newly created TrackerNotifier, NULL on error.

[nullable]

Since: 1.12

tracker_notifier_event_get_event_type ()

TrackerNotifierEventType
tracker_notifier_event_get_event_type (TrackerNotifierEvent *event);

Returns the event type.

Parameters

event

A TrackerNotifierEvent

Returns

The event type

Since: 1.12

tracker_notifier_event_get_id ()

gint64
tracker_notifier_event_get_id (TrackerNotifierEvent *event);

Returns the tracker:id of the element being notified upon.

Parameters

event

A TrackerNotifierEvent

Returns

the resource ID

Since: 1.12

tracker_notifier_event_get_type ()

const gchar *
tracker_notifier_event_get_type (TrackerNotifierEvent *event);

Returns the RDF type that this notification event relates to, in their expanded forms (for example, http://www.semanticdesktop.org/ontologies/2007/03/22/nfoAudio).

A resource may have multiple RDF types. In the case of changes to a resource with multiple types, one event will be notified for each RDF type the notifier is subscribed to.

For performance reasons, Tracker only sends notifications for events that are explicitly marked with the tracker:notify property in their ontology.

Parameters

event

A TrackerNotifierEvent

Returns

the RDF type of the element

Since: 1.12

tracker_notifier_event_get_urn ()

const gchar *
tracker_notifier_event_get_urn (TrackerNotifierEvent *event);

Returns the Uniform Resource Name of the element if the notifier has the flag TRACKER_NOTIFIER_FLAG_QUERY_URN enabled.

This URN is an unique string identifier for the resource being notified upon, typically of the form "urn:uuid:...".

Parameters

event

A TrackerNotifierEvent

Returns

The element URN

Since: 1.12

tracker_notifier_event_get_location ()

const gchar *
tracker_notifier_event_get_location (TrackerNotifierEvent *event);

Returns the location (e.g. an URI) of the element if the notifier has the flag TRACKER_NOTIFIER_FLAG_QUERY_LOCATION, and it can be obtained at the time of emission.

Parameters

event

A TrackerNotifierEvent

Returns

The element location, or NULL.

[nullable]

Since: 1.12

Types and Values

enum TrackerNotifierFlags

Flags affecting TrackerNotifier behavior.

Members

TRACKER_NOTIFIER_FLAG_NONE	No flags
TRACKER_NOTIFIER_FLAG_QUERY_URN	Query URN of notified elements
TRACKER_NOTIFIER_FLAG_QUERY_LOCATION	Query location of notified elements
TRACKER_NOTIFIER_FLAG_NOTIFY_UNEXTRACTED	Added/updated Elements are notified in 2 steps (a CREATE/UPDATE event after the file is first known, and an UPDATE event after metadata is extracted). The default TrackerNotifier behavior coalesces those events in one.