2
* Copyright (C) 2010, 2011 Tuomo Penttinen, all rights reserved.
4
* Author: Tuomo Penttinen <tp@herqq.org>
6
* This file is part of Herqq UPnP (HUPnP) library.
8
* Herqq UPnP is free software: you can redistribute it and/or modify
9
* it under the terms of the GNU Lesser General Public License as published by
10
* the Free Software Foundation, either version 3 of the License, or
11
* (at your option) any later version.
13
* Herqq UPnP is distributed in the hope that it will be useful,
14
* but WITHOUT ANY WARRANTY; without even the implied warranty of
15
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16
* GNU Lesser General Public License for more details.
18
* You should have received a copy of the GNU Lesser General Public License
19
* along with Herqq UPnP. If not, see <http://www.gnu.org/licenses/>.
22
#ifndef HSERVERDEVICE_H_
23
#define HSERVERDEVICE_H_
25
#include <HUpnpCore/HResourceType>
27
#include <QtCore/QObject>
38
class HServerDevicePrivate;
41
* \brief This is an abstract base class for server-side UPnP devices hosted
44
* \c %HServerDevice is a core component of the HUPnP's server-side \ref hupnp_devicemodel
45
* and it models a UPnP device, both root and embedded.
47
* \note As detailed in the UPnP Device Architecture specification,
48
* a UPnP device is essentially a container for services and possibly for other
49
* (embedded) UPnP devices.
51
* <h2>Using the class</h2>
53
* The most common uses of \c %HServerDevice involve reading the various device
54
* information elements originally set in the device description file and enumerating the
55
* exposed services. By calling info() you get an HDeviceInfo object from
56
* which you can read all the informational elements found in the device description.
57
* Calling services() gives you a list of HServerService instances the device
58
* exposes. Note that it is the services that contain the functionality
59
* and runtime status of the device.
61
* Some devices also contain embedded devices, which you can get by calling
64
* You can retrieve the device's description file by calling description() or
65
* you can manually read it from any of the locations returned by locations(). If
66
* the device is an embedded device, it always has a parent device, which you can
67
* get by calling parentDevice().
69
* <h2>Sub-classing</h2>
71
* First of all, if you want to implement a custom UPnP device using HUPnP, note
72
* that you do not have to subclass HServerDevice. But you can and there are valid
75
* Subclassing HServerDevice is extremely simple, as you are not required to override
76
* anything. However, if you choose to subclass HServerDevice, it is most likely
78
* - you want HUPnP to run strict validation routines on the description
79
* documents provided by users,
80
* - you want a custom HServerDevice type to do some additional initialization
82
* - you want to extend the HServerDevice API in some way or
83
* - you want to create a custom type for design purposes.
85
* See \ref setting_up_the_devicemodel for more information of this topic.
87
* \headerfile HServerDevice.h HServerDevice
89
* \ingroup hupnp_devicemodel
91
* \remarks This class is not thread-safe.
93
class H_UPNP_CORE_EXPORT HServerDevice :
97
H_DISABLE_COPY(HServerDevice)
98
H_DECLARE_PRIVATE(HServerDevice)
99
friend class HServerModelCreator;
104
* Provides the opportunity to do post-construction initialization routines
105
* in derived classes.
107
* As \c %HServerDevice is part of the HUPnP's server-side \ref hupnp_devicemodel,
108
* its initialization process is usually driven by HUPnP. If this is the case,
109
* at the time of instantiation of a descendant \c %HServerDevice the base
110
* \c %HServerDevice sub-object is not yet fully set up. In other words,
111
* at that time it is not guaranteed that every private or protected member
112
* of a \c %HServerDevice are set to their "final" values that are used
113
* once the object is fully initialized and ready to be used.
115
* Because of the above, descendants of \c %HServerDevice should not
116
* reference or rely on values of \c %HServerDevice at
117
* the time of construction. If the initialization of a \c %HServerDevice
118
* descendant needs to do things that rely on \c %HServerDevice being fully
119
* set up, you can override this method. This method is called \b once
120
* right after the base \c %HServerDevice is fully initialized.
122
* \param errDescription
124
* \return \e true in case the initialization succeeded.
126
* \note It is advisable to keep the constructors of the descendants of
127
* \c %HServerDevice small and fast, and do more involved initialization
130
virtual bool finalizeInit(QString* errDescription);
134
HServerDevicePrivate* h_ptr;
139
// Constructor for derived classes for re-using the h_ptr.
141
HServerDevice(HServerDevicePrivate& dd);
144
* \brief Creates a new instance.
149
* Initializes the instance.
151
* This method will succeed only once after construction. Subsequent
152
* calls will do nothing.
154
* \param info specifies information of the device. This is usually read
155
* from a device description document.
157
* \param parentDevice specifies parent UPnP device, if any.
159
bool init(const HDeviceInfo& info, HServerDevice* parentDevice = 0);
164
* \brief Destroys the instance.
166
virtual ~HServerDevice() = 0;
169
* \brief Returns the parent device of this device, if any.
171
* \return The parent device of this device, if any, or a null pointer
172
* in case the device is a root device.
174
* \remarks The pointer is guaranteed to be valid throughout the lifetime
177
HServerDevice* parentDevice() const;
180
* \brief Returns the root device of the device tree to which this device belongs.
182
* \return The root device of the device tree to which this device belongs.
184
* \remarks This device could be the root device of the device tree in question,
185
* in which case a pointer to this instance is returned.
187
HServerDevice* rootDevice() const;
190
* \brief Returns the service that has the specified service ID.
192
* \param serviceId specifies the service to be returned.
194
* \return The service that has the specified service ID or a null pointer
195
* in case there is no service with the specified ID.
197
* \remarks The pointer is guaranteed to be valid throughout the lifetime
200
HServerService* serviceById(const HServiceId& serviceId) const;
203
* \brief Returns the services this device exports.
205
* \return The services this device exports. The collection is empty
206
* if the device has no services.
208
* \remarks the pointers are guaranteed to be valid throughout the lifetime
211
const HServerServices& services() const;
214
* \brief Returns the services of a specific UPnP service type.
216
* \param serviceType specifies the UPnP service type of interest.
217
* Only services matching the type are returned.
219
* \param versionMatch specifies how the version information in argument
220
* \c serviceType should be used. The default is <em>inclusive match</em>,
221
* which essentially means that any service with a service type version that
222
* is \b less than or \b equal to the version specified in argument
223
* \c serviceType is successfully matched.
225
* \return The services of the specified type.
227
* \remarks the pointers are guaranteed to be valid throughout the lifetime
230
HServerServices servicesByType(
231
const HResourceType& serviceType,
232
HResourceType::VersionMatch versionMatch = HResourceType::Inclusive) const;
235
* \brief Returns the embedded devices of this device.
237
* \return The embedded devices of this device. The collection is empty
238
* if the device has no embedded devices.
240
* \remarks the pointers are guaranteed to be valid throughout the lifetime
243
const HServerDevices& embeddedDevices() const;
246
* \brief Returns the embedded devices of a specific UPnP device type.
248
* \param deviceType specifies the UPnP device type of interest.
249
* Only devices matching the type are returned.
251
* \param versionMatch specifies how the version information in argument
252
* \a deviceType should be used. The default is <em>inclusive match</em>,
253
* which essentially means that any device with a device type version that
254
* is \b less than or \b equal to the version specified in argument
255
* \a deviceType is successfully matched.
257
* \return The embedded devices of the specified type.
259
* \remarks the pointers are guaranteed to be valid throughout the lifetime
262
HServerDevices embeddedDevicesByType(
263
const HResourceType& deviceType,
264
HResourceType::VersionMatch versionMatch = HResourceType::Inclusive) const;
267
* \brief Returns information about the device.
269
* \return information about the device. This is often read from the
270
* device description.
272
const HDeviceInfo& info() const;
275
* \brief Returns the UPnP device description of this device.
277
* \return The UPnP device description that is associated to this device.
279
* \remarks an embedded device returns the same device description as
282
QString description() const;
285
* \brief Returns a list of locations where the device is currently available.
287
* \param urlType specifies whether the returned
288
* location URLs are absolute URLs for retrieving the device description.
289
* By default absolute URLs are returned and from these URLs the device
290
* description should be retrievable.
292
* \return a list of locations where the device is currently available.
294
QList<QUrl> locations(LocationUrlType urlType=AbsoluteUrl) const;
299
const HDeviceStatus& deviceStatus() const;
305
#endif /* HSERVERDEVICE_H_ */