Changeset 98028 in vbox for trunk/src/VBox/Main

Timestamp:

Jan 9, 2023 9:46:16 AM (2 years ago)

Author:

vboxsync

Message:

Audio/Main: Made the Backupable<T> align with the rest of Main (via a private struct), added more documentation.

Location:

trunk/src/VBox/Main

Files:

• include/AudioAdapterImpl.h (modified) (1 diff)
• include/AudioSettingsImpl.h (modified) (1 diff)
• src-server/AudioAdapterImpl.cpp (modified) (37 diffs)
• src-server/AudioSettingsImpl.cpp (modified) (21 diffs)

trunk/src/VBox/Main/include/AudioAdapterImpl.h

@@ -85 +85 @@
     HRESULT setProperty(const com::Utf8Str &aKey, const com::Utf8Str &aValue);
 
-    AudioSettings * const              mParent;
-    const ComObjPtr<AudioAdapter>      mPeer;
-    Backupable<settings::AudioAdapter> mData;
+private:
+
+    struct Data;
+    Data *m;
 };
 

trunk/src/VBox/Main/include/AudioSettingsImpl.h

@@ -64 +64 @@
 
     // public methods only for internal purposes
-    Machine* i_getParent(void);
     bool     i_canChangeSettings(void);
     void     i_onAdapterChanged(IAudioAdapter *pAdapter);

trunk/src/VBox/Main/src-server/AudioAdapterImpl.cpp

@@ -41 +41 @@
 
 
+////////////////////////////////////////////////////////////////////////////////
+//
+// AudioAdapter private data definition
+//
+////////////////////////////////////////////////////////////////////////////////
+
+struct AudioAdapter::Data
+{
+    Data()
+        : pParent(NULL)
+    { }
+
+    AudioSettings * const          pParent;
+    const ComObjPtr<AudioAdapter>  pPeer;
+
+    // use the XML settings structure in the members for simplicity
+    Backupable<settings::AudioAdapter> bd;
+};
+
 // constructor / destructor
 /////////////////////////////////////////////////////////////////////////////
 
 AudioAdapter::AudioAdapter()
-    : mParent(NULL)
 {
 }
@@ -68 +86 @@
 
 /**
- *  Initializes the audio adapter object.
- *
- *  @param aParent  Handle of the parent object.
+ * Initializes the audio adapter object.
+ *
+ * @returns HRESULT
+ * @param   aParent             Pointer of the parent object.
  */
 HRESULT AudioAdapter::init(AudioSettings *aParent)
 {
-    LogFlowThisFunc(("aParent=%p\n", aParent));
-
     ComAssertRet(aParent, E_INVALIDARG);
 
@@ -82 +99 @@
     AssertReturn(autoInitSpan.isOk(), E_FAIL);
 
-    unconst(mParent)   = aParent;
+    m = new Data();
+
+    unconst(m->pParent) = aParent;
     /* mPeer is left null */
-
-    mData.allocate();
 
     /* We now always default to the "Default" audio driver, to make it easier
@@ -91 +108 @@
      *
      * This can be changed by the user explicitly, if needed / wanted. */
-    mData->driverType  = AudioDriverType_Default;
-    mData->fEnabledIn  = false;
-    mData->fEnabledOut = false;
+    m->bd.allocate();
+    m->bd->driverType  = AudioDriverType_Default;
+    m->bd->fEnabledIn  = false;
+    m->bd->fEnabledOut = false;
 
     /* Confirm a successful initialization */
@@ -102 +120 @@
 
 /**
- *  Initializes the audio adapter object given another audio adapter object
- *  (a kind of copy constructor). This object shares data with
- *  the object passed as an argument.
- *
- *  @note This object must be destroyed before the original object
- *  it shares data with is destroyed.
- *
- *  @note Locks @a aThat object for reading.
+ * Initializes the audio adapter object given another audio adapter object
+ * (a kind of copy constructor). This object shares data with
+ * the object passed as an argument.
+ *
+ * @note This object must be destroyed before the original object
+ *       it shares data with is destroyed.
+ *
+ * @note Locks @a aThat object for reading.
+ *
+ * @returns HRESULT
+ * @param   aParent             Pointer of the parent object.
+ * @param   aThat               Pointer to audio adapter to use settings from.
  */
 HRESULT AudioAdapter::init(AudioSettings *aParent, AudioAdapter *aThat)
 {
-    LogFlowThisFunc(("aParent=%p, aThat=%p\n", aParent, aThat));
-
     ComAssertRet(aParent && aThat, E_INVALIDARG);
 
@@ -121 +141 @@
     AssertReturn(autoInitSpan.isOk(), E_FAIL);
 
-    unconst(mParent) = aParent;
-    unconst(mPeer) = aThat;
+    m = new Data();
+
+    unconst(m->pParent) = aParent;
+    unconst(m->pPeer)   = aThat;
 
     AutoCaller thatCaller(aThat);
@@ -128 +150 @@
 
     AutoReadLock thatLock(aThat COMMA_LOCKVAL_SRC_POS);
-    mData.share(aThat->mData);
+    m->bd.share(aThat->m->bd);
 
     /* Confirm a successful initialization */
@@ -137 +159 @@
 
 /**
- *  Initializes the audio adapter object given another audio adapter object
- *  (a kind of copy constructor). This object makes a private copy of data
- *  of the original object passed as an argument.
- *
- *  @note Locks @a aThat object for reading.
+ * Initializes the audio adapter object given another audio adapter object
+ * (a kind of copy constructor). This object makes a private copy of data
+ * of the original object passed as an argument.
+ *
+ * @note Locks @a aThat object for reading.
+ *
+ * @returns HRESULT
+ * @param   aParent             Pointer of the parent object.
+ * @param   aThat               Pointer to audio adapter to use settings from.
  */
 HRESULT AudioAdapter::initCopy(AudioSettings *aParent, AudioAdapter *aThat)
 {
-    LogFlowThisFunc(("aParent=%p, aThat=%p\n", aParent, aThat));
-
     ComAssertRet(aParent && aThat, E_INVALIDARG);
 
@@ -153 +177 @@
     AssertReturn(autoInitSpan.isOk(), E_FAIL);
 
-    unconst(mParent) = aParent;
+    m = new Data();
+
+    unconst(m->pParent) = aParent;
     /* mPeer is left null */
 
@@ -160 +186 @@
 
     AutoReadLock thatLock(aThat COMMA_LOCKVAL_SRC_POS);
-    mData.attachCopy(aThat->mData);
+    m->bd.attachCopy(aThat->m->bd);
 
     /* Confirm a successful initialization */
@@ -174 +200 @@
 void AudioAdapter::uninit(void)
 {
-    LogFlowThisFunc(("\n"));
-
     /* Enclose the state transition Ready->InUninit->NotReady */
     AutoUninitSpan autoUninitSpan(this);
@@ -181 +205 @@
         return;
 
-    unconst(mPeer)   = NULL;
-    unconst(mParent) = NULL;
-
-    mData.free();
+    unconst(m->pPeer) = NULL;
+    unconst(m->pParent) = NULL;
+
+    delete m;
+    m = NULL;
 }
 
@@ -197 +222 @@
     AutoReadLock alock(this COMMA_LOCKVAL_SRC_POS);
 
-    *aEnabled = mData->fEnabled;
+    *aEnabled = m->bd->fEnabled;
 
     return S_OK;
@@ -209 +234 @@
     AutoWriteLock alock(this COMMA_LOCKVAL_SRC_POS);
 
-    if (mData->fEnabled != RT_BOOL(aEnabled))
-    {
-        mData.backup();
-        mData->fEnabled = RT_BOOL(aEnabled);
+    if (m->bd->fEnabled != RT_BOOL(aEnabled))
+    {
+        m->bd.backup();
+        m->bd->fEnabled = RT_BOOL(aEnabled);
         alock.release();
 
-        mParent->i_onSettingsChanged(); // mParent is const, needs no locking
-        mParent->i_onAdapterChanged(this);
+        m->pParent->i_onSettingsChanged(); // mParent is const, needs no locking
+        m->pParent->i_onAdapterChanged(this);
     }
 
@@ -229 +254 @@
     AutoReadLock alock(this COMMA_LOCKVAL_SRC_POS);
 
-    *aEnabled = mData->fEnabledIn;
+    *aEnabled = RT_BOOL(m->bd->fEnabledIn);
 
     return S_OK;
@@ -241 +266 @@
     AutoWriteLock alock(this COMMA_LOCKVAL_SRC_POS);
 
-    if (RT_BOOL(aEnabled) != mData->fEnabledIn)
-    {
-        mData.backup();
-        mData->fEnabledIn = RT_BOOL(aEnabled);
+    if (RT_BOOL(aEnabled) != m->bd->fEnabledIn)
+    {
+        m->bd.backup();
+        m->bd->fEnabledIn = RT_BOOL(aEnabled);
 
         alock.release();
 
-        mParent->i_onSettingsChanged(); // mParent is const, needs no locking
-        mParent->i_onAdapterChanged(this);
+        m->pParent->i_onSettingsChanged(); // mParent is const, needs no locking
+        m->pParent->i_onAdapterChanged(this);
     }
 
@@ -262 +287 @@
     AutoReadLock alock(this COMMA_LOCKVAL_SRC_POS);
 
-    *aEnabled = mData->fEnabledOut;
+    *aEnabled = RT_BOOL(m->bd->fEnabledOut);
 
     return S_OK;
@@ -274 +299 @@
     AutoWriteLock alock(this COMMA_LOCKVAL_SRC_POS);
 
-    if (RT_BOOL(aEnabled) != mData->fEnabledOut)
-    {
-        mData.backup();
-        mData->fEnabledOut = RT_BOOL(aEnabled);
+    if (RT_BOOL(aEnabled) != m->bd->fEnabledOut)
+    {
+        m->bd.backup();
+        m->bd->fEnabledOut = RT_BOOL(aEnabled);
 
         alock.release();
 
-        mParent->i_onSettingsChanged(); // mParent is const, needs no locking
-        mParent->i_onAdapterChanged(this);
+        m->pParent->i_onSettingsChanged(); // mParent is const, needs no locking
+        m->pParent->i_onAdapterChanged(this);
     }
 
@@ -295 +320 @@
     AutoReadLock alock(this COMMA_LOCKVAL_SRC_POS);
 
-    *aAudioDriver = mData->driverType;
+    *aAudioDriver = m->bd->driverType;
 
     return S_OK;
@@ -309 +334 @@
     HRESULT rc = S_OK;
 
-    if (mData->driverType != aAudioDriver)
+    if (m->bd->driverType != aAudioDriver)
     {
         if (settings::MachineConfigFile::isAudioDriverAllowedOnThisHost(aAudioDriver))
         {
-            mData.backup();
-            mData->driverType = aAudioDriver;
+            m->bd.backup();
+            m->bd->driverType = aAudioDriver;
 
             alock.release();
 
-            mParent->i_onSettingsChanged(); // mParent is const, needs no locking
+            m->pParent->i_onSettingsChanged(); // mParent is const, needs no locking
         }
         else
@@ -337 +362 @@
     AutoReadLock alock(this COMMA_LOCKVAL_SRC_POS);
 
-    *aAudioController = mData->controllerType;
+    *aAudioController = m->bd->controllerType;
 
     return S_OK;
@@ -351 +376 @@
     HRESULT hrc = S_OK;
 
-    if (mData->controllerType != aAudioController)
+    if (m->bd->controllerType != aAudioController)
     {
         AudioCodecType_T defaultCodec;
@@ -379 +404 @@
         if (SUCCEEDED(hrc))
         {
-            mData.backup();
-            mData->controllerType = aAudioController;
-            mData->codecType      = defaultCodec;
+            m->bd.backup();
+            m->bd->controllerType = aAudioController;
+            m->bd->codecType      = defaultCodec;
 
             alock.release();
 
-            mParent->i_onSettingsChanged(); // mParent is const, needs no locking
+            m->pParent->i_onSettingsChanged(); // mParent is const, needs no locking
         }
     }
@@ -399 +424 @@
     AutoReadLock alock(this COMMA_LOCKVAL_SRC_POS);
 
-    *aAudioCodec = mData->codecType;
+    *aAudioCodec = m->bd->codecType;
 
     return S_OK;
@@ -416 +441 @@
      * ensure that the codec type matches the audio controller
      */
-    switch (mData->controllerType)
+    switch (m->bd->controllerType)
     {
         case AudioControllerType_AC97:
@@ -442 +467 @@
         default:
             AssertMsgFailed(("Wrong audio controller type %d\n",
-                             mData->controllerType));
+                             m->bd->controllerType));
             hrc = E_FAIL;
     }
@@ -451 +476 @@
                         aAudioCodec);
 
-    if (mData->codecType != aAudioCodec)
-    {
-        mData.backup();
-        mData->codecType = aAudioCodec;
+    if (m->bd->codecType != aAudioCodec)
+    {
+        m->bd.backup();
+        m->bd->codecType = aAudioCodec;
 
         alock.release();
 
-        mParent->i_onSettingsChanged(); // mParent is const, needs no locking
+        m->pParent->i_onSettingsChanged(); // mParent is const, needs no locking
     }
 
@@ -474 +499 @@
 
     aProperties.resize(0);
-    StringsMap::const_iterator cit = mData->properties.begin();
-    while(cit != mData->properties.end())
+    StringsMap::const_iterator cit = m->bd->properties.begin();
+    while(cit != m->bd->properties.end())
     {
         Utf8Str key = cit->first;
@@ -492 +517 @@
     AutoReadLock alock(this COMMA_LOCKVAL_SRC_POS);
 
-    settings::StringsMap::const_iterator cit = mData->properties.find(aKey);
-    if (cit != mData->properties.end())
+    settings::StringsMap::const_iterator cit = m->bd->properties.find(aKey);
+    if (cit != m->bd->properties.end())
         aValue = cit->second;
 
@@ -511 +536 @@
     Utf8Str strOldValue;
 
-    settings::StringsMap::const_iterator cit = mData->properties.find(aKey);
-    if (cit != mData->properties.end())
+    settings::StringsMap::const_iterator cit = m->bd->properties.find(aKey);
+    if (cit != m->bd->properties.end())
         strOldValue = cit->second;
 
@@ -518 +543 @@
     {
         if (aValue.isEmpty())
-            mData->properties.erase(aKey);
+            m->bd->properties.erase(aKey);
         else
-            mData->properties[aKey] = aValue;
+            m->bd->properties[aKey] = aValue;
     }
 
@@ -535 +560 @@
 
 /**
- *  Loads settings from the given machine node.
- *  May be called once right after this object creation.
- *
- *  @param data Configuration settings.
- *
- *  @note Locks this object for writing.
+ * Loads settings from the given machine node.
+ * May be called once right after this object creation.
+ *
+ * @returns HRESULT
+ * @param   data                Audio adapter configuration settings to load from.
+ *
+ * @note Locks this object for writing.
  */
 HRESULT AudioAdapter::i_loadSettings(const settings::AudioAdapter &data)
@@ -559 +585 @@
      * the same setting of an object loaded from the old settings file must
      * default to B. */
-    mData.assignCopy(&data);
-
-    return S_OK;
-}
-
-/**
- *  Saves settings to the given machine node.
- *
- *  @param data Configuration settings.
- *
- *  @note Locks this object for reading.
+    m->bd.assignCopy(&data);
+
+    return S_OK;
+}
+
+/**
+ * Saves settings to the given machine node.
+ *
+ * @returns HRESULT
+ * @param   data                Audio adapter configuration settings to save to.
+ *
+ * @note Locks this object for reading.
  */
 HRESULT AudioAdapter::i_saveSettings(settings::AudioAdapter &data)
@@ -578 +605 @@
     AutoReadLock alock(this COMMA_LOCKVAL_SRC_POS);
 
-    data = *mData.data();
-
-    return S_OK;
-}
-
-/**
- *  @note Locks this object for writing.
+    data = *m->bd.data();
+
+    return S_OK;
+}
+
+/**
+ * Rolls back the current configuration to a former state.
+ *
+ * @note Locks this object for writing.
  */
 void AudioAdapter::i_rollback()
@@ -594 +623 @@
     AutoWriteLock alock(this COMMA_LOCKVAL_SRC_POS);
 
-    mData.rollback();
-}
-
-/**
- *  @note Locks this object for writing, together with the peer object (also
- *  for writing) if there is one.
+    m->bd.rollback();
+}
+
+/**
+ * Commits the current settings and propagates those to a peer (if assigned).
+ *
+ * @note Locks this object for writing, together with the peer object (also
+ *       for writing) if there is one.
  */
 void AudioAdapter::i_commit()
@@ -608 +639 @@
 
     /* sanity too */
-    AutoCaller peerCaller(mPeer);
+    AutoCaller peerCaller(m->pPeer);
     AssertComRCReturnVoid(peerCaller.rc());
 
     /* lock both for writing since we modify both (mPeer is "master" so locked
      * first) */
-    AutoMultiWriteLock2 alock(mPeer, this COMMA_LOCKVAL_SRC_POS);
-
-    if (mData.isBackedUp())
-    {
-        mData.commit();
-        if (mPeer)
+    AutoMultiWriteLock2 alock(m->pPeer, this COMMA_LOCKVAL_SRC_POS);
+
+    if (m->bd.isBackedUp())
+    {
+        m->bd.commit();
+        if (m->pPeer)
         {
             /* attach new data to the peer and reshare it */
-            mPeer->mData.attach(mData);
-        }
-    }
-}
-
-/**
- *  @note Locks this object for writing, together with the peer object
- *  represented by @a aThat (locked for reading).
+            m->pPeer->m->bd.attach(m->bd);
+        }
+    }
+}
+
+/**
+ * Copies settings from a given audio adapter object.
+ *
+ * This object makes a private copy of data of the original object passed as
+ * an argument.
+ *
+ * @note Locks this object for writing, together with the peer object
+ *       represented by @a aThat (locked for reading).
+ *
+ * @param aThat                 Audio adapter to load settings from.
  */
 void AudioAdapter::i_copyFrom(AudioAdapter *aThat)
@@ -648 +686 @@
 
     /* this will back up current data */
-    mData.assignCopy(aThat->mData);
+    m->bd.assignCopy(aThat->m->bd);
 }
 /* vi: set tabstop=4 shiftwidth=4 expandtab: */

trunk/src/VBox/Main/src-server/AudioSettingsImpl.cpp

@@ -48 +48 @@
 {
     Data()
-        : pParent(NULL)
+        : pMachine(NULL)
     { }
 
-    Machine * const                pParent;
+    Machine * const                pMachine;
     const ComObjPtr<AudioAdapter>  pAdapter;
     const ComObjPtr<AudioSettings> pPeer;
@@ -76 +76 @@
  * Initializes the audio settings object.
  *
- * @param aParent  Handle of the parent object.
+ * @returns HRESULT
+ * @param   aParent             Pointer of the parent object.
  */
 HRESULT AudioSettings::init(Machine *aParent)
 {
-    LogFlowThisFunc(("aParent=%p\n", aParent));
-
     ComAssertRet(aParent, E_INVALIDARG);
 
@@ -91 +90 @@
 
     /* share the parent weakly */
-    unconst(m->pParent) = aParent;
+    unconst(m->pMachine) = aParent;
 
     /* create the audio adapter object (always present, default is disabled) */
@@ -109 +108 @@
  *
  * @note This object must be destroyed before the original object
- * it shares data with is destroyed.
+ *       it shares data with is destroyed.
  *
  * @note Locks @a aThat object for reading.
+ *
+ * @returns HRESULT
+ * @param   aParent             Pointer of the parent object.
+ * @param   aThat               Pointer to audio adapter to use settings from.
  */
 HRESULT AudioSettings::init(Machine *aParent, AudioSettings *aThat)
 {
-    LogFlowThisFuncEnter();
-    LogFlowThisFunc(("aParent: %p, aThat: %p\n", aParent, aThat));
-
     ComAssertRet(aParent && aThat, E_INVALIDARG);
 
@@ -126 +126 @@
     m = new Data();
 
-    unconst(m->pParent) = aParent;
-    unconst(m->pPeer)   = aThat;
+    unconst(m->pMachine) = aParent;
+    unconst(m->pPeer)    = aThat;
 
     AutoCaller thatCaller(aThat);
@@ -134 +134 @@
     AutoReadLock thatlock(aThat COMMA_LOCKVAL_SRC_POS);
 
-    unconst(m->pAdapter) = aThat->m->pAdapter;
+    HRESULT hrc = unconst(m->pAdapter).createObject();
+    ComAssertComRCRet(hrc, hrc);
+    hrc = m->pAdapter->init(this, aThat->m->pAdapter);
+    ComAssertComRCRet(hrc, hrc);
 
     autoInitSpan.setSucceeded();
 
-    LogFlowThisFuncLeave();
     return S_OK;
 }
@@ -148 +150 @@
  *
  * @note Locks @a aThat object for reading.
+ *
+ * @returns HRESULT
+ * @param   aParent             Pointer of the parent object.
+ * @param   aThat               Pointer to audio adapter to use settings from.
  */
 HRESULT AudioSettings::initCopy(Machine *aParent, AudioSettings *aThat)
 {
-    LogFlowThisFuncEnter();
-    LogFlowThisFunc(("aParent: %p, aThat: %p\n", aParent, aThat));
-
     ComAssertRet(aParent && aThat, E_INVALIDARG);
 
@@ -162 +165 @@
     m = new Data();
 
-    unconst(m->pParent) = aParent;
+    unconst(m->pMachine) = aParent;
     // pPeer is left null
 
@@ -175 +178 @@
     autoInitSpan.setSucceeded();
 
-    LogFlowThisFuncLeave();
     return S_OK;
 }
@@ -185 +187 @@
 void AudioSettings::uninit(void)
 {
-    LogFlowThisFunc(("\n"));
-
     /* Enclose the state transition Ready->InUninit->NotReady */
     AutoUninitSpan autoUninitSpan(this);
@@ -192 +192 @@
         return;
 
+    unconst(m->pPeer)    = NULL;
+    unconst(m->pMachine) = NULL;
+
     delete m;
     m = NULL;
@@ -230 +233 @@
 
 /**
- * Returns the parent object as a weak pointer.
- */
-Machine* AudioSettings::i_getParent(void)
-{
-    AutoCaller autoCaller(this);
-    AssertComRCReturn(autoCaller.rc(), NULL);
-
-    AssertPtrReturn(m, NULL);
-    return m->pParent;
-}
-
-/**
  * Determines whether the audio settings currently can be changed or not.
  *
@@ -248 +239 @@
 bool AudioSettings::i_canChangeSettings(void)
 {
-    AutoAnyStateDependency adep(m->pParent);
+    AutoAnyStateDependency adep(m->pMachine);
     if (FAILED(adep.rc()))
         return false;
@@ -259 +250 @@
  * Gets called when the machine object needs to know that audio adapter settings
  * have been changed.
+ *
+ * @param   pAdapter             Pointer to audio adapter which has changed.
  */
 void AudioSettings::i_onAdapterChanged(IAudioAdapter *pAdapter)
 {
-    LogFlowThisFuncEnter();
-
     AssertPtrReturnVoid(pAdapter);
-
-    m->pParent->i_onAudioAdapterChange(pAdapter); // mParent is const, needs no locking
-
-    LogFlowThisFuncLeave();
+    m->pMachine->i_onAudioAdapterChange(pAdapter); // mParent is const, needs no locking
 }
 
@@ -274 +262 @@
  * Gets called when the machine object needs to know that a host audio device
  * has been changed.
+ *
+ * @param   pDevice             Host audio device which has changed.
+ * @param   fIsNew              Set to \c true if this is a new device (i.e. has not been present before), \c false if not.
+ * @param   enmState            The current state of the device.
+ * @param   pErrInfo            Additional error information in case of error(s).
  */
 void AudioSettings::i_onHostDeviceChanged(IHostAudioDevice *pDevice,
                                           bool fIsNew, AudioDeviceState_T enmState, IVirtualBoxErrorInfo *pErrInfo)
 {
-    LogFlowThisFuncEnter();
-
     AssertPtrReturnVoid(pDevice);
-
-    m->pParent->i_onHostAudioDeviceChange(pDevice, fIsNew, enmState, pErrInfo); // mParent is const, needs no locking
-
-    LogFlowThisFuncLeave();
+    m->pMachine->i_onHostAudioDeviceChange(pDevice, fIsNew, enmState, pErrInfo); // mParent is const, needs no locking
 }
 
@@ -293 +281 @@
 void AudioSettings::i_onSettingsChanged(void)
 {
-    LogFlowThisFuncEnter();
-
-    AutoWriteLock mlock(m->pParent COMMA_LOCKVAL_SRC_POS);
-    m->pParent->i_setModified(Machine::IsModified_AudioSettings);
+    AutoWriteLock mlock(m->pMachine COMMA_LOCKVAL_SRC_POS);
+    m->pMachine->i_setModified(Machine::IsModified_AudioSettings);
     mlock.release();
-
-    LogFlowThisFuncLeave();
 }
 
@@ -306 +290 @@
  * May be called once right after this object creation.
  *
- * @param data Configuration settings.
+ * @returns HRESULT
+ * @param   data                Audio adapter configuration settings to load from.
  *
  * @note Locks this object for writing.
@@ -324 +309 @@
 
 /**
- * Saves settings to the given node.
- *
- * @param data Configuration settings.
+ * Saves audio settings to the given machine node.
+ *
+ * @returns HRESULT
+ * @param   data                Audio configuration settings to save to.
  *
  * @note Locks this object for reading.
@@ -344 +330 @@
 
 /**
+ * Copies settings from a given audio settings object.
+ *
+ * This object makes a private copy of data of the original object passed as
+ * an argument.
+ *
  * @note Locks this object for writing, together with the peer object
- * represented by @a aThat (locked for reading).
+ *       represented by @a aThat (locked for reading).
+ *
+ * @param aThat                 Audio settings to load from.
  */
 void AudioSettings::i_copyFrom(AudioSettings *aThat)
@@ -406 +399 @@
 
 /**
+ * Rolls back the current configuration to a former state.
+ *
  * @note Locks this object for writing.
  */
@@ -422 +417 @@
 
 /**
+ * Commits the current settings and propagates those to a peer (if assigned).
+ *
  * @note Locks this object for writing, together with the peer object (also
- * for writing) if there is one.
+ *       for writing) if there is one.
  */
 void AudioSettings::i_commit(void)