Changeset 10797 in vbox for trunk/src/VBox/Main/idl/VirtualBox.xidl

Timestamp:

Jul 22, 2008 8:12:42 AM (17 years ago)

Author:

vboxsync

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

33575

Message:

Guest properties: initial commit of new interface

File:

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

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

@@ -679 +679 @@
   <interface
      name="IVirtualBoxCallback" extends="$unknown"
-     uuid="ee95ffc2-b6c6-4ce8-9e9e-ceadbb5019fe"
+     uuid="5516cc08-fb81-47a6-b184-031e7bbd2997"
      wsmap="suppress"
      >
@@ -878 +878 @@
       <param name="snapshotId" type="uuid" dir="in">
         <desc>ID of the changed snapshot.</desc>
+      </param>
+    </method>
+
+    <method name="onGuestPropertyChange">
+      <desc>
+        Notification when a guest property has changed.
+      </desc>
+      <param name="machineId" type="uuid" dir="in">
+        <desc>
+          ID of the machine this event relates to.
+        </desc>
+      </param>
+      <param name="name" type="wstring" dir="in">
+        <desc>
+          The name of the property that has changed.
+        </desc>
+      </param>
+      <param name="value" type="wstring" dir="in">
+        <desc>
+          The new property value.
+        </desc>
+      </param>
+      <param name="flags" type="wstring" dir="in">
+        <desc>
+          The new property flags.
+        </desc>
       </param>
     </method>
@@ -2511 +2537 @@
   <interface
      name="IMachine" extends="$unknown"
-     uuid="9966d6d7-8bed-4f18-8553-2486f32957b3"
+     uuid="1e509de4-d96c-4f44-8b94-860194f710ac"
      wsmap="managed"
      >
@@ -3494 +3520 @@
     <method name="getGuestProperty">
       <desc>
-        Reads a value from the machine's host/guest property store.
-
-        If a session for this virtual machine is currently open then queries the
-        session object for the value, since the current values of the property
-        store will be held in RAM in the session. Otherwise reads the value from
-        machine extra data, where it is stored between sessions.
-
-        This method will fail if we are currently transitioning between session
-        states.
+        Reads an entry from the machine's guest property store.
       </desc>
       <param name="key" type="wstring" dir="in">
@@ -3509 +3527 @@
         </desc>
       </param>
-      <param name="value" type="wstring" dir="return">
+      <param name="value" type="wstring" dir="out">
         <desc>
           The value of the key.  If the key does not exist then this will be
@@ -3515 +3533 @@
         </desc>
       </param>
+      <param name="timestamp" type="unsigned long long" dir="out">
+        <desc>
+          The time at which the key was last modified, as seen by the server
+          process.
+        </desc>
+      </param>
+      <param name="flags" type="wstring" dir="out">
+        <desc>
+          Additional key parameters, passed as a comma-separated list of
+          "name=value" type entries.
+        </desc>
+      </param>
+    </method>
+
+    <method name="getGuestPropertyValue">
+      <desc>
+        Reads a value from the machine's guest property store.
+      </desc>
+      <param name="key" type="wstring" dir="in">
+        <desc>
+          The name of the key to read.
+        </desc>
+      </param>
+      <param name="value" type="wstring" dir="return">
+        <desc>
+          The value of the key.  If the key does not exist then this will be
+          empty.
+        </desc>
+      </param>
+    </method>
+
+    <method name="getGuestPropertyTimestamp">
+      <desc>
+        Reads a key timestamp from the machine's guest property store.
+      </desc>
+      <param name="key" type="wstring" dir="in">
+        <desc>
+          The name of the key to read.
+        </desc>
+      </param>
+      <param name="value" type="unsigned long long" dir="return">
+        <desc>
+          The timestamp.  If the key does not exist then this will be empty.
+        </desc>
+      </param>
     </method>
 
     <method name="setGuestProperty">
       <desc>
-        Sets, changes or deletes a value in the machine's host/guest
-        property store.
-
-        If a session for this virtual machine is currently open then changes the
-        value on the session object, since the current values of the property
-        store will be held in RAM in the session. Otherwise changes the value
-        in machine extra data, where it is stored between sessions.
-
-        This method will fail if we are currently transitioning between session
-        states.
+        Sets, changes or deletes an entry in the machine's guest property
+        store.
       </desc>
       <param name="key" type="wstring" dir="in">
@@ -3538 +3593 @@
         <desc>
           The new value of the key to set, change or delete.  If the key does
-          not yet exist and @a value is non-empty, it will be created.  If
-          @a value is empty, the key will be deleted if it exists.
-        </desc>
-      </param>
-    </method>
-
+          not yet exist and value is non-empty, it will be created.  If value
+          is empty, the key will be deleted if it exists.
+        </desc>
+      </param>
+      <param name="flags" type="wstring" dir="in">
+        <desc>
+          Additional key parameters, passed as a comma-separated list of
+          "name=value" type entries.
+        </desc>
+      </param>
+    </method>
+
+    <method name="setGuestPropertyValue">
+      <desc>
+        Sets, changes or deletes a value in the machine's guest property
+        store.  The flags field will be left unchanged or created empty for a
+        new property.
+      </desc>
+      <param name="key" type="wstring" dir="in">
+        <desc>
+          The name of the key to set, change or delete.
+        </desc>
+      </param>
+      <param name="value" type="wstring" dir="in">
+        <desc>
+          The new value of the key to set, change or delete.  If the key does
+          not yet exist and value is non-empty, it will be created.  If value
+          is empty, the key will be deleted if it exists.
+        </desc>
+      </param>
+    </method>
+
+    <method name="enumerateGuestProperties">
+      <desc>
+        Return a list of the guest properties matching a set of patterns along
+        with their values, timestamps and flags.
+      </desc>
+      <param name="patterns" type="wstring" dir="in">
+        <desc>
+          The patterns to match the properties against as a comma-separated
+          string.  If this is empty, all properties currently set will be
+          returned.
+        </desc>
+      </param>
+      <param name="key" type="wstring" dir="out" safearray="yes">
+        <desc>
+          The key names of the properties returned.
+        </desc>
+      </param>
+      <param name="value" type="wstring" dir="out" safearray="yes">
+        <desc>
+          The values of the properties returned.  The array entries match the
+          corresponding entries in the @a key array.
+        </desc>
+      </param>
+      <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
+        <desc>
+          The timestamps of the properties returned.  The array entries match
+          the corresponding entries in the @a key array.
+        </desc>
+      </param>
+      <param name="flags" type="wstring" dir="out" safearray="yes">
+        <desc>
+          The flags of the properties returned.  The array entries match the
+          corresponding entries in the @a key array.
+        </desc>
+      </param>
+    </method>
   </interface>