ZeitgeistLog

## ZeitgeistLog ZeitgeistLog — Primary access point for talking to the Zeitgeist daemon |

## Synopsis

    #include <zeitgeist.h>

                        ZeitgeistLog;
    struct              ZeitgeistLogClass;
    void                zeitgeist_log_delete_events         (ZeitgeistLog *self,
                                                             GArray *event_ids,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            zeitgeist_log_delete_events_finish  (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);
    void                zeitgeist_log_delete_log            (ZeitgeistLog *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            zeitgeist_log_delete_log_finish     (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);
    void                zeitgeist_log_find_event_ids        (ZeitgeistLog *self,
                                                             ZeitgeistTimeRange *time_range,
                                                             GPtrArray *event_templates,
                                                             ZeitgeistStorageState storage_state,
                                                             guint32 num_events,
                                                             ZeitgeistResultType result_type,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GArray *            zeitgeist_log_find_event_ids_finish (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);
    void                zeitgeist_log_find_events           (ZeitgeistLog *self,
                                                             ZeitgeistTimeRange *time_range,
                                                             GPtrArray *event_templates,
                                                             ZeitgeistStorageState storage_state,
                                                             guint32 num_events,
                                                             ZeitgeistResultType result_type,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    ZeitgeistResultSet * zeitgeist_log_find_events_finish   (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);
    void                zeitgeist_log_find_related_uris     (ZeitgeistLog *self,
                                                             ZeitgeistTimeRange *time_range,
                                                             GPtrArray *event_templates,
                                                             GPtrArray *result_event_templates,
                                                             ZeitgeistStorageState storage_state,
                                                             guint32 num_events,
                                                             ZeitgeistResultType result_type,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gchar **            zeitgeist_log_find_related_uris_finish
                                                            (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);
    ZeitgeistLog *      zeitgeist_log_get_default           (void);
    void                zeitgeist_log_get_events            (ZeitgeistLog *self,
                                                             GArray *event_ids,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    ZeitgeistResultSet * zeitgeist_log_get_events_finish    (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);
    void                zeitgeist_log_get_version           (ZeitgeistLog *self,
                                                             gint *major,
                                                             gint *minor,
                                                             gint *micro);
    void                zeitgeist_log_insert_events         (ZeitgeistLog *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data,
                                                             ...);
    GArray *            zeitgeist_log_insert_events_finish  (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);
    void                zeitgeist_log_insert_events_from_ptrarray
                                                            (ZeitgeistLog *self,
                                                             GPtrArray *events,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    void                zeitgeist_log_insert_events_no_reply
                                                            (ZeitgeistLog *self,
                                                             ...);
    void                zeitgeist_log_insert_events_valist  (ZeitgeistLog *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data,
                                                             va_list events);
    void                zeitgeist_log_install_monitor       (ZeitgeistLog *self,
                                                             ZeitgeistMonitor *monitor);
    gboolean            zeitgeist_log_is_connected          (ZeitgeistLog *self);
    ZeitgeistLog *      zeitgeist_log_new                   (void);
    void                zeitgeist_log_quit                  (ZeitgeistLog *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            zeitgeist_log_quit_finish           (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);
    void                zeitgeist_log_remove_monitor        (ZeitgeistLog *self,
                                                             ZeitgeistMonitor *monitor);

## Object Hierarchy

      GObject
       +----ZeitgeistLog

## Properties

      "connected"                gboolean              : Read

## Description

ZeitgeistLog encapsulates the low level access to the Zeitgeist daemon. You can use it to manage the log by inserting and deleting entries as well as do queries on the logged data.

It's important to realize that the ZeitgeistLog class does not expose any API that does synchronous communications with the message bus - everything is asynchronous. To ease development some of the methods have variants that are "fire and forget" ignoring the normal return value, so that callbacks does not have to be set up.

## Details

### ZeitgeistLog

    typedef struct _ZeitgeistLog ZeitgeistLog;

### struct ZeitgeistLogClass

    struct ZeitgeistLogClass {
      GObjectClass parent_class;
    };

### zeitgeist_log_delete_events ()

    void                zeitgeist_log_delete_events         (ZeitgeistLog *self,
                                                             GArray *event_ids,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

### zeitgeist_log_delete_events_finish ()

    gboolean            zeitgeist_log_delete_events_finish  (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);

### zeitgeist_log_delete_log ()

    void                zeitgeist_log_delete_log            (ZeitgeistLog *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

### zeitgeist_log_delete_log_finish ()

    gboolean            zeitgeist_log_delete_log_finish     (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);

### zeitgeist_log_find_event_ids ()

    void                zeitgeist_log_find_event_ids        (ZeitgeistLog *self,
                                                             ZeitgeistTimeRange *time_range,
                                                             GPtrArray *event_templates,
                                                             ZeitgeistStorageState storage_state,
                                                             guint32 num_events,
                                                             ZeitgeistResultType result_type,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

### zeitgeist_log_find_event_ids_finish ()

    GArray *            zeitgeist_log_find_event_ids_finish (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);

### zeitgeist_log_find_events ()

    void                zeitgeist_log_find_events           (ZeitgeistLog *self,
                                                             ZeitgeistTimeRange *time_range,
                                                             GPtrArray *event_templates,
                                                             ZeitgeistStorageState storage_state,
                                                             guint32 num_events,
                                                             ZeitgeistResultType result_type,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

### zeitgeist_log_find_events_finish ()

    ZeitgeistResultSet * zeitgeist_log_find_events_finish   (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);

Retrieve the result from an asynchronous query started with `zeitgeist_log_find_events()`.

Returns : | A newly allocated ZeitgeistResultSet containing the ZeitgeistEvents matching the query. You must free the result set with `g_object_unref()`. The events held in the result set will automatically be unreffed when the result set is finalized. [transfer-full]

### zeitgeist_log_find_related_uris ()

    void                zeitgeist_log_find_related_uris     (ZeitgeistLog *self,
                                                             ZeitgeistTimeRange *time_range,
                                                             GPtrArray *event_templates,
                                                             GPtrArray *result_event_templates,
                                                             ZeitgeistStorageState storage_state,
                                                             guint32 num_events,
                                                             ZeitgeistResultType result_type,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

### zeitgeist_log_find_related_uris_finish ()

    gchar **            zeitgeist_log_find_related_uris_finish
                                                            (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);

### zeitgeist_log_get_default ()

    ZeitgeistLog *      zeitgeist_log_get_default           (void);

See `zeitgeist_log_new()` for more information.

Returns : | A unique ZeitgeistLog. Do not ref or unref it. [transfer none]

Since 0.3.14

### zeitgeist_log_get_events ()

    void                zeitgeist_log_get_events            (ZeitgeistLog *self,
                                                             GArray *event_ids,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

### zeitgeist_log_get_events_finish ()

    ZeitgeistResultSet * zeitgeist_log_get_events_finish    (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);

### zeitgeist_log_get_version ()

    void                zeitgeist_log_get_version           (ZeitgeistLog *self,
                                                             gint *major,
                                                             gint *minor,
                                                             gint *micro);

Gets version of currently running Zeitgeist daemon.

This method will return the version of Zeitgeist daemon this instance is connected to. If you call this method right after `zeitgeist_log_new()`, only zeros will be returned, a valid version number will only be returned once this instance successfully connected to the Zeitgeist daemon - ie the value of the "connected" property must be TRUE (you can connect to the "notify::connected" signal otherwise).

`self` : | A ZeitgeistLog instance
`major` : | Location for the major version. [out]
`minor` : | Location for the minor version. [out]
`micro` : | Location for the micro version. [out]

### zeitgeist_log_insert_events ()

    void                zeitgeist_log_insert_events         (ZeitgeistLog *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data,
                                                             ...);

Asynchronously send a set of events to the Zeitgeist daemon, requesting they be inserted into the log.

`self` : | The log logging the events
`cancellable` : | To cancel the operation or `NULL`
`callback` : | GAsyncReadyCallback to invoke once the logging operation has completed. Set to `NULL` to ignore the result. In this callback you can invoke `zeitgeist_log_insert_events_finish()` to collect the event ids of the inserted events
`user_data` : | Any user data to pass back to `callback`

### zeitgeist_log_insert_events_finish ()

    GArray *            zeitgeist_log_insert_events_finish  (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);

### zeitgeist_log_insert_events_from_ptrarray ()

    void                zeitgeist_log_insert_events_from_ptrarray
                                                            (ZeitgeistLog *self,
                                                             GPtrArray *events,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously send a set of events to the Zeitgeist daemon, requesting they be inserted into the log.

`self` : | The log logging the events
`events` : | A GPtrArray of ZeitgeistEvents to insert. This method steals the reference to `events` and consumes all floating refs on the event members. It is assumed that the free_func on `events` is set to `g_object_unref()`.
`cancellable` : | To cancel the operation or `NULL`
`callback` : | GAsyncReadyCallback to invoke once the logging operation has completed. Set to `NULL` to ignore the result. In this callback you can invoke `zeitgeist_log_insert_events_finish()` to collect the event ids of the inserted events
`user_data` : | Any user data to pass back to `callback`

### zeitgeist_log_insert_events_no_reply ()

    void                zeitgeist_log_insert_events_no_reply
                                                            (ZeitgeistLog *self,
                                                             ...);

Asynchronously send a set of events to the Zeitgeist daemon, requesting they be inserted into the log. This method is "fire and forget" and the caller will never know whether the events was successfully inserted or not.

This method is exactly equivalent to calling `zeitgeist_log_insert_events()` with `NULL` set as `cancellable`, `callback`, and `user_data`.

`self` : | The log logging the events

### zeitgeist_log_insert_events_valist ()

    void                zeitgeist_log_insert_events_valist  (ZeitgeistLog *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data,
                                                             va_list events);

This method is intended for language bindings. If calling this function from C code it's generally more handy to use `zeitgeist_log_insert_events()` or `zeitgeist_log_insert_events_from_ptrarray()`.

Asynchronously send a set of events to the Zeitgeist daemon, requesting they be inserted into the log.

`self` : | The log logging the events
`cancellable` : | To cancel the operation or `NULL`
`callback` : | GAsyncReadyCallback to invoke once the logging operation has completed. Set to `NULL` to ignore the result. In this callback you can invoke `zeitgeist_log_insert_events_finish()` to collect the event ids of the inserted events
`user_data` : | Any user data to pass back to `callback`
`events` : | A GPtrArray of ZeitgeistEvents to insert. This method steals the reference to `events` and consumes all floating refs on the event members.

### zeitgeist_log_install_monitor ()

    void                zeitgeist_log_install_monitor       (ZeitgeistLog *self,
                                                             ZeitgeistMonitor *monitor);

### zeitgeist_log_is_connected ()

    gboolean            zeitgeist_log_is_connected          (ZeitgeistLog *self);

### zeitgeist_log_new ()

    ZeitgeistLog *      zeitgeist_log_new                   (void);

The ZeitgeistLog object will asynchronously start to connect to the Zeitgeist daemon. Any request you send to via this log object will be queued until the connection is ready - at which point you will get a notify signal on the "connected" property.

It isn't recommended to call this function more than once. If you need to access ZeitgeistLog from different parts of your codebase, consider using `zeitgeist_log_get_default()` instead.

Returns : | A reference to a newly allocated log.

### zeitgeist_log_quit ()

    void                zeitgeist_log_quit                  (ZeitgeistLog *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

### zeitgeist_log_quit_finish ()

    gboolean            zeitgeist_log_quit_finish           (ZeitgeistLog *self,
                                                             GAsyncResult *res,
                                                             GError **error);

### zeitgeist_log_remove_monitor ()

    void                zeitgeist_log_remove_monitor        (ZeitgeistLog *self,
                                                             ZeitgeistMonitor *monitor);

## Property Details

### The `"connected"` property

      "connected"                gboolean              : Read

Determines if this Log instance is currently connected to Zeitgeist daemon.

Default value: FALSE