1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
|
/*
* Copyright (C) 2011 Tuomo Penttinen, all rights reserved.
*
* Author: Tuomo Penttinen <tp@herqq.org>
*
* This file is part of Herqq UPnP Av (HUPnPAv) library.
*
* Herqq UPnP Av is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* Herqq UPnP Av is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with Herqq UPnP Av. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef HCONTAINER_H_
#define HCONTAINER_H_
#include <HUpnpAv/HObject>
namespace Herqq
{
namespace Upnp
{
namespace Av
{
class HContainerEventInfoPrivate;
/*!
* \brief This class is used to contain information of an HContainer modification event.
*
* \headerfile hcontainer.h HContainerEventInfo
*
* \ingroup hupnp_av_cds_objects
*
* \remarks This class is not thread-safe.
*
* \sa HContainer
*/
class H_UPNP_AV_EXPORT HContainerEventInfo
{
private:
QSharedDataPointer<HContainerEventInfoPrivate> h_ptr;
public:
/*!
* \brief This enumeration defines the different event types instances of this class
* are used to depict.
*/
enum EventType
{
/*!
* This event type is not defined.
*/
Undefined,
/*!
* This value is used when a child object has been added into
* this container.
*/
ChildAdded,
/*!
* This value is used when a child object has been removed from
* this container.
*/
ChildRemoved,
/*!
* This value is used when a child object of a container has been
* modified.
*/
ChildModified
};
/*!
* \brief Creates a new, invalid instance.
*
* \sa isValid()
*/
HContainerEventInfo();
/*!
* \brief Creates a new instance.
*
* \param type specifies the type of the event.
*
* \param childId specifies the ID of the child object that was the "target"
* of this event.
*/
HContainerEventInfo(
EventType type, const QString& childId, quint32 updateId = 0);
/*!
* \brief Copy constructor.
*
* Creates a copy of \c other.
*/
HContainerEventInfo(const HContainerEventInfo&);
/*!
* \brief Assignment operator.
*
* Copies the contents of \c other to this.
*/
HContainerEventInfo& operator=(const HContainerEventInfo&);
/*!
* \brief Destroys the instance.
*/
~HContainerEventInfo();
/*!
* \brief Indicates if the instance contains any data.
*
* \return \e true if the instance does not contain any data.
*/
bool isValid() const;
/*!
* \brief Returns the type of the event.
*
* \return The type of the event.
*
* \sa setType()
*/
EventType type() const;
/*!
* \brief Returns the ID of the child object that was the "target"
* of this event.
*
* \return The ID of the child object that was the "target"
* of this event.
*
* \sa setChildId()
*/
QString childId() const;
/*!
* \brief Returns the value of the state variable \c SystemUpdateId at the time this
* event was generated.
*
* \return the value of the state variable \c SystemUpdateId at the time this
* event was generated.
*
* \sa setUpdateId()
*/
quint32 updateId() const;
/*!
* \brief Specifies the type of the event.
*
* \param type specifies the type of the event.
*
* \sa type()
*/
void setType(EventType type);
/*!
* \brief Specifies the ID of the child object that was the "target"
* of this event.
*
* \param arg specifies the ID of the child object that was the "target"
* of this event.
*
* \sa childId()
*/
void setChildId(const QString& arg);
/*!
* \brief Specifies the value of the state variable \c SystemUpdateId at the time this
* event was generated.
*
* \param arg specifies the value of the state variable \c SystemUpdateId at the time this
* event was generated.
*
* \sa updateId()
*/
void setUpdateId(quint32 arg);
};
/*!
* Compares the two objects for equality.
*
* \return \e true in case the objects are logically equivalent.
*
* \relates HContainerEventInfo
*/
H_UPNP_AV_EXPORT bool operator==(const HContainerEventInfo&, const HContainerEventInfo&);
/*!
* Compares the two objects for inequality.
*
* \return \e true in case the objects are not logically equivalent.
*
* \relates HContainerEventInfo
*/
inline bool operator!=(const HContainerEventInfo& obj1, const HContainerEventInfo& obj2)
{
return !(obj1 == obj2);
}
class HContainerPrivate;
/*!
* \brief This class is used to represent a collection of individual content objects
* and other collections of individual content objects.
*
* The class identifier specified by the AV Working
* Committee is \c object.container .
*
* \headerfile hcontainer.h HContainer
*
* \ingroup hupnp_av_cds_objects
*
* \remarks This class is not thread-safe.
*/
class H_UPNP_AV_EXPORT HContainer :
public HObject
{
Q_OBJECT
H_DISABLE_COPY(HContainer)
H_DECLARE_PRIVATE(HContainer)
protected:
/*!
* Constructs a new instance.
*
* \param clazz specifies the UPnP class of the object. This cannot be empty.
*
* \param cdsType specifies the CDS type of the object. This cannot be
* HObject::UndefinedCdsType.
*
* \sa isInitialized()
*/
HContainer(const QString& clazz = sClass(), CdsType cdsType = sType());
//
// \internal
//
HContainer(HContainerPrivate&);
/*!
* Specifies the number of child objects the container is supposed to contain.
*
* \param arg specifies the number of child objects the container is supposed to contain.
*
* \sa expectedChildCount()
*/
void setExpectedChildCount(quint32 arg);
virtual bool validate() const;
// Documented in HClonable
virtual HContainer* newInstance() const;
// Documented in HClonable
virtual void doClone(HClonable* target) const;
public:
/*!
* \brief Creates a new instance.
*
* \param title specifies the title of the object.
*
* \param parentId specifies the ID of the object that contains this
* object. If the object has no parent, this has to be left empty.
*
* \param id specifies the ID of this object. If this is not specified,
* a unique identifier within the running process is created for the object.
*
* \sa isValid()
*/
HContainer(
const QString& title,
const QString& parentId = QString(),
const QString& id = QString());
/*!
* \brief Destroys the instance.
*/
virtual ~HContainer();
/*!
* \brief Returns the IDs of the individual content objects that this container
* contains.
*
* \return The IDs of the individual content objects that this container
* contains.
*
* \sa setChildIds(), expectedChildCount()
*/
QSet<QString> childIds() const;
/*!
* \brief Indicates if a search can be performed to this container.
*
* \return \e true if a search can be performed to this container.
*
* \sa setSearchable()
*/
bool searchable() const;
/*!
* \brief Returns the container update ID.
*
* \return The container update ID, which is the value of the state variable
* \c SystemUpdateID at the time of the most recent \e Container \e Modification
* of this instance.
*
* \sa setContainerUpdateId()
*/
quint32 containerUpdateId() const;
/*!
* \brief Returns the total number of child objects that have been deleted
* from this container since the last initialization.
*
* \return the total number of child objects that have been deleted
* from this container since the last initialization.
*
* \sa setTotalDeletedChildCount()
*/
quint32 totalDeletedChildCount() const;
/*!
* \brief Returns the class types that can be created within this container.
*
* \return The class types that can be created within this container.
*
* \sa setCreateClassInfos()
*/
QList<HCdsClassInfo> createClassInfos() const;
/*!
* \brief Returns the class types that can be used in searches targeted to this
* container.
*
* \return The class types that can be used in searches targeted to this
* container.
*
* \sa setSearchClassInfos(), ContentDirectory:3, Appendix B.1.11.
*/
QList<HCdsClassInfo> searchClassInfos() const;
/*!
* Returns the number of child objects the container is supposed to contain.
*
* At server-side the expected child count always equals to the size of
* childIds(). However, at client-side the number of child objects of a
* container are may be known before the actual child objects are available.
* Further, child objects may be added to a container object progressively
* and because of that non-zero size of childIds() does not mean that every
* child object of a container has been retrieved.
*
* You should never consider the size of childIds() as the number of all child
* objects of a container at client-side, unless the size equals to the
* value this method returns.
*
* \return the number of child objects the container is supposed to contain.
*
* \sa setExpectedChildCount(), childIds()
*/
quint32 expectedChildCount() const;
/*!
* Indicates if the container contains the specified child ID.
*
* \param childId specifies the child ID to check.
*
* \return \e true if the container contains the specified child ID.
*/
bool hasChildId(const QString& childId) const;
/*!
* \brief Sets the IDs of the individual content objects that this container contains.
*
* \param childIds specifies the IDs of the individual content objects that this
* container contains.
*/
void setChildIds(const QSet<QString>& childIds);
/*!
* Adds the specified IDs of the individual content objects to this container.
*
* \param childIds specifies the IDs of the individual content objects to
* be added to this container.
*/
void addChildIds(const QSet<QString>& childIds);
/*!
* Adds an ID of an individual content object to this container.
*
* \param childId specifies the ID of the individual content object to
* be added to this container.
*/
void addChildId(const QString& childId);
/*!
* Removes the specified child ID.
*
* \param childId specifies the child ID to be removed.
*/
void removeChildId(const QString& childId);
/*!
* Removes the specified child IDs.
*
* \param childIds specifies the child IDs to be removed.
*/
void removeChildIds(const QSet<QString>& childIDs);
/*!
* \brief Specifies the class types that can be created within this
* container.
*
* \param arg specifies the class types that can be created within this
* container.
*
* \sa searchClassInfos()
*/
void setCreateClassInfos(const QList<HCdsClassInfo>& arg);
/*!
* \brief Specifies the container update ID.
*
* \param arg specifies the container update ID.
*
* \sa containerUpdateId()
*/
void setContainerUpdateId(quint32 arg);
/*!
* \brief Specifies whether a search can be performed to this container.
*
* \param arg specifies whether a search can be performed to this container.
*
* \sa searchable()
*/
void setSearchable(bool arg);
/*!
* \brief Specifies class types that can be used in searches targeted to this
* container.
*
* \param arg specifies the class types that can be used in searches
* targeted to this container.
*
* \sa searchClassInfos()
*/
void setSearchClassInfos(const QList<HCdsClassInfo>& arg);
/*!
* Specifies the total number of child objects that have been deleted
* from this container since the last initialization.
*
* \param arg specifies the total number of child objects that have been deleted
* from this container since the last initialization.
*
* \sa totalDeletedChildCount()
*/
void setTotalDeletedChildCount(quint32 arg);
/*!
* \brief Returns the class identifier specified by the AV Working Committee.
*
* \return The class identifier specified by the AV Working Committee.
*/
inline static QString sClass() { return "object.container"; }
/*!
* \brief Returns the CdsType value of this class.
*
* \return The CdsType value of this class.
*/
inline static CdsType sType() { return Container; }
/*!
* Creates a new instance with no title or parentID.
*
* \return a pointer to the newly created instance.
*
* \remarks the ownership of the object is transferred to the caller. Make sure
* to delete the object.
*/
inline static HContainer* create() { return new HContainer(); }
Q_SIGNALS:
/*!
* \brief This signal is emitted when a container has been modified.
*
* \param source specifies the HContainer that sent the event.
*
* \param eventInfo specifies information of the \e Container \e Modification that
* occurred.
*
* \note Since HContainer knows only the IDs of its child objects, HContainer
* does not monitor its child objects for changes. Because of this, an
* HContainer instance will never emit this signal when a child object
* has been modified. However, this type of functionality is provided by
* HAbstractCdsDataSource.
*
* \sa HAbstractCdsDataSource
*/
void containerModified(
Herqq::Upnp::Av::HContainer* source,
const Herqq::Upnp::Av::HContainerEventInfo& eventInfo);
};
}
}
}
#endif /* HCONTAINER_H_ */
|