FOLKS_TYPE_BACKEND

#define FOLKS_TYPE_BACKEND (folks_backend_get_type ())

The type for FolksBackend.

folks_backend_disable_persona_store ()

void
folks_backend_disable_persona_store (FolksBackend *self,
                                     FolksPersonaStore *store);

Disable a FolksPersonaStore.

If the given persona store is in this backend "persona-stores", it will be removed, and we will disconnect from its signals.

Since 0.9.0

folks_backend_enable_persona_store ()

void
folks_backend_enable_persona_store (FolksBackend *self,
                                    FolksPersonaStore *store);

Enable a FolksPersonaStore.

If the given persona store is not already in this backend "persona-stores", it will be added to the backend and "persona-stores" property notification will be emitted, along with "persona-store-added".

Since 0.9.0

folks_backend_set_persona_stores ()

void
folks_backend_set_persona_stores (FolksBackend *self,
                                  GeeSet *storeids);

Set the FolksPersonaStores to use in this backend.

This will cause "persona-store-removed" signals to be emitted for all removed stores, followed by "persona-store-added" signals for all added stores. As these signals are emitted, the sets of individuals in any associated FolksIndividualAggregators will be updated, and "individuals-changed" may be emitted multiple times as appropriate. A property change notification for "persona-stores" will be emitted last. Note: pass null storeids to use all available persona stores.

Since 0.9.0

folks_backend_prepare ()

void
folks_backend_prepare (FolksBackend *self,
                       GAsyncReadyCallback _callback_,
                       gpointer _user_data_);

Prepare the Backend for use.

This connects the Backend to whichever backend-specific services it requires, and causes it to create its FolksPersonaStores. This should be called after connecting to the "persona-store-added" and "persona-store-removed" signals, or a race condition could occur, with the signals being emitted before your code has connected to them, and FolksPersonaStores getting "lost" as a result.

This is normally handled transparently by the FolksIndividualAggregator.

If this function throws an error, the Backend 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

G_DBUS_ERROR_SERVICE_UNKNOWN will be returned in error

if a required D-Bus service was not installed or could not be started

See also: folks_backend_prepare_finish()

Since 0.1.11

folks_backend_prepare_finish ()

void
folks_backend_prepare_finish (FolksBackend *self,
                              GAsyncResult *_res_,
                              GError **error);

Prepare the Backend for use.

This connects the Backend to whichever backend-specific services it requires, and causes it to create its FolksPersonaStores. This should be called after connecting to the "persona-store-added" and "persona-store-removed" signals, or a race condition could occur, with the signals being emitted before your code has connected to them, and FolksPersonaStores getting "lost" as a result.

This is normally handled transparently by the FolksIndividualAggregator.

If this function throws an error, the Backend 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

G_DBUS_ERROR_SERVICE_UNKNOWN will be returned in error

if a required D-Bus service was not installed or could not be started

See also: folks_backend_prepare()

Since 0.1.11

folks_backend_unprepare ()

void
folks_backend_unprepare (FolksBackend *self,
                         GAsyncReadyCallback _callback_,
                         gpointer _user_data_);

Revert the Backend to its pre-prepared state.

This will disconnect this Backend and its dependencies from their respective services and the Backend will issue "persona-store-removed" for each of its FolksPersonaStores.

Most users won't need to use this function.

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

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 unpreparing the backend-specific services failed — this will be a backend-specific error

See also: folks_backend_unprepare_finish()

Since 0.3.2

folks_backend_unprepare_finish ()

void
folks_backend_unprepare_finish (FolksBackend *self,
                                GAsyncResult *_res_,
                                GError **error);

Revert the Backend to its pre-prepared state.

This will disconnect this Backend and its dependencies from their respective services and the Backend will issue "persona-store-removed" for each of its FolksPersonaStores.

Most users won't need to use this function.

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

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 unpreparing the backend-specific services failed — this will be a backend-specific error

See also: folks_backend_unprepare()

Since 0.3.2

folks_backend_get_is_prepared ()

gboolean
folks_backend_get_is_prepared (FolksBackend *self);

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

Whether folks_backend_prepare() has successfully completed for this backend.

Since 0.3.0

folks_backend_get_is_quiescent ()

gboolean
folks_backend_get_is_quiescent (FolksBackend *self);

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

Whether the backend has reached a quiescent state. This will happen at some point after folks_backend_prepare() has successfully completed for the backend. A backend is in a quiescent state when all the FolksPersonaStores 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.

When folks_backend_unprepare() is called, this will be reset to false.

Since 0.6.2

folks_backend_get_name ()

const gchar *
folks_backend_get_name (FolksBackend *self);

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

A unique name for the backend.

This will be used to identify the backend, and should also be used as the "type-id" of the FolksPersonaStores used by the backend.

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

folks_backend_get_persona_stores ()

GeeMap *
folks_backend_get_persona_stores (FolksBackend *self);

Get and return the current value of the "persona-stores" property.

The FolksPersonaStores in use by the backend.

A backend may expose FolksPersonas from multiple servers or accounts (for example), so may have a FolksPersonaStore for each.

Since 0.5.1

struct FolksBackend

struct FolksBackend;

A single backend to libfolks, such as Telepathy or evolution-data-server. Each backend provides FolksPersonas which are aggregated to form FolksIndividuals.

After creating a Backend instance, you must connect to the "persona-store-added" and "persona-store-removed" signals, then call folks_backend_prepare(), otherwise a race condition may occur between emission of "persona-store-added" and your code connecting to it.

struct FolksBackendClass

struct FolksBackendClass {
	GObjectClass parent_class;
	void (*disable_persona_store) (FolksBackend* self, FolksPersonaStore* store);
	void (*enable_persona_store) (FolksBackend* self, FolksPersonaStore* store);
	void (*set_persona_stores) (FolksBackend* self, GeeSet* storeids);
	void (*prepare) (FolksBackend* self, GAsyncReadyCallback _callback_, gpointer _user_data_);
	void (*prepare_finish) (FolksBackend* self, GAsyncResult* _res_, GError** error);
	void (*unprepare) (FolksBackend* self, GAsyncReadyCallback _callback_, gpointer _user_data_);
	void (*unprepare_finish) (FolksBackend* self, GAsyncResult* _res_, GError** error);
	gboolean (*get_is_prepared) (FolksBackend* self);
	gboolean (*get_is_quiescent) (FolksBackend* self);
	const gchar* (*get_name) (FolksBackend* self);
	GeeMap* (*get_persona_stores) (FolksBackend* self);
};

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

The “is-prepared” property

  “is-prepared”              gboolean

Whether folks_backend_prepare() has successfully completed for this backend.

Flags: Read

Default value: FALSE

Since 0.3.0

The “is-quiescent” property

  “is-quiescent”             gboolean

Whether the backend has reached a quiescent state. This will happen at some point after folks_backend_prepare() has successfully completed for the backend. A backend is in a quiescent state when all the FolksPersonaStores 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.

When folks_backend_unprepare() is called, this will be reset to false.

Flags: Read

Default value: FALSE

Since 0.6.2

The “name” property

  “name”                     gchar *

A unique name for the backend.

This will be used to identify the backend, and should also be used as the "type-id" of the FolksPersonaStores used by the backend.

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

Flags: Read

Default value: NULL

The “persona-stores” property

  “persona-stores”           GeeMap *

The FolksPersonaStores in use by the backend.

A backend may expose FolksPersonas from multiple servers or accounts (for example), so may have a FolksPersonaStore for each.

Flags: Read

Since 0.5.1

The “persona-store-added” signal

void
user_function (FolksBackend      *backend,
               FolksPersonaStore *store,
               gpointer           user_data)

Emitted when a FolksPersonaStore is added to the backend.

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

Flags: Run Last

The “persona-store-removed” signal

void
user_function (FolksBackend      *backend,
               FolksPersonaStore *store,
               gpointer           user_data)

Emitted when a FolksPersonaStore is removed from the backend.

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

Flags: Run Last