![]() |
![]() |
![]() |
API Documentation for the Zeitgeist Client Library | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
ZeitgeistEventZeitgeistEvent — ZeitgeistEvent objects abstract events returned from Zeitgeist queries |
#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
);
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.
|
The event to add a subject to |
|
The subject to add |
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
|
The event to set the actor for |
Returns : |
A URI designating the actor of the event |
guint32 zeitgeist_event_get_id (ZeitgeistEvent *event
);
Get the event id as assigned by the Zeitgeist engine.
|
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. |
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
|
The event to get the interpretation of |
Returns : |
The event interpretation as a URI or NULL if unset |
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
|
The event to get the manifestation of |
Returns : |
The event interpretation as a URI or NULL if unset |
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.
|
The event to get the origin from |
Returns : |
The origin of event . |
Since 0.3.14
GByteArray * zeitgeist_event_get_payload (ZeitgeistEvent *event
);
Look up the free form binary payload of 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. |
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()
.
|
The event to get a subject for |
|
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. |
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()
.
|
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. |
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()
|
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()
.
|
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()
|
ZeitgeistEvent * zeitgeist_event_new_full (const gchar *interpretation
,const gchar *manifestation
,const gchar *actor
,...
);
Create a new event structure with predefined data
|
The interpretation type of the event. See ZEITGEIST_ZG_EVENT_INTERPRETATION for a list of event interpretation types |
|
The manifestation type of the event. See ZEITGEIST_ZG_EVENT_MANIFESTATION for a list of event manifestation types |
|
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()
|
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
|
The manifestation type of the event. See ZEITGEIST_ZG_EVENT_MANIFESTATION for a list of event manifestation types |
|
The actor triggering the event. See zeitgeist_event_set_actor()
for details on how to encode this. |
|
A va_list of ZeitgeistSubjects terminated by NULL
|
gint zeitgeist_event_num_subjects (ZeitgeistEvent *event
);
Get the number of subjects for an event. This is a constant time operation.
|
The event to get the number of subjects for |
Returns : |
The number of subjects for this event. |
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
|
The event to set the actor for |
|
URI designating the actor triggering the event. Fx. 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()
.
|
The event to get the event id for |
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
|
The event to set the interpretation of |
|
URI designating the interpretation type of the event |
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
|
The event to set the manifestation of |
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.
|
The event to set the origin of |
|
The origin to set |
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.
|
Event to add the payload to |
|
The payload to add to event . [transfer-full]
|
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.
|
The event to set the timestamp for |
GVariant * zeitgeist_event_to_variant (ZeitgeistEvent *event
);
Serialize a ZeitgeistEvent to a GVariant. The reverse operation
is zeitgeist_event_new_from_variant()
.
|
The ZeitgeistEvent to serialize to a GVariant |
Returns : |
A floating reference to a GVariant with signature ZEITGEIST_EVENT_VARIANT_SIGNATURE |
GPtrArray * zeitgeist_events_from_valist (va_list events
);
Utility function to convert a va_list of ZeitgeistEvent into a GPtrArray containing these 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()
|
GPtrArray * zeitgeist_events_from_variant (GVariant *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() . |
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.
|
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() . |