VirtualBox Main API

Public Member Functions | Public Attributes | List of all members
IVirtualSystemDescription Interface Reference

Represents one virtual system (machine) in an appliance. More...

Inheritance diagram for IVirtualSystemDescription:

## Public Member Functions
void | getDescription (out VirtualSystemDescriptionType[] types, out wstring[] refs, out wstring[] OVFValues, out wstring[] VBoxValues, out wstring[] extraConfigValues)
| Returns information about the virtual system as arrays of instruction items. More...
void | getDescriptionByType (in VirtualSystemDescriptionType type, out VirtualSystemDescriptionType[] types, out wstring[] refs, out wstring[] OVFValues, out wstring[] VBoxValues, out wstring[] extraConfigValues)
| This is the same as getDescription except that you can specify which types should be returned. More...
void | getValuesByType (in VirtualSystemDescriptionType type, in VirtualSystemDescriptionValueType which, [retval] out wstring[] values)
| This is the same as getDescriptionByType except that you can specify which value types should be returned. More...
void | setFinalValues (in boolean[] enabled, in wstring[] VBoxValues, in wstring[] extraConfigValues)
| This method allows the appliance's user to change the configuration for the virtual system descriptions. More...
void | addDescription (in VirtualSystemDescriptionType type, in wstring VBoxValue, in wstring extraConfigValue)
| This method adds an additional description entry to the stack of already available descriptions for this virtual system. More...

## Public Attributes
readonly attribute unsigned long | count
| Return the number of virtual system description entries. More...

## Detailed Description

Represents one virtual system (machine) in an appliance.

This interface is used in the IAppliance::virtualSystemDescriptions array. After IAppliance::interpret has been called, that array contains information about how the virtual systems described in the OVF should best be imported into VirtualBox virtual machines. See IAppliance for the steps required to import an OVF into VirtualBox.

Interface ID:
  `{316C99A2-405D-41AF-8508-46889144D067}`

## Member Function Documentation

## ◆ getDescription()

void IVirtualSystemDescription::getDescription | ( | out VirtualSystemDescriptionType [] | types,
|  | out wstring [] | refs,
|  | out wstring [] | OVFValues,
|  | out wstring [] | VBoxValues,
|  | out wstring [] | extraConfigValues
| ) |  |

Returns information about the virtual system as arrays of instruction items.

In each array, the items with the same indices correspond and jointly represent an import instruction for VirtualBox.

The list below identifies the value sets that are possible depending on the VirtualSystemDescriptionType enum value in the array item in aTypes[]. In each case, the array item with the same index in OVFValues[] will contain the original value as contained in the OVF file (just for informational purposes), and the corresponding item in aVBoxValues[] will contain a suggested value to be used for VirtualBox. Depending on the description type, the aExtraConfigValues[] array item may also be used.

- "OS": the guest operating system type. There must be exactly one such array item on import. The corresponding item in aVBoxValues[] contains the suggested guest operating system for VirtualBox. This will be one of the values listed in IVirtualBox::guestOSTypes. The corresponding item in OVFValues[] will contain a numerical value that described the operating system in the OVF.
- "Name": the name to give to the new virtual machine. There can be at most one such array item; if none is present on import, then an automatic name will be created from the operating system type. The corresponding item im OVFValues[] will contain the suggested virtual machine name from the OVF file, and aVBoxValues[] will contain a suggestion for a unique VirtualBox IMachine name that does not exist yet.
- "Description": an arbitrary description.
- "License": the EULA section from the OVF, if present. It is the responsibility of the calling code to display such a license for agreement; the Main API does not enforce any such policy.
- Miscellaneous: reserved for future use.
- "CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.
- "Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none is present on import, then VirtualBox will set a meaningful default based on the operating system type.
- "HardDiskControllerIDE": an IDE hard disk controller. There can be at most two such items. An optional value in OVFValues[] and aVBoxValues[] can be "PIIX3" or "PIIX4" to specify the type of IDE controller; this corresponds to the ResourceSubType element which VirtualBox writes into the OVF. The matching item in the aRefs[] array will contain an integer that items of the "Harddisk" type can use to specify which hard disk controller a virtual disk should be connected to. Note that in OVF, an IDE controller has two channels, corresponding to "master" and "slave" in traditional terminology, whereas the IDE storage controller that VirtualBox supports in its virtual machines supports four channels (primary master, primary slave, secondary master, secondary slave) and thus maps to two IDE controllers in the OVF sense.
- "HardDiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This has no value in OVFValues[] or aVBoxValues[]. The matching item in the aRefs[] array will be used as with IDE controllers (see above).
- "HardDiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item. The items in OVFValues[] and aVBoxValues[] will either be "LsiLogic", "BusLogic" or "LsiLogicSas". (Note that in OVF, the LsiLogicSas controller is treated as a SCSI controller whereas VirtualBox considers it a class of storage controllers of its own; see StorageControllerType). The matching item in the aRefs[] array will be used as with IDE controllers (see above).

- "HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an arbitrary number of these items, one for each virtual disk image that accompanies the OVF.

  The array item in OVFValues[] will contain the file specification from the OVF file (without a path since the image file should be in the same location as the OVF file itself), whereas the item in aVBoxValues[] will contain a qualified path specification to where VirtualBox uses the hard disk image. This means that on import the image will be copied and converted from the "ovf" location to the "vbox" location; on export, this will be handled the other way round.

  The matching item in the aExtraConfigValues[] array must contain a string of the following format: "controller=&lt;index&gt;;channel=&lt;c&gt;" In this string, <index> must be an integer specifying the hard disk controller to connect the image to. That number must be the index of an array item with one of the hard disk controller types (HardDiskControllerSCSI, HardDiskControllerSATA, HardDiskControllerIDE). In addition, <c> must specify the channel to use on that controller. For IDE controllers, this can be 0 or 1 for master or slave, respectively. For compatibility with VirtualBox versions before 3.2, the values 2 and 3 (for secondary master and secondary slave) are also supported, but no longer exported. For SATA and SCSI controllers, the channel can range from 0-29.

- "CDROM": a virtual CD-ROM drive. The matching item in aExtraConfigValue[] contains the same attachment information as with "HardDiskImage" items.
- "CDROM": a virtual floppy drive. The matching item in aExtraConfigValue[] contains the same attachment information as with "HardDiskImage" items.
- "NetworkAdapter": a network adapter. The array item in aVBoxValues[] will specify the hardware for the network adapter, whereas the array item in aExtraConfigValues[] will have a string of the "type=&lt;X&gt;" format, where <X> must be either "NAT" or "Bridged".
- "USBController": a USB controller. There can be at most one such item. If, and only if, such an item is present, USB support will be enabled for the new virtual machine.
- "SoundCard": a sound card. There can be at most one such item. If and only if such an item is present, sound support will be enabled for the new virtual machine. Note that the virtual machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which may be different from the virtual soundcard expected by the appliance.

Parameters

  types |
  refs |
  OVFValues |
  VBoxValues |
  extraConfigValues |

## ◆ getDescriptionByType()

void IVirtualSystemDescription::getDescriptionByType | ( | in VirtualSystemDescriptionType | type,
|  | out VirtualSystemDescriptionType [] | types,
|  | out wstring [] | refs,
|  | out wstring [] | OVFValues,
|  | out wstring [] | VBoxValues,
|  | out wstring [] | extraConfigValues
| ) |  |

This is the same as getDescription except that you can specify which types should be returned.

Parameters

  type |
  types |
  refs |
  OVFValues |
  VBoxValues |
  extraConfigValues |

## ◆ getValuesByType()

void IVirtualSystemDescription::getValuesByType | ( | in VirtualSystemDescriptionType | type,
|  | in VirtualSystemDescriptionValueType | which,
|  | [retval] out wstring [] | values
| ) |  |

This is the same as getDescriptionByType except that you can specify which value types should be returned.

See VirtualSystemDescriptionValueType for possible values.

Parameters

  type |
  which |
  values |

## ◆ setFinalValues()

void IVirtualSystemDescription::setFinalValues | ( | in boolean [] | enabled,
|  | in wstring [] | VBoxValues,
|  | in wstring [] | extraConfigValues
| ) |  |

This method allows the appliance's user to change the configuration for the virtual system descriptions.

For each array item returned from getDescription, you must pass in one boolean value and one configuration value.

Each item in the boolean array determines whether the particular configuration item should be enabled. You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA, HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController and SoundCard.

For the "vbox" and "extra configuration" values, if you pass in the same arrays as returned in the aVBoxValues and aExtraConfigValues arrays from getDescription, the configuration remains unchanged. Please see the documentation for getDescription for valid configuration values for the individual array item types. If the corresponding item in the aEnabled array is `false`, the configuration value is ignored.

Parameters

  enabled |
  VBoxValues |
  extraConfigValues |

## ◆ addDescription()

void IVirtualSystemDescription::addDescription | ( | in VirtualSystemDescriptionType | type,
|  | in wstring | VBoxValue,
|  | in wstring | extraConfigValue
| ) |  |

This method adds an additional description entry to the stack of already available descriptions for this virtual system.

This is handy for writing values which aren't directly supported by VirtualBox. One example would be the License type of VirtualSystemDescriptionType.

Parameters

  type |
  VBoxValue |
  extraConfigValue |

## Member Data Documentation

## ◆ count

readonly attribute unsigned long IVirtualSystemDescription::count

Return the number of virtual system description entries.