FolksIndividual: Reference Manual

## FolksIndividual FolksIndividual — A physical person, aggregated from the various FolksPersonas the person might have, such as their different IM addresses or vCard entries. An individual must always contain at least one FolksPersona. |

## Functions

gboolean | folks_individual_has_anti_link_with_persona ()
gboolean | folks_individual_has_anti_link_with_individual ()
FolksIndividual * | folks_individual_new ()
FolksTrustLevel | folks_individual_get_trust_level ()
gboolean | folks_individual_get_is_user ()
const gchar * | folks_individual_get_id ()
const gchar * | folks_individual_get_display_name ()
GeeSet * | folks_individual_get_personas ()
void | folks_individual_set_personas ()

## Types and Values

#define | FOLKS_TYPE_INDIVIDUAL
struct | FolksIndividual
struct | FolksIndividualClass
enum | FolksTrustLevel

## Description

When choosing the values of single-valued properties (such as "alias" and "avatar"; but not multi-valued properties such as "groups" and "im-addresses") from the FolksPersonas in the individual to present as the values of those properties of the individual, it is guaranteed that if the individual contains a persona from the primary persona store (see "primary-store"), its property values will be chosen above all others. This means that any changes to property values made through folks (which are normally written to the primary store) will always be used by FolksIndividuals.

No further guarantees are made about the order of preference used for choosing which property values to use for the FolksIndividual, other than that the order may vary between properties, but is guaranteed to be stable for a given property.

## Functions

### folks_individual_has_anti_link_with_persona ()

    gboolean
    folks_individual_has_anti_link_with_persona
                                   (FolksIndividual *self,
                                    FolksPersona *p);

Anti-linked with a persona?

Check whether this individual is anti-linked to FolksPersona `p` at all. If so, `true` will be returned — `false` will be returned otherwise.

Note that this will check for anti-links in either direction, since anti-links are not necessarily symmetric.

#### Parameters

self | the FolksIndividual instance |
p | . persona to check for anti-links with . | [in]

#### Returns

`true` if this individual is anti-linked with persona `p`; `false` otherwise

Since: 0.7.3

### folks_individual_has_anti_link_with_individual ()

    gboolean
    folks_individual_has_anti_link_with_individual
                                   (FolksIndividual *self,
                                    FolksIndividual *i);

Anti-linked with an individual?

Check whether this individual is anti-linked to any of the FolksPersonas in FolksIndividual `i`. If so, `true` will be returned — `false` will be returned otherwise.

Note that this will check for anti-links in either direction, since anti-links are not necessarily symmetric.

#### Parameters

self | the FolksIndividual instance |
i | . individual to check for anti-links with . | [in]

#### Returns

`true` if this individual is anti-linked with individual `i`; `false` otherwise

Since: 0.7.3

### folks_individual_new ()

    FolksIndividual *
    folks_individual_new (GeeSet *personas);

Create a new Individual.

The Individual can optionally be seeded with the FolksPersonas in `personas`. Otherwise, it will have to have personas added using the "personas" property after construction.

#### Parameters

personas | . a list of FolksPersonas to initialise the FolksIndividual with, or `null` . | [in][allow-none]

#### Returns

a new Individual

Since: 0.5.1

### folks_individual_get_trust_level ()

    FolksTrustLevel
    folks_individual_get_trust_level (FolksIndividual *self);

Get and return the current value of the "trust-level" property.

The trust level of the Individual.

This specifies how far the Individual can be trusted to be who it claims to be. See the descriptions for the elements of FolksTrustLevel.

Clients should not allow linking of Individuals who have a trust level of FOLKS_TRUST_LEVEL_NONE.

#### Parameters

self | the FolksIndividual instance to query |

#### Returns

the value of the "trust-level" property

Since: 0.1.15

### folks_individual_get_is_user ()

    gboolean
    folks_individual_get_is_user (FolksIndividual *self);

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

Whether the Individual is the user.

Iff the Individual represents the user – the person who owns the account in the backend for each FolksPersona in the Individual – this is `true`.

It is not guaranteed that every FolksPersona in the Individual has its "is-user" set to the same value as the Individual. For example, the user could own two Telepathy accounts, and have added the other account as a contact in each account. The accounts will expose a FolksPersona for the user (which will have "is-user" set to `true`) and a FolksPersona for the contact for the other account (which will have "is-user" set to `false`).

It is guaranteed that iff this property is set to `true` on an Individual, there will be at least one FolksPersona in the Individual with its "is-user" set to `true`.

It is guaranteed that there will only ever be one Individual with this property set to `true`.

#### Parameters

self | the FolksIndividual instance to query |

#### Returns

the value of the "is-user" property

Since: 0.3.0

### folks_individual_get_id ()

    const gchar *
    folks_individual_get_id (FolksIndividual *self);

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

A unique identifier for the Individual.

This uniquely identifies the Individual, and persists across FolksIndividualAggregator instances. It may not persist across linking the Individual with other Individuals.

This is an opaque string and has no structure.

If an identifier is required which will be used for a long-lived link between different stored data, it may be more desirable to use the "uid" of the most relevant FolksPersona in the Individual instead. For example, if storing references to Individuals who are tagged in a photo, it may be safer to store the UID of the Persona whose backend provided the photo (e.g. Facebook).

As a special case, the ID defaults to an empty string when the individual has no personas (i.e. if it’s just been constructed).

#### Parameters

self | the FolksIndividual instance to query |

#### Returns

the value of the "id" property

### folks_individual_get_display_name ()

    const gchar *
    folks_individual_get_display_name (FolksIndividual *self);

Get and return the current value of the "display-name" property.

The name of this Individual to display in the UI.

This value is set according to the following list of possibilities, each one being tried first on the primary persona, then on all other personas in the Individual, before falling back to the next item on the list: # Alias # Full name, structured name or nickname # E-mail address # Phone number # Display ID (e.g. foo`example.org`) # Postal address # _("Unnamed Person")

#### Parameters

self | the FolksIndividual instance to query |

#### Returns

the value of the "display-name" property

Since: 0.9.7

### folks_individual_get_personas ()

    GeeSet *
    folks_individual_get_personas (FolksIndividual *self);

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

The set of FolksPersonas encapsulated by this Individual.

There must always be at least one Persona in this set.

No order is specified over the set of personas, as such an order may be different across each of the properties implemented by the personas (e.g. should they be ordered by presence, name, star sign, etc.?).

Changing the set of personas may cause updates to the aggregated properties provided by the Individual, resulting in property notifications for them.

Changing the set of personas will not cause permanent linking/unlinking of the added/removed personas to/from this Individual. To do that, call `folks_individual_aggregator_link_personas()` or `folks_individual_aggregator_unlink_individual()`, which will ensure the link changes are written to the appropriate backend.

#### Parameters

self | the FolksIndividual instance to query |

#### Returns

the value of the "personas" property

Since: 0.5.1

### folks_individual_set_personas ()

    void
    folks_individual_set_personas (FolksIndividual *self,
                                   GeeSet *value);

Set the value of the "personas" property to `value` .

The set of FolksPersonas encapsulated by this Individual.

There must always be at least one Persona in this set.

No order is specified over the set of personas, as such an order may be different across each of the properties implemented by the personas (e.g. should they be ordered by presence, name, star sign, etc.?).

Changing the set of personas may cause updates to the aggregated properties provided by the Individual, resulting in property notifications for them.

Changing the set of personas will not cause permanent linking/unlinking of the added/removed personas to/from this Individual. To do that, call `folks_individual_aggregator_link_personas()` or `folks_individual_aggregator_unlink_individual()`, which will ensure the link changes are written to the appropriate backend.

#### Parameters

self | the FolksIndividual instance to modify |
value | the new value of the "personas" property |

Since: 0.5.1

## Types and Values

### FOLKS_TYPE_INDIVIDUAL

    #define FOLKS_TYPE_INDIVIDUAL (folks_individual_get_type ())

The type for FolksIndividual.

### struct FolksIndividual

    struct FolksIndividual {
    	GObject parent_instance;
    	FolksIndividualPrivate * priv;
    };

A physical person, aggregated from the various FolksPersonas the person might have, such as their different IM addresses or vCard entries. An individual must always contain at least one FolksPersona.

When choosing the values of single-valued properties (such as "alias" and "avatar"; but not multi-valued properties such as "groups" and "im-addresses") from the FolksPersonas in the individual to present as the values of those properties of the individual, it is guaranteed that if the individual contains a persona from the primary persona store (see "primary-store"), its property values will be chosen above all others. This means that any changes to property values made through folks (which are normally written to the primary store) will always be used by FolksIndividuals.

No further guarantees are made about the order of preference used for choosing which property values to use for the FolksIndividual, other than that the order may vary between properties, but is guaranteed to be stable for a given property.

### struct FolksIndividualClass

    struct FolksIndividualClass {
    	GObjectClass parent_class;
    };

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

#### Members

### enum FolksTrustLevel

Trust level for an FolksIndividual for use in the UI.

#### Members

FOLKS_TRUST_LEVEL_NONE | The FolksIndividual's FolksPersonas aren't trusted at all. This is the trust level for an FolksIndividual which contains one or more FolksPersonas which cannot be guaranteed to be the same FolksPersonas as were originally linked together. For example, an FolksIndividual containing a link-local XMPP FolksPersona would have this trust level, since someone else could easily spoof the link-local XMPP FolksPersona's identity. |
FOLKS_TRUST_LEVEL_PERSONAS | The FolksIndividual's FolksPersonas are trusted. This trust level is for FolksIndividuals where it can be guaranteed that all the FolksPersonas are the same ones as when they were originally linked together. Note that this doesn't guarantee that the user who behind each FolksPersona is who they claim to be. |

Since: 0.1.15