XesamGSession

XesamGSession — A client connection to a search engine

Synopsis

                    XesamGSessionPrivate;
                    XesamGSession;
XesamGSession*      xesam_g_session_new                 (XesamGSearcher *searcher);
XesamGSearcher*     xesam_g_session_get_searcher        (XesamGSession *session);
gchar*              xesam_g_session_get_id              (XesamGSession *session);
GHashTable*         xesam_g_session_get_field_map       (XesamGSession *session);
gboolean            xesam_g_session_is_ready            (XesamGSession *session);
gboolean            xesam_g_session_is_closed           (XesamGSession *session);
void                xesam_g_session_close               (XesamGSession *session);
void                xesam_g_session_sync_property       (XesamGSession *session,
                                                         gchar *property);
gboolean            xesam_g_session_test_property       (XesamGSession *session,
                                                         gchar *property);
XesamGSearch*       xesam_g_session_new_search          (XesamGSession *session,
                                                         XesamGQuery *query);
XesamGSearch*       xesam_g_session_new_search_from_text
                                                        (XesamGSession *session,
                                                         gchar *search_text);
const GError*       xesam_g_session_get_last_error      (XesamGSession *session);

Object Hierarchy

  GObject
   +----XesamGSession

Properties

  "hit-fields"               GStrv*                : Read / Write
  "hit-fields-extended"      GStrv*                : Read / Write
  "hit-snippet-length"       gint                  : Read / Write
  "search-live"              gboolean              : Read / Write
  "sort-order"               gchar*                : Read / Write
  "sort-primary"             gchar*                : Read / Write
  "sort-secondary"           gchar*                : Read / Write
  "vendor-display"           gchar*                : Read
  "vendor-extensions"        GStrv*                : Read
  "vendor-id"                gchar*                : Read
  "vendor-maxhits"           guint                 : Read
  "vendor-ontologies"        gpointer              : Read
  "vendor-ontology-contents" GStrv*                : Read
  "vendor-ontology-fields"   GStrv*                : Read
  "vendor-ontology-sources"  GStrv*                : Read
  "vendor-version"           guint                 : Read
  "vendor-xesam"             guint                 : Read

Signals

  "closed"                                         : Run Last
  "error"                                          : Run Last
  "ready"                                          : Run Last

Description

XesamGSession is the client side representation of a connection to a search engine. Every Xesam client application must first set up session before any searches can be spawned. Given a session searches are spawned via xesam_g_session_new_search() or xesam_g_session_new_search_from_text().

Before any searches are spawned the client should set any relevant properties on the session. The session properties are used to control how searches behave and once the first search has been spawned the session properties can not be changed again on that session.

XesamGSession is available since 1.0

Details

XesamGSessionPrivate

typedef struct _XesamGSessionPrivate XesamGSessionPrivate;


XesamGSession

typedef struct _XesamGSession XesamGSession;


xesam_g_session_new ()

XesamGSession*      xesam_g_session_new                 (XesamGSearcher *searcher);

Create a new session on the provided searcher.

Then session is ready for operation when the "ready" signal is emitted on it.

searcher :

Searcher to pass communications through

Returns :

A newly created XesamGSession on the provided searcher or NULL on error

xesam_g_session_get_searcher ()

XesamGSearcher*     xesam_g_session_get_searcher        (XesamGSession *session);

session :

The session to get the XesamGSearcher object for.

Returns :

XesamGSearcher used by the session

xesam_g_session_get_id ()

gchar*              xesam_g_session_get_id              (XesamGSession *session);

Each session is identified on the server via a session id. Use this method to get it.

Note that this method returning non-NULL does not imply that the session is ready.

session :

The session to retrieve the unique id for

Returns :

The unique id for the session. If the session is not ready this method will return NULL.

xesam_g_session_get_field_map ()

GHashTable*         xesam_g_session_get_field_map       (XesamGSession *session);

session :

Returns :


xesam_g_session_is_ready ()

gboolean            xesam_g_session_is_ready            (XesamGSession *session);

Check whether a session is ready to spawn searches and/or get and set properties.

session :

The session to check for readiness

Returns :

TRUE if and only if the session has received a session id from the server. This means that FALSE is returned on error.

xesam_g_session_is_closed ()

gboolean            xesam_g_session_is_closed           (XesamGSession *session);

Check if a session has been closed. Returns TRUE on error.

session :

The session to check

Returns :

TRUE if and only if the session has been closed by a call to xesam_g_session_close.

xesam_g_session_close ()

void                xesam_g_session_close               (XesamGSession *session);

Close a session. Spawning searches and setting/getting properties on a closed session is illegal.

session :

Session to close

xesam_g_session_sync_property ()

void                xesam_g_session_sync_property       (XesamGSession *session,
                                                         gchar *property);

Asynchronously update the cached value of a session property. When the requested property has been retrieved a notification will be emitted for this property.

It is not legal to to call g_object_get() on a session before a notification has been emitted on the requested property.

You may invoke this method even though the session is not ready. The request will just be queued until the session becomes ready.

Calling g_object_set() will also synchronize a property. To test whether a property has been synced call xesam_g_session_test_property().

session :

Session on which to synchronize a property

property :

Name of the property to synchronize

xesam_g_session_test_property ()

gboolean            xesam_g_session_test_property       (XesamGSession *session,
                                                         gchar *property);

Test whether a given property has been synchronized from the server. It is illegal to call g_object_get() on a property that has not been synced.

A property is synchronized if you have either written to it or if you have called xesam_g_session_sync_property() on it.

session :

The session on which to test a property

property :

Name of property to test for

Returns :

TRUE if and only if the property is ready for reading with g_object_get().

xesam_g_session_new_search ()

XesamGSearch*       xesam_g_session_new_search          (XesamGSession *session,
                                                         XesamGQuery *query);

Create a new XesamGSearch from a XesamGQuery.

session :

Session to spawn a search on

query :

Query the search should match

Returns :

A newly created search object.

xesam_g_session_new_search_from_text ()

XesamGSearch*       xesam_g_session_new_search_from_text
                                                        (XesamGSession *session,
                                                         gchar *search_text);

Create a new XesamGSearch from a string composed in the Xesam User Search Language.

This method is suitable for use on raw user input.

session :

Session to spawn search on

search_text :

A string encoded in the XESAM User Search Language.

Returns :

A newly created search object

xesam_g_session_get_last_error ()

const GError*       xesam_g_session_get_last_error      (XesamGSession *session);

When an error occurs it is reported by the "error" signal, after which you can inspect it with this method.

Only communication errors with the search engine is reported this way. Programming errors are not reported this way.

session :

The XesamGSession to inspect for errors

Returns :

The last GError registered by the session or NULL if no error has occured

Property Details

The "hit-fields" property

  "hit-fields"               GStrv*                : Read / Write

Fields to return for each hit.


The "hit-fields-extended" property

  "hit-fields-extended"      GStrv*                : Read / Write

Extra fields fetched on request.


The "hit-snippet-length" property

  "hit-snippet-length"       gint                  : Read / Write

Length of hit summaries in characters.

Allowed values: [0,1000]

Default value: 200


The "search-live" property

  "search-live"              gboolean              : Read / Write

If TRUE any XesamGSearch spawned on this session will continue to monitor the query and notify about changes via the relevant signal on the search object.

The XesamGSearch objects will only use the "hits-modified" and "hits-removed" signals if this property is TRUE.

Default value: FALSE


The "sort-order" property

  "sort-order"               gchar*                : Read / Write

The order in whic to sort results.

Default value: "descending"


The "sort-primary" property

  "sort-primary"             gchar*                : Read / Write

Name of field to sort hits after.

Default value: "xesam:score"


The "sort-secondary" property

  "sort-secondary"           gchar*                : Read / Write

Name of field used to sort if primary sort keys equal.

Default value: ""


The "vendor-display" property

  "vendor-display"           gchar*                : Read

A short string describing the vendor suitable for display.

Default value: "Unknown"


The "vendor-extensions" property

  "vendor-extensions"        GStrv*                : Read

A list of all xesam query language extensions supported by the search engine.


The "vendor-id" property

  "vendor-id"                gchar*                : Read

A string uniquely identofying the search engine vendor.

Default value: "Unknown"


The "vendor-maxhits" property

  "vendor-maxhits"           guint                 : Read

The max number of hits retrievable from the search engine. The actual number of hits might be bigger than this.

Default value: 1


The "vendor-ontologies" property

  "vendor-ontologies"        gpointer              : Read

A GPtrArray of GStrvs. Each GStrv has three elements and describes an ontology. The members of the ontology descriptors are unique_name, version, and path.


The "vendor-ontology-contents" property

  "vendor-ontology-contents" GStrv*                : Read

A list of all content types supported by the search engine.


The "vendor-ontology-fields" property

  "vendor-ontology-fields"   GStrv*                : Read

A list of all field names supported by the search engine.


The "vendor-ontology-sources" property

  "vendor-ontology-sources"  GStrv*                : Read

A list of all source types supported by the search engine.


The "vendor-version" property

  "vendor-version"           guint                 : Read

Integer representation of the vendors version number.

Default value: 0


The "vendor-xesam" property

  "vendor-xesam"             guint                 : Read

The XESAM search specification version number implemented by the search engine.

Default value: 1

Signal Details

The "closed" signal

void                user_function                      (XesamGSession *xesamgsession,
                                                        gpointer       user_data)          : Run Last

xesamgsession :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "error" signal

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

Emitted when an error has occured. Only errors related to communications with the search engine is reported this way. Internal- or programming errors are not reported via this signal.

To inspect the last error call xesam_g_session_get_last_error().

user_data :

user data set when the signal handler was connected.

The "ready" signal

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

Emitted when the session handle has been retrieved from the underlying XesamGSearcher.

All operations on a session require a session handle, so you should generally wait for this signal before doing anything with your session.

user_data :

user data set when the signal handler was connected.