XesamGSearcher

XesamGSearcher — Low level interface to a search engine

Synopsis

                    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);

Object Hierarchy

  GInterface
   +----XesamGSearcher

Prerequisites

XesamGSearcher requires GObject.

Known Implementations

XesamGSearcher is implemented by XesamGDBusSearcher.

Signals

  "hits-added"                                     : Run Last
  "hits-modified"                                  : Run Last
  "hits-removed"                                   : Run Last
  "search-done"                                    : Run Last
  "state-changed"                                  : Run Last

Description

XesamGSearcher is a low level interface abstracting access to a search engine. In other words this interface represents the protocol used to talk to a search engine.

Clients consuming xesam-glib should normally not use this interface, but use XesamGSession, XesamGSearch, and friends instead. They provide an object oriented API abstracting out the protocol.

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. Because of this all methods on this interface has asynchrnous callbacks instead of return values.

Search engines not wishing to, or not capable of, exposing a DBus interface should use this interface instead.

Given an implementation of XesamGSearcher it is easy to export it over DBus by simply passing a searcher instance to xesam_g_dbus_searcher_stub_export().

XesamGSearcher is available since 1.0

Details

XesamGSearcher

typedef struct _XesamGSearcher XesamGSearcher;


XesamGSearcherIface

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;


XesamGSearcherGotProperty ()

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.

searcher :

The searcher on which the initial request was made

prop_name :

Name of the property received. This is the Xesam formatted name, ie separated with dots like "hit.snippet.length"

value :

The value of the property, or NULL on error

user_data :

Arbitrary pointer provided by the user in the function triggering this callback.

error :

Set in case the XesamGSearcher encountered an error. If error is non-NULL, value will be NULL

XesamGSearcherGotHandle ()

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.

searcher :

The searcher on which the initial request was made

handle :

Search- or session handle received

user_data :

Arbitrary pointer provided by the user in the function triggering this callback.

error :

Set in case the XesamGSearcher encountered an error. If error is non-NULL, handle will be NULL

XesamGSearcherGotHits ()

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.

In responses to xesam_g_searcher_get_hits() the hit ids can be calculated as the sequence number in which the hit was read from the search engine. For example the ten first hits to be read will have ids 0-9. Reading another batch of 20 hits will give you the hits with id 10-29.

For responses to xesam_g_searcher_get_hit_data() the hit ids will match those passed in as the hit_ids parameter to said method.

searcher :

The searcher on which the initial request was made

hits :

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. This argument is NULL on error

user_data :

Arbitrary pointer provided by the user in the function triggering this callback.

error :

Set in case the XesamGSearcher encountered an error. If error is non-NULL, hits will be NULL

XesamGSearcherGotHitCount ()

void                (*XesamGSearcherGotHitCount)        (XesamGSearcher *searcher,
                                                         guint hit_count,
                                                         gpointer user_data,
                                                         GError *error);

Callback used for responses to xesam_g_searcher_get_hit_count().

searcher :

The searcher on which the initial request was made

hit_count :

user_data :

Arbitrary pointer provided by the user in the function triggering this callback.

error :

Set in case the XesamGSearcher encountered an error. If error is non-NULL count can be arbitrary

XesamGSearcherGotState ()

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.

searcher :

The searcher on which the initial request was made

state_info :

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. This argument is NULL on errors

user_data :

Arbitrary pointer provided by the user in the function triggering this callback.

error :

Set in case the XesamGSearcher encountered an error. If error is non-NULL state_info is NULL

XesamGSearcherVoidResponse ()

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.

searcher :

user_data :

error :


enum XesamGSearcherError

typedef enum
{
	XESAM_G_SEARCHER_ERROR_BAD_RESPONSE /* Return value from a Searcher is invalid */
} XesamGSearcherError;

Error codes for GErrors related to XesamGSearchers

XESAM_G_SEARCHER_ERROR_BAD_RESPONSE

A call to an external source failed

xesam_g_searcher_new_session ()

void                xesam_g_searcher_new_session        (XesamGSearcher *self,
                                                         XesamGSearcherGotHandle callback,
                                                         gpointer user_data);

Asynchronously create a new session. When the search engine is ready the session handle will be passed back through callback.

self :

Searcher on which to create a new session

callback :

Called when the the session handle is ready

user_data :

Data to pass back with callback

xesam_g_searcher_close_session ()

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.

self :

Searcher on which to create a new session

session_handle :

Unique identifier supplied by the search engine, as obtained from the callback of xesam_g_searcher_new_session()

callback :

Called when the server has acknowledged the session as closed. Optionally NULL in which case nothing will be done when the method has completed. In this case you should also pass user_data NULL

user_data :

Data to pass back with callback

xesam_g_searcher_get_property ()

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 value of the property is passed back through callback.

self :

The searcher to get the session property on

session_handle :

The session for which the property should be retrieved, as obtained from the callback of xesam_g_searcher_new_session()

prop_name :

The name of the property to retrieve

callback :

Callback to invoke when the data is ready

user_data :

Any data to pass to callback

xesam_g_searcher_set_property ()

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.

It is important to notice that the search engine might not respect the requested property value. The actual property value the search engine will use is passed back through callback.

self :

The searcher to get the session property on

session_handle :

The session for which the property should be retrieved, as obtained from the callback of xesam_g_searcher_new_session()

prop_name :

The name of the property to retrieve

value :

The value to set

callback :

Callback to invoke when the data is ready. This may optionally be NULL in which case user_data should also be NULL

user_data :

Any data to pass to callback

xesam_g_searcher_new_search ()

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.

self :

The searcher on which to spawn a search

session_handle :

The session for which to spawn the search, as obtained from the callback of xesam_g_searcher_new_session()

query :

The valid Xesam Query xml string

callback :

Callback to invoke when the search handle is ready

user_data :

Any data to pass to callback

xesam_g_searcher_start_search ()

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().

self :

The searcher to start the search on

search_handle :

The search handle obtained from the callback of xesam_g_searcher_new_search()

callback :

Callback to invoke when the search has been started. This may optionally be NULL in which case user_data should also be NULL

user_data :

Any data to pass to callback

xesam_g_searcher_close_search ()

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.

self :

The searcher to close the search on

search_handle :

The search handle obtained from the callback of xesam_g_searcher_new_search()

callback :

Callback to invoke when the search has been closed. This may optionally be NULL in which case user_data should also be NULL

user_data :

Any data to pass to callback

xesam_g_searcher_get_hits ()

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 metadata fields of the hits will match those set in the session property hit.fields. When the server

self :

The searcher to start the search on

search_handle :

The search handle obtained from the callback of xesam_g_searcher_new_search()

count :

callback :

Callback to invoke when the hit data is ready

user_data :

Any data to pass to callback

xesam_g_searcher_get_hit_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);

Get arbitrary hit metadata. When the hit data is ready it is passed back to the caller via callback.

self :

The searcher to start the search on

search_handle :

The search handle obtained from the callback of xesam_g_searcher_new_search()

hit_ids :

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

field_names :

callback :

Callback to invoke when the requested metadata is ready

user_data :

Any data to pass to callback

xesam_g_searcher_get_hit_count ()

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 hit count is passed to callback when the server replies.

self :

The searcher to start the search on

search_handle :

The search handle obtained from the callback of xesam_g_searcher_new_search()

callback :

Callback to invoke when the search has been started. This may optionally be NULL in which case user_data should also be NULL

user_data :

Any data to pass to callback

xesam_g_searcher_get_state ()

void                xesam_g_searcher_get_state          (XesamGSearcher *self,
                                                         XesamGSearcherGotState callback,
                                                         gpointer user_data);

Inspect the current state of the search engine. The state is passed to callback when the server replies.

self :

The searcher to inspect

callback :

Callback to invoke when the search engine state has been determined

user_data :

Any data to pass to callback

XESAM_G_SEARCHER_ERROR

#define XESAM_G_SEARCHER_ERROR xesam_g_searcher_error_quark()


xesam_g_searcher_error_quark ()

GQuark              xesam_g_searcher_error_quark        (void);

Returns :


xesam_g_searcher_hits_added ()

void                xesam_g_searcher_hits_added         (XesamGSearcher *self,
                                                         const gchar *search_handle,
                                                         guint count);

Emit the XesamGSearcher::hits-added signal on the searcher.

self :

The searcher to emit the signal on

search_handle :

The search handle on which hits where updated

count :

The number of hits added

xesam_g_searcher_hits_modified ()

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.

self :

The searcher to emit the signal on

search_handle :

The search handle on which hits where updated

hit_ids :

Array of guints containing the ids of the changed hits

xesam_g_searcher_hits_removed ()

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.

self :

The searcher to emit the signal on

search_handle :

The search handle on which hits where updated

hit_ids :

Array of guints containing the ids of the removed hits

xesam_g_searcher_search_done ()

void                xesam_g_searcher_search_done        (XesamGSearcher *self,
                                                         const gchar *search_handle);

Emit the XesamGSearcher::search-done signal on the searcher.

self :

The searcher to emit the signal on

search_handle :

The search handle for which the search has completed on the server

xesam_g_searcher_state_changed ()

void                xesam_g_searcher_state_changed      (XesamGSearcher *self,
                                                         const GStrv state_info);

Emit the XesamGSearcher::state_changed signal on the searcher.

self :

The searcher to emit the signal on

state_info :

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.

Signal Details

The "hits-added" signal

void                user_function                      (XesamGSearcher *searcher,
                                                        gchar          *search_handle,
                                                        guint           count,
                                                        gpointer        user_data)          : Run Last

Emitted when the server finds new hits. To retrieve the actual hits call xesam_g_searcher_get_hits().

searcher :

The searcher emitting the signal

search_handle :

The search on which the hits where found

count :

The number of hits found on the server

user_data :

user data set when the signal handler was connected.

The "hits-modified" signal

void                user_function                      (XesamGSearcher *searcher,
                                                        gchar          *search_handle,
                                                        gpointer        hit_ids,
                                                        gpointer        user_data)          : Run Last

Emitted when the server discovers that the object (think, a file) represented by a hit has changed. To retrieve the updated hit data call xesam_g_searcher_get_hit_data().

searcher :

The searcher emitting the signal

search_handle :

The search on which the hits where modified

hit_ids :

A GArray containing the the guint hit ids of the modified hits

user_data :

user data set when the signal handler was connected.

The "hits-removed" signal

void                user_function                      (XesamGSearcher *searcher,
                                                        gchar          *search_handle,
                                                        gpointer        hit_ids,
                                                        gpointer        user_data)          : Run Last

Emitted when the server discovers that an object represented by a hit has been removed or changed in a way such that it longer matches the query of search_handle.

searcher :

The searcher emitting the signal

search_handle :

The search on which the hits where removed

hit_ids :

A GArray containing the the guint hit ids of the removed hits

user_data :

user data set when the signal handler was connected.

The "search-done" signal

void                user_function                      (XesamGSearcher *searcher,
                                                        gchar          *search_handle,
                                                        gpointer        user_data)          : Run Last

Emitted when the server is done scanning for hits on search_handle. On most servers this will mean that the server is done scanning the index.

It is important to note that further emissions of "hits-added", "hits-removed", and "hits-modified" may still occur if the session property "search.live" has been set to TRUE via xesam_g_searcher_set_property(). A live search is a search where the search engine will keep monitoring the result set for changes to the underlying objects and notify the consumer on such changes.

searcher :

The searcher emitting the signal

search_handle :

The search on which the hits where removed

user_data :

user data set when the signal handler was connected.

The "state-changed" signal

void                user_function                      (XesamGSearcher *searcher,
                                                        GStrv          *state_info,
                                                        gpointer        user_data)       : Run Last

Emitted when the server state changes. Normally meaning that it starts updating its indexes or stops doing so.

You can manually retrieve the state information via xesam_g_searcher_get_state().

searcher :

The searcher emitting the signal

state_info :

A GStrv of length 2. The string in position 0 is either "IDLE", "UPDATE", or "FULL_INDEX" and the string at position 1 is parseable as an integer in the range 0-100 indicating the completeness of either the UPDATE or FULL_INDEX state. The second value should be ignored if the state is IDLE

user_data :

user data set when the signal handler was connected.