ZeitgeistIndex

ZeitgeistIndex — Query the Zeitgeist Full Text Search Extension

Synopsis

#include <zeitgeist.h>

                    ZeitgeistIndex;
                    ZeitgeistIndexClass;
ZeitgeistIndex*     zeitgeist_index_new                 (void);
void                zeitgeist_index_search              (ZeitgeistIndex *self,
                                                         const gchar *query,
                                                         ZeitgeistTimeRange *time_range,
                                                         GPtrArray *event_templates,
                                                         guint32 offset,
                                                         guint32 num_events,
                                                         ZeitgeistResultType result_type,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
ZeitgeistResultSet * zeitgeist_index_search_finish      (ZeitgeistIndex *self,
                                                         GAsyncResult *res,
                                                         GError **error);

Object Hierarchy

  GObject
   +----ZeitgeistIndex

Description

Details

ZeitgeistIndex

typedef struct _ZeitgeistIndex ZeitgeistIndex;


ZeitgeistIndexClass

typedef struct {
  GObjectClass parent_class;
} ZeitgeistIndexClass;


zeitgeist_index_new ()

ZeitgeistIndex*     zeitgeist_index_new                 (void);

Index instances are not overly expensive for neither client or the Zeitgeist daemon so there's no need to go to lenghts to keep singleton instances around.

Returns :

A reference to a newly allocated index.

zeitgeist_index_search ()

void                zeitgeist_index_search              (ZeitgeistIndex *self,
                                                         const gchar *query,
                                                         ZeitgeistTimeRange *time_range,
                                                         GPtrArray *event_templates,
                                                         guint32 offset,
                                                         guint32 num_events,
                                                         ZeitgeistResultType result_type,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Perform a full text search possibly restricted to a ZeitgeistTimeRange and/or set of event templates.

The default boolean operator is AND. Thus the query foo bar will be interpreted as foo AND bar. To exclude a term from the result set prepend it with a minus sign - eg foo -bar. Phrase queries can be done by double quoting the string "foo is a bar". You can truncate terms by appending a *.

There are a few keys you can prefix to a term or phrase to search within a specific set of metadata. They are used like key:value. The keys name and title search strictly within the text field of the event subjects. The key app searches within the application name or description that is found in the actor attribute of the events. Lastly you can use the site key to search within the domain name of the subject URIs.

You can also control the results with theboolean operators AND and OR and you may use brackets, ( and ), to control the operator presedence.

self :

The ZeitgeistIndex you want to query

query :

The search string to send to Zeitgeist

time_range :

Restrict matched events to ones within this time range. If you are not interested in restricting the timerange pass zeitgeist_time_range_new_anytime() as Zeitgeist will detect this and optimize the query accordingly

event_templates :

Restrict matches events to ones matching these templates

offset :

Offset into the result set to read events from

num_events :

Maximal number of events to retrieve

result_type :

The ZeitgeistResultType determining the sort order. You may pass ZEITGEIST_RESULT_TYPE_RELEVANCY to this method to have the results ordered by relevancy calculated in relation to query

cancellable :

A GCancellable used to cancel the call or NULL

callback :

A GAsyncReadyCallback to invoke when the search results are ready

user_data :

User data to pass back with callback

zeitgeist_index_search_finish ()

ZeitgeistResultSet * zeitgeist_index_search_finish      (ZeitgeistIndex *self,
                                                         GAsyncResult *res,
                                                         GError **error);

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

The total hit count of the query will be avilable via the returned result set by calling zeitgeist_result_set_estimated_matches(). This will often be bigger than actual number of events held in the result set, which is limited by the num_events paramter passed to zeitgeist_index_search().

self :

The ZeitgeistIndex to retrieve results from

res :

The GAsyncResult you received in the GAsyncReadyCallback you passed to zeitgeist_index_search()

error :

A place to store a GError or NULL in case you want to ignore errors

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 it is finalized.