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

GError will be returned in error

if preparing the backend-specific services failed — this will be a backend-specific error

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

GError will be returned in error

if preparing the backend-specific services failed — this will be a backend-specific error

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

FolksPersonaStoreError will be returned in error

if adding the persona failed

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

FolksPersonaStoreError will be returned in error

if adding the persona failed

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

FolksPersonaStoreError will be returned in error

if removing the persona failed

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

FolksPersonaStoreError will be returned in error

if removing the persona failed

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);

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

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. It is immutable over the life of the FolksPersonaStore.

folks_persona_store_get_display_name ()

const gchar *
folks_persona_store_get_display_name (FolksPersonaStore *self);

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

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. Its value may change throughout the life of the store.

Since 0.1.13

folks_persona_store_get_id ()

const gchar *
folks_persona_store_get_id (FolksPersonaStore *self);

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

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.

It is immutable over the life of the FolksPersonaStore.

folks_persona_store_get_personas ()

GeeMap *
folks_persona_store_get_personas (FolksPersonaStore *self);

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

The FolksPersonas exposed by this PersonaStore.

Since 0.5.1

folks_persona_store_get_can_add_personas ()

FolksMaybeBool
folks_persona_store_get_can_add_personas
                               (FolksPersonaStore *self);

Get and return the current value of the "can-add-personas" property.

Whether this FolksPersonaStore can add FolksPersonas.

This value may change throughout the life of the FolksPersonaStore.

Since 0.3.1

folks_persona_store_get_can_alias_personas ()

FolksMaybeBool
folks_persona_store_get_can_alias_personas
                               (FolksPersonaStore *self);

Get and return the current value of the "can-alias-personas" property.

Whether this FolksPersonaStore can set the alias of FolksPersonas.

Since 0.3.1

folks_persona_store_get_can_group_personas ()

FolksMaybeBool
folks_persona_store_get_can_group_personas
                               (FolksPersonaStore *self);

Get and return the current value of the "can-group-personas" property.

Whether this FolksPersonaStore can set the groups of FolksPersonas.

Since 0.3.1

folks_persona_store_get_can_remove_personas ()

FolksMaybeBool
folks_persona_store_get_can_remove_personas
                               (FolksPersonaStore *self);

Get and return the current value of the "can-remove-personas" property.

Whether this FolksPersonaStore can remove FolksPersonas.

This value may change throughout the life of the FolksPersonaStore.

Since 0.3.1

folks_persona_store_get_is_prepared ()

gboolean
folks_persona_store_get_is_prepared (FolksPersonaStore *self);

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

Whether folks_persona_store_prepare() has successfully completed for this store.

It’s guaranteed that this will only ever change from false to true in the lifetime of the FolksPersonaStore.

Since 0.3.0

folks_persona_store_get_is_quiescent ()

gboolean
folks_persona_store_get_is_quiescent (FolksPersonaStore *self);

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

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.

Since 0.6.2

folks_persona_store_get_is_writeable ()

gboolean
folks_persona_store_get_is_writeable (FolksPersonaStore *self);

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

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.

Since 0.1.13

folks_persona_store_set_is_writeable ()

void
folks_persona_store_set_is_writeable (FolksPersonaStore *self,
                                      gboolean value);

Set the value of the "is-writeable" property to value .

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.

Since 0.1.13

folks_persona_store_get_trust_level ()

FolksPersonaStoreTrust
folks_persona_store_get_trust_level (FolksPersonaStore *self);

Get and return the current value of the "trust-level" property.

The trust level of the PersonaStore for linking.

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

This value may change throughout the life of the FolksPersonaStore.

The trust level may be queried by clients, but must not be set by them. The setter for this property is for libfolks internal use only.

Since 0.1.13

folks_persona_store_set_trust_level ()

void
folks_persona_store_set_trust_level (FolksPersonaStore *self,
                                     FolksPersonaStoreTrust value);

Set the value of the "trust-level" property to value .

The trust level of the PersonaStore for linking.

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

This value may change throughout the life of the FolksPersonaStore.

The trust level may be queried by clients, but must not be set by them. The setter for this property is for libfolks internal use only.

Since 0.1.13

folks_persona_store_get_always_writeable_properties ()

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

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

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

folks_persona_store_get_is_primary_store ()

gboolean
folks_persona_store_get_is_primary_store
                               (FolksPersonaStore *self);

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

Whether this FolksPersonaStore is the primary store to be used for linking FolksPersonas.

Since 0.6.3

folks_persona_store_get_is_user_set_default ()

gboolean
folks_persona_store_get_is_user_set_default
                               (FolksPersonaStore *self);

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

Whether this FolksPersonaStore is marked as the default in its backend by the user.

i.e. A FolksPersonaStore for the EDS backend would set this to true if it represents the user’s default address book.

Since 0.6.3

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.

struct FolksPersonaStoreClass

struct FolksPersonaStoreClass {
	GObjectClass parent_class;
	void (*prepare) (FolksPersonaStore* self, GAsyncReadyCallback _callback_, gpointer _user_data_);
	void (*prepare_finish) (FolksPersonaStore* self, GAsyncResult* _res_, GError** error);
	void (*flush) (FolksPersonaStore* self, GAsyncReadyCallback _callback_, gpointer _user_data_);
	void (*flush_finish) (FolksPersonaStore* self, GAsyncResult* _res_);
	void (*add_persona_from_details) (FolksPersonaStore* self, GHashTable* details, GAsyncReadyCallback _callback_, gpointer _user_data_);
	FolksPersona* (*add_persona_from_details_finish) (FolksPersonaStore* self, GAsyncResult* _res_, GError** error);
	void (*remove_persona) (FolksPersonaStore* self, FolksPersona* persona, GAsyncReadyCallback _callback_, gpointer _user_data_);
	void (*remove_persona_finish) (FolksPersonaStore* self, GAsyncResult* _res_, GError** error);
	const gchar* (*get_type_id) (FolksPersonaStore* self);
	GeeMap* (*get_personas) (FolksPersonaStore* self);
	FolksMaybeBool (*get_can_add_personas) (FolksPersonaStore* self);
	FolksMaybeBool (*get_can_alias_personas) (FolksPersonaStore* self);
	FolksMaybeBool (*get_can_group_personas) (FolksPersonaStore* self);
	FolksMaybeBool (*get_can_remove_personas) (FolksPersonaStore* self);
	gboolean (*get_is_prepared) (FolksPersonaStore* self);
	gboolean (*get_is_quiescent) (FolksPersonaStore* self);
	gchar** (*get_always_writeable_properties) (FolksPersonaStore* self, int* result_length1);
};

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

enum FolksPersonaStoreTrust

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

Trust levels are set internally by the backends, and must not be modified by clients.

Since 0.1.13

enum FolksPersonaDetail

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

Since 0.5.0

enum FolksPersonaStoreError

Errors from FolksPersonaStores.

The “always-writeable-properties” property

  “always-writeable-properties” GStrv

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.

Flags: Read

Since 0.6.2

The “can-add-personas” property

  “can-add-personas”         FolksMaybeBool

Whether this FolksPersonaStore can add FolksPersonas.

This value may change throughout the life of the FolksPersonaStore.

Flags: Read

Default value: FOLKS_MAYBE_BOOL_UNSET

Since 0.3.1

The “can-alias-personas” property

  “can-alias-personas”       FolksMaybeBool

Whether this FolksPersonaStore can set the alias of FolksPersonas.

Flags: Read

Default value: FOLKS_MAYBE_BOOL_UNSET

Since 0.3.1

The “can-group-personas” property

  “can-group-personas”       FolksMaybeBool

Whether this FolksPersonaStore can set the groups of FolksPersonas.

Flags: Read

Default value: FOLKS_MAYBE_BOOL_UNSET

Since 0.3.1

The “can-remove-personas” property

  “can-remove-personas”      FolksMaybeBool

Whether this FolksPersonaStore can remove FolksPersonas.

This value may change throughout the life of the FolksPersonaStore.

Flags: Read

Default value: FOLKS_MAYBE_BOOL_UNSET

Since 0.3.1

The “display-name” property

  “display-name”             gchar *

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. Its value may change throughout the life of the store.

Flags: Read / Write / Construct Only

Default value: NULL

Since 0.1.13

The “id” property

  “id”                       gchar *

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.

It is immutable over the life of the FolksPersonaStore.

Flags: Read / Write / Construct Only

Default value: NULL

The “is-prepared” property

  “is-prepared”              gboolean

Whether folks_persona_store_prepare() has successfully completed for this store.

It’s guaranteed that this will only ever change from false to true in the lifetime of the FolksPersonaStore.

Flags: Read

Default value: FALSE

Since 0.3.0

The “is-primary-store” property

  “is-primary-store”         gboolean

Whether this FolksPersonaStore is the primary store to be used for linking FolksPersonas.

Flags: Read / Write

Default value: FALSE

Since 0.6.3

The “is-quiescent” property

  “is-quiescent”             gboolean

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.

Flags: Read

Default value: FALSE

Since 0.6.2

The “is-user-set-default” property

  “is-user-set-default”      gboolean

Whether this FolksPersonaStore is marked as the default in its backend by the user.

i.e. A FolksPersonaStore for the EDS backend would set this to true if it represents the user’s default address book.

Flags: Read / Write

Default value: FALSE

Since 0.6.3

The “is-writeable” property

  “is-writeable”             gboolean

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.

Flags: Read / Write

Default value: FALSE

Since 0.1.13

The “personas” property

  “personas”                 GeeMap *

The FolksPersonas exposed by this PersonaStore.

Flags: Read

Since 0.5.1

The “trust-level” property

  “trust-level”              FolksPersonaStoreTrust

The trust level of the PersonaStore for linking.

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

This value may change throughout the life of the FolksPersonaStore.

The trust level may be queried by clients, but must not be set by them. The setter for this property is for libfolks internal use only.

See also: FolksPersonaStoreTrust

Flags: Read / Write

Default value: FOLKS_PERSONA_STORE_TRUST_NONE

Since 0.1.13

The “type-id” property

  “type-id”                  gchar *

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. It is immutable over the life of the FolksPersonaStore.

Flags: Read

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)

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.

Flags: Run Last

Since 0.5.1

The “removed” signal

void
user_function (FolksPersonaStore *persona_store,
               gpointer           user_data)

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.

Flags: Run Last