FolksBackend: Reference Manual

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

## Functions

void | folks_backend_disable_persona_store ()
void | folks_backend_enable_persona_store ()
void | folks_backend_set_persona_stores ()
void | folks_backend_prepare ()
void | folks_backend_prepare_finish ()
void | folks_backend_unprepare ()
void | folks_backend_unprepare_finish ()
gboolean | folks_backend_get_is_prepared ()
gboolean | folks_backend_get_is_quiescent ()
const gchar * | folks_backend_get_name ()
GeeMap * | folks_backend_get_persona_stores ()

## Types and Values

#define | FOLKS_TYPE_BACKEND
struct | FolksBackend
struct | FolksBackendClass

## Description

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.

## Functions

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

#### Parameters

self | the FolksBackend instance |
store | . the FolksPersonaStore to disable. . | [in]

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

#### Parameters

self | the FolksBackend instance |
store | . the FolksPersonaStore to enable. . | [in]

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.

#### Parameters

self | the FolksBackend instance |
storeids | . a Set of FolksPersonaStore IDs to use. . | [in][allow-none]

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()`

#### Parameters

self | the FolksBackend instance |
_callback_ | callback to call when the request is satisfied. | [scope async]
_user_data_ | the data to pass to `_callback_` function. | [closure]

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()`

#### Parameters

self | the FolksBackend instance |
_res_ | a GAsyncResult |
error | location to store the error occurring, or `NULL` to ignore |

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()`

#### Parameters

self | the FolksBackend instance |
_callback_ | callback to call when the request is satisfied. | [scope async]
_user_data_ | the data to pass to `_callback_` function. | [closure]

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()`

#### Parameters

self | the FolksBackend instance |
_res_ | a GAsyncResult |
error | location to store the error occurring, or `NULL` to ignore |

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.

#### Parameters

self | the FolksBackend instance to query |

#### Returns

the value of the "is-prepared" property

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

#### Parameters

self | the FolksBackend instance to query |

#### Returns

the value of the "is-quiescent" property

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.

#### Parameters

self | the FolksBackend instance to query |

#### Returns

the value of the "name" property

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

#### Parameters

self | the FolksBackend instance to query |

#### Returns

the value of the "persona-stores" property

Since: 0.5.1

## Types and Values

### FOLKS_TYPE_BACKEND

    #define FOLKS_TYPE_BACKEND (folks_backend_get_type ())

The type for FolksBackend.

### struct FolksBackend

    struct FolksBackend {
    	GObject parent_instance;
    	FolksBackendPrivate * priv;
    };

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.

#### Members

`disable_persona_store` () | virtual method called by `folks_backend_disable_persona_store()` |
`enable_persona_store` () | virtual method called by `folks_backend_enable_persona_store()` |
`set_persona_stores` () | virtual method called by `folks_backend_set_persona_stores()` |
`prepare` () | virtual method called by `folks_backend_prepare()` |
`prepare_finish` () | asynchronous finish function for `prepare`, called by `folks_backend_prepare()` |
`unprepare` () | virtual method called by `folks_backend_unprepare()` |
`unprepare_finish` () | asynchronous finish function for `unprepare`, called by `folks_backend_unprepare()` |
`get_is_prepared` () | getter method for the abstract property "is-prepared" |
`get_is_quiescent` () | getter method for the abstract property "is-quiescent" |
`get_name` () | getter method for the abstract property "name" |
`get_persona_stores` () | getter method for the abstract property "persona-stores" |