Windows Dev Center

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

 

 

Build date: 10/26/2012

Community Additions

ADD
Show:
© 2015 Microsoft