XesamGHit

XesamGHit — A single hit mapping the metadata requested from the search engine

Synopsis

                    XesamGHitPrivate;
                    XesamGHit;
guint               xesam_g_hit_get_field_id            (XesamGHit *hit,
                                                         const gchar *field_name);
const GValue*       xesam_g_hit_get_field               (XesamGHit *hit,
                                                         const gchar *field_name);
const gchar*        xesam_g_hit_get_string              (XesamGHit *hit,
                                                         const gchar *field_name);
const GValue*       xesam_g_hit_get_field_by_id         (XesamGHit *hit,
                                                         guint field_id);
guint               xesam_g_hit_get_id                  (XesamGHit *hit);
gchar**             xesam_g_hit_get_field_names         (XesamGHit *hit);
guint               xesam_g_hit_num_fields              (XesamGHit *hit);

Object Hierarchy

  GObject
   +----XesamGHit

Description

The XesamGHit class conveniently maps the fields specified in the originating session's "hit-fields" property.

XesamGHit is available since 1.0

Details

XesamGHitPrivate

typedef struct _XesamGHitPrivate XesamGHitPrivate;


XesamGHit

typedef struct _XesamGHit XesamGHit;


xesam_g_hit_get_field_id ()

guint               xesam_g_hit_get_field_id            (XesamGHit *hit,
                                                         const gchar *field_name);

Used to look up a handle to read a given field by. This can be used to speed up field lookups.

The implementation guarantees that all XesamGHit objects read from the same XesamGHits object must use the same field ids. Thus this handle can be re-used on several hits from the same parent XesamGHits object.

You can always access field by name with xesam_g_hit_get_field().

hit :

The hit object on which to look up a field id

field_name :

The name of the field to look up the id for

Returns :

An integer id that can be used for fast field lookups with xesam_g_hit_get_field_by_id()

xesam_g_hit_get_field ()

const GValue*       xesam_g_hit_get_field               (XesamGHit *hit,
                                                         const gchar *field_name);

Get the value of a field by name look up. This method has the overhead of a hash table look up. For even faster access use xesam_g_hit_get_field_by_id() if you know the array index of the field in the session's "hit-fields" property.

If you know the data type of the field beforehand you can use the convenience method xesam_g_hit_get_string() to access the field value.

Field Value Types

The returned GValue will hold a data type as described below. The field data type as defined by the relevant ontology is on the left:

string 

G_TYPE_STRING

integer 

G_TYPE_INT

float 

G_TYPE_FLOAT

boolean 

G_TYPE_BOOLEAN

date 

An ISO-8601 encoded date in a G_TYPE_STRING

uri 

An URI encoded in a G_TYPE_STRING

list of strings 

G_TYPE_STRV

list of integers 

a GArray holding gints

list of floats 

A GArray holding gfloats

list of booleans 

a GArray holding gbooleans

list of dates 

A G_TYPE_STRV with dates formatted as described under the date entry

list of uris 

A G_TYPE_STRV holding the URI strings

hit :

The hit object on which to look up a field value

field_name :

The fully qualified name of the field as set through the session property "hit-fields".

Returns :

The value of a named field. If the field is not known NULL is returned. See below for details on the returned GValue.

xesam_g_hit_get_string ()

const gchar*        xesam_g_hit_get_string              (XesamGHit *hit,
                                                         const gchar *field_name);

Look up the value of a field containing a string. For generic field value look ups use xesam_g_hit_get_field().

hit :

The hit to look up a string valued field on

field_name :

Returns :

The string value of the field. The memory allocated by the string is private to the hit and should not be freed.

xesam_g_hit_get_field_by_id ()

const GValue*       xesam_g_hit_get_field_by_id         (XesamGHit *hit,
                                                         guint field_id);

Look up a field value based on the offset of the field name in the sessions "hit-fields" property.

To look up a field by name use xesam_g_hit_get_field().

hit :

The hit object on which to look up a field value

field_id :

The offset into the array of field names provided when requesting the hits. Normally when receiving hits via the search' "hits-ready" signal this will be equal to the offset of the field name into the session's "hit-fields" property, but if you request hits by other means (fx. by calling xesam_g_search_request_extended_data()) this may not be true. Consult the documentation of the relevant methods in that case.

Returns :

The value of a field given by its offset in the session's hit-fields property. See xesam_g_hit_get_field() for details on the return value

xesam_g_hit_get_id ()

guint               xesam_g_hit_get_id                  (XesamGHit *hit);

The Hit id is the offset of the hit within the scope of all results returned by a XesamGSearch.

hit :

The hit to get the id for

Returns :

The hit id. This is defined as the offset of the hit relative to the total number of hits retrieved from the server.

xesam_g_hit_get_field_names ()

gchar**             xesam_g_hit_get_field_names         (XesamGHit *hit);

Return a NULL terminated array listing the field names used in this Hit. You must free the array with g_strfreev().

hit :

The hit object for which to list the field names

Returns :

A NULL terminated array of strings

xesam_g_hit_num_fields ()

guint               xesam_g_hit_num_fields              (XesamGHit *hit);

hit :

The hit object for which to count the number of fields

Returns :

The number of fields present in the hit