Share via

3.4.5.2.24.3 IVdsAdvancedDisk::CreatePartition (Opnum 5)

  • Article

 The CreatePartition method creates a partition on a disk at a specified byte offset.

 HRESULT CreatePartition(
   [in] ULONGLONG ullOffset,
   [in] ULONGLONG ullSize,
   [in] CREATE_PARTITION_PARAMETERS* para,
   [out] IVdsAsync** ppAsync
 );

ullOffset: MUST be the byte offset from the beginning of the disk at which to create the new partition.

The partition is created at or beyond the ullOffset such that the offset is divisible by the default alignment value of the disk. The offset value returned in the server's partition notification, after CreatePartition is successful, reflects the rounded-up value.

ullSize: MUST be the size of the new partition, in bytes.

para: MUST be a pointer to a CREATE_PARTITION_PARAMETERS structure that describes the new partition to create.

ppAsync: MUST be 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, the interfaces returned in the VDS_ASYNC_OUTPUT structure MUST be released as well.

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

Note Creating or deleting partitions on dynamic disks is not supported.

Note This method is not valid on CD/DVD or super floppy devices. These devices do not support partition tables.

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

  • Verify that para is not NULL.

  • Verify that ppAsync is not NULL.

The server MUST perform the following:

  • If the partition cannot be created because there is not enough free space on the specified disk, 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_CREATEPARTITION and set the pointer that 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.

  • Create a new partition following the parameters specified to the method.

    • If the partition 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.

  • Set the task-specific return values in the async object to return the values associated with VDS_ASYNCOUT_CREATEPARTITION. For details on asynchronous tasks, 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 was required 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 was 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 that is registered in the list of callback objects, call the callback object's IVdsAdviseSink::OnNotify (Opnum 3) method by using a VDS_NOTIFICATION structure that has the following attributes:

    • objectType member is VDS_NTT_PARTITION.

    • Partition member is a VDS_PARTITION_NOTIFICATION that has the following attributes:

      • ulEvent is VDS_NF_PARTITION_ARRIVE.

      • diskId is the VDS_OBJECT_ID of the disk object that corresponds to the disk on which the partition was added.

      • ullOffset is the byte offset at which the partition starts on the disk.

  • If the partition is created on a removable media disk, for each callback object that is registered in the list of callback objects, call the callback object's IVdsAdviseSink::OnNotify (Opnum 3) method by using a VDS_NOTIFICATION structure that has the following attributes:

    • objectType member is VDS_NTT_VOLUME.

    • Volume member is a VDS_VOLUME_NOTIFICATION that has the following attributes:

      • ulEvent is VDS_NF_VOLUME_ARRIVE.

      • volumeId is the VDS_OBJECT_ID of the volume object corresponding to the removable media drive.

      • plexId is NULL GUID, 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.

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

    • objectType member is VDS_NTT_DISK.

    • Disk member is a VDS_DISK_NOTIFICATION that has the following attributes:

      • ulEvent is VDS_NF_DISK_MODIFY.

      • diskId is the VDS_OBJECT_ID of this disk object.

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.