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

## Types and Values

enum | TrackerNotifierFlags
| TrackerNotifier
struct | TrackerNotifierClass
enum | TrackerNotifierEventType
| TrackerNotifierEvent

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

    1
    2
    3
    4
    5
    6
    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/nfo#Audio).

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

### TrackerNotifier

    typedef struct _TrackerNotifier TrackerNotifier;

### struct TrackerNotifierClass

    struct TrackerNotifierClass {
    	GObjectClass parent_class;

    	void (* events) (TrackerNotifier *notifier,
    	                 const GPtrArray *events);

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

### enum TrackerNotifierEventType

Notifier event types.

#### Members

TRACKER_NOTIFIER_EVENT_CREATE | An element was created. |
TRACKER_NOTIFIER_EVENT_DELETE | An element was deleted. |
TRACKER_NOTIFIER_EVENT_UPDATE | An element was updated. |

### TrackerNotifierEvent

    typedef struct _TrackerNotifierEvent TrackerNotifierEvent;