CreateVirtualDisk function (virtdisk.h)

Article
08/23/2022

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, optional] PSECURITY_DESCRIPTOR            SecurityDescriptor,
  [in]           CREATE_VIRTUAL_DISK_FLAG        Flags,
  [in]           ULONG                           ProviderSpecificFlags,
  [in]           PCREATE_VIRTUAL_DISK_PARAMETERS Parameters,
  [in, optional] LPOVERLAPPED                    Overlapped,
  [out]          PHANDLE                         Handle
);

Parameters

[in] VirtualStorageType

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

[in] Path

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

[in] VirtualDiskAccessMask

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.

[in, optional] SecurityDescriptor

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.

[in] Flags

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

[in] ProviderSpecificFlags

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

[in] Parameters

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

[in, optional] Overlapped

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

[out] Handle

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:

The CREATE_VIRTUAL_DISK_FLAG_FULL_PHYSICAL_ALLOCATION flag should be specified.
ParentPath should not be specified.
SourcePath can be specified if desired.

The CREATE_VIRTUAL_DISK_FLAG_FULL_PHYSICAL_ALLOCATION flag should not be specified.
ParentPath should not be specified.
SourcePath can be specified if desired.

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

Requirement	Value
Minimum supported client	Windows 7
Minimum supported server	Windows Server 2008 R2
Target Platform	Windows
Header	virtdisk.h
Library	VirtDisk.lib
DLL	VirtDisk.dll