FOLKS_TYPE_INDIVIDUAL_AGGREGATOR

#define FOLKS_TYPE_INDIVIDUAL_AGGREGATOR (folks_individual_aggregator_get_type ())

The type for FolksIndividualAggregator.

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.)

See also: folks_individual_aggregator_prepare_finish()

Since 0.1.11

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.)

See also: folks_individual_aggregator_prepare()

Since 0.1.11

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.

Since 0.5.1

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.

Since 0.5.1

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:

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

See also: folks_individual_aggregator_add_persona_from_details_finish()

Since 0.3.5

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:

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

See also: folks_individual_aggregator_add_persona_from_details()

Since 0.3.5

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.

See also: folks_individual_aggregator_remove_individual_finish()

Since 0.1.11

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.

See also: folks_individual_aggregator_remove_individual()

Since 0.1.11

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.

See also: folks_individual_aggregator_remove_persona_finish()

Since 0.1.11

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.

See also: folks_individual_aggregator_remove_persona()

Since 0.1.11

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".

See also: folks_individual_aggregator_link_personas_finish()

Since 0.5.1

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".

See also: folks_individual_aggregator_link_personas()

Since 0.5.1

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".

See also: folks_individual_aggregator_unlink_individual_finish()

Since 0.1.13

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".

See also: folks_individual_aggregator_unlink_individual()

Since 0.1.13

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.

See also: folks_individual_aggregator_ensure_individual_property_writeable_finish()

Since 0.6.2

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.

See also: folks_individual_aggregator_ensure_individual_property_writeable()

Since 0.6.2

folks_individual_aggregator_new ()

FolksIndividualAggregator * folks_individual_aggregator_new
                                                        (void);

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_individual_aggregator_get_is_prepared ()

gboolean            folks_individual_aggregator_get_is_prepared
                                                        (FolksIndividualAggregator *self);

folks_individual_aggregator_get_is_quiescent ()

gboolean            folks_individual_aggregator_get_is_quiescent
                                                        (FolksIndividualAggregator *self);

folks_individual_aggregator_get_primary_store ()

FolksPersonaStore * folks_individual_aggregator_get_primary_store
                                                        (FolksIndividualAggregator *self);

folks_individual_aggregator_get_individuals ()

GeeMap *            folks_individual_aggregator_get_individuals
                                                        (FolksIndividualAggregator *self);

folks_individual_aggregator_get_user ()

FolksIndividual *   folks_individual_aggregator_get_user
                                                        (FolksIndividualAggregator *self);

struct FolksIndividualAggregator

struct FolksIndividualAggregator;

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.

enum FolksIndividualAggregatorError

typedef enum {
	FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_ADD_FAILED,
	FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_NO_WRITEABLE_STORE,
	FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_STORE_OFFLINE,
	FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_PROPERTY_NOT_WRITEABLE,
	FOLKS_INDIVIDUAL_AGGREGATOR_ERROR_NO_PRIMARY_STORE
} FolksIndividualAggregatorError;

Errors from FolksIndividualAggregators.

The "individuals" property

  "individuals"              GeeMap*               : Read

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.

Since 0.5.1

The "is-prepared" property

  "is-prepared"              gboolean              : Read

Whether folks_individual_aggregator_prepare() has successfully completed for this aggregator.

Default value: FALSE

Since 0.3.0

The "is-quiescent" property

  "is-quiescent"             gboolean              : Read

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.

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

Default value: FALSE

Since 0.6.2

The "primary-store" property

  "primary-store"            FolksPersonaStore*    : Read

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 GConf key set in _FOLKS_CONFIG_KEY (system set store) - going with the `key-file` or `eds` store as the fall-back option

Since 0.5.0

The "user" property

  "user"                     FolksIndividual*      : Read

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.

Since 0.3.0

The "individuals-changed" signal

void                user_function                      (FolksIndividualAggregator    *individual_aggregator,
                                                        GeeSet                       *added,
                                                        GeeSet                       *removed,
                                                        gchar                        *message,
                                                        FolksPersona                 *actor,
                                                        FolksGroupDetailsChangeReason reason,
                                                        gpointer                      user_data)                  : Run Last

Emitted when one or more FolksIndividuals are added to or removed from the aggregator.

If more information about the relationships between FolksIndividuals which have been linked and unlinked is needed, consider connecting to "individuals-changed-detailed" instead, which is emitted at the same time as this signal.

This will not be emitted until after folks_individual_aggregator_prepare() has been called.

Since 0.5.1

The "individuals-changed-detailed" signal

void                user_function                      (FolksIndividualAggregator *individual_aggregator,
                                                        GeeMultiMap               *changes,
                                                        gpointer                   user_data)                  : Run Last

Emitted when one or more FolksIndividuals are added to or removed from the aggregator.

This is emitted at the same time as "individuals-changed", but includes more information about the relationships between FolksIndividuals which have been linked and unlinked.

Individuals which have been linked will be listed in the multi-map as mappings from the old individuals to the single new individual which replaces them (i.e. each of the old individuals will map to the same new individual). This new individual is the one which will be specified as the `replacement_individual` in the "removed" signal for the old individuals.

Individuals which have been unlinked will be listed in the multi-map as a mapping from the unlinked individual to a set of one or more individuals which replace it.

Individuals which have been added will be listed in the multi-map as a mapping from `null` to the set of added individuals. If `null` doesn't map to anything, no individuals have been added to the aggregator.

Individuals which have been removed will be listed in the multi-map as mappings from the removed individual to `null`.

This will not be emitted until after folks_individual_aggregator_prepare() has been called.

Since 0.6.2