IVdsPack::CreateVolume method (vds.h)
[Beginning with Windows 8 and Windows Server 2012, the Virtual Disk Service COM interface is superseded by the Windows Storage Management API.]
Creates a volume within the pack. The interface pointer for the new volume object can be retrieved by calling IVdsAsync::Wait through the ppAsync parameter. The VDS_ASYNC_OUTPUT structure returned contains the volume object interface pointer in the cv.pVolumeUnk member.
Syntax
HRESULT CreateVolume(
[in] VDS_VOLUME_TYPE type,
[in] VDS_INPUT_DISK *pInputDiskArray,
[in] LONG lNumberOfDisks,
[in] ULONG ulStripeSize,
[out] IVdsAsync **ppAsync
);
Parameters
[in] type
A volume type enumerated by VDS_VOLUME_TYPE. Volumes on basic disks can have only one extent, and only the VDS_VT_SIMPLE flag is valid.
[in] pInputDiskArray
Pointer to an array of VDS_INPUT_DISK structures; one structure for each disk. A disk can be included in the array only once. All disks in the array must be used, or the method fails. Callers must allocate and initialize the array, and free the memory when the call returns.
[in] lNumberOfDisks
The total number of disks contributing to the volume.
[in] ulStripeSize
If the volume is striped, the size of each stripe in bytes. Pass in zero bytes for VDS_VT_SIMPLE, VDS_VT_SPAN, and VDS_VT_MIRROR; 64 kilobytes for VDS_VT_STRIPE and VDS_VT_PARITY.
[out] ppAsync
The address of an IVdsAsync interface pointer, which VDS initializes on return. Callers must release the interface. Use this pointer to cancel, wait for, or query the status of the operation.
If you call IVdsAsync::Wait on this method and a success HRESULT value is returned, you must release the interfaces returned in the VDS_ASYNC_OUTPUT structure 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/value | Description |
|---|---|
|
The volume was created successfully. |
|
No volume arrival notification was received. You may need to call IVdsService::Refresh. |
|
The volume is created successfully, but VDS failed to update the boot options in the Boot Configuration Data (BCD) store.
Windows Server 2003: Boot options are stored in the boot.ini file on an x86 or x64 system or NVRAM on an Itanium system. |
|
The specified disks do not belong to the same pack. |
|
LDM service failed a method. |
|
Extent size passed in is too small. |
|
The number of disks specified is not valid for this operation. |
|
The member count for the volume must be greater than zero. |
|
The member indexes must be monotonically increasing and begin with zero. |
|
The disk passed in is a CD-ROM or DVD device. |
|
This operation is not allowed on this disk pack. |
|
The plex count for the volume must be greater than zero. |
|
The plex indexes must be monotonically increasing and begin with zero. |
|
The stripe size in bytes must be a power of 2 for striped and RAID-5 volume types and must be zero for all other volume types. |
|
The specified disk is missing. |
|
There is no media in a removable drive passed in through the disk array. |
|
There is not enough space on one of the disks. |
|
The volume type is not supported, or a volume already exists on the removable disk passed into the method. A removable disk can have only one volume. |
|
At least one of the disks passed in is not found. |
|
A single disk cannot contribute to multiple members or multiple plexes of the same volume. |
|
The target pack is inaccessible. |
|
The maximum number of partitions (primary partitions or primary partitions with an extended partition) already exists when the caller tries to create an additional primary partition or extended partition. |
|
The dynamic provider cache is corrupt. |
|
No more than 32 disks are allowed per volume. |
|
The volume size is too small. |
Remarks
Basic disks can contain only simple volumes. Dynamic disks can contain volumes of all types as long as the operating system supports the binding operation; non-server platforms do not support fault-tolerant binding operations. All newly created volumes lack a drive letter.
On a basic disk, this method creates a primary partition. If there are already three primary partitions on the disk, it creates an extended partition to cover the largest contiguous free disk space extent left on the disk, and then creates a logical drive within the extended partition.
A disk cannot contribute to more than one plex of the same volume; however, a single disk can contribute to multiple volumes. A simple volume has only one VDS_INPUT_DISK structure, whereas, spanned, striped, mirrored, and RAID-5 volumes have one structure for each contributing disk.
The size of the disk specified in the VDS_INPUT_DISK structure can be the full disk or a portion of the disk. When two disks form a mirrored volume, VDS uses the smallest disk to calculate the size of the mirror. (Provider policy determines the actual offset, length, and number of disk extents allocated on a given input disk.) Use the IVdsPack::QueryVolumes method to determine the exact size of the created volume.
To create a logical volume with an optional alignment parameter, use the IVdsPack2::CreateVolume2 method or use the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\vds\Alignment registry key to specify the alignment value in bytes.
Windows 7, Windows Server 2008 R2, Windows Vista and Windows Server 2008: On a basic disk, the CreateVolume method ignores the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\vds\Alignment registry key. This is a known issue and is being addressed. As a workaround, use the IVdsAdvancedDisk::CreatePartition or IVdsCreatePartitionEx::CreatePartitionEx method to create partitions on the basic disk so that they are aligned correctly.
Dynamic partitions and volumes are aligned using the values under the following registry key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\vds\Alignment
The default alignment is 1 MB if the disk is 4 GB or larger, or 64 KB if the disk is smaller than 4 GB.
Implementers must return a pointer to the IVdsAsync interface for this method, regardless of whether the call initiates an asynchronous operation.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | vds.h |
| Library | Uuid.lib |