DBus API

This is the raw DBus API for the Zeitgeist engine. Applications written in Python are encouraged to use the ZeitgeistClient API instead.

Event Serialization Format

The wire representation of events is central to the DBus API of the Zeitgeist engine. An event has DBus signature asaasay. The Python client library includes an Event class that conforms, without manual mashalling, to the DBus wire format described here.

The first array of strings, as, contains the event metadata at the following offsets:

  1. Event id, which is guaranteed to be an unsigned integer. Applications must never set this field, it is an error to do so. The field will be filled out when you ask for events from the Zeitgeist engine.
  2. Timestamp in milliseconds since the Unix Epoch
  3. Interpretation - the abstract notion of “what happened” defined by a formal URI. There is a predefined set of event interpretations in the zeitgeist.datamodel.Interpretation class
  4. Manifestation - the abstract notion of “how did this happen” defined by a formal URI. There is a predefined set of event manifestations in the zeitgeist.datamodel.Manifestation class
  5. Actor - a URI defining the entity spawning the event. In most cases this will be an application. The URI of an application is defined as the app:// URI-scheme with the base filename of the application’s .desktop file (with the extension). Fx Firefox with .desktop file /usr/share/applications/firefox.desktop will have an actor URI of app://firefox.desktop.

The second component in the event datastructure is the list of subjects, aas, each subject being an as. Note that an event can have more than one subject - fx. when deleting a collection of files with one click in the file manager. The subject metadata is defined with the following offsets:

  1. URI - eg. http://example.com/myfile.pdf or file:///tmp/my.txt
  2. Interpretation - the abstract notion of what the subject is, eg. “this is a document” or “this is an image”. The interpretation is formally represented by a URI. The zeitgeist.datamodel.Interpretation class contains a collection of predefined subject interpretations. It is otherwise recommended to use Nepomuk Information Elements to describe subject interpretations.
  3. Manifestation - the abstract notion of how the subject is stored or available, eg. “this is file” or “this is a webpage”. The manifestation is formally represented by a URI. The zeitgeist.datamodel.Manifestation class contains a collection of predefined subject manifestations. It is otherwise recommended to use Nepomuk Data Objects to describe subject manifestations.
  4. Origin - the URI where the user accessed the subject from
  5. Mimetype - The mimetype of the subject, eg. text/plain
  6. Text - A short textual representation of the subject suitable for display
  7. Storage - the id storage device the subject is. For files this would be the UUID of the volume, for subjects requiring a network interface use the string “net”. If the subject has been deleted use the string “deleted”. The storage id of the subject is used internally in the Zeitgeist engine to keep track of subject availability. This way clients can request hits only on subjects that are currently available.

The third an last component of the event data structure is an array of bytes, ay, called the payload. The payload can be used to hold any kind of free form data and its intent and purpose is entirely up to the entity inserting the event into the log.

org.gnome.zeitgeist.Log

org.gnome.zeitgeist.Monitor

class zeitgeist.client.Monitor(time_range, event_templates, insert_callback, delete_callback, monitor_path=None, event_type=None)

DBus interface for monitoring the Zeitgeist log for certain types of events.

When using the Python bindings monitors are normally instantiated indirectly by calling ZeitgeistClient.install_monitor().

It is important to understand that the Monitor instance lives on the client side, and expose a DBus service there, and the Zeitgeist engine calls back to the monitor when matching events are registered.

NotifyInsert(time_range, events)

Receive notification that a set of events matching the monitor’s templates has been recorded in the log.

This method is the raw DBus callback and should normally not be overridden. Events are received via the insert_callback argument given in the constructor to this class.

Parameters:
  • time_range – A two-tuple of 64 bit integers with the minimum and maximum timestamps found in events. DBus signature (xx)
  • events – A list of DBus event structs, signature a(asaasay) with the events matching the monitor. See ZeitgeistClient.install_monitor()
NotifyDelete(time_range, event_ids)

Receive notification that a set of events within the monitor’s matched time range has been deleted. Note that this notification will also be emitted for deleted events that doesn’t match the event templates of the monitor. It’s just the time range which is considered here.

This method is the raw DBus callback and should normally not be overridden. Events are received via the delete_callback argument given in the constructor to this class.

Parameters:
  • time_range – A two-tuple of 64 bit integers with the minimum and maximum timestamps found in events. DBus signature (xx)
  • event_ids – A list of event ids. An event id is simply and unsigned 32 bit integer. DBus signature au.

org.gnome.zeitgeist.Blacklist

org.gnome.zeitgeist.DataSourceRegistry

org.gnome.zeitgeist.StorageMonitor