1 | /***************************************************************************** |
2 | * This file is part of the BlueDevil project * |
3 | * * |
4 | * Copyright (C) 2010 Rafael Fernández López <ereslibre@kde.org> * |
5 | * Copyright (C) 2010 UFO Coders <info@ufocoders.com> * |
6 | * * |
7 | * This library is free software; you can redistribute it and/or * |
8 | * modify it under the terms of the GNU Library General Public * |
9 | * License as published by the Free Software Foundation; either * |
10 | * version 2 of the License, or (at your option) any later version. * |
11 | * * |
12 | * This library is distributed in the hope that it will be useful, * |
13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of * |
14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * |
15 | * Library General Public License for more details. * |
16 | * * |
17 | * You should have received a copy of the GNU Library General Public License * |
18 | * along with this library; see the file COPYING.LIB. If not, write to * |
19 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, * |
20 | * Boston, MA 02110-1301, USA. * |
21 | *****************************************************************************/ |
22 | |
23 | #ifndef BLUEDEVILMANAGER_H |
24 | #define BLUEDEVILMANAGER_H |
25 | |
26 | #include <bluedevil/bluedevil_export.h> |
27 | |
28 | #include <QtCore/QObject> |
29 | #include <QtDBus/QDBusObjectPath> |
30 | |
31 | namespace BlueDevil { |
32 | |
33 | class Device; |
34 | class Adapter; |
35 | class ManagerPrivate; |
36 | |
37 | /** |
38 | * @class Manager bluedevilmanager.h bluedevil/bluedevilmanager.h |
39 | * |
40 | * Manager class. The entry point to BlueDevil exposed services. |
41 | * |
42 | * The typical way to proceed is to work with the first adapter, but you can also list all |
43 | * bluetooth adapters and work with the one you want. |
44 | * |
45 | * The interface is a singleton with release-when-you-want capability. |
46 | * |
47 | * All adapters and devices are created by BlueDevil, and the ownership is always of BlueDevil. |
48 | * |
49 | * @author Rafael Fernández López <ereslibre@kde.org> |
50 | */ |
51 | class BLUEDEVIL_EXPORT Manager |
52 | : public QObject |
53 | { |
54 | Q_OBJECT |
55 | |
56 | Q_PROPERTY(Manager* self READ self) |
57 | Q_PROPERTY(QList<Adapter*> adapters READ adapters) |
58 | Q_PROPERTY(bool isBluetoothOperational READ isBluetoothOperational) |
59 | |
60 | friend class ManagerPrivate; |
61 | public: |
62 | enum RegisterCapability { |
63 | DisplayOnly = 0, |
64 | DisplayYesNo = 1, |
65 | KeyboardOnly = 2, |
66 | NoInputNoOutput = 3 |
67 | }; |
68 | |
69 | virtual ~Manager(); |
70 | |
71 | /** |
72 | * @return The Manager instance. |
73 | */ |
74 | static Manager *self(); |
75 | |
76 | /** |
77 | * When you consider you have finished working with BlueDevil you can immediatly release the |
78 | * memory by calling this method. It will automatically delete all Adapters and Devices that |
79 | * were still on memory. |
80 | */ |
81 | static void release(); |
82 | |
83 | /** |
84 | * @return The first adapter that is ready to be used (is powered). If there are no usable |
85 | * adapters, NULL will be returned. |
86 | */ |
87 | Adapter *usableAdapter() const; |
88 | |
89 | /** |
90 | * @return A list with all the connected adapters. |
91 | */ |
92 | QList<Adapter*> adapters() const; |
93 | |
94 | /** |
95 | * Returns a device for a given UBI independently of the adapter they are in |
96 | * |
97 | * All devices belong to an adapter so in order to find a device when we have more than |
98 | * one adapter is iterating on all adapters and call deviceForUBI. This method basically |
99 | * does that so application developers doesn't have to do it. |
100 | * |
101 | * @param Device UBI to find |
102 | * @return A device for the given UBI or null if none is found |
103 | */ |
104 | Device *deviceForUBI(const QString &UBI) const; |
105 | |
106 | /** |
107 | * Return a list of all known devices by all connected adaptors |
108 | * @return a list of all known devices |
109 | */ |
110 | QList<Device*> devices() const; |
111 | /** |
112 | * @return Whether the bluetooth system is ready to be used, and there is a usable adapter |
113 | * connected and turned on at the system. |
114 | * |
115 | * @note After this check, if succeeded, you can freely access to all libbluedevil functionality |
116 | * by retrieving the an adapter through a call to usableAdapter(). |
117 | * |
118 | * @note If this method returns false, you can connect to the usableAdapterChanged signal, so |
119 | * you can be notified when bluetooth is operational. |
120 | */ |
121 | bool isBluetoothOperational() const; |
122 | |
123 | public Q_SLOTS: |
124 | /** |
125 | * Registers agent. |
126 | */ |
127 | void registerAgent(const QString &agentPath, RegisterCapability registerCapability); |
128 | |
129 | /** |
130 | * Unregisters agent. |
131 | */ |
132 | void unregisterAgent(const QString &agentPath); |
133 | |
134 | /** |
135 | * Request to set Agent with agentPath as default agent. |
136 | */ |
137 | void requestDefaultAgent(const QString &agentPath); |
138 | |
139 | Q_SIGNALS: |
140 | /** |
141 | * This signal will be emitted when an adapter has been connected. |
142 | */ |
143 | void adapterAdded(Adapter *adapter); |
144 | |
145 | /** |
146 | * This signal will be emitted when an adapter has been disconnected. |
147 | */ |
148 | void adapterRemoved(Adapter *adapter); |
149 | |
150 | /** |
151 | * This signal will be emitted when the current usable adapter has changed. This basically |
152 | * means two cases: |
153 | * |
154 | * - There were no usable adapters (powered off, or not present), and a new one has been |
155 | * connected and is powered on. |
156 | * - The adapter that was considered usable has been removed or powered off. |
157 | * |
158 | * If any of those cases happen, and it was possible to find a usable adapter, this signal |
159 | * will report the new adapter. If no usable adapter could be found, 0 will be placed at @p |
160 | * adapter. |
161 | * |
162 | */ |
163 | void usableAdapterChanged(Adapter *adapter); |
164 | |
165 | /** |
166 | * This signal will be emitted when all adapters have been disconnected. |
167 | */ |
168 | void allAdaptersRemoved(); |
169 | |
170 | private: |
171 | /** |
172 | * @internal |
173 | */ |
174 | Manager(QObject *parent = 0); |
175 | |
176 | ManagerPrivate *const d; |
177 | }; |
178 | |
179 | } |
180 | |
181 | #endif // BLUEDEVILMANAGER_H |
182 | |