Share via

3.4.5.2.41.1 IVdsOpenVDisk::Attach (Opnum 3)

  • Article

The Attach method creates an operating system disk device for a virtual disk.

 HRESULT Attach(
   [in, unique] LPWSTR pStringSecurityDescriptor,
   [in] ATTACH_VIRTUAL_DISK_FLAG Flags,
   [in] ULONG ProviderSpecificFlags,
   [in] ULONG TimeoutInMs,
   [out] IVdsAsync** ppAsync
 );

pStringSecurityDescriptor: A NULL-terminated wide-character string containing the security descriptor to be applied to the virtual disk.<140> If this parameter is NULL, the security descriptor in the caller's access token MUST be used.

Flags: A bitmask of ATTACH_VIRTUAL_DISK_FLAG (section 2.2.2.20.1.1) enumeration values specifying virtual disk attaching options.

ProviderSpecificFlags: A bitmask of flags that are specific to the type of virtual disk that is being surfaced. These flags are provider-specific.<141>

TimeoutInMs: The length of time, in milliseconds, before this method MAY<142> return after waiting for the virtual disk to be surfaced completely. If this parameter is zero, the method returns immediately without waiting for the disk to be surfaced. If this parameter is INFINITE, the method does not return until the surfacing operation is complete. If this parameter is set to a value other than zero or INFINITE and the time-out value is reached, the method guarantees that the disk is not surfaced after the operation is complete.

ppAsync: A pointer to an IVdsAsync (section 3.1.3.1) 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.

Return Values: This 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 ppAsync is not NULL.

The server MUST perform the following:

  • Create a new async object implementing the IVdsAsync interface with an output type of VDS_ASYNCOUT_ATTACH_VDISK and set the pointer ppAsync 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.

  • Pass the input parameters to the operating system to attach the virtual disk.

  • Set the return code in the async object to an HRESULT indicating failure or success of the operating system. 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.

At any point in the preceding sequence, before the percentage-completed value in the async object is 100, the server MUST update the percentage-completed value if forward progress is made during the compact operation.