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
31namespace BlueDevil {
32
33class Device;
34class Adapter;
35class 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 */
51class 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;
61public:
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
123public 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
139Q_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
170private:
171 /**
172 * @internal
173 */
174 Manager(QObject *parent = 0);
175
176 ManagerPrivate *const d;
177};
178
179}
180
181#endif // BLUEDEVILMANAGER_H
182