internal extern static async E.SourceRegistry create_source_registry (GLib.Cancellable? cancellable = null) throws GLib.Error;
/**
- * A persona store.
- * It will create {@link Persona}s for each contacts on the main addressbook.
+ * A persona store representing a single EDS address book.
+ *
+ * The persona store will contain {@link Edsf.Persona}s for each contact in the
+ * address book it represents.
*/
public class Edsf.PersonaStore : Folks.PersonaStore
{
/**
* A persona subclass which represents a single EDS contact.
+ *
+ * Each {@link Edsf.Persona} instance represents a single EDS {@link E.Contact}.
+ * When the contact is modified (either by this folks client, or a different
+ * client), the {@link Edsf.Persona} remains the same, but is assigned a new
+ * {@link E.Contact}. It then updates its properties from this new contact.
*/
public class Edsf.Persona : Folks.Persona,
AntiLinkable,
"email_1", "email_2", "email_3", "email_4"
};
- [Deprecated]
/**
* vCard field names for miscellaneous URIs.
*
* @since 0.6.0
*/
+ [Deprecated]
public static const string[] url_properties = {
"blog_url", "fburl", "homepage_url", "video_url"
};
/**
* A persona store which is associated with a single libsocialweb service.
+ *
* It will create {@link Persona}s for each of the contacts known to that
* service.
*/
/**
* A persona subclass which represents a single libsocialweb contact.
+ *
+ * There is a one-to-one correspondence between {@link Swf.Persona}s and
+ * {@link SocialWebClient.Contact}s.
*/
public class Swf.Persona : Folks.Persona,
AvatarDetails,
/**
* A persona subclass which represents a single instant messaging contact from
* Telepathy.
+ *
+ * There is a one-to-one correspondence between {@link Tpf.Persona}s and
+ * {@link TelepathyGLib.Contact}s, although at any time the
+ * {@link Tpf.Persona.contact} property of a persona may be `null` if the
+ * contact's Telepathy connection isn't available (e.g. due to being offline).
+ * In this case, the persona's properties persist from a local cache.
*/
public class Tpf.Persona : Folks.Persona,
AliasDetails,
using GLib;
/**
- * Interface for classes which represent aliasable contacts, such as
- * {@link Persona} and {@link Individual}.
+ * Alias for a contact.
+ *
+ * This allows representation of aliases for contacts, where the user has chosen
+ * their own name for the contact to better represent that contact to them. A
+ * typical example of this is the use of user-chosen aliases for contacts in
+ * instant messaging programs.
*/
public interface Folks.AliasDetails : Object
{
using GLib;
/**
- * A singleton persistent cache object for avatars used across backends in
- * folks. Avatars may be added to the cache, and referred to by a persistent
- * URI from that point onwards.
+ * A singleton persistent cache for avatars in folks.
+ *
+ * Avatars may be added to the cache, and referred to by a persistent
+ * URI from that point onwards. The avatars will be stored on disk in the user's
+ * XDG cache directory.
+ *
+ * The avatar cache is typically used by backends where retrieving avatars is an
+ * expensive operation (for example, they have to be downloaded from the network
+ * every time they're used).
+ *
+ * All avatars from all users of the {@link Folks.AvatarCache} are stored in the
+ * same namespace, so callers must ensure that the IDs they use for avatars are
+ * globally unique (e.g. by using the corresponding {@link Folks.Persona.uid}).
*
* @since 0.6.0
*/
}
/**
- * Create or return the singleton {@link AvatarCache} class instance.
+ * Create or return the singleton {@link Folks.AvatarCache} class instance.
* If the instance doesn't exist already, it will be created.
*
* This function is thread-safe.
*
- * @return Singleton {@link AvatarCache} instance
+ * @return Singleton {@link Folks.AvatarCache} instance
* @since 0.6.0
*/
public static AvatarCache dup ()
using GLib;
/**
- * Interface for classes which represent contacts which have an avatar
- * (pictorial representation), such as {@link Persona} and {@link Individual}.
+ * Avatar for a contact.
+ *
+ * This allows avatars to be associated with contacts. An avatar is a small
+ * image file which represents the contact, such as a photo of them.
+ *
+ * @since 0.6.0
*/
public interface Folks.AvatarDetails : Object
{
/**
* An avatar for the contact.
*
- * An avatar is a small image file which represents the contact. It may be
- * `null` if unset. Otherwise, the image data may be asynchronously loaded
- * using the methods of the {@link GLib.LoadableIcon} implementation.
+ * The avatar may be `null` if unset. Otherwise, the image data may be
+ * asynchronously loaded using the methods of the {@link GLib.LoadableIcon}
+ * implementation.
*
* @since 0.6.0
*/
using GLib;
/**
- * This interface contains the birth date of a {@link Persona} and
- * {@link Individual}
+ * Birthday details for a contact.
+ *
+ * This allows representation of the birth date and associated calendar event ID
+ * of a contact.
*
* @since 0.4.0
*/
/**
* The event ID of the birthday event from the source calendar.
*
- * If this is `null`, the birthday event is unknown.
+ * If this is `null`, the birthday event is unknown. The semantics of the
+ * event ID are left unspecified by folks.
*
* @since 0.4.0
*/
...);
/**
- * Manage debug output and status reporting for all folks objects. All GLib
- * debug logging calls are passed through a log handler in this class, which
- * allows debug domains to be outputted according to whether they've been
+ * Manages debug output and status reporting for all folks objects.
+ *
+ * All GLib debug logging calls are passed through a log handler in this class,
+ * which allows debug domains to be outputted according to whether they've been
* enabled by being passed to {@link Debug.dup}.
*
* @since 0.5.1
}
/**
- * Create or return the singleton {@link Debug} class instance.
+ * Create or return the singleton {@link Folks.Debug} class instance.
* If the instance doesn't exist already, it will be created with no debug
* domains enabled.
*
* This function is thread-safe.
*
- * @return Singleton {@link Debug} instance
+ * @return Singleton {@link Folks.Debug} instance
* @since 0.5.1
*/
public static Debug dup ()
}
/**
- * Create or return the singleton {@link Debug} class instance.
+ * Create or return the singleton {@link Folks.Debug} class instance.
* If the instance doesn't exist already, it will be created with the given
* set of debug domains enabled. Otherwise, the existing instance will have
* its set of enabled domains changed to the provided set.
* null to disable debug output
* @param colour_enabled Whether debug output should be coloured using
* terminal escape sequences
- * @return Singleton {@link Debug} instance
+ * @return Singleton {@link Folks.Debug} instance
* @since 0.5.1
*/
public static Debug dup_with_flags (string? debug_flags,
/**
* Causes all significant objects in the library to print their current
* status to standard output, obeying the options set on this
- * {@link Debug} instance for colouring and other formatting.
+ * {@link Folks.Debug} instance for colouring and other formatting.
*
* @since 0.5.1
*/
using GLib;
/**
- * Interface exposing a {@link Persona}'s or {@link Individual}'s user-defined
- * status as a favourite.
+ * Favourite status for a contact.
+ *
+ * This allows user-defined favourite contacts to be specified. A contact is a
+ * favourite if the user has selected them as such; the semantics of 'favourite'
+ * are left unspecified by folks. Typically, a user might select the contacts
+ * that they talk to most frequently as their favourite contacts in an instant
+ * messaging program, for example.
*/
public interface Folks.FavouriteDetails : Object
{
}
/**
- * Interface for specifying the gender of a contact.
+ * Gender of a contact.
+ *
+ * This allows representation of the gender of a contact.
*
* @since 0.3.5
*/
using Gee;
/**
- * Interface for {@link Persona}s or {@link Individual}s which can be grouped
- * into sets of similar objects.
+ * Groups for a contact.
+ *
+ * This allows contacts to be collected into user-defined groups (or categories)
+ * for organisational purposes. Groups are non-exclusive and non-hierarchical,
+ * so a single contact can be put into many groups, but groups may not
+ * themselves be put into groups.
*/
public interface Folks.GroupDetails : Object
{
* persona store (see {@link IndividualAggregator.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 {@link Individual}s.
+ * store) will always be used by {@link Folks.Individual}s.
*
* No further guarantees are made about the order of preference used for
- * choosing which property values to use for the {@link Individual}, other than
- * that the order may vary between properties, but is guaranteed to be stable
- * for a given property.
+ * choosing which property values to use for the {@link Folks.Individual}, other
+ * than that the order may vary between properties, but is guaranteed to be
+ * stable for a given property.
*/
public class Folks.Individual : Object,
AliasDetails,
* {@link Folks.Individual.personas} property after construction.
*
* @param personas a list of {@link Persona}s to initialise the
- * {@link Individual} with, or `null`
+ * {@link Folks.Individual} with, or `null`
* @return a new Individual
*
* @since 0.5.1
* Anti-linked with an individual?
*
* Check whether this individual is anti-linked to any of the {@link Persona}s
- * in {@link Individual} `i`. If so, `true` will be returned — `false` will be
- * returned otherwise.
+ * in {@link Folks.Individual} `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.
using GLib;
/**
- * Object representing interaction details for an Individual or Persona.
- * Interaction details are the number of calls or IM interactions with
- * a {@link Persona} or an {@link Individual} as well as the the datetime of
- * the last call and IM interaction.
+ * Interaction details of a contact.
+ *
+ * Interaction details are the number and date/time of calls or IM interactions
+ * with a contact, giving an idea of the recent interactions the user has had
+ * with that contact.
*
* @since 0.7.1
*/
using GLib;
/**
- * Object for a full name split in its constituent parts (given name,
+ * Structured name representation for human names.
+ *
+ * Represents a full name split in its constituent parts (given name,
* family name, etc.). This structure corresponds to the "N" field in
- * VCards. The parts of the name are never null, an empty string
+ * vCards. The parts of the name are never `null`: an empty string
* indicates that a property is not set.
*
* @since 0.3.5
/**
* Object representing a postal mail address.
- * The components of the address are never null, an empty string
+ *
+ * The components of the address are never `null`: an empty string
* indicates that a property is not set.
*/
public class Folks.PostalAddress : Object
}
/**
- * This class provides functionality to explore a potential match between
- * two individuals.
+ * Match calculator for pairs of individuals.
+ *
+ * This provides functionality to explore the degree of a potential match
+ * between two individuals. It compares the similarity of the individuals'
+ * properties to determine how likely it is that the individuals represent the
+ * same physical person.
+ *
+ * This can be used by folks clients to, for example, present suggestions of
+ * pairs of individuals which should be linked by the user.
*
* @since 0.5.0
*/
}
/**
+ * Create a new PotentialMatch.
+ *
+ * @return a new PotentialMatch
+ *
+ * @since 0.5.0
+ */
+ public PotentialMatch ()
+ {
+ base ();
+ }
+
+ /**
* Whether two individuals are likely to be the same person.
*
* @param a an individual to compare
using GLib;
/**
- * This interface represents the role a {@link Persona} and {@link Individual}
- * have in a given Organisation.
+ * Role a contact has in an organisation.
+ *
+ * This represents the role a {@link Persona} or {@link Individual} has in a
+ * single given organisation, such as a company.
*
* @since 0.4.0
*/
using Gee;
+/* TODO: This should be converted to a nested namespace, rather than a class,
+ * when folks next breaks API. Having it as a class means that a GType is always
+ * registered for it, and a C constructor function created, even though
+ * instantiating it is pointless as all the methods are static (and should
+ * remain so). */
/**
* Utility functions to simplify common patterns in Folks client code.
*
+ * These may be used by folks clients as well, and are part of folks' supported
+ * stable API.
+ *
* @since 0.6.0
*/
public class Folks.Utils : Object
}
/**
+ * Create a new utilities object.
+ *
+ * This method is useless and should never be used. It will be removed in a
+ * future version in favour of making the Utils class into a nested namespace.
+ *
+ * @return a new utilities object
+ * @since 0.6.0
+ */
+ [Deprecated (since = "UNRELEASED")]
+ public Utils ()
+ {
+ base ();
+ }
+
+ /**
* Check whether two multi-maps of strings to strings are equal. This performs
* a deep check for equality, checking whether both maps are of the same size,
* and that each key maps to the same set of values in both maps.