2
* Copyright (C) 2011 Tuomo Penttinen, all rights reserved.
4
* Author: Tuomo Penttinen <tp@herqq.org>
6
* This file is part of Herqq UPnP Av (HUPnPAv) library.
8
* Herqq UPnP Av is free software: you can redistribute it and/or modify
9
* it under the terms of the GNU 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 Av 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 General Public License for more details.
18
* You should have received a copy of the GNU General Public License
19
* along with Herqq UPnP Av. If not, see <http://www.gnu.org/licenses/>.
22
#ifndef HMEDIABROWSER_H_
23
#define HMEDIABROWSER_H_
25
#include <HUpnpAv/HUpnpAv>
26
#include <HUpnpCore/HUpnp>
28
#include <QtCore/QSet>
29
#include <QtCore/QString>
30
#include <QtCore/QObject>
41
class HBrowseParamsPrivate;
44
* \brief This class is used to configure a \e browse operation run by a HMediaBrowser.
46
* \headerfile hmediabrowser.h HBrowseParams
48
* \ingroup hupnp_av_cds_browsing
50
* \remarks This class is not thread-safe.
52
* \sa HMediaBrowser::browse()
54
class H_UPNP_AV_EXPORT HBrowseParams
59
* \brief This enumeration defines the different browse operations available.
64
* The browse targets a single CDS object.
69
* The browse targets the children of the CDS container.
74
* The browse targets a CDS container \b and its children. Contrast this
75
* to \c DirectChildren, which targets \b only the children.
77
ObjectAndDirectChildren,
80
* The browse targets a CDS container \b and its children recursively.
82
ObjectAndChildrenRecursively
87
HBrowseParamsPrivate* h_ptr;
92
* Creates a new, invalid instance.
99
* \brief Creates a new instance.
101
* \param browseType specifies the type of the browse operation.
105
HBrowseParams(BrowseType browseType);
108
* \brief Creates a new instance.
110
* \param objectId specifies the ID of the target object.
112
* \param browseType specifies the type of the browse operation.
116
HBrowseParams(const QString& objectId, BrowseType loadType);
119
* \brief Destroys the instance.
124
* \brief Copy constructor.
126
* Creates a copy of \c other.
128
HBrowseParams(const HBrowseParams&);
131
* \brief Assignment operator.
133
* Copies the contents of \c other to this.
135
HBrowseParams& operator=(const HBrowseParams&);
138
* \brief Specifies the ID of the target object.
140
* \param id specifies the ID of the target object. In case of a recursive
141
* browse, this is the ID of the root object.
145
void setObjectId(const QString& id);
148
* \brief Specifies the type of the browse operation.
150
* \param type specifies the type of the browse operation.
154
void setBrowseType(BrowseType type);
157
* \brief Specifies the \e filter for the operation.
159
* A filter specifies the CDS metadata properties that should be returned
160
* by the server. A special value of \c "*" means that every available
161
* metadata property should be returned. For more information, see the
162
* ContentDirectory:3 specification, section 2.3.15.
164
* \param filter specifies the CDS metadata properties that the server
165
* should include in the response.
169
void setFilter(const QSet<QString>& filter);
172
* \brief Indicates the validity of the object.
174
* \return \e true in case the object is valid, i.e. at least objectId()
177
bool isValid() const;
180
* \brief Returns the ID of the target object.
182
* \return The ID of the target object.
186
QString objectId() const;
189
* \brief Returns the type of the browse operation.
191
* \return The type of the browse operation.
193
* \sa setBrowseType()
195
BrowseType browseType() const;
198
* \brief Returns the CDS metadata properties that the server
199
* should include in the response.
201
* \return The the CDS metadata properties that the server
202
* should include in the response.
206
QSet<QString> filter() const;
209
class HMediaBrowserPrivate;
212
* \brief This class provides a simple API for browsing a ContentDirectory service and
213
* caching the contents of it.
215
* \headerfile hmediabrowser.h HMediaBrowser
217
* \ingroup hupnp_av_cds_browsing
219
* \remarks This class is not thread-safe.
221
class H_UPNP_AV_EXPORT HMediaBrowser :
225
H_DISABLE_COPY(HMediaBrowser)
226
H_DECLARE_PRIVATE(HMediaBrowser)
230
HMediaBrowserPrivate* h_ptr;
235
* \brief Creates a new instance.
237
* \param parent specifies parent \c QObject.
241
explicit HMediaBrowser(QObject* parent = 0);
244
* \brief Destroys the instance.
246
virtual ~HMediaBrowser();
249
* Resets the ContentDirectory service being browsed.
251
* \param cds specifies the ContentDirectory service object to be browsed.
253
* \return \e true if the CDS object was successfully set and it is ready
258
bool reset(HClientService* cds);
261
* Resets the ContentDirectory service being browsed.
263
* \param cds specifies the ContentDirectory service object to be browsed.
265
* \param takeOwnership specifies whether the \c %HMediaBrowser instance
266
* takes the ownership of the specified ContentDirectory instance.
268
* \return \e true if the CDS object was successfully set and it is ready
273
bool reset(HContentDirectoryAdapter* cds, bool takeOwnership);
276
* Initiates a browse operation based on the provided parameters.
278
* \params specifies the parameters for the browse operation.
280
* \return \e true when the operation was successfully dispatched.
283
* This is an asynchronous operation.
285
* \sa browseComplete(), objectsBrowsed(), cancel()
287
bool browse(const HBrowseParams& params);
290
* Attempts to browse everything the ContentDirectory service exposes.
292
* This is a convenience method.
294
* \return \e true when the operation was successfully dispatched.
297
* This is an asynchronous operation.
299
* \sa browse(), browseComplete(), objectsBrowsed(), cancel()
304
* Attempts to browse the metadata of a root container and everything directly
307
* This is a convenience method.
309
* \return \e true when the operation was successfully dispatched.
312
* This is an asynchronous operation.
314
* \sa browse(), browseComplete()
319
* \brief Returns the data source that contains all the loaded data.
321
* \return The data source that contains all the loaded data. The returned
322
* pointer is \b never null and the ownership of the data source is
323
* \b never transferred to the caller.
325
HCdsDataSource* dataSource() const;
328
* \brief Returns the ContentDirectory that is the target of browsing.
330
* \return The ContentDirectory that is the target of browsing.
331
* This is null when the ContentDirectory service has not been set.
335
HContentDirectoryAdapter* contentDirectory() const;
338
* \brief Indicates if the object is ready for browsing.
340
* \return \e true when the object is ready for browsing.
342
* \sa reset(), isActive()
344
bool isReady() const;
347
* \brief Indicates if an browse operation is currently ongoing.
349
* \return \e true if an browse operation is currently active.
351
bool isActive() const;
354
* Returns the last error code that occurred.
356
* \return the last error code that occurred. This is set to zero if no
357
* error has occurred.
359
* \sa lastErrorDescription()
361
qint32 lastErrorCode() const;
364
* Returns the last error description that occurred.
366
* \return the last error description that occurred. The returned string is
367
* empty if no error has occurred.
369
* \sa lastErrorDescription()
371
QString lastErrorDescription() const;
374
* Cancels currently active browse operation.
376
* This function does nothing if there is no browse operation currently active.
381
* Indicates if the object should automatically process LastChange events and
382
* attempt to update its data source.
384
* \return \e true if the object should automatically process LastChange events and
385
* attempt to update its data source.
387
* \sa setAutoUpdate()
389
bool isAutoUpdateEnabled();
392
* Specifies whether the object should automatically process LastChange events and
393
* attempt to update its data source.
395
* \param enable specifies whether the object should automatically process
396
* LastChange events and attempt to update its data source.
398
* \sa isAutoUpdateEnabled()
400
void setAutoUpdate(bool enable);
405
* \brief This signal is emitted when the previously started load operation failed
408
* \param source specifies the source of the event.
410
* \sa browseComplete()
412
void browseFailed(Herqq::Upnp::Av::HMediaBrowser* source);
415
* \brief This signal is emitted when a previously started browse operation is
416
* successfully completed.
418
* \param source specifies the source of the event.
420
* \sa browseFailed(), objectsBrowsed()
422
void browseComplete(Herqq::Upnp::Av::HMediaBrowser* source);
425
* \brief This signal is emitted when new objects have been browsed and cached
428
* \brief This signal is emitted whenever the contents of a single CDS container
429
* have been browsed and cached. This signal is especially useful in situations
430
* where the browse operation involves multiple CDS containers, as it enables
431
* progressive processing of the results while the operation is running
432
* (before the browseComplete() is emitted).
434
* \param source specifies the source of the event.
436
* \param ids specifies the IDs of the objects browsed. You can now retrieve
437
* these objects from the dataSource().
439
* \sa browseComplete(), browseFailed()
441
void objectsBrowsed(Herqq::Upnp::Av::HMediaBrowser* source, const QSet<QString>& ids);
444
* This signal is emitted when the instance has received LastChange data
445
* from the ContentDirectoryService.
447
* \param data specifies the received LastChange data.
449
void receivedLastChange(const Herqq::Upnp::Av::HCdsLastChangeInfos& data);
456
#endif /* HMEDIABROWSER_H_ */