Changeset 105266 in vbox for trunk/src/VBox/Main/idl

Timestamp:

Jul 11, 2024 7:49:37 AM (6 months ago)

Author:

vboxsync

Message:

Recording: Implemented support for a dedicated progress object, which is exposed to API clients. This can be used for better tracking the recording progress as well as for error reporting. The RecordingSettings API also now has a dedicated start() method to start recording, as well as support for attaching to an already ongoing recording by retrieving the progress object at a later time. Adapted FE/Qt (draft, see @todos), FE/VBoxManage and the Validation Kit testdriver to the new APIs. VBoxManage also can attach to an ongoing recording now. The recording progress object also will have multiple operations to get the recording progress for convenience. bugref:10718

File:

• trunk/src/VBox/Main/idl/VirtualBox.xidl (modified) (11 diffs)

trunk/src/VBox/Main/idl/VirtualBox.xidl

@@ -316 +316 @@
 <application
   name="VirtualBox"
-  uuid="a89ce63a-c7c9-4380-a62a-ffb9052ddb37"
+  uuid="61ff179a-5f10-4077-81f4-060beba09dec"
   supportsErrorInfo="yes"
 >
@@ -486 +486 @@
     <desc>
       Platform architecture is not supported.
+    </desc>
+  </result>
+
+  <result name="VBOX_E_RECORDING_ERROR" value="0x80BB0013">
+    <desc>
+      A recording error has occurred.
     </desc>
   </result>
@@ -6370 +6376 @@
   <interface
     name="IRecordingSettings" extends="$unknown"
-    uuid="D88F2A5A-47C7-4A3F-AAE1-1B516817DB41"
+    uuid="bea3ef5c-de2f-4b74-aa3a-15d6249371a0"
     wsmap="managed"
     rest="managed"
@@ -6391 +6397 @@
     </method>
 
+    <method name="start">
+      <desc>Starts recording and returns a progress object.</desc>
+      <param name="progress" type="IProgress" dir="return">
+        <desc>The recording progress object for this VM.</desc>
+      </param>
+      <result name="E_FAIL">
+        Unable to start recording due to recording already being started or not
+        available. See error message for more information.
+      </result>
+    </method>
+
     <attribute name="enabled" type="boolean" default="false">
       <desc>
-        This setting determines whether VirtualBox uses recording to record a
-        VM session.</desc>
+        This setting determines whether recording is enabled for this VM.
+
+        Note that this attribute does not actually start or stop recording.
+        For starting recording, use <link to="IRecordingSettings::start"/>, for
+        stopping, use the the progress object via <link to="IRecordingSettings::progress"/>.
+
+        If a VM is being started with this setting enabled, recording automatically
+        will be started with the currently configured recording settings.
+      </desc>
     </attribute>
 
@@ -6401 +6425 @@
         This setting returns an array for recording settings of all configured
         virtual screens.</desc>
+    </attribute>
+
+    <attribute name="progress" type="IProgress" readonly="yes">
+      <desc>
+        Returns the recording progress object.
+
+        Cancelling the progress will stop the recording.
+
+        <result name="E_FAIL">
+          Failed to get the recording progress object due to not (yet) started
+          recording.
+        </result>
+      </desc>
     </attribute>
 
@@ -24604 +24641 @@
   <interface
     name="IInternalSessionControl" extends="$unknown"
-    uuid="5045c372-2e8f-4d9e-ad9d-121ab1661146"
+    uuid="739160a6-53ea-465b-bb6b-5326c20a3c0c"
     internal="yes"
     wsmap="suppress"
@@ -24960 +24997 @@
     </method>
 
-    <method name="onRecordingChange">
-      <desc>
-        Triggered when recording settings have changed.
-      </desc>
-      <param name="enable" type="boolean" dir="in">
-        <desc>TODO</desc>
+    <method name="onRecordingStateChange">
+      <desc>
+        Triggered when a recording state got changed.
+      </desc>
+      <param name="enabled" type="boolean" dir="in">
+        <desc>
+          Whether recording was enabled or disabled.
+        </desc>
+      </param>
+      <param name="progress" type="IProgress" dir="out">
+        <desc>Progress object.</desc>
+      </param>
+    </method>
+
+    <method name="onRecordingScreenStateChange">
+      <desc>
+        Triggered when a recording screen state got changed.
+      </desc>
+      <param name="enabled" type="boolean" dir="in">
+        <desc>
+          Whether recording for that screen was enabled or disabled.
+        </desc>
+      </param>
+      <param name="screen" type="unsigned long" dir="in">
+        <desc>
+          Number of screen for which the event has happened.
+        </desc>
       </param>
     </method>
@@ -26923 +26981 @@
   <enum
     name="VBoxEventType"
-    uuid="f698ab32-91e4-4379-b99c-174cebecfa5e"
+    uuid="0c8f8bd7-c5d8-4085-83c2-558a4025b215"
     >
 
@@ -27282 +27340 @@
       </desc>
     </const>
-    <const name="OnRecordingChanged" value="91">
-      <desc>
-        See <link to="IRecordingChangedEvent">IRecordingChangeEvent</link>.
+    <const name="OnRecordingStateChanged" value="91">
+      <desc>
+        See <link to="IRecordingStateChangedEvent">IRecordingStateChangeEvent</link>.
       </desc>
     </const>
@@ -27454 +27512 @@
       </desc>
     </const>
+    <const name="OnRecordingScreenStateChanged" value="125">
+      <desc>
+        See <link to="IRecordingScreenStateChangedEvent">IRecordingScreenStateChangeEvent</link>.
+      </desc>
+    </const>
     <!-- End event marker -->
-    <const name="End" value="125">
+    <const name="End" value="126">
       <desc>
         Must be last event, used for iterations and structures relying on numerical event values.
@@ -29001 +29064 @@
 
   <interface
-    name="IRecordingChangedEvent" extends="IEvent"
-    uuid="B5DDB370-08A7-4C8F-910D-47AABD67253A"
-    wsmap="managed" autogen="VBoxEvent" id="OnRecordingChanged"
+    name="IRecordingStateChangedEvent" extends="IEvent"
+    uuid="e578bb9c-e88d-416b-bb45-08a4e7a5b463"
+    wsmap="managed" autogen="VBoxEvent" id="OnRecordingStateChanged"
     >
     <desc>
-      Notification when recording settings have changed.
-    </desc>
-    <attribute name="midlDoesNotLikeEmptyInterfaces" readonly="yes" type="boolean"/>
+      Notification when the machine's recording state has changed.
+    </desc>
+    <attribute name="enabled" type="boolean" readonly="yes">
+      <desc>
+        Whether recording was enabled or disabled.
+      </desc>
+    </attribute>
+    <attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
+      <desc>
+        Error information in case the event is indicating an error.
+      </desc>
+    </attribute>
+  </interface>
+
+  <interface
+    name="IRecordingScreenStateChangedEvent" extends="IRecordingStateChangedEvent"
+    uuid="5900472f-cc58-48ac-a088-b571b77f839b"
+    wsmap="managed" autogen="VBoxEvent" id="OnRecordingScreenStateChanged"
+    >
+    <desc>
+      Notification when a screen recording state has changed.
+    </desc>
+    <attribute name="screen" type="unsigned long" readonly="yes">
+      <desc>
+        Number of screen for which the event has happened.
+      </desc>
+    </attribute>
   </interface>