ZeitgeistEvent

ZeitgeistEvent — ZeitgeistEvent objects abstract events returned from Zeitgeist queries

Synopsis

#include <zeitgeist.h>

                    ZeitgeistEvent;
struct              ZeitgeistEventClass;
void                zeitgeist_event_add_subject         (ZeitgeistEvent *event,
                                                         ZeitgeistSubject *subject);
const gchar *       zeitgeist_event_get_actor           (ZeitgeistEvent *event);
guint32             zeitgeist_event_get_id              (ZeitgeistEvent *event);
const gchar *       zeitgeist_event_get_interpretation  (ZeitgeistEvent *event);
const gchar *       zeitgeist_event_get_manifestation   (ZeitgeistEvent *event);
const gchar *       zeitgeist_event_get_origin          (ZeitgeistEvent *event);
GByteArray *        zeitgeist_event_get_payload         (ZeitgeistEvent *event);
ZeitgeistSubject *  zeitgeist_event_get_subject         (ZeitgeistEvent *event,
                                                         gint index);
gint64              zeitgeist_event_get_timestamp       (ZeitgeistEvent *event);
ZeitgeistEvent *    zeitgeist_event_new                 (void);
ZeitgeistEvent *    zeitgeist_event_new_from_variant    (GVariant *event);
ZeitgeistEvent *    zeitgeist_event_new_full            (const gchar *interpretation,
                                                         const gchar *manifestation,
                                                         const gchar *actor,
                                                         ...);
ZeitgeistEvent *    zeitgeist_event_new_full_valist     (const gchar *interpretation,
                                                         const gchar *manifestation,
                                                         const gchar *actor,
                                                         va_list args);
gint                zeitgeist_event_num_subjects        (ZeitgeistEvent *event);
void                zeitgeist_event_set_actor           (ZeitgeistEvent *event,
                                                         const gchar *actor);
void                zeitgeist_event_set_actor_from_app_info
                                                        (ZeitgeistEvent *event,
                                                         GAppInfo *appinfo);
void                zeitgeist_event_set_id              (ZeitgeistEvent *event,
                                                         guint32 id);
void                zeitgeist_event_set_interpretation  (ZeitgeistEvent *event,
                                                         const gchar *interpretation);
void                zeitgeist_event_set_manifestation   (ZeitgeistEvent *event,
                                                         const gchar *manifestation);
void                zeitgeist_event_set_origin          (ZeitgeistEvent *event,
                                                         const gchar *origin);
void                zeitgeist_event_set_payload         (ZeitgeistEvent *event,
                                                         GByteArray *payload);
void                zeitgeist_event_set_timestamp       (ZeitgeistEvent *event,
                                                         gint64 timestamp);
GVariant *          zeitgeist_event_to_variant          (ZeitgeistEvent *event);
GPtrArray *         zeitgeist_events_from_valist        (va_list events);
GPtrArray *         zeitgeist_events_from_variant       (GVariant *events);
GVariant *          zeitgeist_events_to_variant         (GPtrArray *events);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----ZeitgeistEvent

Description

The ZeitgeistEvent class is one of the primary elements for communicating with the Zeitgeist daemon. ZeitgeistEvents serve two purposes. Unsurprisingly they represent events that have happened, but they also can act as templates. See also ZeitgeistSubject.

An event in the Zeitgeist world is characterized by two main properties. "What happened" also called the interpretation, and "How did it happen" also called the manifestation. Besides these properties and event also has an actor which identifies the party responsible for triggering the event which in most cases will be an application. Lastly there is an event timestamp and event id. The timestamp is calculated as the number of milliseconds since the Unix epoch and the event id is a serial number assigned to the event by the Zeitgeist engine when it's logged. These five properties are collectively known as the event metadata.

An event must also describe what it happened to. This is called the event subjects. Most events have one subject, but they are allowed to have zero or many too. The metadata of the subjects are recorded at the time of logging, and are encapsulated by the ZeitgeistSubject class. It's important to understand that it's just the subject metadata at the time of logging, not necessarily the subject metadata as it exists right now.

In addition to the listed properties events may also carry a free form binary payload. The usage of this is is application specific and is generally useless unless you have some contextual information to figure out what's in it.

A large part of the Zeitgeist query and monitoring API revolves around a concept of template matching. A query is simply a list of event templates that you want to look for in the log. An unset property on an event template indicates that anything is allowed in that field. If the property is set it indicates that the property must be an exact match.

Details

ZeitgeistEvent

typedef struct _ZeitgeistEvent ZeitgeistEvent;


struct ZeitgeistEventClass

struct ZeitgeistEventClass {
  GInitiallyUnownedClass parent_class;
};


zeitgeist_event_add_subject ()

void                zeitgeist_event_add_subject         (ZeitgeistEvent *event,
                                                         ZeitgeistSubject *subject);

Append a ZeitgeistSubject to the list of subjects for event. The event will consume the floating reference on subject when you call this method.

event :

The event to add a subject to

subject :

The subject to add

zeitgeist_event_get_actor ()

const gchar *       zeitgeist_event_get_actor           (ZeitgeistEvent *event);

Get the event actor. The actor represents the party responsible for triggering the event. When the actor is an application (which it almost always is) the actor is encoded in the application:// URI scheme with the base name of the .desktop file for the application appended. Eg. application://firefox.desktop

event :

The event to set the actor for

Returns :

A URI designating the actor of the event

zeitgeist_event_get_id ()

guint32             zeitgeist_event_get_id              (ZeitgeistEvent *event);

Get the event id as assigned by the Zeitgeist engine.

event :

The event to get the event id for

Returns :

The event id or 0 if it's unset. An event retrieved from the Zeitgeist engine will always have an event id.

zeitgeist_event_get_interpretation ()

const gchar *       zeitgeist_event_get_interpretation  (ZeitgeistEvent *event);

The event interpretation represents "what happened". It is encoded as URI defined by the Zeitgeist Event Ontology. Examples could be "something was opened" or "something was modified".

FIXME: Needs link to ontology and some defines to help coding

event :

The event to get the interpretation of

Returns :

The event interpretation as a URI or NULL if unset

zeitgeist_event_get_manifestation ()

const gchar *       zeitgeist_event_get_manifestation   (ZeitgeistEvent *event);

The event manifestation represents "how did it happen". It is encoded as URI defined by the Zeitgeist Event Ontology. Examples could be "the user did it" or "the system send a notification".

FIXME: Needs link to ontology and some defines to help coding

event :

The event to get the manifestation of

Returns :

The event interpretation as a URI or NULL if unset

zeitgeist_event_get_origin ()

const gchar *       zeitgeist_event_get_origin          (ZeitgeistEvent *event);

Get the origin of an event. This differs from a subject's origin, as it describes where the event comes from, not where it resides.

event :

The event to get the origin from

Returns :

The origin of event.

Since 0.3.14


zeitgeist_event_get_payload ()

GByteArray *        zeitgeist_event_get_payload         (ZeitgeistEvent *event);

Look up the free form binary payload of event.

event :

The event to get the payload for

Returns :

The event payload or NULL if unset. Do not free. If you want to keep the subject around you need to g_byte_array_ref() it.

zeitgeist_event_get_subject ()

ZeitgeistSubject *  zeitgeist_event_get_subject         (ZeitgeistEvent *event,
                                                         gint index);

Get the n'th subject of this event. You can find the number of subjects by calling zeitgeist_event_num_subjects().

event :

The event to get a subject for

index :

The 0-based offset of the subject

Returns :

The subject at position index. Do not free. If you want to keep the subject around you need to g_object_ref() it.

zeitgeist_event_get_timestamp ()

gint64              zeitgeist_event_get_timestamp       (ZeitgeistEvent *event);

Get the event timestamp. The timestamp is in milliseconds since the Unix epoch. There are a few helpers available for converting to and from other time representations such a GTimeVal. See for example zeitgeist_timestamp_to_timeval() and zeitgeist_timestamp_from_timeval().

event :

The event to get the timestamp for

Returns :

The event timestamp. Note that 0 is ambiguous as it denotes both an unset timestamp and the time of the Unix Epoch.

zeitgeist_event_new ()

ZeitgeistEvent *    zeitgeist_event_new                 (void);

Create a new empty event structure

Returns :

A newly create ZeitgeistEvent instance. The returned event will have a floating reference which will be consumed if you pass the event to any of the methods provided by this library. If you do not do that then you must free the event youself with g_object_unref()

zeitgeist_event_new_from_variant ()

ZeitgeistEvent *    zeitgeist_event_new_from_variant    (GVariant *event);

Parse the data in a GVariant and build a ZeitgeistEvent from it. The reverse operation of this is zeitgeist_event_to_variant().

event :

A GVariant with signature defined in ZEITGEIST_EVENT_VARIANT_SIGNATURE. If event is a floating reference the floating reference will be consumed.

Returns :

A newly allocated ZeitgeistEvent filled with the metadata, subjects, and payload described by event. The returned event will have a floating reference which will be consumed if you pass the event to any of the methods provided by this library. If you do not do that then you must free the event yourself with g_object_unref()

zeitgeist_event_new_full ()

ZeitgeistEvent *    zeitgeist_event_new_full            (const gchar *interpretation,
                                                         const gchar *manifestation,
                                                         const gchar *actor,
                                                         ...);

Create a new event structure with predefined data

interpretation :

The interpretation type of the event. See ZEITGEIST_ZG_EVENT_INTERPRETATION for a list of event interpretation types

manifestation :

The manifestation type of the event. See ZEITGEIST_ZG_EVENT_MANIFESTATION for a list of event manifestation types

actor :

The actor triggering the event. See zeitgeist_event_set_actor() for details on how to encode this.

Returns :

A newly create ZeitgeistEvent instance. The returned event will have a floating reference which will be consumed if you pass the event to any of the methods provided by this library. If you do not do that then you must free the event yourself with g_object_unref()

zeitgeist_event_new_full_valist ()

ZeitgeistEvent *    zeitgeist_event_new_full_valist     (const gchar *interpretation,
                                                         const gchar *manifestation,
                                                         const gchar *actor,
                                                         va_list args);

As zeitgeist_event_new_full() but intended for language bindings

manifestation :

The manifestation type of the event. See ZEITGEIST_ZG_EVENT_MANIFESTATION for a list of event manifestation types

actor :

The actor triggering the event. See zeitgeist_event_set_actor() for details on how to encode this.

args :

A va_list of ZeitgeistSubjects terminated by NULL

zeitgeist_event_num_subjects ()

gint                zeitgeist_event_num_subjects        (ZeitgeistEvent *event);

Get the number of subjects for an event. This is a constant time operation.

event :

The event to get the number of subjects for

Returns :

The number of subjects for this event.

zeitgeist_event_set_actor ()

void                zeitgeist_event_set_actor           (ZeitgeistEvent *event,
                                                         const gchar *actor);

Get the event actor. The actor represents the party responsible for triggering the event. When the actor is an application (which it almost always is) the actor is encoded in the application:// URI scheme with the base name of the .desktop file for the application appended. Eg. application://firefox.desktop

event :

The event to set the actor for

actor :

URI designating the actor triggering the event. Fx. application://firefox.desktop

zeitgeist_event_set_actor_from_app_info ()

void                zeitgeist_event_set_actor_from_app_info
                                                        (ZeitgeistEvent *event,
                                                         GAppInfo *appinfo);


zeitgeist_event_set_id ()

void                zeitgeist_event_set_id              (ZeitgeistEvent *event,
                                                         guint32 id);

Set the event id of an event. Note that it is an error to send an event with a pre set event id to zeitgeist_log_insert_events().

event :

The event to get the event id for

zeitgeist_event_set_interpretation ()

void                zeitgeist_event_set_interpretation  (ZeitgeistEvent *event,
                                                         const gchar *interpretation);

The event interpretation represents "what happened". It is encoded as URI defined by the Zeitgeist Event Ontology.

FIXME: Needs link to ontology and some defines to help coding

event :

The event to set the interpretation of

interpretation :

URI designating the interpretation type of the event

zeitgeist_event_set_manifestation ()

void                zeitgeist_event_set_manifestation   (ZeitgeistEvent *event,
                                                         const gchar *manifestation);

The event manifestation represents "how did it happen". It is encoded as URI defined by the Zeitgeist Event Ontology.

FIXME: Needs link to ontology and some defines to help coding

event :

The event to set the manifestation of

zeitgeist_event_set_origin ()

void                zeitgeist_event_set_origin          (ZeitgeistEvent *event,
                                                         const gchar *origin);

Set the origin of an event. This differs from a subject's origin, as it describes where the event comes from, not where it resides.

event :

The event to set the origin of

origin :

The origin to set

Since 0.3.14


zeitgeist_event_set_payload ()

void                zeitgeist_event_set_payload         (ZeitgeistEvent *event,
                                                         GByteArray *payload);

Attach a a free form binary payload to event. Payloads are application specific and can not be assumed to have any particular format unless you have other contextual information about the event.

The event will assume ownership of payload. You should never call g_byte_array_free() on payload and only call g_byte_array_unref() on it if you have added an extra reference to it.

event :

Event to add the payload to

payload :

The payload to add to event. [transfer-full]

zeitgeist_event_set_timestamp ()

void                zeitgeist_event_set_timestamp       (ZeitgeistEvent *event,
                                                         gint64 timestamp);

Set the event timestamp. The timestamp is in milliseconds since the Unix epoch. There are a few helpers available for converting to and from other time representations such a GTimeVal. See for example zeitgeist_timestamp_to_timeval() and zeitgeist_timestamp_from_timeval().

Note that the if you insert events into the Zeitgeist log without a timestamp set the Zeiteist daemon will automatically assign the timestamp of the logging time to the event.

event :

The event to set the timestamp for

zeitgeist_event_to_variant ()

GVariant *          zeitgeist_event_to_variant          (ZeitgeistEvent *event);

Serialize a ZeitgeistEvent to a GVariant. The reverse operation is zeitgeist_event_new_from_variant().

event :

The ZeitgeistEvent to serialize to a GVariant

Returns :

A floating reference to a GVariant with signature ZEITGEIST_EVENT_VARIANT_SIGNATURE

zeitgeist_events_from_valist ()

GPtrArray *         zeitgeist_events_from_valist        (va_list events);

Utility function to convert a va_list of ZeitgeistEvent into a GPtrArray containing these events.

events :

a va_list of ZeitgeistEvents.

Returns :

A GPtrArray of ZeitgeistEvents. The events are not further reffed and will still be floating if they where so when you called this method. The pointer array will have its free_func set to g_object_unref()

zeitgeist_events_from_variant ()

GPtrArray *         zeitgeist_events_from_variant       (GVariant *events);

events :

A GVariant with signature as an array of ZEITGEIST_EVENT_VARIANT_SIGNATURE. If event is floating this method will consume the floating reference.

Returns :

A reference to a GPtrArray of ZeitgeistEvents. All the events will be floating references, and the GPtrArray's free_func will be set to g_object_unref().

zeitgeist_events_to_variant ()

GVariant *          zeitgeist_events_to_variant         (GPtrArray *events);

Convert a set of ZeitgeistEvent<-- -->s to a GVariant with signature as an array of ZEITGEIST_EVENT_VARIANT_SIGNATURE.

events :

A GPtrArray of ZeitgeistEvents. If the events has floating references they will be consumed. Furthermore the reference on the GPtrArray itself will also be stolen and its free_func set to NULL

Returns :

A floating reference to a GVariant as described above. Unless the floating reference is consumed somewhere you must free it with g_variant_unref().