FOLKS_TYPE_PERSONA

#define FOLKS_TYPE_PERSONA (folks_persona_get_type ())

The type for FolksPersona.

folks_persona_linkable_property_to_links ()

void
folks_persona_linkable_property_to_links
                               (FolksPersona *self,
                                const gchar *prop_name,
                                FolksPersonaLinkablePropertyCallback callback,
                                void *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"

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.

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.

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

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.

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.

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.

Since 0.6.0

folks_persona_get_linkable_properties ()

gchar **
folks_persona_get_linkable_properties (FolksPersona *self,
                                       int *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.

Since 0.1.13

folks_persona_get_writeable_properties ()

gchar **
folks_persona_get_writeable_properties
                               (FolksPersona *self,
                                int *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.

Since 0.6.0

FolksPersonaLinkablePropertyCallback ()

void
(*FolksPersonaLinkablePropertyCallback)
                               (const gchar *link,
                                void *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.

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.

See also: folks_persona_split_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()

Since 0.1.13

struct FolksPersona

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

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, void* callback_target);
	gchar** (*get_linkable_properties) (FolksPersona* self, int* result_length1);
	gchar** (*get_writeable_properties) (FolksPersona* self, int* result_length1);
};

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

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.

Since 0.6.2

The “display-id” property

  “display-id”               gchar *

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

Flags: Read / Write / Construct Only

Default value: NULL

Since 0.1.13

The “iid” property

  “iid”                      gchar *

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.

Flags: Read / Write / Construct Only

Default value: NULL

The “individual” property

  “individual”               FolksIndividual *

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.

Flags: Read / Write

Since 0.6.0

The “is-user” property

  “is-user”                  gboolean

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.

Flags: Read / Write / Construct Only

Default value: FALSE

Since 0.3.0

The “linkable-properties” property

  “linkable-properties”      GStrv

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.

Flags: Read

Since 0.1.13

The “store” property

  “store”                    FolksPersonaStore *

The FolksPersonaStore which contains this Persona.

Flags: Read / Write / Construct Only

The “uid” property

  “uid”                      gchar *

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.

See also: folks_persona_build_uid(), folks_persona_split_uid()

Flags: Read / Write / Construct Only

Default value: NULL

The “writeable-properties” property

  “writeable-properties”     GStrv

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.

Flags: Read

Since 0.6.0