![]() |
![]() |
![]() |
Xesam GLib Reference Manual | |
---|---|---|---|---|
XesamGSearcher; XesamGSearcherIface; void (*XesamGSearcherGotProperty) (XesamGSearcher *searcher, gchar *prop_name, GValue *value, gpointer user_data, GError *error); void (*XesamGSearcherGotHandle) (XesamGSearcher *searcher, gchar *handle, gpointer user_data, GError *error); void (*XesamGSearcherGotHits) (XesamGSearcher *searcher, GPtrArray *hits, gpointer user_data, GError *error); void (*XesamGSearcherGotHitCount) (XesamGSearcher *searcher, guint hit_count, gpointer user_data, GError *error); void (*XesamGSearcherGotState) (XesamGSearcher *searcher, GStrv state_info, gpointer user_data, GError *error); void (*XesamGSearcherVoidResponse) (XesamGSearcher *searcher, gpointer user_data, GError *error); enum XesamGSearcherError; void xesam_g_searcher_new_session (XesamGSearcher *self, XesamGSearcherGotHandle callback, gpointer user_data); void xesam_g_searcher_close_session (XesamGSearcher *self, const gchar *session_handle, XesamGSearcherVoidResponse callback, gpointer user_data); void xesam_g_searcher_get_property (XesamGSearcher *self, const gchar *session_handle, const gchar *prop_name, XesamGSearcherGotProperty callback, gpointer user_data); void xesam_g_searcher_set_property (XesamGSearcher *self, const gchar *session_handle, const gchar *prop_name, const GValue *value, XesamGSearcherGotProperty callback, gpointer user_data); void xesam_g_searcher_new_search (XesamGSearcher *self, const gchar *session_handle, const gchar *query, XesamGSearcherGotHandle callback, gpointer user_data); void xesam_g_searcher_start_search (XesamGSearcher *self, const gchar *search_handle, XesamGSearcherVoidResponse callback, gpointer user_data); void xesam_g_searcher_close_search (XesamGSearcher *self, const gchar *search_handle, XesamGSearcherVoidResponse callback, gpointer user_data); void xesam_g_searcher_get_hits (XesamGSearcher *self, const gchar *search_handle, guint count, XesamGSearcherGotHits callback, gpointer user_data); void xesam_g_searcher_get_hit_data (XesamGSearcher *self, const gchar *search_handle, GArray *hit_ids, GStrv field_names, XesamGSearcherGotHits callback, gpointer user_data); void xesam_g_searcher_get_hit_count (XesamGSearcher *self, const gchar *search_handle, XesamGSearcherGotHitCount callback, gpointer user_data); void xesam_g_searcher_get_state (XesamGSearcher *self, XesamGSearcherGotState callback, gpointer user_data); #define XESAM_G_SEARCHER_ERROR GQuark xesam_g_searcher_error_quark (void); void xesam_g_searcher_hits_added (XesamGSearcher *self, const gchar *search_handle, guint count); void xesam_g_searcher_hits_modified (XesamGSearcher *self, const gchar *search_handle, const GArray *hit_ids); void xesam_g_searcher_hits_removed (XesamGSearcher *self, const gchar *search_handle, const GArray *hit_ids); void xesam_g_searcher_search_done (XesamGSearcher *self, const gchar *search_handle); void xesam_g_searcher_state_changed (XesamGSearcher *self, const GStrv state_info);
XesamGSearcher is a low level interface abstracting access to a search engine. Clients consuming libxesam-glib should normally not use this interface, but use XesamGSession, XesamGSearch, and friends instead.
The intent of this interface is to allow other implementations than the DBus one defined by the Xesam standard - such as an in-process library, or networked search engine.
Search engines not wishing to, or not capable of, exposing a DBus interface should use this interface instead.
XesamGSearcher is available since 1.0
typedef struct { GTypeInterface parent; void (*new_session) (XesamGSearcher * self, XesamGSearcherGotHandle callback, gpointer user_data); void (*close_session) (XesamGSearcher *self, const gchar *session_handle, XesamGSearcherVoidResponse callback, gpointer user_data); void (*get_property) (XesamGSearcher *self, const gchar *session_handle, const gchar *prop_name, XesamGSearcherGotProperty callback, gpointer user_data); void (*set_property) (XesamGSearcher *self, const gchar *session_handle, const gchar *prop_name, const GValue *value, XesamGSearcherGotProperty callback, gpointer user_data); void (*new_search) (XesamGSearcher *self, const gchar *session_handle, const gchar *query, XesamGSearcherGotHandle callback, gpointer user_data); void (*start_search) (XesamGSearcher *self, const gchar *search_handle, XesamGSearcherVoidResponse callback, gpointer user_data); void (*close_search) (XesamGSearcher *self, const gchar *search_handle, XesamGSearcherVoidResponse callback, gpointer user_data); void (*get_hits) (XesamGSearcher *self, const gchar *search_handle, guint count, XesamGSearcherGotHits callback, gpointer user_data); void (*get_hit_data) (XesamGSearcher *self, const gchar *search_handle, GArray *hit_ids, GStrv field_names, XesamGSearcherGotHits callback, gpointer user_data); void (*get_hit_count) (XesamGSearcher *self, const gchar *search_handle, XesamGSearcherGotHitCount callback, gpointer user_data); void (*get_state) (XesamGSearcher *self, XesamGSearcherGotState callback, gpointer user_data); } XesamGSearcherIface;
void (*XesamGSearcherGotProperty) (XesamGSearcher *searcher, gchar *prop_name, GValue *value, gpointer user_data, GError *error);
Used for responses to xesam_g_searcher_set_property()
and
xesam_g_searcher_get_property()
.
As with all XesamGSearcher callbacks, the receiver is responsible for
freeing all parameters, ie prop_name
, value
, user_data
, and error
.
|
The searcher on which the initial request was made |
|
Name of the property received. This is the Xesam formatted name, ie separated with dots like "hit.snippet.length" |
|
The value of the property, or NULL on error
|
|
Arbitrary pointer provided by the user in the function triggering this callback. |
|
Set in case the XesamGSearcher encountered an error. If error is
non-NULL , value will be NULL
|
void (*XesamGSearcherGotHandle) (XesamGSearcher *searcher, gchar *handle, gpointer user_data, GError *error);
Used for responses to xesam_g_searcher_new_session()
and
xesam_g_searcher_new_search()
.
As with all XesamGSearcher callbacks, the receiver is responsible for
freeing all parameters, ie handle
, user_data
, and error
.
|
The searcher on which the initial request was made |
|
Search- or session handle received |
|
Arbitrary pointer provided by the user in the function triggering this callback. |
|
Set in case the XesamGSearcher encountered an error. If error is
non-NULL , handle will be NULL
|
void (*XesamGSearcherGotHits) (XesamGSearcher *searcher, GPtrArray *hits, gpointer user_data, GError *error);
Callback used for responses to xesam_g_searcher_get_hits()
and
xesam_g_searcher_get_hit_data()
.
As with all XesamGSearcher callbacks, the receiver is responsible for
freeing all parameters, ie hits
, user_data
, and error
.
|
The searcher on which the initial request was made |
|
A GPtrArray of GPtrArrays of GValues. Each GPtrArray in the outermost array maps to a hit. The GValues in each hit map to the fields requested in the given context |
|
Arbitrary pointer provided by the user in the function triggering this callback. |
|
Set in case the XesamGSearcher encountered an error. If error is
non-NULL , hits will be NULL
|
void (*XesamGSearcherGotHitCount) (XesamGSearcher *searcher, guint hit_count, gpointer user_data, GError *error);
Callback used for responses to xesam_g_searcher_get_hit_count()
.
|
The searcher on which the initial request was made |
|
|
|
Arbitrary pointer provided by the user in the function triggering this callback. |
|
Set in case the XesamGSearcher encountered an error. If error is
non-NULL count can be arbitrary
|
void (*XesamGSearcherGotState) (XesamGSearcher *searcher, GStrv state_info, gpointer user_data, GError *error);
Callback used for responses to xesam_g_searcher_get_state()
.
As with all XesamGSearcher callbacks, the receiver is responsible for
freeing all parameters, ie state_info
, user_data
, and error
.
|
The searcher on which the initial request was made |
|
A GStrv of length 2. The first entry is one of IDLE, UPDATE, or FULL_INDEX, the second entry is parsable as an integer between 0 and 100 and denotes a percentage of the running task's completion. The second entry is meaningless if the first entry is IDLE |
|
Arbitrary pointer provided by the user in the function triggering this callback. |
|
Set in case the XesamGSearcher encountered an error. If error is
non-NULL count can be arbitrary
|
void (*XesamGSearcherVoidResponse) (XesamGSearcher *searcher, gpointer user_data, GError *error);
Callback issued for xesam_g_searcher_close_session()
,
xesam_g_searcher_close_search()
and xesam_g_searcher_start_search()
As with all XesamGSearcher callbacks, the receiver is responsible for
freeing all parameters except searcher
, which has not been referenced.
|
|
|
|
|
typedef enum { XESAM_G_SEARCHER_ERROR_BAD_RESPONSE /* Return value from a Searcher is invalid */ } XesamGSearcherError;
Error codes for GErrors related to XesamGSearchers
void xesam_g_searcher_new_session (XesamGSearcher *self, XesamGSearcherGotHandle callback, gpointer user_data);
Asynchronously create a new session.
|
Searcher on which to create a new session |
|
Called when the the session handle is ready |
|
Data to pass back with callback |
void xesam_g_searcher_close_session (XesamGSearcher *self, const gchar *session_handle, XesamGSearcherVoidResponse callback, gpointer user_data);
Notify the search engine that a session is no longer needed. Any searches spawned on this session is also invalidated automatically by the server.
|
Searcher on which to create a new session |
|
Unique identifier supplied by the search engine |
|
Called when the the session handle is ready. Optionally NULL
in which case nothing will be done when the method has completed.
In this case you should also pass user_data NULL
|
|
Data to pass back with callback |
void xesam_g_searcher_get_property (XesamGSearcher *self, const gchar *session_handle, const gchar *prop_name, XesamGSearcherGotProperty callback, gpointer user_data);
Look up a session property on a XesamGSearcher.
|
The searcher to get the session property on |
|
The session for which the property should be retrieved |
|
The name of the property to retrieve |
|
Callback to invoke when the data is ready |
|
Any data to pass to callback
|
void xesam_g_searcher_set_property (XesamGSearcher *self, const gchar *session_handle, const gchar *prop_name, const GValue *value, XesamGSearcherGotProperty callback, gpointer user_data);
Set a session property on a XesamGSearcher.
|
The searcher to get the session property on |
|
The session for which the property should be retrieved |
|
The name of the property to retrieve |
|
The value to set |
|
Callback to invoke when the data is ready. This may optionally be
NULL in which case user_data should also be NULL
|
|
Any data to pass to callback
|
void xesam_g_searcher_new_search (XesamGSearcher *self, const gchar *session_handle, const gchar *query, XesamGSearcherGotHandle callback, gpointer user_data);
Spawn a new search in a session. Before any hits will be reported via
the "hits-added" signal xesam_g_searcher_start_search()
must be invoked on the search handle obtained in the callback from this method.
|
The searcher on which to spawn a search |
|
The session for which to spawn the search |
|
The valid Xesam Query xml string |
|
Callback to invoke when the search handle is ready |
|
Any data to pass to callback
|
void xesam_g_searcher_start_search (XesamGSearcher *self, const gchar *search_handle, XesamGSearcherVoidResponse callback, gpointer user_data);
Run a search registered with xesam_g_searcher_new_search()
.
|
The searcher to start the search on |
|
The search handle obtained from xesam_g_searcher_new_search()
|
|
Callback to invoke when the search has been started.
This may optionally be
NULL in which case user_data should also be NULL
|
|
Any data to pass to callback
|
void xesam_g_searcher_close_search (XesamGSearcher *self, const gchar *search_handle, XesamGSearcherVoidResponse callback, gpointer user_data);
Notify the search engine that the search is not longer needed. search_handle
will be invalid when callback
is invoked.
|
The searcher to close the search on |
|
The search handle obtained from xesam_g_searcher_new_search()
|
|
Callback to invoke when the search has been closed.
This may optionally be
NULL in which case user_data should also be NULL
|
|
Any data to pass to callback
|
void xesam_g_searcher_get_hits (XesamGSearcher *self, const gchar *search_handle, guint count, XesamGSearcherGotHits callback, gpointer user_data);
Read hit metadata from the search engine. The returned metadata fields will match those set in the session property hit.fields.
|
The searcher to start the search on |
|
The search handle obtained from xesam_g_searcher_new_search()
|
|
|
|
Callback to invoke when the hit data is ready |
|
Any data to pass to callback
|
void xesam_g_searcher_get_hit_data (XesamGSearcher *self, const gchar *search_handle, GArray *hit_ids, GStrv field_names, XesamGSearcherGotHits callback, gpointer user_data);
Get arbitrary hit metadata.
|
The searcher to start the search on |
|
The search handle obtained from xesam_g_searcher_new_search(p |
|
A GArray containing the guint ids of the hits for which to look
up additional data
A GStrv containing the names of the fields to look up
|
|
|
|
Callback to invoke when the requested metadata is ready |
|
Any data to pass to callback
|
void xesam_g_searcher_get_hit_count (XesamGSearcher *self, const gchar *search_handle, XesamGSearcherGotHitCount callback, gpointer user_data);
Get the current number of found hits. This number is not final before
"search-done" has been emitted on search_handle
.
|
The searcher to start the search on |
|
The search handle obtained from xesam_g_searcher_new_search()
|
|
Callback to invoke when the search has been started.
This may optionally be
NULL in which case user_data should also be NULL
|
|
Any data to pass to callback
|
void xesam_g_searcher_get_state (XesamGSearcher *self, XesamGSearcherGotState callback, gpointer user_data);
Inspect the current state of the search engine
|
The searcher to inspect |
|
Callback to invoke when the search engine state has been determined |
|
Any data to pass to callback
|
void xesam_g_searcher_hits_added (XesamGSearcher *self, const gchar *search_handle, guint count);
Emit the XesamGSearcher
::hits-added signal on the searcher.
|
The searcher to emit the signal on |
|
The search handle on which hits where updated |
|
The number of hits added |
void xesam_g_searcher_hits_modified (XesamGSearcher *self, const gchar *search_handle, const GArray *hit_ids);
Emit the XesamGSearcher
::hits-modified signal on the searcher.
|
The searcher to emit the signal on |
|
The search handle on which hits where updated |
|
Array of guint s containing the ids of the changed hits
|
void xesam_g_searcher_hits_removed (XesamGSearcher *self, const gchar *search_handle, const GArray *hit_ids);
Emit the XesamGSearcher
::hits-removed signal on the searcher.
|
The searcher to emit the signal on |
|
The search handle on which hits where updated |
|
Array of guint s containing the ids of the removed hits
|
void xesam_g_searcher_search_done (XesamGSearcher *self, const gchar *search_handle);
Emit the XesamGSearcher
::search-done signal on the searcher.
|
The searcher to emit the signal on |
|
The search handle for which the search has completed on the server |
void xesam_g_searcher_state_changed (XesamGSearcher *self, const GStrv state_info);
Emit the XesamGSearcher
::state_changed signal on the searcher.
|
The searcher to emit the signal on |
|
NULL terminated string array of length 2. The first entry should
be a valid state as defined by the Xesam Search 1.0 specification
and the second entry should be parsable as an integer between
0 and 100.
|
"hits-added"
signalvoid user_function (XesamGSearcher *xesamgsearcher, gchar *arg1, guint arg2, gpointer user_data) : Run Last
|
the object which received the signal. |
|
|
|
|
|
user data set when the signal handler was connected. |
"search-done"
signalvoid user_function (XesamGSearcher *xesamgsearcher, gchar *arg1, gpointer user_data) : Run Last
|
the object which received the signal. |
|
|
|
user data set when the signal handler was connected. |
"state-changed"
signalvoid user_function (XesamGSearcher *xesamgsearcher, GStrv *arg1, gpointer user_data) : Run Last
|
the object which received the signal. |
|
|
|
user data set when the signal handler was connected. |