FolksSearchView

FolksSearchView — A view of FolksIndividuals which match a given FolksQuery.

Functions

Types and Values

Description

The search view supports ‘live’ and ‘snapshot’ search results. Live results will continue to update over a long period of time as persona stores go online and offline or individuals are edited so they start or stop matching the FolksQuery.

For a shell search provider, for example, snapshot results are appropriate. For a search in a contacts UI, live results are more appropriate as they will update over time as other edits are made in the application.

In both cases, "individuals" is guaranteed to be correct after folks_search_view_prepare() finishes.

For live results, continue listening to the "individuals-changed-detailed" signal.

Functions

folks_search_view_prepare ()

void
folks_search_view_prepare (FolksSearchView *self,
                           GAsyncReadyCallback _callback_,
                           gpointer _user_data_);

Prepare the view for use.

This calls folks_individual_aggregator_prepare() as necessary to start aggregating all FolksIndividuals.

This function is guaranteed to be idempotent, so multiple search views may share a single aggregator; folks_search_view_prepare() must be called on all of the views.

For any clients only interested in a snapshot of search results, "individuals" is valid once this async function is finished.

GError will be returned in error

if preparation failed

See also: folks_search_view_prepare_finish()

Parameters

self

the FolksSearchView instance

 

_callback_

callback to call when the request is satisfied.

[scope async]

_user_data_

the data to pass to _callback_ function.

[closure]

Since: 0.11.0

folks_search_view_prepare_finish ()

void
folks_search_view_prepare_finish (FolksSearchView *self,
                                  GAsyncResult *_res_,
                                  GError **error);

Prepare the view for use.

This calls folks_individual_aggregator_prepare() as necessary to start aggregating all FolksIndividuals.

This function is guaranteed to be idempotent, so multiple search views may share a single aggregator; folks_search_view_prepare() must be called on all of the views.

For any clients only interested in a snapshot of search results, "individuals" is valid once this async function is finished.

GError will be returned in error

if preparation failed

See also: folks_search_view_prepare()

Parameters

self

the FolksSearchView instance

 

_res_

a GAsyncResult

 

error

location to store the error occurring, or NULL to ignore

 

Since: 0.11.0

folks_search_view_unprepare ()

void
folks_search_view_unprepare (FolksSearchView *self,
                             GAsyncReadyCallback _callback_,
                             gpointer _user_data_);

Clean up and release resources used by the search view.

This will disconnect the aggregator cleanly from any resources it is using. It is recommended to call this method before finalising the search view, but calling it is not required.

Note that this will not unprepare the underlying aggregator: call folks_individual_aggregator_unprepare() to do that. This allows multiple search views to use a single aggregator and unprepare at different times.

Concurrent calls to this function from different threads will block until preparation has completed. However, concurrent calls to this function from a single thread might not, i.e. the first call will block but subsequent calls might return before the first one. (Though they will be safe in every other respect.)

GError will be returned in error

if unpreparing the backend-specific services failed — this will be a backend-specific error

See also: folks_search_view_unprepare_finish()

Parameters

self

the FolksSearchView instance

 

_callback_

callback to call when the request is satisfied.

[scope async]

_user_data_

the data to pass to _callback_ function.

[closure]

Since: 0.11.0

folks_search_view_unprepare_finish ()

void
folks_search_view_unprepare_finish (FolksSearchView *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Clean up and release resources used by the search view.

This will disconnect the aggregator cleanly from any resources it is using. It is recommended to call this method before finalising the search view, but calling it is not required.

Note that this will not unprepare the underlying aggregator: call folks_individual_aggregator_unprepare() to do that. This allows multiple search views to use a single aggregator and unprepare at different times.

Concurrent calls to this function from different threads will block until preparation has completed. However, concurrent calls to this function from a single thread might not, i.e. the first call will block but subsequent calls might return before the first one. (Though they will be safe in every other respect.)

GError will be returned in error

if unpreparing the backend-specific services failed — this will be a backend-specific error

See also: folks_search_view_unprepare()

Parameters

self

the FolksSearchView instance

 

_res_

a GAsyncResult

 

error

location to store the error occurring, or NULL to ignore

 

Since: 0.11.0

folks_search_view_refresh ()

void
folks_search_view_refresh (FolksSearchView *self,
                           GAsyncReadyCallback _callback_,
                           gpointer _user_data_);

Refresh the view’s results.

Explicitly re-match all the view’s results to ensure matches are up to date. For a normal FolksIndividualAggregator, this is explicitly not necessary, as the view will watch signal emissions from the aggregator and keep itself up to date.

However, for search-only persona stores, which do not support notification of changes to personas, this method is the only way to update the set of matches against the store.

This method should be called whenever an explicit update is needed to the search results, e.g. if the user requests a refresh.

GError will be returned in error

if matching failed

See also: folks_search_view_refresh_finish()

Parameters

self

the FolksSearchView instance

 

_callback_

callback to call when the request is satisfied.

[scope async]

_user_data_

the data to pass to _callback_ function.

[closure]

Since: 0.11.0

folks_search_view_refresh_finish ()

void
folks_search_view_refresh_finish (FolksSearchView *self,
                                  GAsyncResult *_res_,
                                  GError **error);

Refresh the view’s results.

Explicitly re-match all the view’s results to ensure matches are up to date. For a normal FolksIndividualAggregator, this is explicitly not necessary, as the view will watch signal emissions from the aggregator and keep itself up to date.

However, for search-only persona stores, which do not support notification of changes to personas, this method is the only way to update the set of matches against the store.

This method should be called whenever an explicit update is needed to the search results, e.g. if the user requests a refresh.

GError will be returned in error

if matching failed

See also: folks_search_view_refresh()

Parameters

self

the FolksSearchView instance

 

_res_

a GAsyncResult

 

error

location to store the error occurring, or NULL to ignore

 

Since: 0.11.0

folks_search_view_new ()

FolksSearchView *
folks_search_view_new (FolksIndividualAggregator *aggregator,
                       FolksQuery *query);

Create a new view of Individuals matching a given query.

This view will be kept up-to-date as individuals change (which may change their membership in the results).

Parameters

aggregator

 .

the FolksIndividualAggregator to match within

.

[in]

query

 .

query to match upon

.

[in]

Since: 0.11.0

folks_search_view_get_aggregator ()

FolksIndividualAggregator *
folks_search_view_get_aggregator (FolksSearchView *self);

Get and return the current value of the "aggregator" property.

The FolksIndividualAggregator that this view is based upon.

Parameters

self

the FolksSearchView instance to query

 

Returns

the value of the "aggregator" property

Since: 0.11.0

folks_search_view_get_query ()

FolksQuery *
folks_search_view_get_query (FolksSearchView *self);

Get and return the current value of the "query" property.

The FolksQuery that this view is based upon.

If this folks_search_view_new() has already been prepared, setting this will force a re-evaluation of all FolksIndividuals in the FolksIndividualAggregator which can be an expensive operation.

This re-evaluates the query immediately, so most clients should implement de-bouncing to ensure re-evaluation only happens when (for example) the user has stopped typing a new query.

Parameters

self

the FolksSearchView instance to query

 

Returns

the value of the "query" property

Since: 0.11.0

folks_search_view_set_query ()

void
folks_search_view_set_query (FolksSearchView *self,
                             FolksQuery *value);

Set the value of the "query" property to value .

The FolksQuery that this view is based upon.

If this folks_search_view_new() has already been prepared, setting this will force a re-evaluation of all FolksIndividuals in the FolksIndividualAggregator which can be an expensive operation.

This re-evaluates the query immediately, so most clients should implement de-bouncing to ensure re-evaluation only happens when (for example) the user has stopped typing a new query.

Parameters

self

the FolksSearchView instance to modify

 

value

the new value of the "query" property

 

Since: 0.11.0

folks_search_view_get_individuals ()

GeeSortedSet *
folks_search_view_get_individuals (FolksSearchView *self);

Get and return the current value of the "individuals" property.

A sorted set of FolksIndividuals which match the search query.

This is the canonical set of FolksIndividuals provided by this view. It is sorted by match strength, with the individual who is the best match to the search query as the gee_sorted_set_first() element of the set.

Match strengths are not publicly exposed, as they are on an arbitrary scale. To compare two matching individuals for match strength, check for membership of one of them in the gee_sorted_set_head_set() of the other.

For clients who only wish to have a snapshot of search results, this property is valid once folks_search_view_prepare() is finished and this folks_search_view_new() may be unreferenced and ignored afterward.

Parameters

self

the FolksSearchView instance to query

 

Returns

the value of the "individuals" property

Since: 0.11.0

folks_search_view_get_is_prepared ()

gboolean
folks_search_view_get_is_prepared (FolksSearchView *self);

Get and return the current value of the "is-prepared" property.

Whether folks_individual_aggregator_prepare() has successfully completed for this view's aggregator.

Parameters

self

the FolksSearchView instance to query

 

Returns

the value of the "is-prepared" property

Since: 0.11.0

folks_search_view_get_is_quiescent ()

gboolean
folks_search_view_get_is_quiescent (FolksSearchView *self);

Get and return the current value of the "is-quiescent" property.

Whether the search view has reached a quiescent state. This will happen at some point after folks_individual_aggregator_prepare() has successfully completed for its aggregator.

It's guaranteed that this property's value will only ever change after "is-prepared" has changed to true.

Parameters

self

the FolksSearchView instance to query

 

Returns

the value of the "is-quiescent" property

Since: 0.11.0

Types and Values

FOLKS_TYPE_SEARCH_VIEW

#define FOLKS_TYPE_SEARCH_VIEW (folks_search_view_get_type ())

The type for FolksSearchView.

struct FolksSearchView

struct FolksSearchView {
	GObject parent_instance;
	FolksSearchViewPrivate * priv;
};

A view of FolksIndividuals which match a given FolksQuery.

The search view supports ‘live’ and ‘snapshot’ search results. Live results will continue to update over a long period of time as persona stores go online and offline or individuals are edited so they start or stop matching the FolksQuery.

For a shell search provider, for example, snapshot results are appropriate. For a search in a contacts UI, live results are more appropriate as they will update over time as other edits are made in the application.

In both cases, "individuals" is guaranteed to be correct after folks_search_view_prepare() finishes.

For live results, continue listening to the "individuals-changed-detailed" signal.

Since: 0.11.0

struct FolksSearchViewClass

struct FolksSearchViewClass {
	GObjectClass parent_class;
};

The class structure for FOLKS_TYPE_SEARCH_VIEW. All the fields in this structure are private and should never be accessed directly.

Members