1/****************************************************************************
2**
3** Copyright (C) 2015 The Qt Company Ltd and/or its subsidiary(-ies).
4** Contact: http://www.qt-project.org/legal
5**
6** This file is part of the QtSystems module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL21$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see http://www.qt.io/terms-conditions. For further
15** information use the contact form at http://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 2.1 or version 3 as published by the Free
20** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22** following information to ensure the GNU Lesser General Public License
23** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25**
26** As a special exception, The Qt Company gives you certain additional
27** rights. These rights are described in The Qt Company LGPL Exception
28** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29**
30** $QT_END_LICENSE$
31**
32****************************************************************************/
33
34#include <qvaluespace.h>
35#include <qvaluespacepublisher.h>
36
37#include "qvaluespace_p.h"
38#include "qvaluespacemanager_p.h"
39
40QT_BEGIN_NAMESPACE
41
42/*!
43 \class QAbstractValueSpaceLayer
44 \brief The QAbstractValueSpaceLayer class provides support for adding new logical data layers
45 to the Qt Value Space.
46 \inmodule QtPublishSubscribe
47 \ingroup publishsubscribe
48 \internal
49
50 To create a new layer in the Value Space subclass this class and reimplement all of the virtual
51 functions. The available layers are installed when QValueSpaceManager::init() is called.
52*/
53
54/*!
55 \typedef QAbstractValueSpaceLayer::Handle
56
57 The Handle type is an opaque, pointer sized contextual handle used to represent paths within
58 Value Space layers. Handles are only ever created by QAbstractValueSpaceLayer::item() and are
59 always released by calls to QAbstractValueSpaceLayer::removeHandle(). The special value,
60 \c {InvalidHandle} is reserved to represent an invalid handle.
61*/
62
63/*!
64 \enum QAbstractValueSpaceLayer::Properties
65
66 To allow for efficient layer implementations, expensive handle operations, currently only
67 monitoring for changes, are enabled and disabled as needed on a per-handle basis. The
68 Properties enumeration is a bitmask representing the different properties that can exist on a
69 handle.
70
71 \value Publish Enable change notification for the handle. When set, the layer should emit
72 QAbstractValueSpaceLayer::handleChanged() signals when appropriate for the
73 handle.
74*/
75
76/*!
77 \fn QUuid QAbstractValueSpaceLayer::id()
78
79 Returns a globally unique identifier for the layer.
80*/
81
82/*!
83 \fn Handle QAbstractValueSpaceLayer::item(Handle parent, const QString &subPath)
84
85 Returns a new opaque handle for the requested \a subPath of \a parent. If \a parent is an
86 InvalidHandle, \a subPath is interpreted as an absolute path.
87
88 The caller should call removeHandle() to free resources used by the handle when it is no longer
89 required.
90*/
91
92/*!
93 \fn void QAbstractValueSpaceLayer::removeHandle(Handle handle)
94
95 Releases a \a handle previously returned from QAbstractValueSpaceLayer::item().
96*/
97
98/*!
99 \fn void QAbstractValueSpaceLayer::setProperty(Handle handle, Properties property)
100
101 Apply the specified \a property mask to \a handle.
102*/
103
104/*!
105 \fn bool QAbstractValueSpaceLayer::value(Handle handle, QVariant *data)
106
107 Returns the value for a particular \a handle. If a value is available, the layer will set
108 \a data and return true. If no value is available, false is returned.
109*/
110
111/*!
112 \fn bool QAbstractValueSpaceLayer::value(Handle handle, const QString &subPath, QVariant *data)
113
114 Returns the value for a particular \a subPath of \a handle. If a value is available, the
115 layer will set \a data and return true. If no value is available, false is returned.
116*/
117
118/*!
119 \fn QSet<QString> QAbstractValueSpaceLayer::children(Handle handle)
120
121 Returns the set of children of \a handle. For example, in a layer providing the following items:
122
123 \code
124 /Device/Configuration/Applications/FocusedApplication
125 /Device/Configuration/Buttons/PrimaryInput
126 /Device/Configuration/Name
127 \endcode
128
129 a request for children of "/Device/Configuration" will return
130 { "Applications", "Buttons", "Name" }.
131*/
132
133/*!
134 \fn QValueSpace::LayerOptions QAbstractValueSpaceLayer::layerOptions() const
135
136 Returns the QValueSpace::LayerOptions describing this layer.
137
138 \sa QValueSpace::LayerOption
139*/
140
141/*!
142 \fn bool QAbstractValueSpaceLayer::supportsInterestNotification() const
143
144 Returns true if the layer supports interest notifications; otherwise returns false.
145*/
146
147/*!
148 \fn bool QAbstractValueSpaceLayer::notifyInterest(Handle handle, bool interested)
149
150 Registers or unregisters that the caller is interested in \a handle and any subpaths under it.
151 If \a interested is true interest in \a handle is registered; otherwise it is unregistered.
152
153 The caller should ensure that all calls to this function with \a interested set to true have a
154 matching call with \a interested set to false.
155
156 Returns true if the notification was successfully sent; otherwise returns false.
157*/
158
159/*!
160 \fn bool QAbstractValueSpaceLayer::setValue(QValueSpacePublisher *creator, Handle handle, const QString &subPath, const QVariant &value)
161
162 Process calls to QValueSpacePublisher::setValue() by setting the value specified by the
163 \a subPath under \a handle to \a value. Ownership of the Value Space item is assigned to
164 \a creator.
165
166 Returns true on success; otherwise returns false.
167*/
168
169/*!
170 \fn bool QAbstractValueSpaceLayer::removeValue(QValueSpacePublisher *creator, Handle handle, const QString &subPath)
171
172 Process calls to QValueSpacePublisher::resetValue() by removing the Value Space item
173 identified by \a handle and \a subPath and created by \a creator.
174
175 Returns true on success; otherwise returns false.
176*/
177
178/*!
179 \fn bool QAbstractValueSpaceLayer::removeSubTree(QValueSpacePublisher *creator, Handle handle)
180
181 Process calls to QValueSpacePublisher::~QValueSpacePublisher() by removing the entire sub tree
182 created by \a creator under \a handle.
183
184 Returns true on success; otherwise returns false.
185*/
186
187/*!
188 \fn void QAbstractValueSpaceLayer::addWatch(QValueSpacePublisher *creator, Handle handle)
189
190 Registers \a creator for change notifications to values under \a handle.
191
192 \sa removeWatches()
193*/
194
195/*!
196 \fn void QAbstractValueSpaceLayer::removeWatches(QValueSpacePublisher *creator, Handle parent)
197
198 Removes all registered change notifications for \a creator under \a parent.
199
200 \sa addWatch()
201*/
202
203/*!
204 \fn void QAbstractValueSpaceLayer::sync()
205
206 Flushes all pending changes made by calls to setValue(), removeValue() and removeSubTree().
207*/
208
209/*!
210 Emits the QValueSpacePublisher::interestChanged() signal on \a publisher with \a path
211 and \a interested.
212*/
213void QAbstractValueSpaceLayer::emitInterestChanged(QValueSpacePublisher *publisher, const QString &path, bool interested)
214{
215 emit publisher->interestChanged(attribute: path, interested);
216}
217
218/*!
219 \fn void QAbstractValueSpaceLayer::handleChanged(quintptr handle)
220
221 Emitted whenever the \a handle's value, or any sub value, changes.
222*/
223
224
225/*!
226 \namespace QValueSpace
227 \brief The QValueSpace namespace contains miscellaneous identifiers used throughtout the
228 Publish and Subscribe API.
229 \inmodule QtPublishSubscribe
230*/
231
232/*!
233 \enum QValueSpace::LayerOption
234
235 This enum describes the behaviour of the Value Space layer. In addition this enum is used as
236 a filter when constructing a QValueSpacePublisher or QValueSpaceSubscriber.
237
238 \value UnspecifiedLayer Used as a filter to specify that any layer should be used.
239 \value PermanentLayer Indicates that the layer uses a permanent backing store. When used
240 as a filter only layers that use a permanent backing store will be
241 used.
242 \br
243 Values stored in a layer with this option will persist with in the
244 layer after the QValueSpacePublisher that published them is
245 destroyed.
246 \br
247 This option and the TransientLayer option are mutually
248 exclusive.
249 \value TransientLayer Indicates that the layer does not use a permanent backing store.
250 When used as a filter only layers that do not use permanent backing
251 stores will be used.
252 \br
253 Values stored in a layer with this option will be removed when the
254 QValueSpacePublisher that published them is destroyed.
255 \br
256 This option and the PermanentLayer option are mutually exclusive.
257 \value WritableLayer Indicates that the layer can update its contents. When used as a
258 filter only layers that are writable will be used.
259 \br
260 Applications can use QValueSpacePublisher to publish values to
261 layers that have this option.
262 \br
263 This option and the ReadOnlyLayer option are mutually exclusive.
264 \value ReadOnlyLayer Indicates that the layer cannot update its contents. When used as
265 a filter only layers that are read-only will be used.
266 \br
267 Applications can not publish values to layers with this option.
268 \br
269 This option and the WritableLayer option are mutually exclusive.
270*/
271
272/*!
273 \macro QVALUESPACE_VOLATILEREGISTRY_LAYER
274 \relates QValueSpace
275
276 The UUID of the Volatile Registry layer as a QUuid. The actual UUID value is
277 {8ceb5811-4968-470f-8fc2-264767e0bbd9}.
278
279 This value can be passed to the constructor of QValueSpacePublisher or QValueSpaceSubscriber to
280 force the constructed object to only access the Volatile Registry layer.
281
282 You can test if the Volatile Registry layer is available by checking if the list returned by
283 QValueSpace::availableLayers() contains this value. The Volatile Registry layer is only
284 available on Windows platforms.
285*/
286
287/*!
288 \macro QVALUESPACE_NONVOLATILEREGISTRY_LAYER
289 \relates QValueSpace
290
291 The UUID of the Non-Volatile Registry layer as a QUuid. The actual UUID value is
292 {8e29561c-a0f0-4e89-ba56-080664abc017}.
293
294 This value can be passed to the constructor of QValueSpacePublisher or QValueSpaceSubscriber to
295 force the constructed object to only access the Non-Volatile Registry layer.
296
297 You can test if the Non-Volatile Registry layer is available by checking if the list returned
298 by QValueSpace::availableLayers() contains this value. The Non-Volatile Registry layer is only
299 available on Windows platforms.
300*/
301
302/*!
303 \macro QVALUESPACE_GCONF_LAYER
304 \relates QValueSpace
305
306 The UUID of the GConf layer as a QUuid. The actual UUID value is
307 {0e2e5da0-0044-11df-941c-0002a5d5c51b}.
308
309 This value can be passed to the constructor of QValueSpacePublisher or QValueSpaceSubscriber to
310 force the constructed object to only access the GConf layer.
311
312 You can test if the GConf layer is available by checking if the list returned by
313 QValueSpace::availableLayers() contains this value. The GConf layer is only available on Linux
314 platforms.
315*/
316
317/*!
318 Returns a list of QUuids of all of the available layers, sorted in the priority order.
319*/
320QList<QUuid> QValueSpace::availableLayers()
321{
322 QList<QAbstractValueSpaceLayer *> layers = QValueSpaceManager::instance()->getLayers();
323
324 QList<QUuid> uuids;
325
326 for (int i = 0; i < layers.count(); ++i)
327 uuids.append(t: layers.at(i)->id());
328
329 return uuids;
330}
331
332/*!
333 \internal
334 \inmodule QtPublishSubscribe
335
336 Returns \a path with all duplicate '/' characters removed.
337*/
338QString qCanonicalPath(const QString &path)
339{
340 QString result;
341 result.resize(size: path.length());
342 const QChar *from = path.constData();
343 const QChar *fromend = from + path.length();
344 int outc=0;
345 QChar *to = result.data();
346 do {
347 to[outc++] = QLatin1Char('/');
348 while (from!=fromend && *from == QLatin1Char('/'))
349 ++from;
350 while (from!=fromend && *from != QLatin1Char('/'))
351 to[outc++] = *from++;
352 } while (from != fromend);
353 if (outc > 1 && to[outc-1] == QLatin1Char('/'))
354 --outc;
355 result.resize(size: outc);
356 return result;
357}
358
359QT_END_NAMESPACE
360

source code of qtsystems/src/publishsubscribe/qvaluespace.cpp