1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
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 https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://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 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include "qmediacontrol_p.h"
41#include "qaudiodecodercontrol.h"
42
43QT_BEGIN_NAMESPACE
44
45
46/*!
47 \class QAudioDecoderControl
48 \inmodule QtMultimedia
49
50
51 \ingroup multimedia_control
52
53 \brief The QAudioDecoderControl class provides access to the audio decoding
54 functionality of a QMediaService.
55
56 \preliminary
57
58 The functionality provided by this control is exposed to application
59 code through the QAudioDecoder class.
60
61 The interface name of QAudioDecoderControl is \c org.qt-project.qt.audiodecodercontrol/5.0 as
62 defined in QAudioDecoderControl_iid.
63
64 \sa QMediaService::requestControl(), QAudioDecoder
65*/
66
67/*!
68 \macro QAudioDecoderControl_iid
69
70 \c org.qt-project.qt.audiodecodercontrol/5.0
71
72 Defines the interface name of the QAudioDecoderControl class.
73
74 \relates QAudioDecoderControl
75*/
76
77/*!
78 Destroys an audio decoder control.
79*/
80QAudioDecoderControl::~QAudioDecoderControl()
81{
82}
83
84/*!
85 Constructs a new audio decoder control with the given \a parent.
86*/
87QAudioDecoderControl::QAudioDecoderControl(QObject *parent):
88 QMediaControl(*new QMediaControlPrivate, parent)
89{
90}
91
92/*!
93 \fn QAudioDecoderControl::state() const
94
95 Returns the state of a player control.
96*/
97
98/*!
99 \fn QAudioDecoderControl::stateChanged(QAudioDecoder::State newState)
100
101 Signals that the state of a player control has changed to \a newState.
102
103 \sa state()
104*/
105
106/*!
107 \fn QAudioDecoderControl::sourceFilename() const
108
109 Returns the current media source filename, or a null QString if none (or a device)
110*/
111
112/*!
113 \fn QAudioDecoderControl::setSourceFilename(const QString &fileName)
114
115 Sets the current source to \a fileName. Changing the source will
116 stop any current decoding and discard any buffers.
117
118 Sources are exclusive, so only one can be set.
119*/
120
121/*!
122 \fn QAudioDecoderControl::sourceDevice() const
123
124 Returns the current media source QIODevice, or 0 if none (or a file).
125*/
126
127/*!
128 \fn QAudioDecoderControl::setSourceDevice(QIODevice *device)
129
130 Sets the current source to \a device. Changing the source will
131 stop any current decoding and discard any buffers.
132
133 Sources are exclusive, so only one can be set.
134*/
135
136/*!
137 \fn QAudioDecoderControl::start()
138
139 Starts decoding the current media.
140
141 If successful the player control will immediately enter the \l {QAudioDecoder::DecodingState}
142 {decoding} state.
143
144 \sa state(), read()
145*/
146
147/*!
148 \fn QAudioDecoderControl::stop()
149
150 Stops playback of the current media and discards any buffers.
151
152 If successful the player control will immediately enter the \l {QAudioDecoder::StoppedState}
153 {stopped} state.
154*/
155
156/*!
157 \fn QAudioDecoderControl::error(int error, const QString &errorString)
158
159 Signals that an \a error has occurred. The \a errorString provides a more detailed explanation.
160*/
161
162/*!
163 \fn QAudioDecoderControl::bufferAvailableChanged(bool available)
164
165 Signals that the bufferAvailable property has changed to \a available.
166*/
167
168/*!
169 \fn QAudioDecoderControl::bufferReady()
170
171 Signals that a new buffer is ready for reading.
172*/
173
174/*!
175 \fn QAudioDecoderControl::bufferAvailable() const
176
177 Returns true if a buffer is available to be read,
178 and false otherwise.
179*/
180
181/*!
182 \fn QAudioDecoderControl::sourceChanged()
183
184 Signals that the current source of the decoder has changed.
185
186 \sa sourceFilename(), sourceDevice()
187*/
188
189/*!
190 \fn QAudioDecoderControl::formatChanged(const QAudioFormat &format)
191
192 Signals that the current audio format of the decoder has changed to \a format.
193
194 \sa audioFormat(), setAudioFormat()
195*/
196
197/*!
198 \fn void QAudioDecoderControl::finished()
199
200 Signals that the decoding has finished successfully.
201 If decoding fails, error signal is emitted instead.
202
203 \sa start(), stop(), error()
204*/
205
206/*!
207 \fn void QAudioDecoderControl::positionChanged(qint64 position)
208
209 Signals that the current \a position of the decoder has changed.
210
211 \sa durationChanged()
212*/
213
214/*!
215 \fn void QAudioDecoderControl::durationChanged(qint64 duration)
216
217 Signals that the estimated \a duration of the decoded data has changed.
218
219 \sa positionChanged()
220*/
221
222/*!
223 \fn QAudioDecoderControl::audioFormat() const
224 Returns the current audio format of the decoded stream.
225
226 Any buffers returned should have this format.
227
228 \sa setAudioFormat(), formatChanged()
229*/
230
231/*!
232 \fn QAudioDecoderControl::setAudioFormat(const QAudioFormat &format)
233 Set the desired audio format for decoded samples to \a format.
234
235 If the decoder does not support this format, \l error() will
236 be set to \c FormatError.
237
238 If you do not specify a format, the format of the decoded
239 audio itself will be used. Otherwise, some format conversion
240 will be applied.
241
242 If you wish to reset the decoded format to that of the original
243 audio file, you can specify an invalid \a format.
244*/
245
246/*!
247 \fn QAudioDecoderControl::read()
248 Attempts to read a buffer from the decoder, without blocking. Returns invalid buffer if there are
249 no decoded buffers available, or on error.
250*/
251
252/*!
253 \fn QAudioDecoderControl::position() const
254 Returns position (in milliseconds) of the last buffer read from
255 the decoder or -1 if no buffers have been read.
256*/
257
258/*!
259 \fn QAudioDecoderControl::duration() const
260 Returns total duration (in milliseconds) of the audio stream
261 or -1 if not available.
262*/
263
264#include "moc_qaudiodecodercontrol.cpp"
265QT_END_NAMESPACE
266
267