Changeset 98028 in vbox for trunk/src/VBox/Main/src-server/AudioSettingsImpl.cpp

Timestamp:

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

Author:

vboxsync

svn:sync-xref-src-repo-rev:

155122

Message:

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

File:

• trunk/src/VBox/Main/src-server/AudioSettingsImpl.cpp (modified) (21 diffs)

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)