Some API and doc fixes for QAudioDecoder

Change-Id: I0f839896c9f813939b99b01242b54a00796731a8
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>

9 files changed, 51 insertions, 46 deletions

diff --git a/src/multimedia/audio/qaudiodecoder.cpp b/src/multimedia/audio/qaudiodecoder.cpp
index e7c0b48ae..6de7ab285 100644
--- a/src/multimedia/audio/qaudiodecoder.cpp
+++ b/src/multimedia/audio/qaudiodecoder.cpp
@@ -48,6 +48,7 @@
 #include <QtCore/qcoreevent.h>
 #include <QtCore/qmetaobject.h>
 #include <QtCore/qtimer.h>
+#include <QtCore/qurl.h>
 #include <QtCore/qdebug.h>
 #include <QtCore/qpointer.h>
 
@@ -55,18 +56,17 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QAudioDecoder
-    \brief The QAudioDecoder class allows decoding audio.
+    \brief The QAudioDecoder class implements decoding audio.
     \inmodule QtMultimedia
     \ingroup multimedia
     \ingroup multimedia_audio
 
     \preliminary
 
-    The QAudioDecoder class is a high level class for decoding local
+    The QAudioDecoder class is a high level class for decoding
     audio media files.  It is similar to the QMediaPlayer class except
     that audio is provided back through this API rather than routed
-    directly to audio hardware. Network and streaming
-    based media are not supported.
+    directly to audio hardware.
 
     \sa QAudioBuffer
 */
@@ -113,8 +113,7 @@ void QAudioDecoderPrivate::_q_error(int error, const QString &errorString)
 }
 
 /*!
-    Construct an QAudioDecoder instance
-    parented to \a parent.
+    Construct an QAudioDecoder instance with \a parent.
 */
 QAudioDecoder::QAudioDecoder(QObject *parent)
     : QObject(*new QAudioDecoderPrivate, parent)
@@ -151,11 +150,17 @@ QAudioDecoder::~QAudioDecoder()
         delete d->control;
 }
 
+/*!
+    Returns true is audio decoding is supported on this platform.
+*/
 bool QAudioDecoder::isAvailable() const
 {
     return d_func()->control != nullptr;
 }
 
+/*!
+    Returns the current state of the audio decoder.
+*/
 QAudioDecoder::State QAudioDecoder::state() const
 {
     return d_func()->state;
@@ -164,12 +169,15 @@ QAudioDecoder::State QAudioDecoder::state() const
 /*!
     Returns the current error state.
 */
-
 QAudioDecoder::Error QAudioDecoder::error() const
 {
     return d_func()->error;
 }
 
+/*!
+    Returns a human readable description of the current error.
+    Returns an empty string is there is no error.
+*/
 QString QAudioDecoder::errorString() const
 {
     return d_func()->errorString;
@@ -221,11 +229,11 @@ void QAudioDecoder::stop()
     If \l setSourceDevice was called, this will
     be empty.
 */
-QString QAudioDecoder::sourceFilename() const
+QUrl QAudioDecoder::source() const
 {
     Q_D(const QAudioDecoder);
     if (d->control)
-        return d->control->sourceFilename();
+        return d->control->source();
     return QString();
 }
 
@@ -238,17 +246,17 @@ QString QAudioDecoder::sourceFilename() const
     You can only specify either a source filename or
     a source QIODevice.  Setting one will unset the other.
 */
-void QAudioDecoder::setSourceFilename(const QString &fileName)
+void QAudioDecoder::setSource(const QUrl &fileName)
 {
     Q_D(QAudioDecoder);
 
     if (d->control != nullptr)
-        d_func()->control->setSourceFilename(fileName);
+        d_func()->control->setSource(fileName);
 }
 
 /*!
     Returns the current source QIODevice, if one was set.
-    If \l setSourceFilename() was called, this will be 0.
+    If \l setSource() was called, this will be a nullptr.
 */
 QIODevice *QAudioDecoder::sourceDevice() const
 {
@@ -420,7 +428,7 @@ QAudioBuffer QAudioDecoder::read() const
 
     Signals that the current source of the decoder has changed.
 
-    \sa sourceFilename(), sourceDevice()
+    \sa source(), sourceDevice()
 */
 
 /*!
@@ -493,7 +501,7 @@ QAudioBuffer QAudioDecoder::read() const
 */
 
 /*!
-    \property QAudioDecoder::sourceFilename
+    \property QAudioDecoder::source
     \brief the active filename being decoded by the decoder object.
 */
 
diff --git a/src/multimedia/audio/qaudiodecoder.h b/src/multimedia/audio/qaudiodecoder.h
index 2629e4db8..b3f7c6bdc 100644
--- a/src/multimedia/audio/qaudiodecoder.h
+++ b/src/multimedia/audio/qaudiodecoder.h
@@ -51,7 +51,7 @@ class QAudioDecoderPrivate;
 class Q_MULTIMEDIA_EXPORT QAudioDecoder : public QObject
 {
     Q_OBJECT
-    Q_PROPERTY(QString sourceFilename READ sourceFilename WRITE setSourceFilename NOTIFY sourceChanged)
+    Q_PROPERTY(QUrl source READ source WRITE setSource NOTIFY sourceChanged)
     Q_PROPERTY(State state READ state NOTIFY stateChanged)
     Q_PROPERTY(QString error READ errorString)
     Q_PROPERTY(bool bufferAvailable READ bufferAvailable NOTIFY bufferAvailableChanged)
@@ -81,8 +81,8 @@ public:
     bool isAvailable() const;
     State state() const;
 
-    QString sourceFilename() const;
-    void setSourceFilename(const QString &fileName);
+    QUrl source() const;
+    void setSource(const QUrl &fileName);
 
     QIODevice* sourceDevice() const;
     void setSourceDevice(QIODevice *device);
diff --git a/src/multimedia/doc/snippets/multimedia-snippets/audio.cpp b/src/multimedia/doc/snippets/multimedia-snippets/audio.cpp
index 571c824b0..4b7e09dc2 100644
--- a/src/multimedia/doc/snippets/multimedia-snippets/audio.cpp
+++ b/src/multimedia/doc/snippets/multimedia-snippets/audio.cpp
@@ -240,7 +240,7 @@ void AudioDecodingExample::decode()
 
     QAudioDecoder *decoder = new QAudioDecoder(this);
     decoder->setAudioFormat(desiredFormat);
-    decoder->setSourceFilename("level1.mp3");
+    decoder->setSource("level1.mp3");
 
     connect(decoder, SIGNAL(bufferReady()), this, SLOT(readBuffer()));
     decoder->start();
diff --git a/src/multimedia/platform/gstreamer/audio/qgstreameraudiodecoder.cpp b/src/multimedia/platform/gstreamer/audio/qgstreameraudiodecoder.cpp
index 50675c30f..0f5a0ee0a 100644
--- a/src/multimedia/platform/gstreamer/audio/qgstreameraudiodecoder.cpp
+++ b/src/multimedia/platform/gstreamer/audio/qgstreameraudiodecoder.cpp
@@ -277,12 +277,12 @@ bool QGstreamerAudioDecoder::processBusMessage(const QGstreamerMessage &message)
     return false;
 }
 
-QString QGstreamerAudioDecoder::sourceFilename() const
+QUrl QGstreamerAudioDecoder::source() const
 {
     return mSource;
 }
 
-void QGstreamerAudioDecoder::setSourceFilename(const QString &fileName)
+void QGstreamerAudioDecoder::setSource(const QUrl &fileName)
 {
     stop();
     mDevice = nullptr;
@@ -320,7 +320,7 @@ void QGstreamerAudioDecoder::start()
     addAppSink();
 
     if (!mSource.isEmpty()) {
-        m_playbin.set("uri", QUrl::fromLocalFile(mSource).toEncoded().constData());
+        m_playbin.set("uri", mSource.toEncoded().constData());
     } else if (mDevice) {
         // make sure we can read from device
         if (!mDevice->isOpen() || !mDevice->isReadable()) {
diff --git a/src/multimedia/platform/gstreamer/audio/qgstreameraudiodecoder_p.h b/src/multimedia/platform/gstreamer/audio/qgstreameraudiodecoder_p.h
index 628065f85..22d024801 100644
--- a/src/multimedia/platform/gstreamer/audio/qgstreameraudiodecoder_p.h
+++ b/src/multimedia/platform/gstreamer/audio/qgstreameraudiodecoder_p.h
@@ -54,6 +54,8 @@
 #include <QtMultimedia/private/qtmultimediaglobal_p.h>
 #include <QObject>
 #include <QtCore/qmutex.h>
+#include <QtCore/qurl.h>
+
 #include "private/qplatformaudiodecoder_p.h"
 #include <private/qgstpipeline_p.h>
 #include "qaudiodecoder.h"
@@ -82,8 +84,8 @@ public:
     // QAudioDecoder interface
     QAudioDecoder::State state() const override { return m_state; }
 
-    QString sourceFilename() const override;
-    void setSourceFilename(const QString &fileName) override;
+    QUrl source() const override;
+    void setSource(const QUrl &fileName) override;
 
     QIODevice *sourceDevice() const override;
     void setSourceDevice(QIODevice *device) override;
@@ -131,7 +133,7 @@ private:
     GstAppSink *m_appSink = nullptr;
     QGstAppSrc *m_appSrc = nullptr;
 
-    QString mSource;
+    QUrl mSource;
     QIODevice *mDevice = nullptr;
     QAudioFormat mFormat;
 
diff --git a/src/multimedia/platform/qplatformaudiodecoder.cpp b/src/multimedia/platform/qplatformaudiodecoder.cpp
index e0b43f0e9..2b29fd1ac 100644
--- a/src/multimedia/platform/qplatformaudiodecoder.cpp
+++ b/src/multimedia/platform/qplatformaudiodecoder.cpp
@@ -79,13 +79,13 @@ QPlatformAudioDecoder::QPlatformAudioDecoder(QObject *parent)
 */
 
 /*!
-    \fn QPlatformAudioDecoder::sourceFilename() const
+    \fn QPlatformAudioDecoder::source() const
 
     Returns the current media source filename, or a null QString if none (or a device)
 */
 
 /*!
-    \fn QPlatformAudioDecoder::setSourceFilename(const QString &fileName)
+    \fn QPlatformAudioDecoder::setSource(const QString &fileName)
 
     Sets the current source to \a fileName.  Changing the source will
     stop any current decoding and discard any buffers.
@@ -158,7 +158,7 @@ QPlatformAudioDecoder::QPlatformAudioDecoder(QObject *parent)
 
     Signals that the current source of the decoder has changed.
 
-    \sa sourceFilename(), sourceDevice()
+    \sa source(), sourceDevice()
 */
 
 /*!
diff --git a/src/multimedia/platform/qplatformaudiodecoder_p.h b/src/multimedia/platform/qplatformaudiodecoder_p.h
index a0af01b1a..09e3a02b4 100644
--- a/src/multimedia/platform/qplatformaudiodecoder_p.h
+++ b/src/multimedia/platform/qplatformaudiodecoder_p.h
@@ -67,8 +67,8 @@ class Q_MULTIMEDIA_EXPORT QPlatformAudioDecoder : public QObject
 public:
     virtual QAudioDecoder::State state() const = 0;
 
-    virtual QString sourceFilename() const = 0;
-    virtual void setSourceFilename(const QString &fileName) = 0;
+    virtual QUrl source() const = 0;
+    virtual void setSource(const QUrl &fileName) = 0;
 
     virtual QIODevice* sourceDevice() const = 0;
     virtual void setSourceDevice(QIODevice *device) = 0;
diff --git a/src/multimedia/platform/windows/decoder/mfaudiodecodercontrol.cpp b/src/multimedia/platform/windows/decoder/mfaudiodecodercontrol.cpp
index 3995eee35..5a07d7e08 100644
--- a/src/multimedia/platform/windows/decoder/mfaudiodecodercontrol.cpp
+++ b/src/multimedia/platform/windows/decoder/mfaudiodecodercontrol.cpp
@@ -89,9 +89,9 @@ QAudioDecoder::State MFAudioDecoderControl::state() const
     return m_state;
 }
 
-QString MFAudioDecoderControl::sourceFilename() const
+QUrl MFAudioDecoderControl::source() const
 {
-    return m_sourceFilename;
+    return m_source;
 }
 
 void MFAudioDecoderControl::onSourceCleared()
@@ -112,23 +112,18 @@ void MFAudioDecoderControl::onSourceCleared()
         emit durationChanged(m_duration);
 }
 
-void MFAudioDecoderControl::setSourceFilename(const QString &fileName)
+void MFAudioDecoderControl::setSource(const QUrl &fileName)
 {
-    if (!m_device && m_sourceFilename == fileName)
+    if (!m_device && m_source == fileName)
         return;
     m_sourceReady = false;
     m_sourceResolver->cancel();
     m_decoderSourceReader->setSource(0, m_audioFormat);
     m_device = 0;
-    m_sourceFilename = fileName;
-    if (!m_sourceFilename.isEmpty()) {
+    m_source = fileName;
+    if (!m_source.isEmpty()) {
         m_sourceResolver->shutdown();
-        QUrl url;
-        if (m_sourceFilename.startsWith(':'))
-            url = QUrl(QStringLiteral("qrc%1").arg(m_sourceFilename));
-        else
-            url = QUrl::fromLocalFile(m_sourceFilename);
-        m_sourceResolver->load(url, 0);
+        m_sourceResolver->load(m_source, 0);
         m_loadingSource = true;
     } else {
         onSourceCleared();
@@ -143,12 +138,12 @@ QIODevice* MFAudioDecoderControl::sourceDevice() const
 
 void MFAudioDecoderControl::setSourceDevice(QIODevice *device)
 {
-    if (m_device == device && m_sourceFilename.isEmpty())
+    if (m_device == device && m_source.isEmpty())
         return;
     m_sourceReady = false;
     m_sourceResolver->cancel();
     m_decoderSourceReader->setSource(0, m_audioFormat);
-    m_sourceFilename.clear();
+    m_source.clear();
     m_device = device;
     if (m_device) {
         m_sourceResolver->shutdown();
diff --git a/src/multimedia/platform/windows/decoder/mfaudiodecodercontrol_p.h b/src/multimedia/platform/windows/decoder/mfaudiodecodercontrol_p.h
index 78be5afef..563b9efb6 100644
--- a/src/multimedia/platform/windows/decoder/mfaudiodecodercontrol_p.h
+++ b/src/multimedia/platform/windows/decoder/mfaudiodecodercontrol_p.h
@@ -66,8 +66,8 @@ public:
 
     QAudioDecoder::State state() const;
 
-    QString sourceFilename() const;
-    void setSourceFilename(const QString &fileName);
+    QUrl source() const;
+    void setSource(const QUrl &fileName);
 
     QIODevice* sourceDevice() const;
     void setSourceDevice(QIODevice *device);
@@ -99,7 +99,7 @@ private:
     SourceResolver         *m_sourceResolver;
     IMFTransform           *m_resampler;
     QAudioDecoder::State    m_state;
-    QString                 m_sourceFilename;
+    QUrl                    m_source;
     QIODevice              *m_device;
     QAudioFormat            m_audioFormat;
     DWORD                   m_mfInputStreamID;