ZeitgeistEvent

## 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()`.