CreateVirtualDisk function

Creates a virtual hard disk (VHD) image file, either using default parameters or using an existing virtual disk or physical disk.

Syntax


DWORD CreateVirtualDisk(
  _In_     PVIRTUAL_STORAGE_TYPE           VirtualStorageType,
  _In_     PCWSTR                          Path,
  _In_     VIRTUAL_DISK_ACCESS_MASK        VirtualDiskAccessMask,
  _In_opt_ PSECURITY_DESCRIPTOR            SecurityDescriptor,
  _In_     CREATE_VIRTUAL_DISK_FLAG        Flags,
  _In_     ULONG                           ProviderSpecificFlags,
  _In_     PCREATE_VIRTUAL_DISK_PARAMETERS Parameters,
  _In_opt_ LPOVERLAPPED                    Overlapped,
  _Out_    PHANDLE                         Handle
);

Parameters

VirtualStorageType [in]

A pointer to a VIRTUAL_STORAGE_TYPE structure that contains the desired disk type and vendor information.

Path [in]

A pointer to a valid string that represents the path to the new virtual disk image file.

VirtualDiskAccessMask [in]

The VIRTUAL_DISK_ACCESS_MASK value to use when opening the newly created virtual disk file. If the Version member of the Parameters parameter is set to CREATE_VIRTUAL_DISK_VERSION_2 then only the VIRTUAL_DISK_ACCESS_NONE (0) value may be specified.

SecurityDescriptor [in, optional]

An optional pointer to a SECURITY_DESCRIPTOR to apply to the virtual disk image file. If this parameter is NULL, the parent directory's security descriptor will be used.

Flags [in]

Creation flags, which must be a valid combination of the CREATE_VIRTUAL_DISK_FLAG enumeration.

ProviderSpecificFlags [in]

Flags specific to the type of virtual disk being created. May be zero if none are required.

Parameters [in]

A pointer to a valid CREATE_VIRTUAL_DISK_PARAMETERS structure that contains creation parameter data.

Overlapped [in, optional]

An optional pointer to a valid OVERLAPPED structure if asynchronous operation is desired.

Handle [out]

A pointer to the handle object that represents the newly created virtual disk.

Return value

If the function succeeds, the return value is ERROR_SUCCESS and the Handle parameter contains a valid pointer to the new virtual disk object.

If the function fails, the return value is an error code and the value of the Handle parameter is undefined. For more information, see System Error Codes.

Remarks

If the CreateVirtualDisk function fails with an error code value of ERROR_INVALID_PARAMETER, the cause may be due to any of the following conditions:

  • The VirtualStorageType parameter is NULL.
  • The Parameters parameter is NULL.
  • The Version member of the Parameters parameter is not set to CREATE_VIRTUAL_DISK_VERSION_1 or CREATE_VIRTUAL_DISK_VERSION_2.
  • The Version member of the Parameters parameter is set to CREATE_VIRTUAL_DISK_VERSION_2 but the VirtualDiskAccessMask parameter is not set to VIRTUAL_DISK_ACCESS_NONE.
  • The BlockSizeInBytes member of the Parameters parameter is not set to CREATE_VIRTUAL_DISK_PARAMETERS_DEFAULT_BLOCK_SIZE (0), 0x80000 (512 KB), or 0x200000 (2 MB).
  • The MaximumSize member of the Parameters parameter is less than 3 MB.
  • The MaximumSize member of the Parameters parameter is not aligned with the value of the SectorSizeInBytes member.
  • The VirtualDiskAccessMask parameter is set to a value of (VirtualDiskAccessMask & ~VIRTUAL_DISK_ACCESS_ALL).
  • The Flags parameter is larger than CREATE_VIRTUAL_DISK_FLAG_FULL_PHYSICAL_ALLOCATION.

The host volume containing the new virtual disk image file cannot be compressed or EFS encrypted.

When creating the various types of virtual disks, the following combinations of creation parameters are recommended:

Fixed
  • The CREATE_VIRTUAL_DISK_FLAG_FULL_PHYSICAL_ALLOCATION flag should be specified.
  • ParentPath should not be specified.
  • SourcePath can be specified if desired.
Expandable
  • The CREATE_VIRTUAL_DISK_FLAG_FULL_PHYSICAL_ALLOCATION flag should not be specified.
  • ParentPath should not be specified.
  • SourcePath can be specified if desired.
Differencing
  • The CREATE_VIRTUAL_DISK_FLAG_FULL_PHYSICAL_ALLOCATION flag should not be specified.
  • ParentPath should be specified.
  • SourcePath should not be specified.

The CreateVirtualDisk function can also be used as a mechanism for converting one type of virtual disk to another, or a physical disk to a virtual disk. This is accomplished through the use of the SourcePath member of the CREATE_VIRTUAL_DISK_PARAMETERS structure to pre-populate the new virtual disk with block data from the source disk.

Requirements

Minimum supported client

Windows 7

Minimum supported server

Windows Server 2008 R2

Header

VirtDisk.h (include Windows.h)

Library

VirtDisk.lib

DLL

VirtDisk.dll

See also

About VHD
OpenVirtualDisk
VHD Reference

 

 

Show: