1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
/*
* Copyright (C) 2010 Collabora Ltd.
*
* This library is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation, either version 2.1 of the License, or
* (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this library. If not, see <http://www.gnu.org/licenses/>.
*
* Authors:
* Travis Reitter <travis.reitter@collabora.co.uk>
*/
using GLib;
using Gee;
/**
* A single backend to libfolks, such as Telepathy or evolution-data-server.
* Each backend provides {@link Persona}s which are aggregated to form
* {@link Individual}s.
*
* After creating a Backend instance, you must connect to the
* {@link Backend.persona_store_added} and
* {@link Backend.persona_store_removed} signals, //then// call
* {@link Backend.prepare}, otherwise a race condition may occur between
* emission of {@link Backend.persona_store_added} and your code connecting to
* it.
*/
public abstract class Folks.Backend : Object
{
/**
* Whether {@link Backend.prepare} has successfully completed for this
* backend.
*
* @since 0.3.0
*/
public abstract bool is_prepared { get; default = false; }
/**
* A unique name for the backend.
*
* This will be used to identify the backend, and should also be used as the
* {@link PersonaStore.type_id} of the {@link PersonaStore}s used by the
* backend.
*
* This is guaranteed to always be available; even before
* {@link Backend.prepare} is called.
*/
public abstract string name { get; }
/**
* The {@link PersonaStore}s in use by the backend.
*
* A backend may expose {@link Persona}s from multiple servers or accounts
* (for example), so may have a {@link PersonaStore} for each.
*
* @since 0.5.1
*/
public abstract Map<string, PersonaStore> persona_stores { get; }
/**
* Emitted when a {@link PersonaStore} is added to the backend.
*
* This will not be emitted until after {@link Backend.prepare} has been
* called.
*
* @param store the {@link PersonaStore}
*/
public abstract signal void persona_store_added (PersonaStore store);
/**
* Emitted when a {@link PersonaStore} is removed from the backend.
*
* This will not be emitted until after {@link Backend.prepare} has been
* called.
*
* @param store the {@link PersonaStore}
*/
public abstract signal void persona_store_removed (PersonaStore store);
/**
* Prepare the Backend for use.
*
* This connects the Backend to whichever backend-specific services it
* requires, and causes it to create its {@link PersonaStore}s. This should be
* called //after// connecting to the {@link Backend.persona_store_added} and
* {@link Backend.persona_store_removed} signals, or a race condition could
* occur, with the signals being emitted before your code has connected to
* them, and {@link PersonaStore}s getting "lost" as a result.
*
* This is normally handled transparently by the {@link IndividualAggregator}.
*
* If this function throws an error, the Backend will not be functional.
*
* This function is guaranteed to be idempotent (since version 0.3.0).
*
* @since 0.1.11
*/
public abstract async void prepare () throws GLib.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
* {@link Backend.persona_store_removed} for each of its
* {@link PersonaStore}s.
*
* Most users won't need to use this function.
*
* If this function throws an error, the Backend will not be functional.
*
* @since 0.3.2
*/
public abstract async void unprepare () throws GLib.Error;
}
|
