Top | ![]() |
![]() |
![]() |
![]() |
ZeitgeistEventZeitgeistEvent — ZeitgeistEvent objects abstract events returned from Zeitgeist queries |
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.
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.
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
guint32
zeitgeist_event_get_id (ZeitgeistEvent *event
);
Get the event id as assigned by the Zeitgeist engine.
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
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
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.
Since 0.3.14
GByteArray *
zeitgeist_event_get_payload (ZeitgeistEvent *event
);
Look up the free form binary payload of event
.
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.
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()
.
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()
.
ZeitgeistEvent *
zeitgeist_event_new (void
);
Create a new empty event structure
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()
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 |
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()
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 |
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()
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 |
|
args |
A |
gint
zeitgeist_event_num_subjects (ZeitgeistEvent *event
);
Get the number of subjects for an event. This is a constant time operation.
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
void zeitgeist_event_set_actor_from_app_info (ZeitgeistEvent *event
,GAppInfo *appinfo
);
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()
.
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
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
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.
Since 0.3.14
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.
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.
GVariant *
zeitgeist_event_to_variant (ZeitgeistEvent *event
);
Serialize a ZeitgeistEvent to a GVariant. The reverse operation
is zeitgeist_event_new_from_variant()
.
GPtrArray *
zeitgeist_events_from_valist (va_list events
);
Utility function to convert a va_list of ZeitgeistEvent into a GPtrArray containing these events.
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()
GPtrArray *
zeitgeist_events_from_variant (GVariant *events
);
events |
A GVariant with signature as an array of
ZEITGEIST_EVENT_VARIANT_SIGNATURE. If |
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()
.
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
|