AttachVirtualDisk function

Attaches a virtual hard disk (VHD) or CD or DVD image file (ISO) by locating an appropriate VHD provider to accomplish the attachment.

Syntax


DWORD AttachVirtualDisk(
  _In_      HANDLE VirtualDiskHandle,
  _In_opt_  PSECURITY_DESCRIPTOR SecurityDescriptor,
  _In_      ATTACH_VIRTUAL_DISK_FLAG Flags,
  _In_      ULONG ProviderSpecificFlags,
  _In_opt_  PATTACH_VIRTUAL_DISK_PARAMETERS Parameters,
  _In_opt_  LPOVERLAPPED Overlapped
);

Parameters

VirtualDiskHandle [in]

A handle to an open virtual disk. For information on how to open a virtual disk, see the OpenVirtualDisk function.

SecurityDescriptor [in, optional]

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

Flags [in]

A valid combination of values of the ATTACH_VIRTUAL_DISK_FLAG enumeration.

ProviderSpecificFlags [in]

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

Parameters [in, optional]

A pointer to a valid ATTACH_VIRTUAL_DISK_PARAMETERS structure that contains attachment parameter data.

Overlapped [in, optional]

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

Return value

Status of the request.

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error code. For more information, see System Error Codes.

Remarks

The AttachVirtualDisk function is not supported for VHDs or ISOs hosted on Secure Digital (SD) media plugged into an SD controller in native mode (for which sffdisk.sys, sffp_sd.sys, and sdbus.sys drivers would be loaded) and will fail with the error ERROR_FILE_NOT_FOUND. VHDs and ISOs hosted on SD media connected to a USB reader are supported.

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

  • The VirtualDiskHandle parameter is not a valid handle created by the OpenVirtualDisk function.
  • The Flags parameter is set to a value larger than 0x020.
  • The Version member of the Parameters parameter is not set to ATTACH_VIRTUAL_DISK_VERSION_1.

The host volume that contains the virtual disk image file cannot be compressed or EFS encrypted.

This function will fail if a provider cannot be found, if the VHD or ISO image file is not valid, if the VHD image is already attached, or if the caller does not have SE_MANAGE_VOLUME_PRIVILEGE access rights. For more information about file security, see File Security and Access Rights.

The intended access mode of the virtual disk must be considered when opening the virtual disk handle. For example, if the virtual disk is being attached for read/write access, the VirtualDiskHandle parameter must have been opened using the VIRTUAL_DISK_ACCESS_ATTACH_RW access flag. For more information, see VIRTUAL_DISK_ACCESS_MASK and OpenVirtualDisk.

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

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
VHD Reference

 

 

Build date: 10/26/2012

Community Additions

ADD
Show:
© 2015 Microsoft