ICustomHardDisk Interface Reference

The ICustomHardDisk interface represents a specific type of IHardDisk that is supported through a third-party plugin. More...

List of all members.

Public Member Functions

void createDynamicImage (in unsigned long long size,[retval] out IProgress progress)
 Starts creating a dymically expanding hard disk image in the background.
void createFixedImage (in unsigned long long size,[retval] out IProgress progress)
 Starts creating a fixed-size hard disk image in the background.
void deleteImage ()
 Deletes the existing hard disk image.

Public Attributes

attribute wstring location
 Location of this custom hard disk.
readonly attribute wstring format
 The plugin name of the image file.
readonly attribute boolean created
 Whether the virual disk image is created or not.


Detailed Description

The ICustomHardDisk interface represents a specific type of IHardDisk that is supported through a third-party plugin.

This interface allows to add support for custom hard disk formats to VirtualBox.

Objects that support this interface also support the IHardDisk interface.

Hard disks using custom hard disk formats can be either opened using IVirtualBox::openHardDisk() or created from scratch using IVirtualBox::createHardDisk().

When a new hard disk object is created from scratch, an image file for it is not automatically created. To do it, you need to specify a valid location, and call createFixedImage() or createDynamicImage(). When it is done, the hard disk object can be registered by calling IVirtualBox::registerHardDisk() and then attached to virtual machines.

The description of the hard disk is stored in the VirtualBox configuration file, so it can be changed (at appropriate times) even when accessible returns false. However, the hard disk must not be attached to a running virtual machine.

Interface ID:
{A7B0236D-3FF4-47C0-A4AA-DDC4DDC1141A}

Member Function Documentation

void ICustomHardDisk::createDynamicImage ( in unsigned long long  size,
[retval] out IProgress  progress 
)

Starts creating a dymically expanding hard disk image in the background.

The previous image associated with this object, if any, must be deleted using deleteImage, otherwise the operation will fail.

Parameters:
size Maximum logical size of the hard disk in megabytes.
progress Progress object to track the operation completion.
Note:
After the returned progress object reports that the operation is complete, this hard disk object can be registered within this VirtualBox installation.

void ICustomHardDisk::createFixedImage ( in unsigned long long  size,
[retval] out IProgress  progress 
)

Starts creating a fixed-size hard disk image in the background.

The previous image, if any, must be deleted using deleteImage, otherwise the operation will fail.

Parameters:
size Logical size of the hard disk in megabytes.
progress Progress object to track the operation completion.
Note:
After the returned progress object reports that the operation is complete, this hard disk object can be registered within this VirtualBox installation.

void ICustomHardDisk::deleteImage (  ) 

Deletes the existing hard disk image.

The hard disk must not be registered within this VirtualBox installation, otherwise the operation will fail.

Note:
After this operation succeeds, it will be impossible to register the hard disk until the image file is created again.

This operation is valid only for non-differencing hard disks, after they are unregistered using IVirtualBox::unregisterHardDisk().


Member Data Documentation

attribute wstring ICustomHardDisk::location

Location of this custom hard disk.

For newly created hard disk objects, this value is null.

The format of the location string is plugin-dependent. In case if the plugin uses a regular file in the local file system to store hard disk data, then the location is a file path and the following rules apply:

  • when assigning a new path, it must be absolute (full path) or relative to the VirtualBox home directory. If only a file name without any path is given, the default VDI folder will be used as a path to the image file.
  • When reading this propery, a full path is always returned.
Note:
This property cannot be changed when created returns true.

readonly attribute wstring ICustomHardDisk::format

The plugin name of the image file.

readonly attribute boolean ICustomHardDisk::created

Whether the virual disk image is created or not.

For newly created hard disk objects or after a successful invocation of deleteImage(), this value is false until createFixedImage() or createDynamicImage() is called.


Generated on Fri Nov 21 21:38:41 2008 for VirtualBox Main API by  doxygen 1.5.5