XesamGSearch

XesamGSearch — Client side representation of a search

Synopsis

                    XesamGSearchPrivate;
                    XesamGSearch;
gboolean            xesam_g_search_is_ready             (XesamGSearch *search);
void                xesam_g_search_start                (XesamGSearch *search);
gboolean            xesam_g_search_is_running           (XesamGSearch *search);
void                xesam_g_search_close                (XesamGSearch *search);
gboolean            xesam_g_search_is_closed            (XesamGSearch *search);
gboolean            xesam_g_search_is_done              (XesamGSearch *search);
void                xesam_g_search_continue             (XesamGSearch *search);
guint               xesam_g_search_get_num_found        (XesamGSearch *search);
guint               xesam_g_search_get_num_read         (XesamGSearch *search);
void                xesam_g_search_get_extended_data    (XesamGSearch *search,
                                                         guint *hit_ids);
XesamGSession*      xesam_g_search_get_session          (XesamGSearch *search);
const gchar*        xesam_g_search_get_id               (XesamGSearch *search);
guint               xesam_g_search_get_max_batch_size   (XesamGSearch *search);
void                xesam_g_search_set_max_batch_size   (XesamGSearch *search,
                                                         guint max_size);
const GError*       xesam_g_search_get_last_error       (XesamGSearch *search);

Object Hierarchy

  GObject
   +----XesamGSearch

Properties

  "max-batch-size"           guint                 : Read / Write

Signals

  "closed"                                         : Run Last
  "done"                                           : Run Last
  "error"                                          : Run Last
  "extended-data-ready"                            : Run Last
  "hits-found"                                     : Run Last
  "hits-modified"                                  : Run Last
  "hits-ready"                                     : Run Last
  "hits-removed"                                   : Run Last
  "ready"                                          : Run Last
  "started"                                        : Run Last

Description

XesamGSearch is a client side representation of a search. A search is created via a XesamGSession object's xesam_g_session_new_search_from_text or xesam_g_session_new_search methods.

All communications with the search engine is completely asynchronous. When hits are available the "hits-ready" signal will be emitted.

A search will not emit any hits before xesam_g_search_start has been called on it.

XesamGSearch is available since 1.0

Details

XesamGSearchPrivate

typedef struct _XesamGSearchPrivate XesamGSearchPrivate;


XesamGSearch

typedef struct _XesamGSearch XesamGSearch;


xesam_g_search_is_ready ()

gboolean            xesam_g_search_is_ready             (XesamGSearch *search);

search :

The search to check for readiness

Returns :

TRUE if and only if the search has received a search handle from the server.

xesam_g_search_start ()

void                xesam_g_search_start                (XesamGSearch *search);

Instruct the server to start a given search. No hits will be returned before this method has been invoked.

search :

The search to start

xesam_g_search_is_running ()

gboolean            xesam_g_search_is_running           (XesamGSearch *search);

Check whether xesam_g_search_start() has been called on the XesamGSearch object.

search :

The search to inspect

Returns :

TRUE if and only if xesam_g_search_start(), but not xesam_g_search_close() has been invoked on the search object

xesam_g_search_close ()

void                xesam_g_search_close                (XesamGSearch *search);

Close a search. The server is allowed to free all resources related to the search when this method is invoked.

A closed search is considered invalid for further use.

There are two ways in which a search can automatically be closed. If the last reference to the search is dropped (the object is finalized), or if the parent session is closed.

A search will be marked closed as soon as xesam_g_search_close() is invoked. The "closed" signal will be emitted when the close request has been acknowledged by the underlying XesamGSearcher.

search :

The search to close

xesam_g_search_is_closed ()

gboolean            xesam_g_search_is_closed            (XesamGSearch *search);

Inspect whether xesam_g_search_close() has been called on a search. A search will be marked closed as soon as xesam_g_search_close() is invoked. The "closed" signal will be emitted when the close request has been acknowledged by the underlying XesamGSearcher.

search :

The search to inspect the state of

Returns :

TRUE if xesam_g_search_close() has been called on search.

xesam_g_search_is_done ()

gboolean            xesam_g_search_is_done              (XesamGSearch *search);

Inspect whether "done" has been emitted on a search. Note that even though the search is done hits might still be added in case the parent session is a live session - ie has the property "search-live" set to TRUE.

search :

The search to inspect the state of

Returns :

TRUE if and only id "done" has been emitted on search.

xesam_g_search_continue ()

void                xesam_g_search_continue             (XesamGSearch *search);

Tell a XesamGSearch that it should continue to fetch hits after a "hits-found" signal has been emitted. This method is automatically called if you call any method on a XesamGHits object passed via the "hits-ready" signal.

If you choose to ignore a XesamGHits object emitted with a "hits-ready" you must manually call this method before any more hits are retrieved from the server.

Under normal operations it is not necessary to invoke this method manually.

search :

The search to continue fetching hits for

xesam_g_search_get_num_found ()

guint               xesam_g_search_get_num_found        (XesamGSearch *search);

Look up how many hits have been found by this search in total. This does not necessarily equal the number of hits retrieved, but just the number registered on the server.

If you want to get the total number of hits matching a given search you should wait for the "done" signal before calling this method.

See also xesam_g_search_get_num_read().

search :

Search object for which to get the total number of found hits

Returns :

The total accumulated number of hits found by this search

xesam_g_search_get_num_read ()

guint               xesam_g_search_get_num_read         (XesamGSearch *search);

Look up how many hits have been read from the server. This is not necessarily equal to the actual number of hits found by the server. The number of hits read equals the cumulative number of hits emitted via the "hits-ready" signal.

Note that this method does not necessarily give the total number of found hits when "done" is emitted (xesam_g_search_get_num_found() will do that). The reason for this is that the read hits are only counted when the hits have been retrieved from the server, and the hits may arrive after the 'done' signal has been emitted.

See also xesam_g_search_get_num_found().

search :

Search object for which to get the number of hits retrieved from the the server

Returns :

The number of hits retrieved from the server

xesam_g_search_get_extended_data ()

void                xesam_g_search_get_extended_data    (XesamGSearch *search,
                                                         guint *hit_ids);

Read additional metadata fields from the search engine as specified in the session property "hit-fields"

Emits a "extened-data-ready" with a new XesamGHits object, when results are ready.

FIXME: It might be better to pass the actual hit objects as arguments. That way we can actual enrich the same hit objects.

FIXME: Not implemented.

search :

The search to which the hit id's are relative.

hit_ids :

An array of hit ids as returned from xesam_g_hit_get_id.

xesam_g_search_get_session ()

XesamGSession*      xesam_g_search_get_session          (XesamGSearch *search);

Look up the parent session for a search.

search :

The search to llok up parent session for

Returns :

The parent session for the given search

xesam_g_search_get_id ()

const gchar*        xesam_g_search_get_id               (XesamGSearch *search);

Get the unique id for a given search.

search :

The search to get the id for.

Returns :

The id. Do not modify this pointer. If the search has not yet emitted "ready" NULL will be returned

xesam_g_search_get_max_batch_size ()

guint               xesam_g_search_get_max_batch_size   (XesamGSearch *search);

Convenience method to get the value of the "max-batch-size" property.

search :

The search to set the max batch size for

Returns :

The maximum number of hits included in each XesamGHits

xesam_g_search_set_max_batch_size ()

void                xesam_g_search_set_max_batch_size   (XesamGSearch *search,
                                                         guint max_size);

Convenience method to set the value of the "max-batch-size" property.

search :

The search to set the max batch size for

max_size :

Maximum number of hits per XesamGHits object emitted

xesam_g_search_get_last_error ()

const GError*       xesam_g_search_get_last_error       (XesamGSearch *search);

See also the signal XesamGSearch::error

search :

The search to inspect for errors

Returns :

The last error encountered from the search engine. If no error(s) has happened NULL is returned

Property Details

The "max-batch-size" property

  "max-batch-size"           guint                 : Read / Write

Maximum number of hits per XesamGHits object, batches can still contain less.

Default value: 20

Signal Details

The "closed" signal

void                user_function                      (XesamGSearch *search,
                                                        gpointer      user_data)      : Run Last

Emitted when someone calls xesam_g_search_close. Note that this can also happen if someone closes the parent XesamGSession.

The search will also be closed on object finalization if it isn't already closed. No signal will be emitted in this case because the object will be under finalization.

search :

The object on which this signal is emitted

user_data :

user data set when the signal handler was connected.

The "done" signal

void                user_function                      (XesamGSearch *search,
                                                        gpointer      user_data)      : Run Last

Emitted when the search engine has finished searching its index.

If "search-live" is TRUE new hits can still be found if new items are created or changed to match the query.

Note that xesam_g_search_get_num_found() will give you the total number of found hits on the search, but xesam_g_search_get_num_read() may not.

search :

The object on which this signal is emitted

user_data :

user data set when the signal handler was connected.

The "error" signal

void                user_function                      (XesamGSearch *arg0,
                                                        gpointer      user_data)      : Run Last

Emitted if there is a communication error with the search engine. The actual error can be looked up with xesam_g_search_get_last_error().

user_data :

user data set when the signal handler was connected.

The "extended-data-ready" signal

void                user_function                      (XesamGSearch *search,
                                                        XesamGHits   *hits,
                                                        gpointer      user_data)      : Run Last

FIXME: This functionality is not implemented yet

Emitted in response to xesam_g_search_get_extended_data.

search :

The object on which this signal is emitted

hits :

XesamGHits object holding all the retrieved XesamGHit objects with the extended data

user_data :

user data set when the signal handler was connected.

The "hits-found" signal

void                user_function                      (XesamGSearch *search,
                                                        guint         num_found,
                                                        gpointer      user_data)      : Run Last

Emitted when the search engine has found new hits. This signal only notifies how many it has found. When the actual hit data is ready "hits-ready" is emitted.

To get the total number of found hits call xesam_g_search_get_num_found().

search :

The object on which this signal is emitted

num_found :

The number of hits found by the search engine since the last time this signal was emitted.

user_data :

user data set when the signal handler was connected.

The "hits-modified" signal

void                user_function                      (XesamGSearch *search,
                                                        gpointer      hits,
                                                        gpointer      user_data)      : Run Last

Emitted when metadata on the hits in question have been modified.

On some search engines moving a file may simply emit a hits-modified, since this really only changes the xesam:url field. Other search engines might remove the hit before re-adding it.

This signal is not used unless the "search-live" property is TRUE.

search :

the object on which this signal is emitted

hits :

A GArray of guint ids of the hits with modified metadata.

user_data :

user data set when the signal handler was connected.

The "hits-ready" signal

void                user_function                      (XesamGSearch *search,
                                                        XesamGHits   *hits,
                                                        gpointer      user_data)      : Run Last

Emitted when new hits are ready. The XesamGHits object is fully loaded with the new XesamGHit objects stored in memory.

To limit the number of hits fetched per hits-ready signal use the "max-batch-size" property.

search :

The object on which this signal is emitted

hits :

A XesamGHits object holding all the retrieved XesamGHit objects

user_data :

user data set when the signal handler was connected.

The "hits-removed" signal

void                user_function                      (XesamGSearch *search,
                                                        gpointer      hit_ids,
                                                        gpointer      user_data)      : Run Last

Emitted when hits no longer match the given search.

On some search engines moving a file may simply emit a "hits-modified", since this really only changes the xesam:url field. Other search engines might remove the hit before re-adding it.

This signal is not used unless the "search-live" property is TRUE.

search :

The object on which this signal is emitted

hit_ids :

A GArray holding the guint ids of the hits that no longer match the query.

user_data :

user data set when the signal handler was connected.

The "ready" signal

void                user_function                      (XesamGSearch *search,
                                                        gpointer      user_data)      : Run Last

Emitted when the search has received an id from the server.

search :

The object on which this signal is emitted

user_data :

user data set when the signal handler was connected.

The "started" signal

void                user_function                      (XesamGSearch *arg0,
                                                        gpointer      user_data)      : Run Last

Emitted when someone calls xesam_g_search_start

user_data :

user data set when the signal handler was connected.

See Also

XesamGSession