Folks

libfolks

libfolks is a library that aggregates people from multiple sources (eg, Telepathy connection managers for IM contacts, evolution data server for local contacts, libsocialweb for web service contacts, etc.) to create metacontacts. It's written in Vala (in part to evaluate Vala). The initial goal is for GObject/C support, though the Vala bindings should basically automatic.

libfolks is under heavy development and not yet API/ABI-stable.

Source

Reference Documentation

Debugging

The main way to debug libfolks (or applications using it) is using the FOLKS_DEBUG environment variable. For example, to collect a log file of all libfolks debug data from Empathy, use the command: 

FOLKS_DEBUG_NO_COLOUR=1 FOLKS_DEBUG=all empathy &> folks.log

Available values for the FOLKS_DEBUG environment variable are:

Multiple values can be specified using commas, e.g.: FOLKS_DEBUG=folks,eds,key-file

Another way to debug libfolks itself is to run the folks-inspect utility which is bundled with libfolks (possibly in a utils or tools package, depending on your distribution). Its use is beyond the scope of this page, but it has a “help” command which should serve as an introduction.

Finally, libfolks has a status printing mechanism. Some libfolks clients may expose this as part of their own debug functionality (for example, folks-inspect uses this for its “debug” command), but it can be invoked more generally using gdb: 

set $folks_debug = folks_debug_dup()
print folks_debug_emit_print_status($folks_debug)

This will print out a listing of the state of all the objects relevant to libfolks' linking decisions.

Finally, libfolks outputs debug and status information using terminal colours and formatting by default. If this isn't desired, set the FOLKS_DEBUG_NO_COLOUR environment variable.

Architecture

Some of this architecture has yet to be implemented.

libfolks.png

Concepts

See also: Folks/Glossary

The core of folks is Folks.Individual. An Individual is meant to represent a person, and contains metadata from one or more contact sources (e.g. the Gabble Jabber connection manager, a local addressbook). Individuals contain one or more Personas, which are a subset of a person's metadata (as exposed by a contact source). These Personas form an unordered set. The Individual object will expose the sum of all n-ary attributes (e.g. e-mail addresses) from all contained Personas and will expose a single value for the attribute from amongst the Personas (according some some attribute-specific heuristic) for unary attributes (e.g. alias, avatar).

For example, an Individual's alias is chosen from its Personas by preferring aliases which are set (Personas don't necessarily have to implement Folks.Alias, or have a non-null alias set) and are not equal to the Persona's display ID (e.g. set to their IM address as a default). The aliases from writeable PersonaStores are preferred to those from other PersonaStores.

Currently, all backends except the key-file backend are read-only. The key-file backend is writeable, which allows for linking of Personas from other backends by creating a Kf.Persona containing linkable properties which can be matched against the Personas being linked together. There is only ever one writeable PersonaStore; libfolks does not do synchronisation, since that can only ever go wrong.

Because Individuals are basically just a set of Personas, it is possible to both link and unlink contacts.

Personas are linked using common fields; the single "blessed" writeable PersonaStore (i.e. the key-file backend's only PersonaStore) returns Personas with fields containing the UIDs of all the other Personas which are linked to that Persona. The IndividualAggregator then assembles Individuals from the Personas whose UIDs are are linked from the blessed PersonaStore.

For example, there are two PersonaStores: Telepathy and a blessed key file PersonaStore. The key file contains the following, which is exposed as a Persona: 

[IndividualID]
    jabber=foo@jabber.org
    msn=bla@hotmail.com

The Telepathy backend exposes these two Personas: 

Persona with uid = jabber:foo@jabber.org
Persona with uid = msn:bla@hotmail.com

Since their UIDs are referenced by a Persona in blessed key file PersonaStore, the IndividualAggregator links the two Personas to form an Individual.

This linking can work on other fields from other PersonaStores. For example, if a verified e-mail address was provided by a Persona from a Facebook backend, that could be used to link Personas (by setting the "im-addresses" property from the Folks.IMable interface as a linkable property). This is only possible for Personas which come from "trusted" PersonaStores since, for example, a malicious user could otherwise set their Jabber address on Facebook to someoneelse@jabber.org and hijack people's contact lists; or someone could impersonate someone else's link-local XMPP account by changing their hostname and username (or just using hacked IM software). PersonaStores can either be completely untrusted (e.g. a link-local XMPP PersonaStore); can have their UIDs trusted, but no other properties (e.g. a Jabber PersonaStore); or can have all their properties trusted (e.g. the key-file backend's PersonaStore).

Classes

Interfaces

Roadmap

See the roadmap page.

Bindings

See QtFolks