FOLKS_TYPE_BACKEND

#define FOLKS_TYPE_BACKEND (folks_backend_get_type ())

The type for FolksBackend.

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

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

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

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

See also: folks_backend_unprepare()

Since 0.3.2

folks_backend_get_is_prepared ()

gboolean            folks_backend_get_is_prepared       (FolksBackend *self);

folks_backend_get_is_quiescent ()

gboolean            folks_backend_get_is_quiescent      (FolksBackend *self);

folks_backend_get_name ()

const gchar *       folks_backend_get_name              (FolksBackend *self);

folks_backend_get_persona_stores ()

GeeMap *            folks_backend_get_persona_stores    (FolksBackend *self);

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.

The "is-prepared" property

  "is-prepared"              gboolean              : Read

Whether folks_backend_prepare() has successfully completed for this backend.

Default value: FALSE

Since 0.3.0

The "is-quiescent" property

  "is-quiescent"             gboolean              : Read

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

Default value: FALSE

Since 0.6.2

The "name" property

  "name"                     gchar*                : Read

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.

Default value: NULL

The "persona-stores" property

  "persona-stores"           GeeMap*               : Read

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

The "persona-store-added" signal

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

Emitted when a FolksPersonaStore is added to the backend.

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

The "persona-store-removed" signal

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

Emitted when a FolksPersonaStore is removed from the backend.

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