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
  "search-done"                                    : Run Last
  "state-changed"                                  : Run Last

Description

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

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.

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

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

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

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.

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

callback :

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

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.

self :

The searcher to get the session property on

session_handle :

The session for which the property should be retrieved

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.

self :

The searcher to get the session property on

session_handle :

The session for which the property should be retrieved

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

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

self :

The searcher to start the search on

search_handle :

The search handle obtained from 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.

self :

The searcher to start the search on

search_handle :

The search handle obtained from xesam_g_searcher_new_search(p

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.

self :

The searcher to start the search on

search_handle :

The search handle obtained from 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

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 *xesamgsearcher,
                                                        gchar          *arg1,
                                                        guint           arg2,
                                                        gpointer        user_data)           : Run Last

xesamgsearcher :

the object which received the signal.

arg1 :

arg2 :

user_data :

user data set when the signal handler was connected.

The "search-done" signal

void                user_function                      (XesamGSearcher *xesamgsearcher,
                                                        gchar          *arg1,
                                                        gpointer        user_data)           : Run Last

xesamgsearcher :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

The "state-changed" signal

void                user_function                      (XesamGSearcher *xesamgsearcher,
                                                        GStrv          *arg1,
                                                        gpointer        user_data)           : Run Last

xesamgsearcher :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.