ZeitgeistResultSet

ZeitgeistResultSet — Cursor-like interface for results sets

Functions

Types and Values

Object Hierarchy

    GInterface
    ╰── ZeitgeistResultSet

Prerequisites

ZeitgeistResultSet requires GObject.

Includes

#include <zeitgeist.h>

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

Functions

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

self

The ZeitgeistResultSet to check the cursor position for

 

Returns

The current position of the cursor

Types and Values

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;