FolksSearchView: Reference Manual

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

## Functions

void | folks_search_view_prepare ()
void | folks_search_view_prepare_finish ()
void | folks_search_view_unprepare ()
void | folks_search_view_unprepare_finish ()
void | folks_search_view_refresh ()
void | folks_search_view_refresh_finish ()
FolksSearchView * | folks_search_view_new ()
FolksIndividualAggregator * | folks_search_view_get_aggregator ()
FolksQuery * | folks_search_view_get_query ()
void | folks_search_view_set_query ()
GeeSortedSet * | folks_search_view_get_individuals ()
gboolean | folks_search_view_get_is_prepared ()
gboolean | folks_search_view_get_is_quiescent ()

## Types and Values

#define | FOLKS_TYPE_SEARCH_VIEW
struct | FolksSearchView
struct | FolksSearchViewClass

## 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