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

Timestamp:

Nov 16, 2007 9:35:01 PM (17 years ago)

Author:

vboxsync

Message:

Manual, API docs, webservice: Begin documenting webservice, add lots of/improve Main API documentation, rename ISessionManager (webservice) to IWebsessionManager

File:

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

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

@@ -512 +512 @@
      >
     <desc>
-      The IVirtualBoxErrorInfo interface represents extended error information
-      that can be set by components after unsuccessful method invocation and
-      returned to the client in addition to the result code.
+      Extended error information.
+
+      Such extended error information can be set by VirtualBox components
+      after unsuccessful method invocation. This can then be returned to the
+      client in addition to a plain result code.
 
       In MS COM, this interface extends the IErrorInfo interface,
@@ -1159 +1161 @@
         This method tries to guess the
         <link to="HardDiskStorageType">hard disk storage type</link> from the
-        format of the location string and from the contens of the resource the
+        format of the location string and from the contents of the resource the
         location points to. Currently, a <i>file path</i> is the only
         supported format for the location string which must point to either a
@@ -2176 +2178 @@
      wsmap="struct"
      >
+    <desc>
+        BIOS settings in a virtual machine. Used in <link to="IMachine::BIOSSettings" />.
+    </desc>
     <attribute name="logoFadeIn" type="boolean">
       <desc>Fade in flag for BIOS logo animation.</desc>
@@ -2239 +2244 @@
      wsmap="managed"
      >
+    <desc>
+      A virtual machine, or guest, created in VirtualBox.
+
+      This is used in two contexts, mainly: A collection of these is in
+      <link to="IVirtualBox::machines" />, listing all the virtual machines
+      that are currently registered with this VirtualBox installation. Also,
+      once a remote session has been opened for this machine (i.e. the
+      virtual machine is running), a copy of the machine is in the console
+      object that represents the connection to the remote session; see
+      <link to="IConsole" /> for details.
+
+      All the settings and actions that are visible in VirtualBox's
+      front-ends are represented by attributes and methods of this interface.
+      However, in order to start a virtual machine, as indicated above,
+      call <link to="IVirtualBox::openRemoteSession" />; to change machine
+      settings, one needs to open a direct session, see
+      <link to="IVirtualBox::openSession" />.
+
+      <see>IConsole, ISession</see>
+    </desc>
+
     <attribute name="parent" type="IVirtualBox" readonly="yes">
       <desc>Associated parent obect.</desc>
@@ -3502 +3528 @@
      wsmap="managed"
      >
+    <desc>
+      Connection to machine's remote session.
+
+      A console conceptually represents a connection to a remote session,
+      as opened by <link to="IVirtualBox::openRemoteSession" />. An
+      IConsole object lives in the local address space (and not remotely,
+      like IVirtualBox and IMachine do) and allows the owner to control
+      the virtual machine's state.
+    </desc>
+
     <attribute name="machine" type="IMachine" readonly="yes">
       <desc>
@@ -3519 +3555 @@
           This property always returns the same value as the corresponding
           property of the IMachine object this console is sessioned with.
-          For the process, that owns (executes) the VM, this is the
-          preferrable way of quierying the VM state, because no IPC
+          For the process that owns (executes) the VM, this is the
+          preferable way of querying the VM state, because no IPC
           calls are made.
         </note>
@@ -4039 +4075 @@
      wsmap="managed"
      >
+    <desc>
+      Physical CD/DVD drive hardware on the host. Used indirectly in <link to="IHost::DVDDrives" />.
+    </desc>
+
     <attribute name="name" type="wstring" readonly="yes">
       <desc>
@@ -4097 +4137 @@
      wsmap="managed"
      >
+    <desc>
+      Physical floppy drive hardware on the host. Used indirectly in <link to="IHost::floppyDrives" />.
+    </desc>
     <attribute name="name" type="wstring" readonly="yes">
       <desc>
@@ -4213 +4256 @@
      wsmap="managed"
      >
+    <desc>
+      The physical machine that this VirtualBox installation runs on.
+
+      This is used in <link to="IVirtualBox::host" /> and contains both read-only
+      information about the host's physical hardware (such as what processors,
+      and disks are available, what the host operating system is, and so on).
+
+      This also allows for manipulating some of the host's hardware, such as
+      USB and host interface networking.
+
+    </desc>
     <attribute name="DVDDrives" type="IHostDVDDriveCollection" readonly="yes">
       <desc>List of DVD drives available on the host.</desc>
@@ -4563 +4617 @@
         is used if a virtual machine's authentication type is set to "external"
         in the VM RemoteDisplay configuration and will be called from
-        within the <link to="ISessionManager::logon" /> implementation.
+        within the <link to="IWebsessionManager::logon" /> implementation.
 
         As opposed to <link to="ISystemProperties::remoteDisplayAuthLibrary" />,
@@ -4569 +4623 @@
         resource (if it is running). Only for this setting (for the webservice),
         setting this value to a literal "null" string disables authentication,
-        meaning that <link to="ISessionManager::logon" /> will always succeed,
+        meaning that <link to="IWebsessionManager::logon" /> will always succeed,
         no matter what user name and password are supplied.
 
@@ -4648 +4702 @@
      >
     <desc>
-      The IGuest interface represents a guest (virtual machine's) operating
-      system. It provides information about the Guest Additions and other
-      guest OS properties.
-
-      <see>IConsole::guest</see>
+      Operating system information of a virtual machine. Used in <link to="IConsole::guest" />.
+
+      IGuest provides information about the guest's operating system, whether
+      Guest Additions are installed and other OS-specific virtual machine properties.
     </desc>
 
@@ -5786 +5839 @@
 
     <desc>
-
-      The IVirtualDiskImage interface represents <link to="IHardDisk">virtual
-      hard disks</link> that use virtual disk image files to store hard disk
-      data.
+      Specific type of <link to="IHardDisk" /> that uses VDI image files.
+
+      The Virtual Disk Image (VDI) format is VirtualBox's native format for
+      hard disk containers.
 
       Hard disks using virtual disk images can be either opened using
@@ -5936 +5989 @@
 
     <desc>
+      Specific type of <link to="IHardDisk" /> that uses iSCSI.
 
       The IISCSIHardDisk interface represents <link to="IHardDisk">virtual
       hard disks</link> that use the Internet SCSI (iSCSI) protocol to store
       hard disk data on remote machines.
+
+      Objects that support this interface also support the
+      <link to="IHardDisk"/> interface. In other words, in C++ terms,
+      one can consider this class to be derived from IHardDisk.
+
+      As with other hard disk objects, hard disks using custom hard disk
+      images can be opened using <link to="IVirtualBox::openHardDisk()"/>.
 
       iSCSI hard disks can be created using
@@ -5949 +6010 @@
       machines.
 
-      Objects that support this interface also support the
-      <link to="IHardDisk"/> interface.
-
       The <link to="IHardDisk::description">description</link>
       of the iSCSI hard disk is stored in the VirtualBox
@@ -6035 +6093 @@
      >
     <desc>
-
-      The IVMDKImage interface represents <link to="IHardDisk">virtual hard
-      disks</link> that use VMware Virtual Machine Disk image files to store
-      hard disk data.
+      Specific type of <link to="IHardDisk" /> that uses VMDK image files.
+
+      The Virtual Machine Disk (VMDK) format is the industry standard format
+      for virtual hard disk image files, which VirtualBox supports besides its
+      own native VDI format.
 
       Hard disks using VMDK images can be either opened using
@@ -6192 +6251 @@
      >
     <desc>
-
-      The ICustomHardDisk interface represents <link to="IHardDisk">virtual hard
-      disks</link> that are supported through third-party plugins.
-
-      Hard disks using custom hard disk images can be opened using
-      <link to="IVirtualBox::openHardDisk()"/>.
+      Specific type of <link to="IHardDisk" /> that is supported through a third-party plugin.
 
       Objects that support this interface also support the
-      <link to="IHardDisk"/> interface.
+      <link to="IHardDisk"/> interface. In other words, in C++ terms,
+      one can consider this class to be derived from IHardDisk.
+
+      As with other hard disk objects, hard disks using custom hard disk
+      images can be opened using <link to="IVirtualBox::openHardDisk()"/>.
 
       When a new hard disk object is created from scratch, an image file for it
@@ -6466 +6524 @@
      wsmap="managed"
      >
+    <desc>
+      Virtual CD/DVD drive in a virtual machine. Used in <link to="IMachine::DVDDrive" />.
+    </desc>
     <attribute name="state" type="DriveState" readonly="yes">
       <desc>Current drive state.</desc>
@@ -6614 +6675 @@
      wsmap="managed"
      >
+    <desc>
+      Virtual floppy drive in a virtual machine. Used in <link to="IMachine::FloppyDrive" />.
+    </desc>
+
     <attribute name="enabled" type="boolean">
       <desc>
@@ -6662 +6727 @@
      wsmap="managed"
      >
+    <desc>
+      A virtual machine's keyboard within an <link to="IConsole" />. Used in <link to="IConsole:.keyboard" />.
+
+      Through this interface, the virtual machine's virtual keyboard can be controlled. One
+      can send keystrokes to the virtual machine and send the Ctrl-Alt-Del sequence to it.
+    </desc>
     <method name="putScancode">
       <desc>Sends a scancode to the keyboard.</desc>
@@ -6704 +6775 @@
      >
     <desc>
-      The IMouse interface represents a virtual mouse device.
+      A virtual machine's mouse within an <link to="IConsole" />. Used in <link to="IConsole:.mouse" />.
+
+      Through this interface, the virtual machine's virtual mouse can be controlled.
     </desc>
 
@@ -7241 +7314 @@
      wsmap="suppress"
      >
+    <desc>
+      A virtual machine's display within an <link to="IConsole" />.
+
+      One display object is contained in each <link to="IConsole::display" />
+      attribute and represents the visual output of the virtual machine. This
+      can represent a window on the host (for a local display).
+
+    </desc>
     <attribute name="width" type="unsigned long" readonly="yes">
       <desc>Current display width.</desc>
@@ -7935 +8016 @@
      >
     <desc>
-      The IUSBDevice interface represents a USB device captured by
-      (attached to) a running virtual machine's USB controller.
-      <see>IConsole::USBDevices</see>
+      Virtual USB device within an <link to="IConsole" />.
+
+      A collection of these is in <link to="IConsole::USBDevices" />.
+      Virtual USB devices can be attached to a running virtual machine's
+      USB controller.
+
     </desc>
 
@@ -8328 +8412 @@
      >
     <desc>
-      The IHostUSBDevice interface represents a USB device attached to
-      the host computer.
+      Physical USB device attached to the host computer.
 
       Among with properties inherited from IUSBDevice,
@@ -8390 +8473 @@
      >
     <desc>
-      The IHostUSBDeviceFilter interface represents a USB device filter used
-      by the host computer.
+      Filter for a physical USB device used by the host computer. Used indirectly
+      in <link to="IHost::USBDeviceFilters" />.
 
       Using filters of this type, the host computer determines the initial
@@ -8438 +8521 @@
      wsmap="struct"
      >
+    <desc>
+        Virtual audio adapter in a virtual machine. Used in <link to="IMachine::audioAdapter" />.
+    </desc>
     <attribute name="enabled" type="boolean">
       <desc>
@@ -8789 +8875 @@
      wsmap="managed"
      >
+    <desc>
+      Serialization primitive for virtual machines.
+
+      Within VirtualBox, any time one wishes to manipulate a virtual machine,
+      an instance of ISession is required. One first creates a session
+      object locally and then passes it with the method call that initiates
+      the machine manipulation. The session serves several purposes: it
+      identifies to the inter-process VirtualBox code which process is currently
+      working with a virtual machine, and it ensures that there are no
+      incompatible requests from several processes for the same virtual machine.
+
+      For example, to start a virtual machine, one would call
+      <link to="IVirtualBox::openRemoteSession" />, which requires a session
+      object as its first parameter. This session then identifies the caller
+      and makes sure that no other process attempts to manipulate the virtual
+      machine's parameters while it is running.
+
+      As another example, to manipulate machine settings, one needs to
+      open a direct session on the machine first by calling
+      <link to="IVirtualBox::openSession" />. This prevents the machine from
+      being changed by other processes.
+
+      In regular COM C++ client code, one can simply create a session object,
+      for example by calling <tt>createLocalObject().</tt>
+
+      In the webservice, the session manager creates one session object during
+      <link to="IWebsessionManager::logon" /> automatically; a managed object
+      reference to that session object can be retrieved by calling
+      <link to="IWebsessionManager::getSessionObject" />.
+    </desc>
+
     <attribute name="state" type="SessionState" readonly="yes">
       <desc>Current state of this session.</desc>
@@ -8840 +8957 @@
      wscpp="hardcoded"
      >
+    <desc>
+      Webservice only: Managed object reference.
+
+      Only within the webservice, a managed object reference (which is really
+      an opaque number) allows a webservice client to address an object
+      that lives in the address space of the webservice server.
+
+      Behind each managed object reference, there is a COM object that lives
+      in the webservice server's address space. The COM object is not freed
+      until the managed object reference is released, either by an explicit
+      call to  <link to="IManagedObjectRef::release" /> or by logging off from
+      the webservice (<link to="IWebsessionManager::logoff" />), which releases
+      all objects created during the webservice session.
+
+      Whenever a method call of the VirtualBox API returns a COM object, the
+      webservice representation of that method will instead return a
+      managed object reference, which can then be used to invoke methods
+      on that object.
+    </desc>
+
     <method name="getInterfaceName">
       <desc>
@@ -8851 +8988 @@
       <desc>
         Releases this managed object reference and frees the resources that
-        were allocated for it in the web service server process. After calling
+        were allocated for it in the webservice server process. After calling
         this method, the identifier of the reference can no longer be used.
       </desc>
@@ -8859 +8996 @@
 
   <!--
-  // ISessionManager
+  // IWebsessionManager
   /////////////////////////////////////////////////////////////////////////
   -->
 
   <interface
-     name="ISessionManager" extends="$unknown"
+     name="IWebsessionManager" extends="$unknown"
      uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
      internal="yes"
@@ -8870 +9007 @@
      wscpp="hardcoded"
      >
+    <desc>
+      Webservice only: Websession manager. This provides essential services
+      to webservice clients.
+    </desc>
     <method name="logon">
       <desc>
@@ -8885 +9026 @@
       <desc>
         Returns a managed object reference to the internal ISession object that was created
-        for this web service session. On each successful logon, the web service server
-        creates such an ISession object, which serves multiple purposes within VirtualBox.
-        For example, it serves as an exclusive lock to disallow several processes from
-        manipulating a VM at the same time.
+        for this web service session when the client logged on.
+
+        <see>ISession</see>
       </desc>
       <param name="refIVirtualBox" type="wstring" dir="in"/>
@@ -8896 +9036 @@
     <method name="logoff">
       <desc>
-        Logs off the client who has previously logged on with ISessionManager::logoff
+        Logs off the client who has previously logged on with <link to="IWebsessionManager::logoff" />
         and destroys all resources associated with the session (most importantly, all
         managed objects created in the server while the session was active).