4.5 Creating a Volume
The following diagram shows how the IVolumeClient interfaces are used to create a volume on a disk.
Figure 5: Steps to create a volume on a disk by using the IVolumeClient interfaces
The client calls IVolumeClient::Initialize and passes its implementation of the IDMNotify interface to the server.
The client calls IVolumeClient::EnumDisks to get the list of disks from the server.
For each disk, a DISK_INFO structure is returned. The server allocates the memory and returns the array of DISK_INFO structures and HRESULT to the client.
The client verifies that the call was successful by looking at the returned HRESULT. If the call was successful, the client finds the disks to be used to create the volume (for example, by looking at the disk name field in the DISK_INFO structure). The client then calls IVolumeClient::EnumDiskRegions to get an array that represents the regions on the disk. The input parameter to EnumDiskRegions is the disk's LdmObjectId, which is the first member of the DISK_INFO structure.
The server allocates an array of REGION_INFO structures and returns the array to the client.
The client verifies that the call was successful by looking at the returned HRESULT. If the call was successful, the client parses the array to find a region with REGIONTYPE REGION_FREE. The client looks at the size of the region to see what size volume can be created in this region. If this free region is not large enough for the expected volume size, the client can continue to look for larger free regions on that disk. The client can repeat the calls to IVolumeClient::EnumDiskRegions on all the disks until it finds the set of disks with free space required to create the volume of expected size. Once the client finds the region to be used to create the new volume, the client calls IVolumeClient::CreateVolume. The input parameter to the call is an array of DISK_SPEC structures and VOLUME_SPEC structures. The client fills in the disk id and lastKnownState members of the DISK_SPEC structure by using the values from the DISK_INFO structure. The client fills in the length field based on the size of the volume to be created on the particular disk. The length cannot be greater than the reported free region length from the REGION_INFO structure. The client also fills in the needContiguous field based on the type of the volume. The client fills in the VOLUME_SPEC structure based on the volume type and size of the volume to be created.
The server creates the volume and fills in the TASK_INFO structure. The call to IVolumeClient::CreateVolume returns this TASK_INFO structure.
The client verifies that the volume was successfully created by looking at the HRESULT returned from the call. The returned TASK_INFO structure will contain the new volume's id in the storageId field. The status field in the TASK_INFO structure will be REQ_COMPLETED.
The server calls back the client with a disk modified notification on the IDMNotify interface's ObjectsChanged method.
The client code processes the disk modified notification. For example, the client might query for the current disk information and all disk regions when it gets a disk modified notification, so that it can update its cache or display.
The server calls back the client with a volume created notification on the IDMNotify interface's ObjectsChanged method.
The client code processes the volume created notification. For example, the client might query for all volumes when it gets a volume created notification, so that it can update its cache or display.