FOLKS_TYPE_PERSONA_STORE

#define FOLKS_TYPE_PERSONA_STORE (folks_persona_store_get_type ())

The type for FolksPersonaStore.

folks_persona_store_prepare ()

void                folks_persona_store_prepare         (FolksPersonaStore *self,
                                                         GAsyncReadyCallback _callback_,
                                                         gpointer _user_data_);

Prepare the PersonaStore for use.

This connects the PersonaStore to whichever backend-specific services it requires to be able to provide FolksPersonas. This should be called after connecting to the "personas-changed" signal, or a race condition could occur, with the signal being emitted before your code has connected to it, and FolksPersonas getting "lost" as a result.

This is normally handled transparently by the FolksIndividualAggregator.

If this function throws an error, the PersonaStore will not be functional.

This function is guaranteed to be idempotent (since version 0.3.0).

Concurrent calls to this function from different threads will block until preparation has completed. However, concurrent calls to this function from a single thread might not, i.e. the first call will block but subsequent calls might return before the first one. (Though they will be safe in every other respect.)

See also: folks_persona_store_prepare_finish()

Since 0.1.11

folks_persona_store_prepare_finish ()

void                folks_persona_store_prepare_finish  (FolksPersonaStore *self,
                                                         GAsyncResult *_res_,
                                                         GError **error);

Prepare the PersonaStore for use.

This connects the PersonaStore to whichever backend-specific services it requires to be able to provide FolksPersonas. This should be called after connecting to the "personas-changed" signal, or a race condition could occur, with the signal being emitted before your code has connected to it, and FolksPersonas getting "lost" as a result.

This is normally handled transparently by the FolksIndividualAggregator.

If this function throws an error, the PersonaStore will not be functional.

This function is guaranteed to be idempotent (since version 0.3.0).

Concurrent calls to this function from different threads will block until preparation has completed. However, concurrent calls to this function from a single thread might not, i.e. the first call will block but subsequent calls might return before the first one. (Though they will be safe in every other respect.)

See also: folks_persona_store_prepare()

Since 0.1.11

folks_persona_store_flush ()

void                folks_persona_store_flush           (FolksPersonaStore *self,
                                                         GAsyncReadyCallback _callback_,
                                                         gpointer _user_data_);

Flush any pending changes to the PersonaStore's backing store.

PersonaStores may (transparently) implement caching or I/O queueing which means that changes to their FolksPersonas may not be immediately written to the PersonaStore's backing store. Calling this function will force all pending changes to be flushed to the backing store.

This must not be called before folks_persona_store_prepare().

See also: folks_persona_store_flush_finish()

Since 0.1.17

folks_persona_store_flush_finish ()

void                folks_persona_store_flush_finish    (FolksPersonaStore *self,
                                                         GAsyncResult *_res_);

Flush any pending changes to the PersonaStore's backing store.

PersonaStores may (transparently) implement caching or I/O queueing which means that changes to their FolksPersonas may not be immediately written to the PersonaStore's backing store. Calling this function will force all pending changes to be flushed to the backing store.

This must not be called before folks_persona_store_prepare().

See also: folks_persona_store_flush()

Since 0.1.17

folks_persona_store_add_persona_from_details ()

void                folks_persona_store_add_persona_from_details
                                                        (FolksPersonaStore *self,
                                                         GHashTable *details,
                                                         GAsyncReadyCallback _callback_,
                                                         gpointer _user_data_);

Add a new FolksPersona to the PersonaStore.

The FolksPersona will be created by the PersonaStore backend from the key-value pairs given in `details`.

All additions through this function will later be emitted through the personas-changed signal to be notified of the new FolksPersona. The return value is purely for convenience, since it can be complicated to correlate the provided details with the final Persona.

If the store is offline (or PersonaStore.prepare() hasn't yet been called successfully), this function will throw FOLKS_PERSONA_STORE_ERROR_STORE_OFFLINE. It's the responsibility of the caller to cache details and re-try this function if it wishes to make offline adds work.

If the details are not recognised or are invalid, FOLKS_PERSONA_STORE_ERROR_INVALID_ARGUMENT will be thrown. A default set of possible details are defined by FolksPersonaDetail but backends can either support a subset or superset of the suggested defaults.

If a FolksPersona with the given details already exists in the store, no error will be thrown and this function will return `null`.

See also: folks_persona_store_add_persona_from_details_finish()

folks_persona_store_add_persona_from_details_finish ()

FolksPersona *      folks_persona_store_add_persona_from_details_finish
                                                        (FolksPersonaStore *self,
                                                         GAsyncResult *_res_,
                                                         GError **error);

Add a new FolksPersona to the PersonaStore.

The FolksPersona will be created by the PersonaStore backend from the key-value pairs given in `details`.

All additions through this function will later be emitted through the personas-changed signal to be notified of the new FolksPersona. The return value is purely for convenience, since it can be complicated to correlate the provided details with the final Persona.

If the store is offline (or PersonaStore.prepare() hasn't yet been called successfully), this function will throw FOLKS_PERSONA_STORE_ERROR_STORE_OFFLINE. It's the responsibility of the caller to cache details and re-try this function if it wishes to make offline adds work.

If the details are not recognised or are invalid, FOLKS_PERSONA_STORE_ERROR_INVALID_ARGUMENT will be thrown. A default set of possible details are defined by FolksPersonaDetail but backends can either support a subset or superset of the suggested defaults.

If a FolksPersona with the given details already exists in the store, no error will be thrown and this function will return `null`.

See also: folks_persona_store_add_persona_from_details()

folks_persona_store_remove_persona ()

void                folks_persona_store_remove_persona  (FolksPersonaStore *self,
                                                         FolksPersona *persona,
                                                         GAsyncReadyCallback _callback_,
                                                         gpointer _user_data_);

Remove a FolksPersona from the PersonaStore.

It isn't guaranteed that the Persona will actually be removed by the time this asynchronous function finishes. The successful removal of the Persona will be signalled through emission of "personas-changed".

If the store is offline (or PersonaStore.prepare() hasn't yet been called successfully), this function will throw FOLKS_PERSONA_STORE_ERROR_STORE_OFFLINE. It's the responsibility of the caller to cache details and re-try this function if it wishes to make offline removals work.

See also: folks_persona_store_remove_persona_finish()

Since 0.1.11

folks_persona_store_remove_persona_finish ()

void                folks_persona_store_remove_persona_finish
                                                        (FolksPersonaStore *self,
                                                         GAsyncResult *_res_,
                                                         GError **error);

Remove a FolksPersona from the PersonaStore.

It isn't guaranteed that the Persona will actually be removed by the time this asynchronous function finishes. The successful removal of the Persona will be signalled through emission of "personas-changed".

If the store is offline (or PersonaStore.prepare() hasn't yet been called successfully), this function will throw FOLKS_PERSONA_STORE_ERROR_STORE_OFFLINE. It's the responsibility of the caller to cache details and re-try this function if it wishes to make offline removals work.

See also: folks_persona_store_remove_persona()

Since 0.1.11

folks_persona_store_get_type_id ()

const gchar *       folks_persona_store_get_type_id     (FolksPersonaStore *self);

folks_persona_store_get_display_name ()

const gchar *       folks_persona_store_get_display_name
                                                        (FolksPersonaStore *self);

folks_persona_store_get_id ()

const gchar *       folks_persona_store_get_id          (FolksPersonaStore *self);

folks_persona_store_get_personas ()

GeeMap *            folks_persona_store_get_personas    (FolksPersonaStore *self);

folks_persona_store_get_can_add_personas ()

FolksMaybeBool      folks_persona_store_get_can_add_personas
                                                        (FolksPersonaStore *self);

folks_persona_store_get_can_alias_personas ()

FolksMaybeBool      folks_persona_store_get_can_alias_personas
                                                        (FolksPersonaStore *self);

folks_persona_store_get_can_group_personas ()

FolksMaybeBool      folks_persona_store_get_can_group_personas
                                                        (FolksPersonaStore *self);

folks_persona_store_get_can_remove_personas ()

FolksMaybeBool      folks_persona_store_get_can_remove_personas
                                                        (FolksPersonaStore *self);

folks_persona_store_get_is_prepared ()

gboolean            folks_persona_store_get_is_prepared (FolksPersonaStore *self);

folks_persona_store_get_is_quiescent ()

gboolean            folks_persona_store_get_is_quiescent
                                                        (FolksPersonaStore *self);

folks_persona_store_get_is_writeable ()

gboolean            folks_persona_store_get_is_writeable
                                                        (FolksPersonaStore *self);

folks_persona_store_set_is_writeable ()

void                folks_persona_store_set_is_writeable
                                                        (FolksPersonaStore *self,
                                                         gboolean value);

folks_persona_store_get_trust_level ()

FolksPersonaStoreTrust folks_persona_store_get_trust_level
                                                        (FolksPersonaStore *self);

folks_persona_store_set_trust_level ()

void                folks_persona_store_set_trust_level (FolksPersonaStore *self,
                                                         FolksPersonaStoreTrust value);

folks_persona_store_get_always_writeable_properties ()

gchar **            folks_persona_store_get_always_writeable_properties
                                                        (FolksPersonaStore *self,
                                                         int *result_length1);

folks_persona_store_get_is_primary_store ()

gboolean            folks_persona_store_get_is_primary_store
                                                        (FolksPersonaStore *self);

folks_persona_store_get_is_user_set_default ()

gboolean            folks_persona_store_get_is_user_set_default
                                                        (FolksPersonaStore *self);

folks_persona_store_detail_key ()

const gchar *       folks_persona_store_detail_key      (FolksPersonaDetail detail);

Returns the key corresponding to detail, for use in the details param of folks_persona_store_add_persona_from_details().

Since 0.5.0

struct FolksPersonaStore

struct FolksPersonaStore;

A store for FolksPersonas.

After creating a PersonaStore instance, you must connect to the "personas-changed" signal, then call folks_persona_store_prepare(), otherwise a race condition may occur between emission of "personas-changed" and your code connecting to it.

enum FolksPersonaStoreTrust

typedef enum {
	FOLKS_PERSONA_STORE_TRUST_NONE,
	FOLKS_PERSONA_STORE_TRUST_PARTIAL,
	FOLKS_PERSONA_STORE_TRUST_FULL
} FolksPersonaStoreTrust;

Trust level for a FolksPersonaStore's FolksPersonas for linking purposes.

Since 0.1.13

enum FolksPersonaDetail

typedef enum {
	FOLKS_PERSONA_DETAIL_INVALID = -1,
	FOLKS_PERSONA_DETAIL_ALIAS = 0,
	FOLKS_PERSONA_DETAIL_AVATAR,
	FOLKS_PERSONA_DETAIL_BIRTHDAY,
	FOLKS_PERSONA_DETAIL_EMAIL_ADDRESSES,
	FOLKS_PERSONA_DETAIL_FULL_NAME,
	FOLKS_PERSONA_DETAIL_GENDER,
	FOLKS_PERSONA_DETAIL_IM_ADDRESSES,
	FOLKS_PERSONA_DETAIL_IS_FAVOURITE,
	FOLKS_PERSONA_DETAIL_LOCAL_IDS,
	FOLKS_PERSONA_DETAIL_NICKNAME,
	FOLKS_PERSONA_DETAIL_NOTES,
	FOLKS_PERSONA_DETAIL_PHONE_NUMBERS,
	FOLKS_PERSONA_DETAIL_POSTAL_ADDRESSES,
	FOLKS_PERSONA_DETAIL_ROLES,
	FOLKS_PERSONA_DETAIL_STRUCTURED_NAME,
	FOLKS_PERSONA_DETAIL_URLS,
	FOLKS_PERSONA_DETAIL_WEB_SERVICE_ADDRESSES,
	FOLKS_PERSONA_DETAIL_GROUPS
} FolksPersonaDetail;

Definition of the available fields to be looked up with folks_persona_store_detail_key().

Since 0.5.0

enum FolksPersonaStoreError

typedef enum {
	FOLKS_PERSONA_STORE_ERROR_INVALID_ARGUMENT,
	FOLKS_PERSONA_STORE_ERROR_CREATE_FAILED,
	FOLKS_PERSONA_STORE_ERROR_UNSUPPORTED_ON_USER,
	FOLKS_PERSONA_STORE_ERROR_STORE_OFFLINE,
	FOLKS_PERSONA_STORE_ERROR_READ_ONLY,
	FOLKS_PERSONA_STORE_ERROR_PERMISSION_DENIED,
	FOLKS_PERSONA_STORE_ERROR_REMOVE_FAILED,
	FOLKS_PERSONA_STORE_ERROR_UNSUPPORTED_ON_NON_USER
} FolksPersonaStoreError;

Errors from FolksPersonaStores.

The "always-writeable-properties" property

  "always-writeable-properties" GStrv                 : Read

The names of the properties of the FolksPersonas in this store which are always writeable.

If a property name is in this list, setting the property on a persona 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).

This property value is guaranteed to be constant for a given persona store, but may vary between persona stores in the same backend. It's guaranteed that this will always be a subset of the value of "writeable-properties" for the personas in this persona store.

Since 0.6.2

The "can-add-personas" property

  "can-add-personas"         FolksMaybeBool        : Read

Whether this folks_persona_store_new() can add FolksPersonas.

Default value: FOLKS_MAYBE_BOOL_UNSET

Since 0.3.1

The "can-alias-personas" property

  "can-alias-personas"       FolksMaybeBool        : Read

Whether this folks_persona_store_new() can set the alias of FolksPersonas.

Default value: FOLKS_MAYBE_BOOL_UNSET

Since 0.3.1

The "can-group-personas" property

  "can-group-personas"       FolksMaybeBool        : Read

Whether this folks_persona_store_new() can set the groups of FolksPersonas.

Default value: FOLKS_MAYBE_BOOL_UNSET

Since 0.3.1

The "can-remove-personas" property

  "can-remove-personas"      FolksMaybeBool        : Read

Whether this folks_persona_store_new() can remove FolksPersonas.

Default value: FOLKS_MAYBE_BOOL_UNSET

Since 0.3.1

The "display-name" property

  "display-name"             gchar*                : Read / Write / Construct Only

The human-readable, service-specific name used to represent the PersonaStore to the user.

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

This should be used whenever the user needs to be presented with a familiar, service-specific name. For instance, in a prompt for the user to select a specific IM account from which to initiate a chat.

This is not guaranteed to be unique even within this PersonaStore's FolksBackend.

Default value: NULL

Since 0.1.13

The "id" property

  "id"                       gchar*                : Read / Write / Construct Only

The instance identifier for this PersonaStore.

Since each FolksBackend can provide multiple different PersonaStores for different accounts or servers (for example), they each need an ID which is unique within the backend.

Default value: NULL

The "is-prepared" property

  "is-prepared"              gboolean              : Read

Whether folks_persona_store_prepare() has successfully completed for this store.

Default value: FALSE

Since 0.3.0

The "is-primary-store" property

  "is-primary-store"         gboolean              : Read / Write

Whether this folks_persona_store_new() is the primary store which is to be used for linking FolksPersonas and such.

Default value: FALSE

Since 0.6.3

The "is-quiescent" property

  "is-quiescent"             gboolean              : Read

Whether the store has reached a quiescent state. This will happen at some point after folks_persona_store_prepare() has successfully completed for the store. A store is in a quiescent state when all the FolksPersonas that it originally knows about have been loaded.

It's guaranteed that this property's value will only ever change after "is-prepared" has changed to `true`.

Default value: FALSE

Since 0.6.2

The "is-user-set-default" property

  "is-user-set-default"      gboolean              : Read / Write

Whether this folks_persona_store_new() has been marked as the default store (in its backend) by the user. I.e.: a PersonaStore for the e-d-s backend would set this to true if it represents the default address book.

Default value: FALSE

Since 0.6.3

The "is-writeable" property

  "is-writeable"             gboolean              : Read / Write

Whether the PersonaStore is writeable.

Only if a PersonaStore is writeable will its FolksPersonas be updated by changes to the FolksIndividuals containing them, and those changes then be written out to the relevant backing store.

If this property is `false`, it doesn't mean that FolksPersonas in this persona store aren't writeable at all. If their properties are updated through the FolksPersona, rather than through the FolksIndividual containing that persona, changes may be propagated to the backing store.

PersonaStores must not set this property themselves; it will be set as appropriate by the FolksIndividualAggregator.

Default value: FALSE

Since 0.1.13

The "personas" property

  "personas"                 GeeMap*               : Read

The FolksPersonas exposed by this PersonaStore.

Since 0.5.1

The "trust-level" property

  "trust-level"              FolksPersonaStoreTrust  : Read / Write

The trust level of the PersonaStore for linking.

Each folks_persona_store_new() is assigned a trust level by the IndividualAggregator, designating whether to trust the properties of its FolksPersonas for linking to produce FolksIndividuals.

See also: FolksPersonaStoreTrust

Default value: FOLKS_PERSONA_STORE_TRUST_NONE

Since 0.1.13

The "type-id" property

  "type-id"                  gchar*                : Read

The type of PersonaStore this is.

This is the same for all PersonaStores provided by a given FolksBackend.

This is guaranteed to always be available; even before folks_persona_store_prepare() is called.

Default value: NULL

The "personas-changed" signal

void                user_function                      (FolksPersonaStore            *persona_store,
                                                        GeeSet                       *added,
                                                        GeeSet                       *removed,
                                                        gchar                        *message,
                                                        FolksPersona                 *actor,
                                                        FolksGroupDetailsChangeReason reason,
                                                        gpointer                      user_data)          : Run Last

Emitted when one or more FolksPersonas are added to or removed from the store.

This will not be emitted until after folks_persona_store_prepare() has been called.

Since 0.5.1

The "removed" signal

void                user_function                      (FolksPersonaStore *persona_store,
                                                        gpointer           user_data)          : Run Last

Emitted when the backing store for this PersonaStore has been removed.

At this point, the PersonaStore and all its FolksPersonas are invalid, so any client referencing it should unreference it.

This will not be emitted until after folks_persona_store_prepare() has been called.