XesamGHits

XesamGHits — Container used to encapsulate a batch of XesamGHit objects

Synopsis

                    XesamGHitsPrivate;
                    XesamGHits;
guint               xesam_g_hits_get_count              (XesamGHits *hits);
XesamGHit*          xesam_g_hits_get                    (XesamGHits *hits,
                                                         guint offset);
XesamGHit*          xesam_g_hits_next                   (XesamGHits *hits,
                                                         XesamGHit *hit);
guint               xesam_g_hits_get_hit_id             (XesamGHits *hits,
                                                         guint offset);
gpointer            xesam_g_hits_get_user_data          (XesamGHits *hits);

Object Hierarchy

  GObject
   +----XesamGHits

Properties

  "field-map"                GHashTable*           : Write / Construct Only
  "hits-data"                gpointer              : Write / Construct Only
  "notify-search"            gboolean              : Read / Write
  "search"                   XesamGSearch*         : Write / Construct Only
  "user-data"                gpointer              : Read / Write / Construct Only
  "user-data-destroy"        gpointer              : Write / Construct Only

Description

Container for conveniently handling and managing a batch of XesamGHit objects.

XesamGHits is available since 1.0

Details

XesamGHitsPrivate

typedef struct _XesamGHitsPrivate XesamGHitsPrivate;


XesamGHits

typedef struct _XesamGHits XesamGHits;


xesam_g_hits_get_count ()

guint               xesam_g_hits_get_count              (XesamGHits *hits);

Calling this method will not cause hit retrieval to continue automatically.

hits :

The hits object to get the hit count on

Returns :

The number of hits in the XesamGHits object

xesam_g_hits_get ()

XesamGHit*          xesam_g_hits_get                    (XesamGHits *hits,
                                                         guint offset);

Get a handle to the n'th XesamGHit in a XesamGHits object.

XesamGHit objects are generated lazily and cached. The hit is cached in the XesamGHits object for the entire lifetime of the parent hits.

If you need a reference to the hit past the lifetime of the XesamGHits object's lifetime you need to reference the XesamGHit object.

Calling this method will cause the parent XesamGSearch object to start reading the next batch of hits from the server, if it hasn't already done so. You can disable this feature by setting the property "auto-continue" to FALSE on the parent XesamGSearch object.

hits :

The XesamGHits object to retrieve a hit from

offset :

Offset in the XesamGHits of the hit to retrieve

Returns :

The hit at the specified offset or NULL if the offset is out of bounds

xesam_g_hits_next ()

XesamGHit*          xesam_g_hits_next                   (XesamGHits *hits,
                                                         XesamGHit *hit);

Use this method to conveniently iterate through a XesamGHits object.

Calling this method will cause the parent XesamGSearch object to start reading the next batch of hits from the server, if it hasn't already done so. You can disable this feature by setting the property "auto-continue" to FALSE on the parent XesamGSearch object.

Here is a simple example on how to employ xesam_g_hits_next()

  static void
  print_hit_urls (XesamGHits *hits)
  {
    XesamGHit	*hit;
   
    hit = NULL;
    while ((hit = xesam_g_hits_next (hits, hit))) {
      g_printf ("%d: %s\n",
                xesam_g_hit_get_id (hit),
                xesam_g_hit_get_string (hit, "xesam:url"));
    }
  }

hits :

The XesamGHits object to read the next hit from

hit :

The hit after which the following should be returned. If hit is NULL then the first hit will be returned

Returns :

The hit immediately following hit in hits, or NULL if hit is the last hit in hits. Note that for some hit subclasses the next hit may not be the one with hit id incremented by one.

xesam_g_hits_get_hit_id ()

guint               xesam_g_hits_get_hit_id             (XesamGHits *hits,
                                                         guint offset);

Get the hit id of a hit.

Recall that the id of a hit correspond to the sequence number in which it was read from the server.

Calling this method will not cause hit retrieval to continue automatically.

hits :

The XesamGHits to inspect

offset :

The offset of the hit in the XesamGHits to inspect the id of

Returns :

The hit id of the hit at the specified offset. In case offset is out of bounds 0 will be returned and a critical error logged. Note that checking for 0 is not a reliable error condition as the very first hit in a search will have id 0.

xesam_g_hits_get_user_data ()

gpointer            xesam_g_hits_get_user_data          (XesamGHits *hits);

Convenience method to access the "user-data" property

hits :

The XesamGHits to look up user data on

Returns :

The user data associated with these hits

Property Details

The "field-map" property

  "field-map"                GHashTable*           : Write / Construct Only

A GHashTable mapping field names to offsets into the GPtrArrays contained in "hit-data".


The "hits-data" property

  "hits-data"                gpointer              : Write / Construct Only

The raw hit data encapsulated as a GPtrArray of GPtrArrays. Each child-GPtrArray contains GValues ordered arcording to the session property "hit-fields".


The "notify-search" property

  "notify-search"            gboolean              : Read / Write

Whether to call xesam_g_search_continue() when calls to either xesam_g_hits_get() or xesam_g_hits_next() are detected.

Default value: FALSE


The "search" property

  "search"                   XesamGSearch*         : Write / Construct Only

The XesamGSearch that spawned this XesamGHits object


The "user-data" property

  "user-data"                gpointer              : Read / Write / Construct Only

User data supplied by the parent XesamGSearch object. This can either be set on the search with xesam_g_search_set_user_data() or be provided via calls like xesam_g_search_request_extended_data().


The "user-data-destroy" property

  "user-data-destroy"        gpointer              : Write / Construct Only

A GDestroyNotify used to free any user_data associated with this hits object.