ZeitgeistEvent

ZeitgeistEvent — ZetigeistEvent objects abstract events returned from Zeitgeist queries

Synopsis

#include <zeitgeist.h>

                    ZeitgeistEvent;
                    ZeitgeistEventClass;
ZeitgeistEvent*     zeitgeist_event_new                 (void);
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);
guint32             zeitgeist_event_get_id              (ZeitgeistEvent *event);
void                zeitgeist_event_set_id              (ZeitgeistEvent *event,
                                                         guint32 id);
gint64              zeitgeist_event_get_timestamp       (ZeitgeistEvent *event);
void                zeitgeist_event_set_timestamp       (ZeitgeistEvent *event,
                                                         gint64 timestamp);
const gchar*        zeitgeist_event_get_interpretation  (ZeitgeistEvent *event);
void                zeitgeist_event_set_interpretation  (ZeitgeistEvent *event,
                                                         const gchar *interpretation);
const gchar*        zeitgeist_event_get_manifestation   (ZeitgeistEvent *event);
void                zeitgeist_event_set_manifestation   (ZeitgeistEvent *event,
                                                         const gchar *manifestation);
const gchar*        zeitgeist_event_get_actor           (ZeitgeistEvent *event);
void                zeitgeist_event_set_actor           (ZeitgeistEvent *event,
                                                         const gchar *actor);
void                zeitgeist_event_set_actor_from_app_info
                                                        (ZeitgeistEvent *event,
                                                         GAppInfo *appinfo);
ZeitgeistSubject *  zeitgeist_event_get_subject         (ZeitgeistEvent *event,
                                                         gint index);
gint                zeitgeist_event_num_subjects        (ZeitgeistEvent *event);
void                zeitgeist_event_add_subject         (ZeitgeistEvent *event,
                                                         ZeitgeistSubject *subject);
GByteArray*         zeitgeist_event_get_payload         (ZeitgeistEvent *event);
void                zeitgeist_event_set_payload         (ZeitgeistEvent *event,
                                                         GByteArray *payload);

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;

ZeitgeistEventClass

typedef struct {
  GInitiallyUnownedClass parent_class;
} ZeitgeistEventClass;

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_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.

... :

 A list of ZeitgeistSubject instances terminated by a NULL

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_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

interpretation :

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

Returns :

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_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 zeitgest_log_insert_events().

event :

 The event to get the event id for

id :

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_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

timestamp :

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_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_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_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

manifestation :

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 app:// URI scheme with the base name of the .desktop file for the application appended. Eg. app://firefox.desktop

event :

 The event to set the actor for

Returns :

 A URI designating the actor of the 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 app:// URI scheme with the base name of the .desktop file for the application appended. Eg. app://firefox.desktop

event :

 The event to set the actor for

actor :

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

zeitgeist_event_set_actor_from_app_info ()

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

event :

appinfo :

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_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_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_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_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]
Generated by GTK-Doc V1.15