IVHDImage Interface Reference

The IVHDImage interface represents virtual hard disks that use Virtual PC Virtual Machine Disk image files to store hard disk data. 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 filePath
 Full file name of the VHD image of this hard disk.
readonly attribute boolean created
 Whether the virual disk image is created or not.


Detailed Description

The IVHDImage interface represents virtual hard disks that use Virtual PC Virtual Machine Disk image files to store hard disk data.

Hard disks using VHD images can be either opened using IVirtualBox::openHardDisk() or created from scratch using IVirtualBox::createHardDisk().

Objects that support this interface also support the IHardDisk interface.

When a new hard disk object is created from scatch, an image file for it is not automatically created. To do it, you need to specify a valid file path, 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 VHD 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.

Note:
In the current imlementation, the type of all VHD hard disks is Writethrough and cannot be changed.
Interface ID:
{163B88C3-7552-424A-8205-DAF17A004747}

Member Function Documentation

void IVHDImage::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 IVHDImage::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 IVHDImage::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 IVHDImage::filePath

Full file name of the VHD image of this hard disk.

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

When assigning a new path, it can 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. In this case, the specified file name can 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.

readonly attribute boolean IVHDImage::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