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
|
/*
* This file is part of TelepathyQt4
*
* @copyright Copyright (C) 2008 Collabora Ltd. <http://www.collabora.co.uk/>
* @copyright Copyright (C) 2008 Nokia Corporation
*
* 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, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/
/**
* \page async_model Asynchronous Object Model
*
* \section async_model_overview Overview
*
* Telepathy-Qt4 uses \dbus to communicate with applications implementing the \telepathy_spec.
*
* When dealing with D-Bus, method calls can take some time to return,
* and in this case is not desirable to make synchronous calls,
* which could turn into applications hanging waiting for method returns.
* In order to avoid this issue, all Telepathy-Qt4 high-level methods requiring
* D-Bus method calls will return a \link Tp::PendingOperation \endlink which will
* emit the signal \link Tp::PendingOperation::finished() \endlink when the operation
* has ended. See individual methods' documentation for more details.
*
* Additionally Telepathy-Qt4 introduces a concept in which object features need
* to be enabled before usage. Information corresponding to enabled features can be inspected
* synchronously with no need for asynchronous D-Bus method calls and the associated
* programming complexity.
*
* To avoid the complexity of doing asynchronous calls when making object features ready
* Telepathy-Qt4 also provides so called factories for the main objects.
* These object features can be enabled by constructing a corresponding factory and enabling the
* desired features, and passing these factories to the objects responsible for creating
* the objects whose features are required.
* Doing that, applications are guaranteed that the specified features are ready in objects
* signaled to them by the library.
*
* However, if a particular feature is only ever used in a specific circumstance, such as an user
* opening some settings dialog separate from the general view of the application,
* features can be later enabled as needed by calling becomeReady(), or in the
* \link Tp::Contact \endlink case by calling \link Tp::ContactManager::upgradeContacts() \endlink,
* with the additional features on the object, and waiting for the resulting PendingOperation to
* finish.
*/
|
