IVdsVdProvider::CreateVDisk method (vds.h)

Article
02/09/2023

[Beginning with Windows 8 and Windows Server 2012, the Virtual Disk Service COM interface is superseded by the Windows Storage Management API.]

Creates a virtual disk.

Syntax

HRESULT CreateVDisk(
  [in]  PVIRTUAL_STORAGE_TYPE        VirtualDeviceType,
  [in]  LPWSTR                       pPath,
  [in]  LPWSTR                       pStringSecurityDescriptor,
  [in]  CREATE_VIRTUAL_DISK_FLAG     Flags,
  [in]  ULONG                        ProviderSpecificFlags,
  [in]  ULONG                        Reserved,
  [in]  PVDS_CREATE_VDISK_PARAMETERS pCreateDiskParameters,
  [out] IVdsAsync                    **ppAsync
);

Parameters

[in] VirtualDeviceType

A pointer to a VIRTUAL_STORAGE_TYPE structure that specifies the type of virtual disk to be created.

[in] pPath

A NULL-terminated wide-character string containing the name and directory path for the backing file to be created for the virtual disk.

[in] pStringSecurityDescriptor

A NULL-terminated wide-character string containing the security descriptor to be applied to the virtual disk. If this parameter is NULL, the security descriptor in the caller's access token will be used.

[in] Flags

A bitmask of CREATE_VIRTUAL_DISK_FLAG enumeration values specifying how the virtual disk is to be created.

Value	Meaning
CREATE_VIRTUAL_DISK_FLAG_NONE 0x00000000	No flags are specified.
CREATE_VIRTUAL_DISK_FLAG_FULL_PHYSICAL_ALLOCATION 0x00000001	Pre-allocate all physical space necessary for the virtual size of the virtual disk. This flag is valid only for a fixed-size virtual disk.

[in] ProviderSpecificFlags

A bitmask of flags that are specific to the type of virtual disk that is being created. These flags are provider-specific. For the Microsoft virtual disk provider, this parameter must be zero.

[in] Reserved

The parameter is reserved and must be zero.

[in] pCreateDiskParameters

A pointer to a VDS_CREATE_VDISK_PARAMETERS structure that contains the virtual disk creation parameters.

[out] ppAsync

A pointer to an IVdsAsync interface that upon successful completion receives the IVdsAsync interface to monitor and control this operation. Callers must release the interface received when they are done with it. If the IVdsAsync::Wait method is called on the interface and a success HRESULT value is returned, the interfaces returned in the VDS_ASYNC_OUTPUT structure must be released by calling the IUnknown::Release method on each interface pointer. However, if Wait returns a failure HRESULT value, or if the pHrResult parameter of Wait receives a failure HRESULT value, the interface pointers in the VDS_ASYNC_OUTPUT structure are NULL and do not need to be released. You can test for success or failure HRESULT values by using the SUCCEEDED and FAILED macros defined in Winerror.h.

Return value

This method can return standard HRESULT values, such as E_INVALIDARG or E_OUTOFMEMORY, and VDS-specific return values. It can also return converted system error codes using the HRESULT_FROM_WIN32 macro. Errors can originate from VDS itself or from the underlying VDS provider that is being used. Possible return values include the following.

Return code	Description
S_OK	The method completed successfully.

Remarks

Applications must initialize process-wide security by calling the CoInitializeSecurity function. The dwImpLevel parameter should be set to RPC_C_IMP_LEVEL_IMPERSONATE.

Windows Server 2008, Windows Vista and Windows Server 2003: These actions are not required until Windows 7 and Windows Server 2008 R2.

If the virtual disk with the specified file name does not exist, it is created. If the virtual disk already exists, the virtual disk provider returns an interface pointer to the existing virtual disk object without re-creating the file.

Requirements

Requirement	Value
Minimum supported client	Windows 7 [desktop apps only]
Minimum supported server	Windows Server 2008 R2 [desktop apps only]
Target Platform	Windows
Header	vds.h
Library	Uuid.lib