From f5e3fdc4a72e1ab26342c4b97408928debc68551 Mon Sep 17 00:00:00 2001 From: Michael Goddard Date: Tue, 12 Jun 2012 11:27:24 +1000 Subject: Clarify documentation about QAudioDecoder::read and blocking. It doesn't block - not safe to implement in all cases. Applications can implement blocking semantics based on their usage of event loops or threads. Change-Id: If9a6b1ae7014df63a43989c4940524bc5eaae383 Reviewed-by: Dmytro Poplavskiy --- src/multimedia/audio/qaudiodecoder.cpp | 15 ++++++++++----- src/multimedia/controls/qaudiodecodercontrol.cpp | 7 +++---- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/src/multimedia/audio/qaudiodecoder.cpp b/src/multimedia/audio/qaudiodecoder.cpp index 9ebe58d04..30c9c0ccc 100644 --- a/src/multimedia/audio/qaudiodecoder.cpp +++ b/src/multimedia/audio/qaudiodecoder.cpp @@ -203,8 +203,8 @@ QString QAudioDecoder::errorString() const when enough data has been decoded. Calling \l read() will then return an audio buffer without blocking. - Alternatively, if you wish to block until enough data has been decoded, - you can call read() at any time to block until a buffer is ready. + If you call read() before a buffer is ready, an invalid buffer will + be returned, again without blocking. \sa read() */ @@ -372,8 +372,7 @@ QtMultimedia::SupportEstimate QAudioDecoder::hasSupport(const QString &mimeType, Returns true if a buffer is available to be read, and false otherwise. If there is no buffer available, calling - the \l read() function may block until a buffer is available or - the end of the media is reached + the \l read() function will return an invalid buffer. */ bool QAudioDecoder::bufferAvailable() const { @@ -410,7 +409,13 @@ qint64 QAudioDecoder::duration() const } /*! - Read a buffer from the decoder. Returns invalid buffer on failure. + Read a buffer from the decoder, if one is available. Returns an invalid buffer + if there are no decoded buffers currently available, or on failure. In both cases + this function will not block. + + You should either respond to the \l bufferReady() signal or check the + \l bufferAvailable() function before calling read() to make sure + you get useful data. */ QAudioBuffer QAudioDecoder::read() const diff --git a/src/multimedia/controls/qaudiodecodercontrol.cpp b/src/multimedia/controls/qaudiodecodercontrol.cpp index f8e7a0f3f..a44824883 100644 --- a/src/multimedia/controls/qaudiodecodercontrol.cpp +++ b/src/multimedia/controls/qaudiodecodercontrol.cpp @@ -177,9 +177,7 @@ QAudioDecoderControl::QAudioDecoderControl(QObject *parent): \fn QAudioDecoderControl::bufferAvailable() const Returns true if a buffer is available to be read, - and false otherwise. If there is no buffer available, calling - the \l read() function may block until a buffer is available or - the end of the media is reached + and false otherwise. */ /*! @@ -249,7 +247,8 @@ QAudioDecoderControl::QAudioDecoderControl(QObject *parent): /*! \fn QAudioDecoderControl::read() - Read a buffer from the decoder. Returns invalid buffer on failure. + Attempts to read a buffer from the decoder, without blocking. Returns invalid buffer if there are + no decoded buffers available, or on error. */ /*! -- cgit v1.2.3