This is the raw DBus API for the Zeitgeist engine. Applications written in Python are encouraged to use the ZeitgeistClient API instead.
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:
- 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.
- Timestamp in milliseconds since the Unix Epoch
- 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
- 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
- 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:
- URI - eg. http://example.com/myfile.pdf or file:///tmp/my.txt
- 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.
- 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.
- Origin - the URI where the user accessed the subject from
- Mimetype - The mimetype of the subject, eg. text/plain
- Text - A short textual representation of the subject suitable for display
- 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.
Primary interface to the Zeitgeist engine. Used to update and query the log. It also provides means to listen for events matching certain criteria. All querying is heavily based around an “event template”-concept.
The main log of the Zeitgeist engine has DBus object path /org/gnome/zeitgeist/log/activity under the bus name org.gnome.zeitgeist.Engine.
Inserts events into the log. Returns an array containing the IDs of the inserted events
Each event which failed to be inserted into the log (either by being blocked or because of an error) will be represented by 0 in the resulting array.
One way events may end up being blocked is if they match any of the blacklist templates.
Any monitors with matching templates will get notified about the insertion. Note that the monitors are notified after the events have been inserted.
| Parameters: | events – List of events to be inserted in the log. If you are using the Python bindings you may pass Event instances directly to this method |
|---|---|
| Returns: | An array containing the event IDs of the inserted events. In case any of the events where already logged, the ID of the existing event will be returned. 0 as ID indicates a failed insert into the log. |
| Return type: | Array of unsigned 32 bits integers. DBus signature au. |
Get full event data for a set of event IDs
Each event which is not found in the event log is represented by the NULL_EVENT struct in the resulting array.
| Parameters: | event_ids (Array of unsigned 32 bit integers. DBus signature au) – An array of event IDs. Fx. obtained by calling FindEventIds() |
|---|---|
| Returns: | Full event data for all the requested IDs. The event data can be conveniently converted into a list of Event instances by calling events = map(Event.new_for_struct, result) |
| Return type: | A list of serialized events. DBus signature a(asaasay). |
Search for events matching a given set of templates and return the IDs of matching events.
Use GetEvents() passing in the returned IDs to look up the full event data.
The matching is done where unset fields in the templates are treated as wildcards. If a template has more than one subject then events will match the template if any one of their subjects match any one of the subject templates.
The fields uri, interpretation, manifestation, origin, and mimetype can be prepended with an exclamation mark ‘!’ in order to negate the matching.
The fields uri, origin, and mimetype can be prepended with an asterisk ‘*’ in order to do truncated matching.
This method is intended for queries potentially returning a large result set. It is especially useful in cases where only a portion of the results are to be displayed at the same time (eg., by using paging or dynamic scrollbars), as by holding a list of IDs you keep a stable ordering and you can ask for the details associated to them in batches, when you need them. For queries yielding a small amount of results, or where you need the information about all results at once no matter how many of them there are, see FindEvents().
| Parameters: |
|
|---|---|
| Returns: | An array containing the IDs of all matching events, up to a maximum of num_events events. Sorted and grouped as defined by the result_type parameter. |
| Return type: | Array of unsigned 32 bit integers |
Get events matching a given set of templates.
The matching is done where unset fields in the templates are treated as wildcards. If a template has more than one subject then events will match the template if any one of their subjects match any one of the subject templates.
The fields uri, interpretation, manifestation, origin, and mimetype can be prepended with an exclamation mark ‘!’ in order to negate the matching.
The fields uri, origin, and mimetype can be prepended with an asterisk ‘*’ in order to do truncated matching.
In case you need to do a query yielding a large (or unpredictable) result set and you only want to show some of the results at the same time (eg., by paging them), use FindEventIds().
| Parameters: |
|
|---|---|
| Returns: | Full event data for all the requested IDs, up to a maximum of num_events events, sorted and grouped as defined by the result_type parameter. The event data can be conveniently converted into a list of Event instances by calling events = map(Event.new_for_struct, result) |
| Return type: | A list of serialized events. DBus signature a(asaasay). |
Warning: This API is EXPERIMENTAL and is not fully supported yet.
Get a list of URIs of subjects which frequently occur together with events matching event_templates within time_range. The resulting URIs must occur as subjects of events matching result_event_templates and have storage state storage_state.
| Parameters: |
|
|---|---|
| Returns: | A list of URIs matching the described criteria |
| Return type: | An array of strings, DBus signature as. |
Delete a set of events from the log given their IDs
| Parameters: | event_ids (list of integers) – list of event IDs obtained, for example, by calling FindEventIds() |
|---|
Delete the log file and all its content
This method is used to delete the entire log file and all its content in one go. To delete specific subsets use FindEventIds() combined with DeleteEvents().
Terminate the running Zeitgeist engine process; use with caution, this action must only be triggered with the user’s explicit consent, as it will affect all applications using Zeitgeist
Register a client side monitor object to receive callbacks when events matching time_range and event_templates are inserted or deleted.
The monitor object must implement the interface org.gnome.zeitgeist.Monitor
The monitor templates are matched exactly like described in FindEventIds().
| Parameters: |
|
|---|
Remove a monitor installed with InstallMonitor()
| Parameters: | monitor_path – DBus object path of monitor to remove as supplied to InstallMonitor(). |
|---|
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.
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: |
|
|---|
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: |
|
|---|
The Zeitgeist engine maintains a list of event templates that is known as the blacklist. When inserting events via org.gnome.zeitgeist.Log.InsertEvents they will be checked against the blacklist templates and if they match they will not be inserted in the log, and any matching monitors will not be signalled.
The blacklist of the Zeitgeist engine has DBus object path /org/gnome/zeitgeist/blacklist under the bus name org.gnome.zeitgeist.Engine.
The Zeitgeist engine maintains a publicly available list of recognized data-sources (components inserting information into Zeitgeist). An option to disable such data-providers is also provided.
The data-source registry of the Zeitgeist engine has DBus object path /org/gnome/zeitgeist/data_source_registry under the bus name org.gnome.zeitgeist.DataSourceRegistry.
Register a data-source as currently running. If the data-source was already in the database, its metadata (name, description and event_templates) are updated.
The optional event_templates is purely informational and serves to let data-source management applications and other data-sources know what sort of information you log.
| Parameters: |
|
|---|
Get the list of known data-sources.
| Returns: | A list of DataSource objects. |
|---|
Get a list of data-sources.
| Parameters: |
|
|---|---|
| Returns: | True on success, False if there is no known data-source matching the given ID. |
| Return type: | Bool |
This signal is emitted whenever a data-source is enabled or disabled.
| Returns: | unique string identifier of a data-source and a bool which is True if it was enabled False if it was disabled. |
|---|---|
| Return type: | struct containing a string and a bool |
This signal is emitted whenever a data-source registers itself.
| Returns: | the registered data-source |
|---|---|
| Return type: | DataSource |
This signal is emitted whenever the last running instance of a data-source disconnects.
| Returns: | the disconnected data-source |
|---|---|
| Return type: | DataSource |
The Storage Monitor monitors the availability of network interfaces and storage devices and updates the Zeitgeist database with this information so clients can efficiently query based on the storage identifier and availability of the storage media the event subjects reside on.
For storage devices the monitor will use the UUID of the partition that a subject reside on as storage id. For network URIs the storage monitor will use the fixed identifier net. For subjects residing on persistent, but unidentifiable, media attached to the computer the id local will be used. For URIs that can’t be handled the storage id will be set to unknown. The local and unknown storage media are considered to be always in an available state. To determine the availability of the net media the monitor will use either Connman or NetworkManager - what ever is available on the host system.
For subjects being inserted into the log that doesn’t have a storage id set on them this extension will try and figure it out on the fly and update the subject appropriately before its inserted into the log.
The storage monitor of the Zeitgeist engine has DBus object path /org/gnome/zeitgeist/storagemonitor under the bus name org.gnome.zeitgeist.Engine.
Retrieve a list describing all storage media known by the Zeitgeist daemon. A storage medium is identified by a key - as set in the subject storage field. For each storage id there is a dict of properties that will minimally include the following: available with a boolean value, icon a string with the name of the icon to use for the storage medium, and display-name a string with a human readable name for the storage medium.
The DBus signature of the return value of this method is a(sa{sv}).
The Zeitgeist daemon emits this signal when the storage medium with id storage_id has become available.
The second parameter for this signal is a dictionary containing string keys and variant values. The keys that are guaranteed to be there are available with a boolean value, icon a string with the name of the icon to use for the storage medium, and display-name a string with a human readable name for the storage medium.
The DBus signature of this signal is sa{sv}.
The Zeitgeist daemon emits this signal when the storage medium with id storage_id is no longer available.
The DBus signature of this signal is s.