FolksPersona: Reference Manual

## FolksPersona FolksPersona — Represents a "shard" of a person from a single source (a single FolksBackend), such as an XMPP contact from Telepathy or a vCard contact from evolution-data-server. |

## Functions

void | folks_persona_linkable_property_to_links ()
const gchar * | folks_persona_get_iid ()
const gchar * | folks_persona_get_uid ()
const gchar * | folks_persona_get_display_id ()
gboolean | folks_persona_get_is_user ()
FolksPersonaStore * | folks_persona_get_store ()
FolksIndividual * | folks_persona_get_individual ()
gchar ** | folks_persona_get_linkable_properties ()
gchar ** | folks_persona_get_writeable_properties ()
void | (*FolksPersonaLinkablePropertyCallback) ()
gchar * | folks_persona_build_uid ()
void | folks_persona_split_uid ()

## Types and Values

#define | FOLKS_TYPE_PERSONA
struct | FolksPersona
struct | FolksPersonaClass
enum | FolksPropertyError

## Description

All the personas belonging to one physical person are aggregated to form a single FolksIndividual representing that person.

Properties of a persona are provided by implementing "details" interfaces, such as FolksNameDetails or FolksEmailDetails. They must be accessed through these interfaces. Different backends' subclasses of FolksPersona may implement different sets of interfaces. The set of interfaces implemented by a given persona is guaranteed not to change over the lifetime of that persona.

## Functions

### folks_persona_linkable_property_to_links ()

    void
    folks_persona_linkable_property_to_links
                                   (FolksPersona *self,
                                    const gchar *prop_name,
                                    FolksPersonaLinkablePropertyCallback callback,
                                    gpointer callback_target);

Produce one or more mapping strings for the given property's value.

This is a virtual method, to be overridden by subclasses of FolksPersona who have linkable properties. Each of their linkable properties should be handled by their implementation of this function, examining the current value of the property and calling `callback` with one or more mapping strings for the property's value. Each of these mapping strings will be added to the FolksIndividualAggregator's link map, related to the FolksIndividual instance which contains this FolksPersona.

See also: "linkable-properties"

#### Parameters

self | the FolksPersona instance |
prop_name | . the name of the linkable property to use, which must be listed in "linkable-properties" . | [in]
callback | . a callback to execute for each of the mapping strings generated by this property . | [in]
callback_target | user data to pass to `callback` . | [allow-none][closure]

Since: 0.1.13

### folks_persona_get_iid ()

    const gchar *
    folks_persona_get_iid (FolksPersona *self);

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

The internal ID used to represent the Persona for linking.

This is opaque, and shouldn't be parsed or considered meaningful by clients.

The internal ID should be unique within a backend, but may not be unique across backends, so that links can be made between Personas with similar internal IDs.

#### Parameters

self | the FolksPersona instance to query |

#### Returns

the value of the "iid" property

### folks_persona_get_uid ()

    const gchar *
    folks_persona_get_uid (FolksPersona *self);

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

The universal ID used to represent the Persona outside its FolksBackend.

This is opaque, and should only be parsed by clients using `folks_persona_split_uid()`.

This is the canonical way to refer to any Persona. It is guaranteed to be unique within the Persona's FolksPersonaStore.

A Persona's UID is immutable over the life of the Persona in the backing store, so a given UID is guaranteed to refer to the same Persona each time libfolks is used, until the Persona is permanently removed from its backing store.

#### Parameters

self | the FolksPersona instance to query |

#### Returns

the value of the "uid" property

### folks_persona_get_display_id ()

    const gchar *
    folks_persona_get_display_id (FolksPersona *self);

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

The human-readable, service-specific universal ID used to represent the Persona.

For example: `foo@`xmpp.example.org``.

This should be used whenever the user needs to be presented with a familiar, service-specific ID. For instance, in a prompt for the user to select a specific IM contact within an FolksIndividual to begin a chat with.

This is not guaranteed to be unique outside of the Persona's FolksPersonaStore, but is guaranteed to be unique within it. If a suitable human-readable ID isn’t available from the backend, the display ID will be equal to the "iid".

#### Parameters

self | the FolksPersona instance to query |

#### Returns

the value of the "display-id" property

Since: 0.1.13

### folks_persona_get_is_user ()

    gboolean
    folks_persona_get_is_user (FolksPersona *self);

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

Whether the Persona is the user.

Iff the Persona represents the user (the person who owns the account in the respective backend) this is `true`.

#### Parameters

self | the FolksPersona instance to query |

#### Returns

the value of the "is-user" property

Since: 0.3.0

### folks_persona_get_store ()

    FolksPersonaStore *
    folks_persona_get_store (FolksPersona *self);

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

The FolksPersonaStore which contains this Persona.

#### Parameters

self | the FolksPersona instance to query |

#### Returns

the value of the "store" property

### folks_persona_get_individual ()

    FolksIndividual *
    folks_persona_get_individual (FolksPersona *self);

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

The FolksIndividual which contains this Persona.

This may be `null`, but should only ever be so when the Persona has just been created, when its FolksPersonaStore is being destroyed, or when it's moving between FolksIndividuals.

#### Parameters

self | the FolksPersona instance to query |

#### Returns

the value of the "individual" property

Since: 0.6.0

### folks_persona_get_linkable_properties ()

    gchar **
    folks_persona_get_linkable_properties (FolksPersona *self,
                                           gint *result_length1);

Get and return the current value of the "linkable-properties" property.

The names of the properties of this Persona which are linkable.

If a property name is in this list, and the Persona is from a FolksPersonaStore whose trust level is FOLKS_PERSONA_STORE_TRUST_FULL, the FolksIndividualAggregator should be able to reliably use the value of the property from a given Persona instance to link the Persona with other Personas and form FolksIndividuals.

Note that "uid" is always implicitly a member of this list, and doesn't need to be added explicitly.

This list will have no effect if the Persona's FolksPersonaStore trust level is not FOLKS_PERSONA_STORE_TRUST_FULL.

This property value is guaranteed to be constant for a given persona, but may vary between personas in the same store.

#### Parameters

self | the FolksPersona instance to query |

#### Returns

the value of the "linkable-properties" property

Since: 0.1.13

### folks_persona_get_writeable_properties ()

    gchar **
    folks_persona_get_writeable_properties
                                   (FolksPersona *self,
                                    gint *result_length1);

Get and return the current value of the "writeable-properties" property.

The names of the properties of this Persona which are writeable.

If a property name is in this list, setting the property should result in the updated value being stored in the backend's permanent storage (unless it gets rejected due to being invalid, or a different error occurs).

It's intended that this property value will be constant for a given Persona subclass, but this isn't guaranteed; it's possible that Persona subclasses may vary the value of this property at run time.

#### Parameters

self | the FolksPersona instance to query |

#### Returns

the value of the "writeable-properties" property

Since: 0.6.0

### FolksPersonaLinkablePropertyCallback ()

    void
    (*FolksPersonaLinkablePropertyCallback)
                                   (const gchar *link,
                                    gpointer user_data);

Callback into the aggregator to manipulate a link mapping.

This is a callback provided by the FolksIndividualAggregator whenever a `folks_persona_linkable_property_to_links()` method is called, which should be called by the `linkable_property_to_links` implementation for each linkable-property-to-individual mapping it wants to add or remove in the aggregator.

#### Parameters

link | . the mapping string to be added to the FolksIndividualAggregator . | [in]
user_data | data to pass to the delegate function. | [closure]

Since: 0.1.13

### folks_persona_build_uid ()

    gchar *
    folks_persona_build_uid (const gchar *backend_name,
                             const gchar *persona_store_id,
                             const gchar *persona_id);

Build a UID from the given components.

Each component is escaped before the UID is built. All components must be non-empty strings.

See also: `folks_persona_split_uid()`

#### Parameters

backend_name | . the "name" . | [in]
persona_store_id | . the "id" . | [in]
persona_id | . the Persona identifier (backend-specific) . | [in]

#### Returns

a valid UID

Since: 0.1.13

### folks_persona_split_uid ()

    void
    folks_persona_split_uid (const gchar *uid,
                             gchar * *backend_name,
                             gchar * *persona_store_id,
                             gchar * *persona_id);

Split a UID into its component parts.

Each component is unescaped before being returned. The UID must be correctly formed.

See also: `folks_persona_build_uid()`

#### Parameters

uid | . a valid UID . | [in]
backend_name | . the "name" . | [out]
persona_store_id | . the "id" . | [out]
persona_id | . the Persona identifier (backend-specific) . | [out]

Since: 0.1.13

## Types and Values

### FOLKS_TYPE_PERSONA

    #define FOLKS_TYPE_PERSONA (folks_persona_get_type ())

The type for FolksPersona.

### struct FolksPersona

    struct FolksPersona {
    	GObject parent_instance;
    	FolksPersonaPrivate * priv;
    };

Represents a "shard" of a person from a single source (a single FolksBackend), such as an XMPP contact from Telepathy or a vCard contact from evolution-data-server.

All the personas belonging to one physical person are aggregated to form a single FolksIndividual representing that person.

Properties of a persona are provided by implementing "details" interfaces, such as FolksNameDetails or FolksEmailDetails. They must be accessed through these interfaces. Different backends' subclasses of FolksPersona may implement different sets of interfaces. The set of interfaces implemented by a given persona is guaranteed not to change over the lifetime of that persona.

### struct FolksPersonaClass

    struct FolksPersonaClass {
    	GObjectClass parent_class;
    	void (*linkable_property_to_links) (FolksPersona* self, const gchar* prop_name, FolksPersonaLinkablePropertyCallback callback, gpointer callback_target);
    	gchar** (*get_linkable_properties) (FolksPersona* self, gint* result_length1);
    	gchar** (*get_writeable_properties) (FolksPersona* self, gint* result_length1);
    };

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

#### Members

`linkable_property_to_links` () | virtual method called by `folks_persona_linkable_property_to_links()` |
`get_linkable_properties` () | getter method for the abstract property "linkable-properties" |
`get_writeable_properties` () | getter method for the abstract property "writeable-properties" |

### enum FolksPropertyError

Errors which can be thrown when asynchronously setting a property of a FolksPersona using a setter method defined on an interface such as FolksAliasDetails.

#### Members

FOLKS_PROPERTY_ERROR_NOT_WRITEABLE | Property is not writeable for this particular object. |
FOLKS_PROPERTY_ERROR_INVALID_VALUE | Value was invalid for the property. |
FOLKS_PROPERTY_ERROR_UNKNOWN_ERROR | Unknown error when setting the property. |
FOLKS_PROPERTY_ERROR_UNAVAILABLE | The backing store is offline or otherwise unavailable. This is a temporary error which should be retifiable by going online or ensuring the backing store is logged in. |

Since: 0.6.2