ZeitgeistResultSet

ZeitgeistResultSet — Cursor-like interface for results sets

Synopsis

#include <zeitgeist.h>

struct              ZeitgeistResultSetIface;
                    ZeitgeistResultSet;
guint               zeitgeist_result_set_size           (ZeitgeistResultSet *self);
guint               zeitgeist_result_set_estimated_matches
                                                        (ZeitgeistResultSet *self);
ZeitgeistEvent *    zeitgeist_result_set_next           (ZeitgeistResultSet *self);
gboolean            zeitgeist_result_set_has_next       (ZeitgeistResultSet *self);
ZeitgeistEvent *    zeitgeist_result_set_peek           (ZeitgeistResultSet *self);
void                zeitgeist_result_set_seek           (ZeitgeistResultSet *self,
                                                         guint pos);
guint               zeitgeist_result_set_tell           (ZeitgeistResultSet *self);

Object Hierarchy

  GInterface
   +----ZeitgeistResultSet

Prerequisites

ZeitgeistResultSet requires GObject.

Description

Interface for results returned by zeitgeist_log_find_events(), zeitgeist_log_get_events(), and zeitgeist_index_search().

This interface utilizes a cursor-like metaphor. You advance the cursor by calling zeitgeist_result_set_next() or adjust it manually by calling zeitgeist_result_set_seek().

Calling zeitgeist_result_set_next() will also return the event at the current cursor position. You may retrieve the current event without advancing the cursor by calling zeitgeist_result_set_peek().

Details

struct ZeitgeistResultSetIface

struct ZeitgeistResultSetIface {
  GTypeInterface g_iface;

  guint           (*size)              (ZeitgeistResultSet *self);

  guint           (*estimated_matches) (ZeitgeistResultSet *self);

  ZeitgeistEvent* (*next)              (ZeitgeistResultSet *self);

  gboolean        (*has_next)          (ZeitgeistResultSet *self);
  
  ZeitgeistEvent* (*peek)              (ZeitgeistResultSet *self);

  void            (*seek)              (ZeitgeistResultSet *self,
                                        guint               pos);

  guint           (*tell)              (ZeitgeistResultSet *self);
};


ZeitgeistResultSet

typedef struct _ZeitgeistResultSet ZeitgeistResultSet;


zeitgeist_result_set_size ()

guint               zeitgeist_result_set_size           (ZeitgeistResultSet *self);

Get the number of ZeitgeistEvents held in a ZeitgeistResultSet. Unlike the number obtained from zeitgeist_result_set_estimated_matches() the size of the result set is always equal to the number of times you can call zeitgeist_result_set_next().

self :

The ZeitgeistResultSet to get the size of

Returns :

The number of events held in the result set

zeitgeist_result_set_estimated_matches ()

guint               zeitgeist_result_set_estimated_matches
                                                        (ZeitgeistResultSet *self);

Get an estimated total number of matches that would have been for the query that generated the result set had it not been restricted in size.

For zeitgeist_log_find_events() and zeitgeist_log_get_events() this will always be the same as zeitgeist_result_set_size(). For cases like zeitgeist_index_search() where you specify a subset of the hits to retrieve the estimated match count will often be bigger than the result set size.

self :

The ZeitgeistResultSet to get the number of estimated matches on

Returns :

The number of events that matched the query

zeitgeist_result_set_next ()

ZeitgeistEvent *    zeitgeist_result_set_next           (ZeitgeistResultSet *self);

Get the current event from the result set and advance the cursor. To ensure that calls to this method will succeed you can call zeitgeist_result_set_has_next().

To retrieve the current event without advancing the cursor call zeitgeist_result_set_peek() in stead of this method.

self :

The ZeitgeistResultSet to get an event from

Returns :

The ZeitgeistEvent at the current cursor position

zeitgeist_result_set_has_next ()

gboolean            zeitgeist_result_set_has_next       (ZeitgeistResultSet *self);

Check if a call to zeitgeist_result_set_next() will succeed.

self :

The ZeitgeistResultSet to check

Returns :

TRUE if and only if more events can be retrieved by calling zeitgeist_result_set_next()

zeitgeist_result_set_peek ()

ZeitgeistEvent *    zeitgeist_result_set_peek           (ZeitgeistResultSet *self);

Get the event at the current cursor position.

To retrieve the current event and advance the cursor position call zeitgeist_result_set_next() in stead of this method.

self :

The ZeitgeistResultSet to get an event from

Returns :

The ZeitgeistEvent at the current cursor position

zeitgeist_result_set_seek ()

void                zeitgeist_result_set_seek           (ZeitgeistResultSet *self,
                                                         guint pos);

Set the cursor position. Following calls to zeitgeist_result_set_peek() or zeitgeist_result_set_next() will read the event at position pos.

self :

The ZeitgeistResultSet to seek in

pos :

The position to seek to

zeitgeist_result_set_tell ()

guint               zeitgeist_result_set_tell           (ZeitgeistResultSet *self);

Get the current position of the cursor.

self :

The ZeitgeistResultSet to check the cursor position for

Returns :

The current position of the cursor