3.4.5.2.17.2 IVdsVdProvider::CreateVDisk (Opnum 4)

  • Article

The CreateVDisk method defines a new virtual disk. This method creates a virtual disk file to be used as the backing store for the virtual disk.

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

VirtualDeviceType: Pointer to a VIRTUAL_STORAGE_TYPE (section 2.2.1.3.23) structure that specifies the type of virtual hard disk to be created.

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

pStringSecurityDescriptor: A NULL-terminated wide-character string containing the security descriptor to be applied to the virtual disk. Security descriptors MUST be in the Security Descriptor Definition Language (see [MSDN-SDDLforDevObj]).<77> If this parameter is NULL, the security descriptor in the caller's access token (see [MSFT-WSM/WEDWNK]) MUST be used.

Flags: Bitmask of flags specifying how the virtual disk is to be created.

ProviderSpecificFlags: A bitmask of flags that are specific to the type of virtual hard disk that is being surfaced. These flags are provider-specific.<78>

Reserved: The parameter is reserved for future use and MAY be zero.<79>

pCreateDiskParameters: Pointer to a VDS_CREATE_VDISK_PARAMETERS (section 2.2.2.18.2.1) structure that contains the virtual hard disk creation parameters.

ppAsync: A pointer to an IVdsAsync (section 3.1.3.1) interface that, if the operation is successfully completed, receives the IVdsAsync interface to monitor and control this operation. Callers MUST release the interface when they are done with it.

Return Values: The method MUST return zero to indicate success, or return an implementation-specific nonzero error code to indicate failure. For the HRESULT values predefined by the Virtual Disk Service Remote Protocol, see section 2.2.3.

When the server receives this message, it MUST validate the following parameters:

  • Verify that VirtualDeviceType is not NULL.

  • Verify that pPath is not NULL.

  • Verify that pStringSecurityDescriptor is not NULL.

  • Verify that if there are multiple flags, the Flags correspond to a bitwise OR of one or more flags specified in the CREATE_VIRTUAL_DISK_FLAG (section 2.2.2.18.1.1) enumeration; otherwise it is just the one flag.

  • Verify that ppAsync is not NULL.

The server MUST perform the following:

  • Create a new async object implementing the IVdsAsync interface with an output type of VDS_ASYNCOUT_CREATE_VDISK and set the pointer ppAsync references to the interface.

  • Return an HRESULT indicating failure or success. Any errors encountered up through this point in processing the operation are returned in this HRESULT.

The server MUST then perform the following in sequence. Errors generated in this sequence of steps are returned in the pHrResult parameter to the IVdsAsync::Wait or IVdsAsyncQueryStatus methods.

  • Pass the method parameters to the operating system to create the virtual disk.

  • Set the return code in the async object to an HRESULT indicating failure or success.

  • If the task completed successfully, set the percentage completed value in the async object to 100.

  • Set the signal state in the async object to TRUE.

At any point in the preceding sequence--before the percentage completed value in the async object is 100--the server MUST update the percentage completed value if progress has been made.