Share via

3.4.5.2.19.5 IVdsPack::CreateVolume (Opnum 7)

  • Article

The CreateVolume method creates a volume in a disk pack.

 HRESULT CreateVolume(
   [in] VDS_VOLUME_TYPE type,
   [in, size_is(lNumberOfDisks)] VDS_INPUT_DISK* pInputDiskArray,
   [in] long lNumberOfDisks,
   [in] unsigned long ulStripeSize,
   [out] IVdsAsync** ppAsync
 );

type: A value from the VDS_VOLUME_TYPE enumeration that indicates the type of volume to create.

pInputDiskArray: An array of VDS_INPUT_DISK structures that indicate the disks on which to create the volume.<80>

lNumberOfDisks: The number of elements in pInputDiskArray.

ulStripeSize: The stripe size of the new volume.<81>

ppAsync: A pointer to an IVdsAsync 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. If the IVdsAsync::Wait (Opnum 4) method is called on the interface, the interfaces returned in the VDS_ASYNC_OUTPUT structure MUST be released as well. For information on handling asynchronous tasks, see section 3.4.5.1.9.

Return Values: The method MUST return zero or a non-error HRESULT (as specified in [MS-ERREF]) 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 pInputDiskArray is not NULL.

  • Verify that the specified disk(s) belong to the given pack.

  • Verify that ppAsync is not NULL.

The server MUST perform the following:

  • Verify that the volume size that is specified using the array of VDS_INPUT_DISK structures is greater than zero. The requested size of the volume is equal to the sum of the ullSize members of each element in the array of VDS_INPUT_DISK structures.  If the volume size is not greater than zero, then the server MUST return VDS_E_EXTENT_SIZE_LESS_THAN_MIN.

  • For each VDS_INPUT_DISK structure in the pInputDiskArray parameter, verify that the value of the ullSize field does not exceed the amount of free space on the given disk. If the volume is being created within a dynamic disk pack and if this requirement is not met, then the server MUST return VDS_E_EXTENT_EXCEEDS_DISK_FREE_SPACE. If the volume is being created in a basic disk pack and if this requirement is not being met, then the server MUST return VDS_E_NOT_ENOUGH_SPACE.

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

  • Return an HRESULT indicating failure or success. Any errors encountered up until this point in processing the CreateVolume 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.

  • Create a new volume that uses the parameters that are specified for this method.

    • If the volume creation resulted in the renumbering of existing partitions on a boot disk, the server MUST update the boot configuration file with the new partition numbering.

  • Create a new volume object that corresponds to the new volume, implement the IVdsVolume interface, and assign it a unique VDS_OBJECT_ID.

  • Set the volume object's pack pointer to this pack object.

  • Create new volume plex objects that correspond to the new volume plexes, implement the IVdsVolumePlex interface, and assign it a unique VDS_OBJECT_ID.

  • Set the volume plex object's volume pointer to this volume object.

  • Add the volume plex object to the list of storage management objects.

  • Add the volume object to the list of storage management objects.

  • Set the task-specific return values in the async object to return the values that are associated with VDS_ASYNCOUT_CREATEVOLUME. See section 3.4.5.1.9.

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

    • If the server tried to update the boot configuration file but failed, the return code MUST be set to VDS_S_UPDATE_BOOTFILE_FAILED (HRESULT of 0x80042434).

  • 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.

  • For each callback object registered in the list of callback objects, call the callback object's IVdsAdviseSink::OnNotify (Opnum 3) method with a VDS_NOTIFICATION structure with the following attributes:

    • objectType member is VDS_NTT_VOLUME.

    • Volume member is a VDS_VOLUME_NOTIFICATION with the following attributes:

      • ulEvent is VDS_NF_VOLUME_ARRIVE.

      • volumeId is the VDS_OBJECT_ID of the volume object that was added.

      • plexId SHOULD be GUID_NULL, but it is not relevant when ulEvent is VDS_NF_VOLUME_ARRIVE.

      • ulPercentCompleted ranges from 0-100; however, it is not relevant when ulEvent is VDS_NF_VOLUME_ARRIVE.

The server MUST update the percentage completed value periodically during the preceding sequence. How often the percentage completed is updated, and at what point in the sequence, is implementation-specific.