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 HMEDIARENDERER_CONNECTION_H_
23
#define HMEDIARENDERER_CONNECTION_H_
25
#include <HUpnpAv/HUpnpAv>
26
#include <HUpnpAv/HRendererConnectionInfo>
28
#include <QtCore/QObject>
41
class HRendererConnectionPrivate;
42
class HRendererConnectionController;
45
* This class defines an interface for rendering media content.
47
* This is a server-side class from which users derive custom classes,
48
* instantiate them and provide those instances to HUPnPAv, which at appropriate
49
* times uses them. The purpose of this class is to simplify the process of writing custom
50
* MediaRenderers by allowing the user to focus on actual content rendering, rather
51
* than to the details of AVTransport and RenderingControl specifications.
53
* \headerfile hrendererconnection_manager.h HRendererConnection
55
* \ingroup hupnp_av_mediarenderer
57
* \remarks This class is not thread-safe.
59
* \sa HRendererConnectionManager, HAvDeviceModelCreator, HMediaRendererDeviceConfiguration
61
class H_UPNP_AV_EXPORT HRendererConnection :
65
H_DISABLE_COPY(HRendererConnection)
66
friend class HRendererConnectionManager;
70
HRendererConnectionPrivate* h_ptr;
72
void init(qint32 connectionId);
78
* \brief Creates a new instance.
80
* \param parent specifies the parent \c QObject.
82
HRendererConnection(QObject* parent = 0);
85
* Provides the implementation for play().
87
* Every descendant has to override this.
89
* \param speed specifies the speed of the playback relative to normal speed.
91
* \retval Herqq::Upnp::UpnpErrorCode
92
* \retval HAvTransportInfo::ErrorCode
94
virtual qint32 doPlay(const QString& speed) = 0;
97
* Provides the implementation for stop().
99
* Every descendant has to override this.
101
* \retval Herqq::Upnp::UpnpErrorCode
102
* \retval HAvTransportInfo::ErrorCode
104
virtual qint32 doStop() = 0;
107
* Provides the implementation for pause().
109
* This method models an optional UPnP action and because of that it does not
110
* have to be overridden.
112
* \retval Herqq::Upnp::UpnpErrorCode
113
* \retval HAvTransportInfo::ErrorCode
115
virtual qint32 doPause();
118
* Provides the implementation for record().
120
* This method models an optional UPnP action and because of that it does not
121
* have to be overridden.
123
* \retval Herqq::Upnp::UpnpErrorCode
124
* \retval HAvTransportInfo::ErrorCode
126
virtual qint32 doRecord();
129
* Provides the implementation for seek().
131
* Every descendant has to override this.
133
* \param seekInfo specifies information about the seek operation.
135
* \retval Herqq::Upnp::UpnpErrorCode
136
* \retval HAvTransportInfo::ErrorCode
138
virtual qint32 doSeek(const HSeekInfo& seekInfo) = 0;
141
* Provides the implementation for next().
143
* Every descendant has to override this.
145
* \retval Herqq::Upnp::UpnpErrorCode
146
* \retval HAvTransportInfo::ErrorCode
148
virtual qint32 doNext() = 0;
151
* Provides the implementation for previous().
153
* Every descendant has to override this.
155
* \retval Herqq::Upnp::UpnpErrorCode
156
* \retval HAvTransportInfo::ErrorCode
158
virtual qint32 doPrevious() = 0;
161
* Provides the implementation for setPlayMode().
163
* This method models an optional UPnP action and because of that it does not
164
* have to be overridden.
166
* \param newMode specifies the new play mode.
168
* \retval Herqq::Upnp::UpnpErrorCode
169
* \retval HAvTransportInfo::ErrorCode
171
virtual qint32 doSetPlayMode(const HPlayMode& newMode);
174
* Provides the implementation for setRecordQualityMode().
176
* This method models an optional UPnP action and because of that it does not
177
* have to be overridden.
179
* \param newMode specifies the new new record quality mode.
181
* \retval Herqq::Upnp::UpnpErrorCode
182
* \retval HAvTransportInfo::ErrorCode
184
virtual qint32 doSetRecordQualityMode(const HRecordQualityMode& newMode);
187
* \brief Provides the implementation for setResource().
189
* \param resourceUri specifies the location of the new resource.
191
* \param cdsMetadata specifies optional metadata about the resource.
192
* This is null when no metadata is available.
194
* \retval Herqq::Upnp::UpnpErrorCode
195
* \retval HAvTransportInfo::ErrorCode
197
virtual qint32 doSetResource(
198
const QUrl& resourceUri, HObject* cdsMetadata = 0) = 0;
201
* \brief Provides the implementation for setNextResource().
203
* This method models an optional UPnP action and because of that it does not
204
* have to be overridden.
206
* \param resourceUri specifies the location of the new resource.
208
* \param cdsMetadata specifies optional metadata about the resource.
209
* This is null when no metadata is available.
211
* \retval Herqq::Upnp::UpnpErrorCode
212
* \retval HAvTransportInfo::ErrorCode
214
virtual qint32 doSetNextResource(
215
const QUrl& resourceUri, HObject* cdsMetadata = 0);
218
* \brief Provides the implementation for selectPreset().
220
* Every descendant has to override this.
222
* \param presetName specifies the preset.
224
* \retval Herqq::Upnp::UpnpErrorCode
225
* \retval HRenderingControlInfo::ErrorCode
227
virtual qint32 doSelectPreset(const QString& presetName) = 0;
230
* \brief Provides the implementation for setRcsValue().
232
* \param rcsAttrib specifies the RenderingControl property.
234
* \param newValue specifies the new value of the property.
236
* \retval Herqq::Upnp::UpnpErrorCode
237
* \retval HRenderingControlInfo::ErrorCode
239
virtual qint32 doSetRcsValue(
240
HRendererConnectionInfo::RcsAttribute rcsAttrib, quint16 newValue);
243
* \brief Provides the implementation for setHorizontalKeystone().
245
* This method models an optional UPnP action and because of that it does not
246
* have to be overridden.
248
* \param desiredHorizontalKeyStone specifies the new value.
250
* \retval Herqq::Upnp::UpnpErrorCode
251
* \retval HRenderingControlInfo::ErrorCode
253
virtual qint32 doSetHorizontalKeystone(qint16 desiredHorizontalKeyStone);
256
* \brief Provides the implementation for setVerticalKeystone().
258
* This method models an optional UPnP action and because of that it does not
259
* have to be overridden.
261
* \param desiredVerticalKeyStone specifies the new value.
263
* \retval Herqq::Upnp::UpnpErrorCode
264
* \retval HRenderingControlInfo::ErrorCode
266
virtual qint32 doSetVerticalKeystone(qint16 desiredHorizontalKeyStone);
269
* \brief Provides the implementation for setMute().
271
* This method models an optional UPnP action and because of that it does not
272
* have to be overridden.
274
* \param channel specifies the audio channel.
276
* \param muted specifies whether the channel is muted.
278
* \retval Herqq::Upnp::UpnpErrorCode
279
* \retval HRenderingControlInfo::ErrorCode
281
virtual qint32 doSetMute(const HChannel& channel, bool muted);
284
* \brief Provides the implementation for setVolume().
286
* This method models an optional UPnP action and because of that it does not
287
* have to be overridden.
289
* \param channel specifies the audio channel.
291
* \param volume specifies the target volume.
293
* \retval Herqq::Upnp::UpnpErrorCode
294
* \retval HRenderingControlInfo::ErrorCode
296
virtual qint32 doSetVolume(const HChannel& channel, quint16 volume);
299
* \brief Provides the implementation for setVolumeDb().
301
* This method models an optional UPnP action and because of that it does not
302
* have to be overridden.
304
* \param channel specifies the audio channel.
306
* \param volume specifies the target volume.
308
* \retval Herqq::Upnp::UpnpErrorCode
309
* \retval HRenderingControlInfo::ErrorCode
311
virtual qint32 doSetVolumeDb(const HChannel& channel, qint16 volume);
314
* \brief Provides the implementation for setLoudness().
316
* This method models an optional UPnP action and because of that it does not
317
* have to be overridden.
319
* \param channel specifies the audio channel.
321
* \param enabled specifies whether the loudness is enabled.
323
* \retval Herqq::Upnp::UpnpErrorCode
324
* \retval HRenderingControlInfo::ErrorCode
326
virtual qint32 doSetLoudness(const HChannel& channel, bool enabled);
329
* \brief Returns an object capable of retrieving and setting
330
* information about the capabilities and runtime status of the
331
* media manager instance.
333
* \return an object capable of retrieving and setting
334
* information about the capabilities and runtime status of the
335
* media manager instance.
337
HRendererConnectionInfo* writableInfo();
342
* \brief Destroys the instance.
344
virtual ~HRendererConnection() = 0;
347
* Returns the ID of the ConnectionManager connection with which this
348
* instance is associated.
350
* \return the ID of the ConnectionManager connection with which this
351
* instance is associated.
353
qint32 connectionId() const;
356
* \brief Returns an object capable of retrieving
357
* information about the capabilities and runtime status of the
358
* media manager instance.
360
* \return an object capable of retrieving and setting
361
* information about the capabilities and runtime status of the
362
* media manager instance.
364
const HRendererConnectionInfo* info() const;
367
* \brief Begins the playback of the current resource.
369
* \param speed specifies the speed of the playback relative to normal speed.
371
* \retval Herqq::Upnp::UpnpErrorCode
372
* \retval HAvTransportInfo::ErrorCode
374
qint32 play(const QString& speed);
377
* \brief Stops the progression of the current resource.
379
* \retval Herqq::Upnp::UpnpErrorCode
380
* \retval HAvTransportInfo::ErrorCode
385
* \brief Pauses the ongoing playback of the current resource associated with the
386
* specified virtual AVTransport instance.
388
* \retval Herqq::Upnp::UpnpErrorCode
389
* \retval HAvTransportInfo::ErrorCode
394
* \brief Begins recording on the specified virtual AVTransport instance.
396
* \retval Herqq::Upnp::UpnpErrorCode
397
* \retval HAvTransportInfo::ErrorCode
402
* \brief Seeks through the current resource of the specified
403
* virtual AVTransport instance.
405
* \param seekInfo specifies information about the seek operation.
407
* \retval Herqq::Upnp::UpnpErrorCode
408
* \retval HAvTransportInfo::ErrorCode
410
qint32 seek(const HSeekInfo& seekInfo);
413
* \brief Advances the current resource of the specified
414
* virtual AVTransport instance to the next track.
416
* \retval Herqq::Upnp::UpnpErrorCode
417
* \retval HAvTransportInfo::ErrorCode
422
* \brief Advances the current resource of the specified
423
* virtual AVTransport instance to the previous track.
425
* \retval Herqq::Upnp::UpnpErrorCode
426
* \retval HAvTransportInfo::ErrorCode
431
* \brief Sets the play mode of the specified virtual AVTransport instance.
433
* \param newMode specifies the new play mode.
435
* \retval Herqq::Upnp::UpnpErrorCode
436
* \retval HAvTransportInfo::ErrorCode
438
qint32 setPlaymode(const HPlayMode& newMode);
441
* \brief Sets the record quality mode of the specified virtual AVTransport instance.
443
* \param newMode specifies the new record quality mode.
445
* \retval Herqq::Upnp::UpnpErrorCode
446
* \retval HAvTransportInfo::ErrorCode
448
qint32 setRecordQualityMode(const HRecordQualityMode& newMode);
451
* \brief Indicates if the instance accepts the current resource to be changed to
452
* the specified resource.
454
* \param resourceUri specifies the location of the new resource.
456
* \param resourceMetadata specifies CDS metadata associated with the
457
* resource, using a DIDL-Lite XML Fragment. This parameter is optional.
459
* \retval Herqq::Upnp::UpnpErrorCode
460
* \retval HAvTransportInfo::ErrorCode
463
const QUrl& resourceUri, const QString& resourceMetadata = QString());
466
* \brief Indicates if the instance accepts the current resource to be changed to
467
* the specified resource.
469
* \param resourceUri specifies the location of the new resource.
471
* \param cdsMetadata specifies CDS metadata associated with the
472
* resource, using a DIDL-Lite XML Fragment. This parameter is optional.
474
* \retval Herqq::Upnp::UpnpErrorCode
475
* \retval HAvTransportInfo::ErrorCode
477
qint32 setNextResource(
478
const QUrl& resourceUri, const QString& resourceMetadata = QString());
481
* \brief Restores the values of the state variables associated with the
484
* \param presetName specifies the preset.
486
* \retval Herqq::Upnp::UpnpErrorCode
487
* \retval HRenderingControlInfo::ErrorCode
489
qint32 selectPreset(const QString& presetName);
492
* \brief Specifies the value for the specified RenderingControl property.
494
* \param rcsAttrib specifies the RenderingControl property.
496
* \param newValue specifies the new value of the property.
498
* \retval Herqq::Upnp::UpnpErrorCode
499
* \retval HRenderingControlInfo::ErrorCode
502
HRendererConnectionInfo::RcsAttribute rcsAttrib, quint16 newValue);
505
* \brief Specifies the horizontal keystone.
507
* \param desiredHorizontalKeyStone specifies the new value.
509
* \retval Herqq::Upnp::UpnpErrorCode
510
* \retval HRenderingControlInfo::ErrorCode
512
qint32 setHorizontalKeystone(qint16 desiredHorizontalKeyStone);
515
* \brief Specifies the vertical keystone.
517
* \param desiredVerticalKeyStone specifies the new value.
519
* \retval Herqq::Upnp::UpnpErrorCode
520
* \retval HRenderingControlInfo::ErrorCode
522
qint32 setVerticalKeystone(qint16 desiredHorizontalKeyStone);
525
* \brief Specifies whether the specified audio channel is muted.
527
* \param channel specifies the audio channel.
529
* \param muted specifies whether the channel is muted.
531
* \retval Herqq::Upnp::UpnpErrorCode
532
* \retval HRenderingControlInfo::ErrorCode
534
qint32 setMute(const HChannel& channel, bool muted);
537
* \brief Specifies the volume of the specified audio channel.
539
* \param channel specifies the audio channel.
541
* \param volume specifies the target volume.
543
* \retval Herqq::Upnp::UpnpErrorCode
544
* \retval HRenderingControlInfo::ErrorCode
546
qint32 setVolume(const HChannel& channel, quint16 volume);
549
* \brief Specifies the volume of the specified audio channel.
551
* \param channel specifies the audio channel.
553
* \param volume specifies the target volume.
555
* \retval Herqq::Upnp::UpnpErrorCode
556
* \retval HRenderingControlInfo::ErrorCode
558
qint32 setVolumeDb(const HChannel& channel, qint16 volume);
561
* \brief Specifies whether the loudness is enabled on the specified audio channel.
563
* \param channel specifies the audio channel.
565
* \param enabled specifies whether the loudness is enabled.
567
* \retval Herqq::Upnp::UpnpErrorCode
568
* \retval HRenderingControlInfo::ErrorCode
570
qint32 setLoudness(const HChannel& channel, bool enabled);
573
* \brief Returns the value of the specified property (state variable).
575
* \param svName specifies the name of the property (state variable), which
576
* value should be returned.
578
* \param ok is a pointer to \c bool, which value is set to \e true, if the value
579
* property was found. This is optional.
581
* \return the value of the specified property (state variable).
585
QString value(const QString& svName, bool* ok = 0) const;
588
* \brief Returns the value of the specified property (state variable).
590
* \param svName specifies the name of the property (state variable), which
591
* value should be returned.
593
* \param channel specifies the audio channel of which the property value is retrieved.
595
* \param ok is a pointer to \c bool, which value is set to \e true, if the value
596
* property was found. This is optional.
598
* \return the value of the specified property (state variable).
602
QString value(const QString& svName, const HChannel& channel, bool* ok = 0) const;
605
* \brief Specifies the value of the specified property (state variable).
607
* \param svName specifies the name of the property (state variable), which
608
* value should be set.
610
* \param value specifies the new value of the property.
612
* \return \e true if the value of the specified property was set.
616
bool setValue(const QString& svName, const QString& value);
619
* \brief Specifies the value of the specified property (state variable).
621
* \param svName specifies the name of the property (state variable), which
622
* value should be set.
624
* \param channel specifies the audio channel of which property should be set.
626
* \param value specifies the new value of the property.
628
* \return \e true if the value of the specified property was set.
632
bool setValue(const QString& svName, const HChannel& channel, const QString& value);
639
void disposed(Herqq::Upnp::Av::HRendererConnection* source);
646
#endif /* HMEDIARENDERER_CONNECTION_H_ */