Public Member Functions | Public Attributes

# IStorageController Interface Reference

Represents a storage controller that is attached to a virtual machine (IMachine). More...

List of all members.

## Public Member Functions
void | getIDEEmulationPort (in long devicePosition,[retval] out long portNumber)
| Gets the corresponding port number which is emulated as an IDE device.
void | setIDEEmulationPort (in long devicePosition, in long portNumber)
| Sets the port number which is emulated as an IDE device.
## Public Attributes
readonly attribute wstring | name
| Name of the storage controller, as originally specified with IMachine::addStorageController.
readonly attribute unsigned long | maxDevicesPerPortCount
| Maximum number of devices which can be attached to one port.
readonly attribute unsigned long | minPortCount
| Minimum number of ports that IStorageController::portCount can be set to.
readonly attribute unsigned long | maxPortCount
| Maximum number of ports that IStorageController::portCount can be set to.
attribute unsigned long | instance
| The instance number of the device in the running VM.
attribute unsigned long | portCount
| The number of currently usable ports on the controller.
readonly attribute StorageBus | bus
| The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy).
attribute StorageControllerType | controllerType
| The exact variant of storage controller hardware presented to the guest.
attribute boolean | useHostIOCache
| If true, the storage controller emulation will use a dedicated I/O thread, enable the host I/O caches and use synchronous file APIs on the host.
readonly attribute boolean | bootable
| Returns whether it is possible to boot from disks attached to this controller.

## Detailed Description

Represents a storage controller that is attached to a virtual machine (IMachine).

Just as drives (hard disks, DVDs, FDs) are attached to storage controllers in a real computer, virtual drives (represented by IMediumAttachment) are attached to virtual storage controllers, represented by this interface.

As opposed to physical hardware, VirtualBox has a very generic concept of a storage controller, and for purposes of the Main API, all virtual storage is attached to virtual machines via instances of this interface. There are five types of such virtual storage controllers: IDE, SCSI, SATA, SAS and Floppy (see bus). Depending on which of these four is used, certain sub-types may be available and can be selected in controllerType.

Depending on these settings, the guest operating system might see significantly different virtual hardware.

Interface ID:
  `{A1556333-09B6-46D9-BFB7-FC239B7FBE1E}`

## Member Function Documentation

void IStorageController::getIDEEmulationPort | ( | in long | devicePosition,
|  | [retval] out long | portNumber |
| ) |  |  |

Gets the corresponding port number which is emulated as an IDE device.

Works only with SATA controllers.

Expected result codes:

  E_INVALIDARG | The devicePosition is not in the range 0 to 3.
  E_NOTIMPL | The storage controller type is not SATAIntelAhci.

void IStorageController::setIDEEmulationPort | ( | in long | devicePosition,
|  | in long | portNumber |
| ) |  |  |

Sets the port number which is emulated as an IDE device.

Works only with SATA controllers.

Expected result codes:

  E_INVALIDARG | The devicePosition is not in the range 0 to 3 or the portNumber is not in the range 0 to 29.
  E_NOTIMPL | The storage controller type is not SATAIntelAhci.

## Member Data Documentation

readonly attribute wstring IStorageController::name

Name of the storage controller, as originally specified with IMachine::addStorageController.

This then uniquely identifies this controller with other method calls such as IMachine::attachDevice and IMachine::mountMedium.

readonly attribute unsigned long IStorageController::maxDevicesPerPortCount

Maximum number of devices which can be attached to one port.

readonly attribute unsigned long IStorageController::minPortCount

Minimum number of ports that IStorageController::portCount can be set to.

readonly attribute unsigned long IStorageController::maxPortCount

Maximum number of ports that IStorageController::portCount can be set to.

attribute unsigned long IStorageController::instance

The instance number of the device in the running VM.

attribute unsigned long IStorageController::portCount

The number of currently usable ports on the controller.

The minimum and maximum number of ports for one controller are stored in IStorageController::minPortCount and IStorageController::maxPortCount.

readonly attribute StorageBus IStorageController::bus

The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy).

attribute StorageControllerType IStorageController::controllerType

The exact variant of storage controller hardware presented to the guest.

Depending on this value, VirtualBox will provide a different virtual storage controller hardware to the guest. For SATA, SAS and floppy controllers, only one variant is available, but for IDE and SCSI, there are several.

For SCSI controllers, the default type is LsiLogic.

attribute boolean IStorageController::useHostIOCache

If true, the storage controller emulation will use a dedicated I/O thread, enable the host I/O caches and use synchronous file APIs on the host.

This was the only option in the API before VirtualBox 3.2 and is still the default for IDE controllers.

If false, the host I/O cache will be disabled for image files attached to this storage controller. Instead, the storage controller emulation will use asynchronous I/O APIs on the host. This makes it possible to turn off the host I/O caches because the emulation can handle unaligned access to the file. This should be used on OS X and Linux hosts if a high I/O load is expected or many virtual machines are running at the same time to prevent I/O cache related hangs. This option new with the API of VirtualBox 3.2 and is now the default for non-IDE storage controllers.

readonly attribute boolean IStorageController::bootable

Returns whether it is possible to boot from disks attached to this controller.