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

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

Properties

gchar * alias Read / Write
GLoadableIcon * avatar Read / Write
GDateTime * birthday Read / Write
gchar * calendar-event-id Read / Write
guint call-interaction-count Read
GStrv client-types Read / Write
gchar * display-name Read
GeeSet * email-addresses Read / Write
gchar * full-name Read / Write
FolksGender gender Read / Write
GeeSet * groups Read / Write
gchar * id Read
GeeMultiMap * im-addresses Read / Write
guint im-interaction-count Read
gboolean is-favourite Read / Write
gboolean is-user Read
GDateTime * last-call-interaction-datetime Read
GDateTime * last-im-interaction-datetime Read
GeeSet * local-ids Read / Write
FolksLocation * location Read / Write
gchar * nickname Read / Write
GeeSet * notes Read / Write
GeeSet * personas Read / Write
GeeSet * phone-numbers Read / Write
GeeSet * postal-addresses Read / Write
gchar * presence-message Read / Write
gchar * presence-status Read / Write
FolksPresenceType presence-type Read / Write
GeeSet * roles Read / Write
FolksStructuredName * structured-name Read / Write
FolksTrustLevel trust-level Read
GeeSet * urls Read / Write
GeeMultiMap * web-service-addresses Read / Write

Signals

void personas-changed Run Last
void removed Run Last

Types and Values

struct FolksIndividual
struct FolksIndividualClass
enum FolksTrustLevel

Object Hierarchy

    GEnum
    ╰── FolksTrustLevel
    GObject
    ╰── FolksIndividual

Implemented Interfaces

FolksIndividual implements FolksAliasDetails, FolksAvatarDetails, FolksBirthdayDetails, FolksEmailDetails, FolksFavouriteDetails, FolksGenderDetails, FolksGroupDetails, FolksImDetails, FolksInteractionDetails, FolksLocalIdDetails, FolksLocationDetails, FolksNameDetails, FolksNoteDetails, FolksPresenceDetails, FolksPhoneDetails, FolksPostalAddressDetails, FolksRoleDetails, FolksUrlDetails and FolksWebServiceDetails.

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_TYPE_INDIVIDUAL

#define FOLKS_TYPE_INDIVIDUAL (folks_individual_get_type ())

The type for FolksIndividual.

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 # Display ID (e.g. fooexample.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

struct FolksIndividual

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

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

GObjectClass parent_class;

the parent class structure

  

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

Property Details

The “alias” property

  “alias”                    gchar *

alias.

Flags: Read / Write

Default value: NULL

The “avatar” property

  “avatar”                   GLoadableIcon *

avatar.

Flags: Read / Write

The “birthday” property

  “birthday”                 GDateTime *

birthday.

Flags: Read / Write

The “calendar-event-id” property

  “calendar-event-id”        gchar *

calendar-event-id.

Flags: Read / Write

Default value: NULL

The “call-interaction-count” property

  “call-interaction-count”   guint

call-interaction-count.

Flags: Read

Default value: 0

The “client-types” property

  “client-types”             GStrv

client-types.

Flags: Read / Write

The “display-name” property

  “display-name”             gchar *

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 # Display ID (e.g. fooexample.org) # Postal address # _("Unnamed Person")

Flags: Read

Default value: NULL

Since 0.9.7

The “email-addresses” property

  “email-addresses”          GeeSet *

email-addresses.

Flags: Read / Write

The “full-name” property

  “full-name”                gchar *

full-name.

Flags: Read / Write

Default value: NULL

The “gender” property

  “gender”                   FolksGender

gender.

Flags: Read / Write

Default value: FOLKS_GENDER_UNSPECIFIED

The “groups” property

  “groups”                   GeeSet *

groups.

Flags: Read / Write

The “id” property

  “id”                       gchar *

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

Flags: Read

Default value: NULL

The “im-addresses” property

  “im-addresses”             GeeMultiMap *

im-addresses.

Flags: Read / Write

The “im-interaction-count” property

  “im-interaction-count”     guint

im-interaction-count.

Flags: Read

Default value: 0

The “is-favourite” property

  “is-favourite”             gboolean

is-favourite.

Flags: Read / Write

Default value: FALSE

The “is-user” property

  “is-user”                  gboolean

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.

Flags: Read

Default value: FALSE

Since 0.3.0

The “last-call-interaction-datetime” property

  “last-call-interaction-datetime” GDateTime *

last-call-interaction-datetime.

Flags: Read

The “last-im-interaction-datetime” property

  “last-im-interaction-datetime” GDateTime *

last-im-interaction-datetime.

Flags: Read

The “local-ids” property

  “local-ids”                GeeSet *

local-ids.

Flags: Read / Write

The “location” property

  “location”                 FolksLocation *

location.

Flags: Read / Write

The “nickname” property

  “nickname”                 gchar *

nickname.

Flags: Read / Write

Default value: NULL

The “notes” property

  “notes”                    GeeSet *

notes.

Flags: Read / Write

The “personas” property

  “personas”                 GeeSet *

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.

Flags: Read / Write

Since 0.5.1

The “phone-numbers” property

  “phone-numbers”            GeeSet *

phone-numbers.

Flags: Read / Write

The “postal-addresses” property

  “postal-addresses”         GeeSet *

postal-addresses.

Flags: Read / Write

The “presence-message” property

  “presence-message”         gchar *

presence-message.

Flags: Read / Write

Default value: NULL

The “presence-status” property

  “presence-status”          gchar *

presence-status.

Flags: Read / Write

Default value: NULL

The “presence-type” property

  “presence-type”            FolksPresenceType

presence-type.

Flags: Read / Write

Default value: FOLKS_PRESENCE_TYPE_UNSET

The “roles” property

  “roles”                    GeeSet *

roles.

Flags: Read / Write

The “structured-name” property

  “structured-name”          FolksStructuredName *

structured-name.

Flags: Read / Write

The “trust-level” property

  “trust-level”              FolksTrustLevel

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.

Flags: Read

Default value: FOLKS_TRUST_LEVEL_NONE

Since 0.1.15

The “urls” property

  “urls”                     GeeSet *

urls.

Flags: Read / Write

The “web-service-addresses” property

  “web-service-addresses”    GeeMultiMap *

web-service-addresses.

Flags: Read / Write

Signal Details

The “personas-changed” signal

void
user_function (FolksIndividual *individual,
               GeeSet          *added,
               GeeSet          *removed,
               gpointer         user_data)

Emitted when one or more FolksPersonas are added to or removed from the Individual. As the parameters are (unordered) sets, the orders of their elements are undefined.

Parameters

individual

the FolksIndividual instance that received the signal

  

added

 .

a set of FolksPersonas which have been added

 

removed

 .

a set of FolksPersonas which have been removed

 

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

Since 0.5.1

The “removed” signal

void
user_function (FolksIndividual *individual,
               FolksIndividual *replacement_individual,
               gpointer         user_data)

Emitted when the last of the Individual's FolksPersonas has been removed.

At this point, the Individual is invalid, so any client referencing it should unreference it and remove it from their UI.

Parameters

individual

the FolksIndividual instance that received the signal

  

replacement_individual

 .

the individual which has replaced this one due to linking, or null if this individual was removed for another reason

 

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

Since 0.1.13

Generated by GTK-Doc V1.21.1