FolksIndividualAggregator

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

Functions

#define FOLKS_TYPE_INDIVIDUAL_AGGREGATOR
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 ()

Properties

FolksBackendStore * backend-store Read / Write / Construct Only
GeeMap * individuals Read
gboolean is-prepared Read
gboolean is-quiescent Read
FolksPersonaStore * primary-store Read
FolksIndividual * user Read

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── FolksIndividualAggregator

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:

1
2
3
4
5
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:

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

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_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 occuring, or NULL to ignore

 

Since 0.1.11


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_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 occuring, or NULL to ignore

 

Since 0.7.3


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_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_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_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 occuring, 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_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_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 occuring, or NULL to ignore

 

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.

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_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 occuring, or NULL to ignore

 

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

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_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 occuring, or NULL to ignore.

[error-domains FolksIndividualAggregatorError]

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

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_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 occuring, or NULL to ignore

 

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.

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_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 occuring, 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_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_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 occuring, or NULL to ignore

 

Returns

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

Since 0.7.0


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:

1
2
3
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_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_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_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_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_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_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_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_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_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

Types and Values

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.

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:

1
2
3
4
5
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:

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


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

GObjectClass parent_class;

the parent class structure

 

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.

 

Property Details

The “backend-store” property

  “backend-store”            FolksBackendStore *

The backend store providing the persona stores for this aggregator.

Flags: Read / Write / Construct Only

Since 0.9.7


The “individuals” property

  “individuals”              GeeMap *

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.

Flags: Read

Since 0.5.1


The “is-prepared” property

  “is-prepared”              gboolean

Whether folks_individual_aggregator_prepare() has successfully completed for this aggregator.

Flags: Read

Default value: FALSE

Since 0.3.0


The “is-quiescent” property

  “is-quiescent”             gboolean

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.

Flags: Read

Default value: FALSE

Since 0.6.2


The “primary-store” property

  “primary-store”            FolksPersonaStore *

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

Flags: Read

Since 0.5.0


The “user” property

  “user”                     FolksIndividual *

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.

Flags: Read

Since 0.3.0

Signal Details

The “individuals-changed” signal

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

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.

FolksIndividualAggregator::individuals-changed has been deprecated since version 0.6.2 and should not be used in newly-written code.

Replaced by “individuals_changed_detailed”.

Parameters

individual_aggregator

the FolksIndividualAggregator instance that received the signal

 

added

 .

a list of FolksIndividuals which have been added

 

removed

 .

a list of FolksIndividuals which have been removed

 

message

 .

a string message from the backend, if any

 

actor

 .

the FolksPersona who made the change, if known

 

reason

 .

the reason for the change

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since 0.5.1


The “individuals-changed-detailed” signal

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

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.

Parameters

individual_aggregator

the FolksIndividualAggregator instance that received the signal

 

changes

 .

a mapping of old FolksIndividuals to new FolksIndividuals for the individuals which have changed in the aggregator

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since 0.6.2