Share via

3.4.5.2.40.1 IVdsVDisk::Open (Opnum 3)

  • Article

The Open method opens a handle to the specified virtual disk file and returns an IVdsOpenVDisk (section 3.1.15.2) interface pointer to an object representing the open virtual disk (an OpenVirtualDisk object). Release the IVdsOpenVDisk interface to close the handle to the virtual disk.

 HRESULT Open(
   [in] VIRTUAL_DISK_ACCESS_MASK AccessMask,
   [in] OPEN_VIRTUAL_DISK_FLAG Flags,
   [in] ULONG ReadWriteDepth,
   [out] IVdsOpenVDisk** ppOpenVDisk
 );

AccessMask: A VIRTUAL_DISK_ACCESS_MASK (section 2.2.2.19.1.4) structure that contains the set of access rights to be applied to the opened virtual disk.

Flags: A bitmask of OPEN_VIRTUAL_DISK_FLAG (section 2.2.2.19.1.2) flags specifying how the virtual disk is to be opened.

ReadWriteDepth: This is applicable only to differencing type virtual disks. The number of backing stores (files) to open read/write. This count includes the child. The remaining stores in the differencing chain MUST be opened as read-only. For example, given a differencing disk with two parents (diskA is the differencing disk whose parent is diskB, and since diskB is a differencing disk, it has a parent which is diskC), entering '2' for this parameter will open the differencing disk (diskA) and the parent used to create this differencing disk (diskB) as read-write. In this case, diskB is also a differencing disk and its parent (diskC) is opened as read-only.

ppOpenVDisk: A pointer to a variable that, if the operation is successfully completed, receives an IVdsOpenVDisk interface pointer to the newly opened virtual disk object. Callers MUST release the interface pointer when it is no longer needed by calling the IUnknown::Release method.

Return Values: The method MUST return zero to indicate success, or return an implementation-specific nonzero error code to indicate failure.

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

  • Verify that ppOpenVDisk is not NULL.

The server MUST then perform the following in sequence:

  • Pass the input parameters to the operating system to open the virtual disk file.

  • If the operating system failed to open the file, return an implementation-specific error code. Otherwise, if the file was successfully opened, the server MUST:

    • Mark the state of the object that implements IVdsVDisk as "open". For details, see section 2.2.2.19.1.1.

    • Create an object that implements the IVdsOpenVDisk interface to represent the virtual disk file in the open state.

    • Point ppOpenVDisk to an IVdsOpenVDisk interface of the virtual disk object created and return an HRESULT indicating success.