Changeset 769 for trunk/src/multimedia/audio/qaudioinput.cpp

Timestamp:

Aug 2, 2010, 9:27:30 PM (15 years ago)

Author:

Dmitry A. Kuminov

Message:

trunk: Merged in qt 4.6.3 sources from branches/vendor/nokia/qt.

Location:

trunk

Files:

• . (modified) (1 prop)
• src/multimedia/audio/qaudioinput.cpp (modified) (13 diffs)

trunk/src/multimedia/audio/qaudioinput.cpp

@@ -96 +96 @@
       format.setSampleType(QAudioFormat::UnSignedInt);
 
-      if (QAudioDeviceInfo info(QAudioDeviceInfo::defaultInputDevice());
+      QAudioDeviceInfo info = QAudioDeviceInfo::defaultInputDevice();
       if (!info.isFormatSupported(format)) {
           qWarning()<<"default format not supported try to use nearest";
@@ -147 +147 @@
 
     \sa QAudioOutput, QAudioDeviceInfo
+
+    \section1 Symbian Platform Security Requirements
+
+    On Symbian, processes which use this class must have the
+    \c UserEnvironment platform security capability.  If the client
+    process lacks this capability, calls to either overload of start()
+    will fail.
+    This failure is indicated by the QAudioInput object setting
+    its error() value to \l{QAudio::OpenError} and then emitting a
+    \l{stateChanged()}{stateChanged}(\l{QAudio::StoppedState}) signal.
+
+    Platform security capabilities are added via the
+    \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY}
+    qmake variable.
 */
 
@@ -191 +205 @@
      All that is required is to open the QIODevice.
 
+     If able to successfully get audio data from the systems audio device the
+     state() is set to either QAudio::ActiveState or QAudio::IdleState,
+     error() is set to QAudio::NoError and the stateChanged() signal is emitted.
+
+     If a problem occurs during this process the error() is set to QAudio::OpenError,
+     state() is set to QAudio::StoppedState and stateChanged() signal is emitted.
+
+    In either case, the stateChanged() signal may be emitted either synchronously
+    during execution of the start() function or asynchronously after start() has
+    returned to the caller.
+
+     \sa {Symbian Platform Security Requirements}
+
      \sa QIODevice
 */
@@ -196 +223 @@
 void QAudioInput::start(QIODevice* device)
 {
-    /*
-       -If currently not StoppedState, stop
-       -If previous start was push mode, delete internal QIODevice.
-       -open audio input.
-       If ok, NoError and ActiveState, else OpenError and StoppedState.
-       -emit stateChanged()
-    */
     d->start(device);
 }
@@ -211 +231 @@
     directly.
 
+    If able to access the systems audio device the state() is set to
+    QAudio::IdleState, error() is set to QAudio::NoError
+    and the stateChanged() signal is emitted.
+
+    If a problem occurs during this process the error() is set to QAudio::OpenError,
+    state() is set to QAudio::StoppedState and stateChanged() signal is emitted.
+
+    In either case, the stateChanged() signal may be emitted either synchronously
+    during execution of the start() function or asynchronously after start() has
+    returned to the caller.
+
+    \sa {Symbian Platform Security Requirements}
+
     \sa QIODevice
 */
@@ -216 +249 @@
 QIODevice* QAudioInput::start()
 {
-    /*
-    -If currently not StoppedState, stop
-    -If no internal QIODevice, create one.
-    -open audio input.
-    -If ok, NoError and IdleState, else OpenError and StoppedState
-    -emit stateChanged()
-    -return internal QIODevice
-    */
     return d->start(0);
 }
@@ -237 +262 @@
 
 /*!
-    Stops the audio input.
+    Stops the audio input, detaching from the system resource.
+
+    Sets error() to QAudio::NoError, state() to QAudio::StoppedState and
+    emit stateChanged() signal.
 */
 
 void QAudioInput::stop()
 {
-    /*
-    -If StoppedState, return
-    -set to StoppedState
-    -detach from audio device
-    -emit stateChanged()
-    */
     d->stop();
 }
@@ -257 +279 @@
 void QAudioInput::reset()
 {
-    /*
-    -drop all buffered audio, set buffers to zero.
-    -call stop()
-    */
     d->reset();
 }
@@ -266 +284 @@
 /*!
     Stops processing audio data, preserving buffered audio data.
+
+    Sets error() to QAudio::NoError, state() to QAudio::SuspendedState and
+    emit stateChanged() signal.
+
+    Note: signal will always be emitted during execution of the resume() function.
 */
 
 void QAudioInput::suspend()
 {
-    /*
-    -If not ActiveState|IdleState, return
-    -stop processing audio, saving all buffered audio data
-    -set NoError and SuspendedState
-    -emit stateChanged()
-    */
     d->suspend();
 }
@@ -281 +298 @@
 /*!
     Resumes processing audio data after a suspend().
+
+    Sets error() to QAudio::NoError.
+    Sets state() to QAudio::ActiveState if you previously called start(QIODevice*).
+    Sets state() to QAudio::IdleState if you previously called start().
+    emits stateChanged() signal.
 */
 
 void QAudioInput::resume()
 {
-    /*
-    -If SuspendedState, return
-    -resume audio
-    -(PULL MODE): set ActiveState, NoError
-    -(PUSH MODE): set IdleState, NoError
-    -kick start audio if needed
-    -emit stateChanged()
-    */
      d->resume();
 }
 
 /*!
-    Sets the audio buffer size to \a value milliseconds.
+    Sets the audio buffer size to \a value bytes.
 
     Note: This function can be called anytime before start(), calls to this
@@ -312 +326 @@
 
 /*!
-    Returns the audio buffer size in milliseconds.
+    Returns the audio buffer size in bytes.
 
     If called before start(), returns platform default value.
@@ -328 +342 @@
 /*!
     Returns the amount of audio data available to read in bytes.
+
+    NOTE: returned value is only valid while in QAudio::ActiveState or QAudio::IdleState
+    state, otherwise returns zero.
 */
 
@@ -353 +370 @@
     Sets the interval for notify() signal to be emitted.
     This is based on the \a ms of audio data processed
-    not on actual real-time. The resolution of the timer is platform specific.
+    not on actual real-time.
+    The minimum resolution of the timer is platform specific and values
+    should be checked with notifyInterval() to confirm actual value
+    being used.
 */