OpenVirtualDisk function

Opens a virtual hard disk (VHD) or CD or DVD image file (ISO) for use.


DWORD OpenVirtualDisk(
  _In_     PVIRTUAL_STORAGE_TYPE         VirtualStorageType,
  _In_     PCWSTR                        Path,
  _In_     VIRTUAL_DISK_ACCESS_MASK      VirtualDiskAccessMask,
  _In_     OPEN_VIRTUAL_DISK_FLAG        Flags,
  _Out_    PHANDLE                       Handle


VirtualStorageType [in]

A pointer to a valid VIRTUAL_STORAGE_TYPE structure.

Path [in]

A pointer to a valid path to the virtual disk image to open.

VirtualDiskAccessMask [in]

A valid value of the VIRTUAL_DISK_ACCESS_MASK enumeration.

Flags [in]

A valid combination of values of the OPEN_VIRTUAL_DISK_FLAG enumeration.

Parameters [in, optional]

An optional pointer to a valid OPEN_VIRTUAL_DISK_PARAMETERS structure. Can be NULL.

Handle [out]

A pointer to the handle object that represents the open virtual disk.

Return value

If the function succeeds, the return value is ERROR_SUCCESS (0) 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.


To prevent an open request failure when attempting to open a handle to a permanently attached virtual disk, the following requirements apply:

  • The VirtualDiskAccessMask parameter must include the VIRTUAL_DISK_ACCESS_DETACH (0x00040000) flag.
  • Write access to the file must not be requested if the original open operation that created the permanently attached virtual disk only requested read access.

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

  • The VirtualStorageType parameter is NULL.
  • The Path parameter is NULL.
  • The VirtualDiskAccessMask parameter is set to a value of (VirtualDiskAccessMask & ~VIRTUAL_DISK_ACCESS_ALL).
  • The Flags parameter is set to a value of (Flags & ~(OPEN_VIRTUAL_DISK_FLAG_NO_PARENTS | OPEN_VIRTUAL_DISK_FLAG_BLANK_FILE)).
  • The Version member of the Parameters parameter is not set to OPEN_VIRTUAL_DISK_VERSION_1.

The host volume that contains the virtual disk image file cannot be compressed or EFS encrypted. This function will fail with error ERROR_UNSUPPORTED_COMPRESSION (618) if the host volume has been compressed or with error ERROR_FILE_ENCRYPTED (6002) if the host volume has been EFS encrypted after the initial virtual disk creation.

The path pointed to by the Path parameter cannot be on a local network share (that is a network share via loopback). This function will fail with error ERROR_FILE_SYSTEM_LIMITATION (665) if the path is on a local network share. This function will fail with error ERROR_FILE_CORRUPT (1392) if an ISO virtual disk is being opened and the file size is not an even multiple of 2 KB (2,048 bytes), is at least 34 KB (34,816 bytes), or the volume structure descriptor does not contain a known CDFS or UDFS volume identifier.

When an application is finished using the object handle returned in the Handle parameter, use the CloseHandle function to close the handle.

CD and DVD image files (ISO) are not supported before Windows 8 and Windows Server 2012.


Minimum supported client

Windows 7

Minimum supported server

Windows Server 2008 R2


VirtDisk.h (include Windows.h)





See also

About VHD
VHD Reference