FolksIndividualAggregator 3 FOLKS Library
FolksIndividualAggregator Stores FolksIndividuals which have been created through aggregation of all the FolksPersonas provided by the various FolksBackends.

## Functions

void | folks_individual_aggregator_prepare ()
void | folks_individual_aggregator_prepare_finish ()
void | folks_individual_aggregator_unprepare ()
void | folks_individual_aggregator_unprepare_finish ()
GeeMap * | folks_individual_aggregator_get_potential_matches ()
GeeMap * | folks_individual_aggregator_get_all_potential_matches ()
void | folks_individual_aggregator_add_persona_from_details ()
FolksPersona * | folks_individual_aggregator_add_persona_from_details_finish ()
void | folks_individual_aggregator_remove_individual ()
void | folks_individual_aggregator_remove_individual_finish ()
void | folks_individual_aggregator_remove_persona ()
void | folks_individual_aggregator_remove_persona_finish ()
void | folks_individual_aggregator_link_personas ()
void | folks_individual_aggregator_link_personas_finish ()
void | folks_individual_aggregator_unlink_individual ()
void | folks_individual_aggregator_unlink_individual_finish ()
void | folks_individual_aggregator_ensure_individual_property_writeable ()
FolksPersona * | folks_individual_aggregator_ensure_individual_property_writeable_finish ()
void | folks_individual_aggregator_look_up_individual ()
FolksIndividual * | folks_individual_aggregator_look_up_individual_finish ()
FolksIndividualAggregator * | folks_individual_aggregator_new ()
FolksIndividualAggregator * | folks_individual_aggregator_new_with_backend_store ()
gboolean | folks_individual_aggregator_get_is_prepared ()
gboolean | folks_individual_aggregator_get_is_quiescent ()
FolksPersonaStore * | folks_individual_aggregator_get_primary_store ()
FolksBackendStore * | folks_individual_aggregator_get_backend_store ()
GeeMap * | folks_individual_aggregator_get_individuals ()
FolksIndividual * | folks_individual_aggregator_get_user ()
FolksIndividualAggregator * | folks_individual_aggregator_dup ()
FolksIndividualAggregator * | folks_individual_aggregator_dup_with_backend_store ()

## Types and Values

#define | FOLKS_TYPE_INDIVIDUAL_AGGREGATOR
struct | FolksIndividualAggregator
struct | FolksIndividualAggregatorClass
enum | FolksIndividualAggregatorError

## Description

This is the main interface for client applications.

Linking and unlinking of personas and individuals is performed entirely through the aggregator. Personas may be linked together to form individuals; for example, the personas which form `individual1` and `individual2` may be linked together with `another_persona` to give a new FolksIndividual:

      var personas = new HashSet<Persona> ();
      personas.add_all (individual1.personas);
      personas.add_all (individual2.personas);
      personas.add (another_persona);
      yield my_individual_aggregator.link_personas (personas);

The individuals which contained those personas will be removed when ``folks_individual_aggregator_link_personas()`` is called. Any personas in those individuals which were not included in the linking call may end up implicitly linked to the new individual, or may be aggregated into other new individuals.

For example, consider the situation where `individual1` contains two personas, `persona1A` and `persona1B`; `individual2` contains one persona, `persona2A`; and `another_persona` comes from `individual3`, which also contains `persona3A` and `persona3B`. Calling ``folks_individual_aggregator_link_personas()`` on `persona1A`, `persona1B`, `persona2A` and `another_persona` will result in `individual1` and `individual2` being removed. A new FolksIndividual will be created containing all the personas passed to the linking function. It might also contain `persona3A` and `persona3B`; or they might be in one or two other new individuals.

An existing individual may be unlinked to form singleton individuals for each of its personas:

      yield my_individual_aggregator.unlink_individual (my_individual);

Note that to link two individuals together, their two sets of personas must be linked together. There is no API to directly link the individuals themselves, as conceptually folks links FolksPersonas, not FolksIndividuals.

Folks does not support having more than one IndividualAggregator instantiated at the same time. Most clients should use ``folks_individual_aggregator_dup()`` to retrieve the IndividualAggregator singleton.

## Functions

### folks_individual_aggregator_prepare ()

    void
    folks_individual_aggregator_prepare (FolksIndividualAggregator *self,
                                         GAsyncReadyCallback _callback_,
                                         gpointer _user_data_);

Prepare the IndividualAggregator for use.

This loads all the available backends and prepares them for use by the IndividualAggregator. This should be called after connecting to the "individuals-changed" signal (or "individuals-changed-detailed" signal), or a race condition could occur, with the signal being emitted before your code has connected to them, and FolksIndividuals getting "lost" as a result.

This function is guaranteed to be idempotent (since version 0.3.0).

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 preparing any of the backends failed — this error will be passed through from ``folks_backend_store_load_backends()``

See also: ``folks_individual_aggregator_prepare_finish()``

#### Parameters

self | the FolksIndividualAggregator instance |
_callback_ | callback to call when the request is satisfied. | [scope async]
_user_data_ | the data to pass to _callback_ function. | [closure]

Since: 0.1.11

folks_individual_aggregator_prepare

### folks_individual_aggregator_prepare_finish ()

    void
    folks_individual_aggregator_prepare_finish
                                   (FolksIndividualAggregator *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Prepare the IndividualAggregator for use.

This loads all the available backends and prepares them for use by the IndividualAggregator. This should be called after connecting to the "individuals-changed" signal (or "individuals-changed-detailed" signal), or a race condition could occur, with the signal being emitted before your code has connected to them, and FolksIndividuals getting "lost" as a result.

This function is guaranteed to be idempotent (since version 0.3.0).

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 preparing any of the backends failed — this error will be passed through from ``folks_backend_store_load_backends()``

See also: ``folks_individual_aggregator_prepare()``

#### Parameters

self | the FolksIndividualAggregator instance |
_res_ | a GAsyncResult |
error | location to store the error occurring, or `NULL` to ignore |

Since: 0.1.11

folks_individual_aggregator_prepare_finish

### folks_individual_aggregator_unprepare ()

    void
    folks_individual_aggregator_unprepare (FolksIndividualAggregator *self,
                                           GAsyncReadyCallback _callback_,
                                           gpointer _user_data_);

Clean up and release resources used by the aggregator.

This will disconnect the aggregator cleanly from any resources it or its persona stores are using. It is recommended to call this method before finalising the individual aggregator, but calling it is not required. If this method is not called then, for example, unsaved changes in backends may not be flushed.

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_individual_aggregator_unprepare_finish()``

#### Parameters

self | the FolksIndividualAggregator instance |
_callback_ | callback to call when the request is satisfied. | [scope async]
_user_data_ | the data to pass to _callback_ function. | [closure]

Since: 0.7.3

folks_individual_aggregator_unprepare

### folks_individual_aggregator_unprepare_finish ()

    void
    folks_individual_aggregator_unprepare_finish
                                   (FolksIndividualAggregator *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Clean up and release resources used by the aggregator.

This will disconnect the aggregator cleanly from any resources it or its persona stores are using. It is recommended to call this method before finalising the individual aggregator, but calling it is not required. If this method is not called then, for example, unsaved changes in backends may not be flushed.

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_individual_aggregator_unprepare()``

#### Parameters

self | the FolksIndividualAggregator instance |
_res_ | a GAsyncResult |
error | location to store the error occurring, or `NULL` to ignore |

Since: 0.7.3

folks_individual_aggregator_unprepare_finish

### folks_individual_aggregator_get_potential_matches ()

    GeeMap *
    folks_individual_aggregator_get_potential_matches
                                   (FolksIndividualAggregator *self,
                                    FolksIndividual *matchee,
                                    FolksMatchResult min_threshold);

Get all matches for a given FolksIndividual.

#### Parameters

self | the FolksIndividualAggregator instance |
matchee | . the individual to find matches for . | [in]
min_threshold | . the threshold for accepting a match . | [in]

#### Returns

a map from matched individuals to the degree with which they match `matchee` (which is guaranteed to at least equal `min_threshold`); if no matches could be found, an empty map is returned

Since: 0.5.1

folks_individual_aggregator_get_potential_matches

### folks_individual_aggregator_get_all_potential_matches ()

    GeeMap *
    folks_individual_aggregator_get_all_potential_matches
                                   (FolksIndividualAggregator *self,
                                    FolksMatchResult min_threshold);

Get all combinations between all FolksIndividuals.

#### Parameters

self | the FolksIndividualAggregator instance |
min_threshold | . the threshold for accepting a match . | [in]

#### Returns

a map from each individual in the aggregator to a map of the other individuals in the aggregator which can be matched with that individual, mapped to the degree with which they match the original individual (which is guaranteed to at least equal `min_threshold`)

Since: 0.5.1

folks_individual_aggregator_get_all_potential_matches

### folks_individual_aggregator_add_persona_from_details ()

    void
    folks_individual_aggregator_add_persona_from_details
                                   (FolksIndividualAggregator *self,
                                    FolksIndividual *parent,
                                    FolksPersonaStore *persona_store,
                                    GHashTable *details,
                                    GAsyncReadyCallback _callback_,
                                    gpointer _user_data_);

Add a new persona in the given FolksPersonaStore based on the `details` provided.

If the target store is offline, this function will throw `FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_STORE_OFFLINE`. It's the responsibility of the caller to cache details and re-try this function if it wishes to make offline adds work.

The details hash is a backend-specific mapping of key, value strings. Common keys include:

- contact - service-specific contact ID

- message - a user-readable message to pass to the persona being added

If a FolksPersona with the given details already exists in the store, no error will be thrown and this function will return `null`.

`FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_STORE_OFFLINE` will be returned in error

if the persona store was offline

`FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_ADD_FAILED` will be returned in error

if any other error occurred while adding the persona

See also: ``folks_individual_aggregator_add_persona_from_details_finish()``

#### Parameters

self | the FolksIndividualAggregator instance |
parent | . an optional FolksIndividual to add the new FolksPersona to. This persona will be appended to its ordered list of personas. . | [in][allow-none]
persona_store | . the FolksPersonaStore to add the persona to . | [in]
details | . a key-value map of details to use in creating the new FolksPersona . | [in]
_callback_ | callback to call when the request is satisfied. | [scope async]
_user_data_ | the data to pass to _callback_ function. | [closure]

Since: 0.3.5

folks_individual_aggregator_add_persona_from_details

### folks_individual_aggregator_add_persona_from_details_finish ()

    FolksPersona *
    folks_individual_aggregator_add_persona_from_details_finish
                                   (FolksIndividualAggregator *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Add a new persona in the given FolksPersonaStore based on the `details` provided.

If the target store is offline, this function will throw `FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_STORE_OFFLINE`. It's the responsibility of the caller to cache details and re-try this function if it wishes to make offline adds work.

The details hash is a backend-specific mapping of key, value strings. Common keys include:

- contact - service-specific contact ID

- message - a user-readable message to pass to the persona being added

If a FolksPersona with the given details already exists in the store, no error will be thrown and this function will return `null`.

`FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_STORE_OFFLINE` will be returned in error

if the persona store was offline

`FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_ADD_FAILED` will be returned in error

if any other error occurred while adding the persona

See also: ``folks_individual_aggregator_add_persona_from_details()``

#### Parameters

self | the FolksIndividualAggregator instance |
_res_ | a GAsyncResult |
error | location to store the error occurring, or `NULL` to ignore. | [error-domains FolksIndividualAggregatorError]

#### Returns

the new FolksPersona or `null` if the corresponding FolksPersona already existed. If non-`null`, the new FolksPersona will also be added to a new or existing FolksIndividual as necessary.

Since: 0.3.5

folks_individual_aggregator_add_persona_from_details_finish

### folks_individual_aggregator_remove_individual ()

    void
    folks_individual_aggregator_remove_individual
                                   (FolksIndividualAggregator *self,
                                    FolksIndividual *individual,
                                    GAsyncReadyCallback _callback_,
                                    gpointer _user_data_);

Completely remove the individual and all of its personas from their backing stores.

This method is safe to call multiple times concurrently (for the same individual or different individuals).

GError will be returned in error

if removing the persona failed — this will be passed through from ``folks_persona_store_remove_persona()``

See also: ``folks_individual_aggregator_remove_individual_finish()``

#### Parameters

self | the FolksIndividualAggregator instance |
individual | . the FolksIndividual to remove . | [in]
_callback_ | callback to call when the request is satisfied. | [scope async]
_user_data_ | the data to pass to _callback_ function. | [closure]

Since: 0.1.11

folks_individual_aggregator_remove_individual

### folks_individual_aggregator_remove_individual_finish ()

    void
    folks_individual_aggregator_remove_individual_finish
                                   (FolksIndividualAggregator *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Completely remove the individual and all of its personas from their backing stores.

This method is safe to call multiple times concurrently (for the same individual or different individuals).

GError will be returned in error

if removing the persona failed — this will be passed through from ``folks_persona_store_remove_persona()``

See also: ``folks_individual_aggregator_remove_individual()``

#### Parameters

self | the FolksIndividualAggregator instance |
_res_ | a GAsyncResult |
error | location to store the error occurring, or `NULL` to ignore |

Since: 0.1.11

folks_individual_aggregator_remove_individual_finish

### folks_individual_aggregator_remove_persona ()

    void
    folks_individual_aggregator_remove_persona
                                   (FolksIndividualAggregator *self,
                                    FolksPersona *persona,
                                    GAsyncReadyCallback _callback_,
                                    gpointer _user_data_);

Completely remove the persona from its backing store.

This will leave other personas in the same individual alone.

This method is safe to call multiple times concurrently (for the same persona or different personas).

GError will be returned in error

if removing the persona failed — this will be passed through from ``folks_persona_store_remove_persona()``

See also: ``folks_individual_aggregator_remove_persona_finish()``

#### Parameters

self | the FolksIndividualAggregator instance |
persona | . the FolksPersona to remove . | [in]
_callback_ | callback to call when the request is satisfied. | [scope async]
_user_data_ | the data to pass to _callback_ function. | [closure]

Since: 0.1.11

folks_individual_aggregator_remove_persona

### folks_individual_aggregator_remove_persona_finish ()

    void
    folks_individual_aggregator_remove_persona_finish
                                   (FolksIndividualAggregator *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Completely remove the persona from its backing store.

This will leave other personas in the same individual alone.

This method is safe to call multiple times concurrently (for the same persona or different personas).

GError will be returned in error

if removing the persona failed — this will be passed through from ``folks_persona_store_remove_persona()``

See also: ``folks_individual_aggregator_remove_persona()``

#### Parameters

self | the FolksIndividualAggregator instance |
_res_ | a GAsyncResult |
error | location to store the error occurring, or `NULL` to ignore |

Since: 0.1.11

folks_individual_aggregator_remove_persona_finish

### folks_individual_aggregator_link_personas ()

    void
    folks_individual_aggregator_link_personas
                                   (FolksIndividualAggregator *self,
                                    GeeSet *personas,
                                    GAsyncReadyCallback _callback_,
                                    gpointer _user_data_);

Link the given FolksPersonas together.

Create links between the given FolksPersonas so that they form a single FolksIndividual. The new FolksIndividual will be returned via the "individuals-changed" signal.

Removal of the FolksIndividuals which the FolksPersonas were in before is signalled by "individuals-changed" and "removed".

This method is safe to call multiple times concurrently.

`FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_NO_PRIMARY_STORE` will be returned in error

if no primary store has been configured for the individual aggregator

FolksIndividualAggregatorError will be returned in error

if adding the linking persona failed — this will be passed through from ``folks_individual_aggregator_add_persona_from_details()``

See also: ``folks_individual_aggregator_link_personas_finish()``

#### Parameters

self | the FolksIndividualAggregator instance |
personas | . the FolksPersonas to be linked . | [in]
_callback_ | callback to call when the request is satisfied. | [scope async]
_user_data_ | the data to pass to _callback_ function. | [closure]

Since: 0.5.1

folks_individual_aggregator_link_personas

### folks_individual_aggregator_link_personas_finish ()

    void
    folks_individual_aggregator_link_personas_finish
                                   (FolksIndividualAggregator *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Link the given FolksPersonas together.

Create links between the given FolksPersonas so that they form a single FolksIndividual. The new FolksIndividual will be returned via the "individuals-changed" signal.

Removal of the FolksIndividuals which the FolksPersonas were in before is signalled by "individuals-changed" and "removed".

This method is safe to call multiple times concurrently.

`FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_NO_PRIMARY_STORE` will be returned in error

if no primary store has been configured for the individual aggregator

FolksIndividualAggregatorError will be returned in error

if adding the linking persona failed — this will be passed through from ``folks_individual_aggregator_add_persona_from_details()``

See also: ``folks_individual_aggregator_link_personas()``

#### Parameters

self | the FolksIndividualAggregator instance |
_res_ | a GAsyncResult |
error | location to store the error occurring, or `NULL` to ignore. | [error-domains FolksIndividualAggregatorError]

Since: 0.5.1

folks_individual_aggregator_link_personas_finish

### folks_individual_aggregator_unlink_individual ()

    void
    folks_individual_aggregator_unlink_individual
                                   (FolksIndividualAggregator *self,
                                    FolksIndividual *individual,
                                    GAsyncReadyCallback _callback_,
                                    gpointer _user_data_);

Unlinks the given FolksIndividual into its constituent FolksPersonas.

This completely unlinks the given FolksIndividual, destroying all of its writeable FolksPersonas.

The FolksIndividual's removal is signalled by "individuals-changed" and "removed".

The FolksPersonas comprising the FolksIndividual will be re-linked into one or more new FolksIndividuals, depending on how much linking data remains (typically only implicit links remain). The addition of these new FolksIndividuals will be signalled by "individuals-changed".

This method is safe to call multiple times concurrently, although concurrent calls for the same individual may result in duplicate personas being created.

GError will be returned in error

if removing the linking persona failed — this will be passed through from ``folks_persona_store_remove_persona()``

See also: ``folks_individual_aggregator_unlink_individual_finish()``

#### Parameters

self | the FolksIndividualAggregator instance |
individual | . the FolksIndividual to unlink . | [in]
_callback_ | callback to call when the request is satisfied. | [scope async]
_user_data_ | the data to pass to _callback_ function. | [closure]

Since: 0.1.13

folks_individual_aggregator_unlink_individual

### folks_individual_aggregator_unlink_individual_finish ()

    void
    folks_individual_aggregator_unlink_individual_finish
                                   (FolksIndividualAggregator *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Unlinks the given FolksIndividual into its constituent FolksPersonas.

This completely unlinks the given FolksIndividual, destroying all of its writeable FolksPersonas.

The FolksIndividual's removal is signalled by "individuals-changed" and "removed".

The FolksPersonas comprising the FolksIndividual will be re-linked into one or more new FolksIndividuals, depending on how much linking data remains (typically only implicit links remain). The addition of these new FolksIndividuals will be signalled by "individuals-changed".

This method is safe to call multiple times concurrently, although concurrent calls for the same individual may result in duplicate personas being created.

GError will be returned in error

if removing the linking persona failed — this will be passed through from ``folks_persona_store_remove_persona()``

See also: ``folks_individual_aggregator_unlink_individual()``

#### Parameters

self | the FolksIndividualAggregator instance |
_res_ | a GAsyncResult |
error | location to store the error occurring, or `NULL` to ignore |

Since: 0.1.13

folks_individual_aggregator_unlink_individual_finish

### folks_individual_aggregator_ensure_individual_property_writeable ()

    void
    folks_individual_aggregator_ensure_individual_property_writeable
                                   (FolksIndividualAggregator *self,
                                    FolksIndividual *individual,
                                    const gchar *property_name,
                                    GAsyncReadyCallback _callback_,
                                    gpointer _user_data_);

Ensure that the given property is writeable for the given FolksIndividual.

This makes sure that there is at least one FolksPersona in the individual which has `property_name` in its "writeable-properties". If no such persona exists in the individual, a new one will be created and linked to the individual. (Note that due to the design of the aggregator, this will result in the previous individual being removed and replaced by a new one with the new persona; listen to the "removed" signal to see the replacement.)

It may not be possible to create a new persona which has the given property as writeable. In that case, a `FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_NO_PRIMARY_STORE` or `FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_PROPERTY_NOT_WRITEABLE` error will be thrown.

This method is safe to call multiple times concurrently, although concurrent calls for the same individual may result in duplicate personas being created.

`FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_NO_PRIMARY_STORE` will be returned in error

if no primary store was configured for this individual aggregator

`FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_PROPERTY_NOT_WRITEABLE` will be returned in error

if the given `property_name` referred to a non-writeable property

FolksIndividualAggregatorError will be returned in error

if adding a new persona (using ``folks_individual_aggregator_add_persona_from_details()``) failed, or if linking personas (using ``folks_individual_aggregator_link_personas()``) failed

See also: ``folks_individual_aggregator_ensure_individual_property_writeable_finish()``

#### Parameters

self | the FolksIndividualAggregator instance |
individual | . the individual for which `property_name` should be writeable . | [in]
property_name | . the name of the property which needs to be writeable (this should be in lower case using hyphens, e.g. “web-service-addresses”) . | [in]
_callback_ | callback to call when the request is satisfied. | [scope async]
_user_data_ | the data to pass to _callback_ function. | [closure]

Since: 0.6.2

folks_individual_aggregator_ensure_individual_property_writeable

### folks_individual_aggregator_ensure_individual_property_writeable_finish ()

    FolksPersona *
    folks_individual_aggregator_ensure_individual_property_writeable_finish
                                   (FolksIndividualAggregator *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Ensure that the given property is writeable for the given FolksIndividual.

This makes sure that there is at least one FolksPersona in the individual which has `property_name` in its "writeable-properties". If no such persona exists in the individual, a new one will be created and linked to the individual. (Note that due to the design of the aggregator, this will result in the previous individual being removed and replaced by a new one with the new persona; listen to the "removed" signal to see the replacement.)

It may not be possible to create a new persona which has the given property as writeable. In that case, a `FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_NO_PRIMARY_STORE` or `FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_PROPERTY_NOT_WRITEABLE` error will be thrown.

This method is safe to call multiple times concurrently, although concurrent calls for the same individual may result in duplicate personas being created.

`FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_NO_PRIMARY_STORE` will be returned in error

if no primary store was configured for this individual aggregator

`FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_PROPERTY_NOT_WRITEABLE` will be returned in error

if the given `property_name` referred to a non-writeable property

FolksIndividualAggregatorError will be returned in error

if adding a new persona (using ``folks_individual_aggregator_add_persona_from_details()``) failed, or if linking personas (using ``folks_individual_aggregator_link_personas()``) failed

See also: ``folks_individual_aggregator_ensure_individual_property_writeable()``

#### Parameters

self | the FolksIndividualAggregator instance |
_res_ | a GAsyncResult |
error | location to store the error occurring, or `NULL` to ignore. | [error-domains FolksIndividualAggregatorError]

#### Returns

a persona (new or existing) which has the given property as writeable

Since: 0.6.2

folks_individual_aggregator_ensure_individual_property_writeable_finish

### folks_individual_aggregator_look_up_individual ()

    void
    folks_individual_aggregator_look_up_individual
                                   (FolksIndividualAggregator *self,
                                    const gchar *id,
                                    GAsyncReadyCallback _callback_,
                                    gpointer _user_data_);

Look up an individual in the aggregator.

This returns the FolksIndividual with the given `id` if it exists in the aggregator, and `null` otherwise.

In future, when lazy-loading of individuals' properties is added to folks, this method guarantees to load all properties of the individual, even if the aggregator hasn't lazy-loaded anything else.

This method is safe to call before ``folks_individual_aggregator_prepare()`` has been called, and will call ``folks_individual_aggregator_prepare()`` itself in that case.

This method is safe to call multiple times concurrently.

GError will be returned in error

from ``folks_individual_aggregator_prepare()``

See also: ``folks_individual_aggregator_look_up_individual_finish()``

#### Parameters

self | the FolksIndividualAggregator instance |
id | . ID of the individual to look up . | [in]
_callback_ | callback to call when the request is satisfied. | [scope async]
_user_data_ | the data to pass to _callback_ function. | [closure]

Since: 0.7.0

folks_individual_aggregator_look_up_individual

### folks_individual_aggregator_look_up_individual_finish ()

    FolksIndividual *
    folks_individual_aggregator_look_up_individual_finish
                                   (FolksIndividualAggregator *self,
                                    GAsyncResult *_res_,
                                    GError **error);

Look up an individual in the aggregator.

This returns the FolksIndividual with the given `id` if it exists in the aggregator, and `null` otherwise.

In future, when lazy-loading of individuals' properties is added to folks, this method guarantees to load all properties of the individual, even if the aggregator hasn't lazy-loaded anything else.

This method is safe to call before ``folks_individual_aggregator_prepare()`` has been called, and will call ``folks_individual_aggregator_prepare()`` itself in that case.

This method is safe to call multiple times concurrently.

GError will be returned in error

from ``folks_individual_aggregator_prepare()``

See also: ``folks_individual_aggregator_look_up_individual()``

#### Parameters

self | the FolksIndividualAggregator instance |
_res_ | a GAsyncResult |
error | location to store the error occurring, or `NULL` to ignore |

#### Returns

individual with `id`, or `null` if no such individual was found

Since: 0.7.0

folks_individual_aggregator_look_up_individual_finish

### folks_individual_aggregator_new ()

    FolksIndividualAggregator *
    folks_individual_aggregator_new (void);

`folks_individual_aggregator_new` has been deprecated since version 0.9.5 and should not be used in newly-written code.

Replaced by `folks_individual_aggregator_dup()`.

Create a new IndividualAggregator.

Clients should connect to the "individuals-changed" signal (or the "individuals-changed-detailed" signal), then call ``folks_individual_aggregator_prepare()`` to load the backends and start aggregating individuals.

An example of how to set up an IndividualAggregator:

      IndividualAggregator agg = new IndividualAggregator ();
      agg.individuals_changed_detailed.connect (individuals_changed_cb);
      agg.prepare ();

Folks does not support having more than one IndividualAggregator instantiated at the same time. So it's recommended to use ``folks_individual_aggregator_dup()`` instead.

folks_individual_aggregator_new

### folks_individual_aggregator_new_with_backend_store ()

    FolksIndividualAggregator *
    folks_individual_aggregator_new_with_backend_store
                                   (FolksBackendStore *store);

`folks_individual_aggregator_new_with_backend_store` has been deprecated since version 0.9.5 and should not be used in newly-written code.

Replaced by `folks_individual_aggregator_dup_with_backend_store()`.

Create a new IndividualAggregator with a custom FolksBackendStore.

This behaves the same as the default constructor for ``folks_individual_aggregator_new()``, but uses the given FolksBackendStore rather than the default one.

#### Parameters

store | . the FolksBackendStore to use instead of the default one. . | [in]

Since: 0.9.0

folks_individual_aggregator_new_with_backend_store
folks_individual_aggregator_new_with_backend_store

### folks_individual_aggregator_get_is_prepared ()

    gboolean
    folks_individual_aggregator_get_is_prepared
                                   (FolksIndividualAggregator *self);

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

Whether ``folks_individual_aggregator_prepare()`` has successfully completed for this aggregator.

#### Parameters

self | the FolksIndividualAggregator instance to query |

#### Returns

the value of the "is-prepared" property

Since: 0.3.0

folks_individual_aggregator_get_is_prepared

### folks_individual_aggregator_get_is_quiescent ()

    gboolean
    folks_individual_aggregator_get_is_quiescent
                                   (FolksIndividualAggregator *self);

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

Whether the aggregator has reached a quiescent state. This will happen at some point after ``folks_individual_aggregator_prepare()`` has successfully completed for the aggregator. An aggregator is in a quiescent state when all the FolksPersonaStores listed by its backends have reached a quiescent state. Once it's reached a quiescent state, this property will never change again (from `true` to `false`).

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

#### Parameters

self | the FolksIndividualAggregator instance to query |

#### Returns

the value of the "is-quiescent" property

Since: 0.6.2

folks_individual_aggregator_get_is_quiescent

### folks_individual_aggregator_get_primary_store ()

    FolksPersonaStore *
    folks_individual_aggregator_get_primary_store
                                   (FolksIndividualAggregator *self);

Get and return the current value of the "primary-store" property.

Our configured primary (writeable) store.

Which one to use is decided (in order or precedence) by:

- the FOLKS_PRIMARY_STORE env var (mostly for debugging) - the GSettings key set in `_PRIMARY_STORE_CONFIG_KEY` (system set store) - going with the `key-file` or `eds` store as the fall-back option

#### Parameters

self | the FolksIndividualAggregator instance to query |

#### Returns

the value of the "primary-store" property

Since: 0.5.0

folks_individual_aggregator_get_primary_store

### folks_individual_aggregator_get_backend_store ()

    FolksBackendStore *
    folks_individual_aggregator_get_backend_store
                                   (FolksIndividualAggregator *self);

Get and return the current value of the "backend-store" property.

The backend store providing the persona stores for this aggregator.

#### Parameters

self | the FolksIndividualAggregator instance to query |

#### Returns

the value of the "backend-store" property

Since: 0.9.7

folks_individual_aggregator_get_backend_store

### folks_individual_aggregator_get_individuals ()

    GeeMap *
    folks_individual_aggregator_get_individuals
                                   (FolksIndividualAggregator *self);

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

A map from "id"s to their FolksIndividuals.

This is the canonical set of FolksIndividuals provided by this IndividualAggregator.

FolksIndividuals may be added or removed using ``folks_individual_aggregator_add_persona_from_details()`` and ``folks_individual_aggregator_remove_individual()``, respectively.

#### Parameters

self | the FolksIndividualAggregator instance to query |

#### Returns

the value of the "individuals" property

Since: 0.5.1

folks_individual_aggregator_get_individuals

### folks_individual_aggregator_get_user ()

    FolksIndividual *
    folks_individual_aggregator_get_user (FolksIndividualAggregator *self);

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

The FolksIndividual representing the user.

If it exists, this holds the FolksIndividual who is the user: the FolksIndividual containing the FolksPersonas who are the owners of the accounts for their respective backends.

#### Parameters

self | the FolksIndividualAggregator instance to query |

#### Returns

the value of the "user" property

Since: 0.3.0

folks_individual_aggregator_get_user

### folks_individual_aggregator_dup ()

    FolksIndividualAggregator *
    folks_individual_aggregator_dup (void);

Create or return the singleton ``folks_individual_aggregator_new()`` class instance. If the instance doesn't exist already, it will be created with the default FolksBackendStore.

This function is thread-safe.

#### Returns

Singleton ``folks_individual_aggregator_new()`` instance

Since: 0.9.5

folks_individual_aggregator_dup

### folks_individual_aggregator_dup_with_backend_store ()

    FolksIndividualAggregator *
    folks_individual_aggregator_dup_with_backend_store
                                   (FolksBackendStore *store);

Create or return the singleton ``folks_individual_aggregator_new()`` class instance with a custom FolksBackendStore. If the instance doesn't exist already, it will be created with the given FolksBackendStore rather than the default one. If the instance already exists but is using another FolksBackendStore then a warning is raised and null is returned.

This function is thread-safe.

#### Parameters

store | . the FolksBackendStore to use instead of the default one. . | [in]

#### Returns

Singleton ``folks_individual_aggregator_new()`` instance, or null

Since: 0.9.5

folks_individual_aggregator_dup_with_backend_store

## Types and Values

### FOLKS_TYPE_INDIVIDUAL_AGGREGATOR

    #define FOLKS_TYPE_INDIVIDUAL_AGGREGATOR (folks_individual_aggregator_get_type ())

The type for FolksIndividualAggregator.

FOLKS_TYPE_INDIVIDUAL_AGGREGATOR

### struct FolksIndividualAggregator

    struct FolksIndividualAggregator {
    	GObject parent_instance;
    	FolksIndividualAggregatorPrivate * priv;
    };

Stores FolksIndividuals which have been created through aggregation of all the FolksPersonas provided by the various FolksBackends.

This is the main interface for client applications.

Linking and unlinking of personas and individuals is performed entirely through the aggregator. Personas may be linked together to form individuals; for example, the personas which form `individual1` and `individual2` may be linked together with `another_persona` to give a new FolksIndividual:

      var personas = new HashSet<Persona> ();
      personas.add_all (individual1.personas);
      personas.add_all (individual2.personas);
      personas.add (another_persona);
      yield my_individual_aggregator.link_personas (personas);

The individuals which contained those personas will be removed when ``folks_individual_aggregator_link_personas()`` is called. Any personas in those individuals which were not included in the linking call may end up implicitly linked to the new individual, or may be aggregated into other new individuals.

For example, consider the situation where `individual1` contains two personas, `persona1A` and `persona1B`; `individual2` contains one persona, `persona2A`; and `another_persona` comes from `individual3`, which also contains `persona3A` and `persona3B`. Calling ``folks_individual_aggregator_link_personas()`` on `persona1A`, `persona1B`, `persona2A` and `another_persona` will result in `individual1` and `individual2` being removed. A new FolksIndividual will be created containing all the personas passed to the linking function. It might also contain `persona3A` and `persona3B`; or they might be in one or two other new individuals.

An existing individual may be unlinked to form singleton individuals for each of its personas:

      yield my_individual_aggregator.unlink_individual (my_individual);

Note that to link two individuals together, their two sets of personas must be linked together. There is no API to directly link the individuals themselves, as conceptually folks links FolksPersonas, not FolksIndividuals.

Folks does not support having more than one IndividualAggregator instantiated at the same time. Most clients should use ``folks_individual_aggregator_dup()`` to retrieve the IndividualAggregator singleton.

FolksIndividualAggregator

### struct FolksIndividualAggregatorClass

    struct FolksIndividualAggregatorClass {
    	GObjectClass parent_class;
    };

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

#### Members

FolksIndividualAggregatorClass

### enum FolksIndividualAggregatorError

Errors from FolksIndividualAggregators.

#### Members

FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_ADD_FAILED | Adding a FolksPersona to a FolksPersonaStore failed. |
FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_NO_WRITEABLE_STORE | An operation which required the use of a writeable store failed because no writeable store was available. |
FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_STORE_OFFLINE | The FolksPersonaStore was offline (ie, this is a temporary failure). |
FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_PROPERTY_NOT_WRITEABLE | The FolksPersonaStore did not support writing to a property which the user requested to write to, or which was necessary to write to for storing linking information. |
FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_NO_PRIMARY_STORE | An operation which required the use of a primary store failed because no primary store was available. |

FolksIndividualAggregatorError