![]() |
![]() |
![]() |
Xesam GLib Reference Manual | ![]() |
---|---|---|---|---|
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);
"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
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
gboolean xesam_g_search_is_ready (XesamGSearch *search);
|
The search to check for readiness |
Returns : |
TRUE if and only if the search has received a search handle
from the server.
|
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.
|
The search to start |
gboolean xesam_g_search_is_running (XesamGSearch *search);
Check whether xesam_g_search_start()
has been called on the XesamGSearch
object.
|
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
|
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.
|
The search to close |
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.
|
The search to inspect the state of |
Returns : |
TRUE if xesam_g_search_close() has been called on search .
|
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
.
|
The search to inspect the state of |
Returns : |
TRUE if and only id "done" has been emitted on search .
|
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.
|
The search to continue fetching hits for |
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 object for which to get the total number of found hits |
Returns : |
The total accumulated number of hits found by this search |
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 object for which to get the number of hits retrieved from the the server |
Returns : |
The number of hits retrieved from the server |
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.
|
The search to which the hit id's are relative. |
|
An array of hit ids as returned from xesam_g_hit_get_id. |
XesamGSession* xesam_g_search_get_session (XesamGSearch *search);
Look up the parent session for a search.
|
The search to llok up parent session for |
Returns : |
The parent session for the given search |
const gchar* xesam_g_search_get_id (XesamGSearch *search);
Get the unique id for a given 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
|
guint xesam_g_search_get_max_batch_size (XesamGSearch *search);
Convenience method to get the value of the "max-batch-size" property.
|
The search to set the max batch size for |
Returns : |
The maximum number of hits included in each XesamGHits |
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.
|
The search to set the max batch size for |
|
Maximum number of hits per XesamGHits object emitted |
const GError* xesam_g_search_get_last_error (XesamGSearch *search);
See also the signal XesamGSearch::error
|
The search to inspect for errors |
Returns : |
The last error encountered from the search engine. If no error(s)
has happened NULL is returned
|
"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
"closed"
signalvoid 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.
|
The object on which this signal is emitted |
|
user data set when the signal handler was connected. |
"done"
signalvoid 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.
|
The object on which this signal is emitted |
|
user data set when the signal handler was connected. |
"error"
signalvoid 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 set when the signal handler was connected. |
"extended-data-ready"
signalvoid 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.
|
The object on which this signal is emitted |
|
XesamGHits object holding all the retrieved XesamGHit objects with the extended data |
|
user data set when the signal handler was connected. |
"hits-found"
signalvoid 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()
.
|
The object on which this signal is emitted |
|
The number of hits found by the search engine since the last time this signal was emitted. |
|
user data set when the signal handler was connected. |
"hits-modified"
signalvoid 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
.
|
the object on which this signal is emitted |
|
A GArray of guint ids of the hits with modified metadata. |
|
user data set when the signal handler was connected. |
"hits-ready"
signalvoid 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.
|
The object on which this signal is emitted |
|
A XesamGHits object holding all the retrieved XesamGHit objects |
|
user data set when the signal handler was connected. |
"hits-removed"
signalvoid 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
.
|
The object on which this signal is emitted |
|
A GArray holding the guint ids of the hits that no longer
match the query.
|
|
user data set when the signal handler was connected. |
"ready"
signalvoid user_function (XesamGSearch *search, gpointer user_data) : Run Last
Emitted when the search has received an id from the server.
|
The object on which this signal is emitted |
|
user data set when the signal handler was connected. |
"started"
signalvoid user_function (XesamGSearch *arg0, gpointer user_data) : Run Last
Emitted when someone calls xesam_g_search_start
|
user data set when the signal handler was connected. |