ホーム › Storage.VirtualDiskService › IVdsOpenVDisk

IVdsOpenVDisk

COM

IID75c8f324-f715-4fe3-a28e-f9011b61a4a1継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

仮想ディスクを管理するためのメソッドを定義します。(IVdsOpenVDisk)

メソッド 6

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT Attach(LPWSTR pStringSecurityDescriptor, ATTACH_VIRTUAL_DISK_FLAG Flags, DWORD ProviderSpecificFlags, DWORD TimeoutInMs, IVdsAsync** ppAsync)

仮想ディスクをアタッチします。

pStringSecurityDescriptor

LPWSTR

仮想ディスクのセキュリティ記述子を含む文字列。指定しない場合、使用されるセキュリティ記述子は、Windows 7 では "D:P(A;;GA;;;WD)"、Windows 8.1 以降では "D:P(A;;GA;;;WD)(A;;GA;;;AC)" です。

Flags

ATTACH_VIRTUAL_DISK_FLAG

仮想ディスクをどのようにアタッチするかを指定する ATTACH_VIRTUAL_DISK_FLAG 列挙値のビットマスク。指定可能な値には次のものがあります。

値	意味
ATTACH_VIRTUAL_DISK_FLAG_NONE 0x00000000	フラグを指定しません。
ATTACH_VIRTUAL_DISK_FLAG_READ_ONLY 0x00000001	仮想ディスクを読み取り専用としてアタッチします。
ATTACH_VIRTUAL_DISK_FLAG_NO_DRIVE_LETTER 0x00000002	アタッチした仮想ディスク上のすべてのボリュームを、ドライブ文字を割り当てずにマウントします。
ATTACH_VIRTUAL_DISK_FLAG_PERMANENT_LIFETIME 0x00000004	VDS サービスはこのフラグを自動的に設定し、IVdsOpenVDisk::Detach メソッドが呼び出されてデタッチされるまで VHD がアタッチされたままになるようにします。
ATTACH_VIRTUAL_DISK_FLAG_NO_LOCAL_HOST 0x00000008	予約済みです。使用しないでください。

ProviderSpecificFlags

DWORD

アタッチする仮想ディスクの種類に固有のフラグのビットマスク。これらのフラグはプロバイダー固有です。Microsoft の仮想ディスクプロバイダーの場合、このパラメーターはゼロでなければなりません。

TimeoutInMs

DWORD

このパラメーターは将来使用するために予約されています。

ppAsync

IVdsAsync**

out

IVdsAsync インターフェイスへのポインター。正常に完了すると、この操作を監視および制御するための IVdsAsync インターフェイスを受け取ります。呼び出し側は、使用し終わったら受け取ったインターフェイスを解放しなければなりません。このインターフェイスで IVdsAsync::Wait メソッドを呼び出して成功を示す HRESULT 値が返された場合、VDS_ASYNC_OUTPUT 構造体で返されるインターフェイスは、各インターフェイスポインターに対して IUnknown::Release メソッドを呼び出して解放しなければなりません。ただし、Wait が失敗を示す HRESULT 値を返した場合、または Wait の pHrResult パラメーターが失敗を示す HRESULT 値を受け取った場合、VDS_ASYNC_OUTPUT 構造体内のインターフェイスポインターは NULL であり、解放する必要はありません。成功または失敗の HRESULT 値は、Winerror.h で定義されている SUCCEEDED および FAILED マクロを使用してテストできます。

戻り値

このメソッドは、E_INVALIDARG や E_OUTOFMEMORY などの標準的な HRESULT 値、および VDS 固有の戻り値を返すことがあります。また、HRESULT_FROM_WIN32 マクロを使用して変換されたシステムエラーコードを返すこともあります。エラーは、VDS 自体、または使用されている基盤の VDS プロバイダーから発生する可能性があります。返される可能性のある値には次のものがあります。

戻り値	説明
S_OK	メソッドは正常に完了しました。

解説(Remarks)

仮想ディスクがアタッチされると、呼び出し側は次の通知の1つまたはすべてを受け取ることができます。

呼び出し側が VDS 通知に登録されている場合、呼び出し側はディスク到着通知を受け取ります。詳細については、VDS Notifications を参照してください。
呼び出し側が PnP 通知に登録されている場合、呼び出し側は PnP ディスク到着通知を受け取ります。詳細については、RegisterDeviceNotification を参照してください。

アプリケーションは、CoInitializeSecurity 関数を呼び出してプロセス全体のセキュリティを初期化しなければなりません。dwImpLevel パラメーターは RPC_C_IMP_LEVEL_IMPERSONATE に設定する必要があります。

Windows Server 2008、Windows Vista および Windows Server 2003: これらの操作は、Windows 7 および Windows Server 2008 R2 までは必要ありません。

vtbl 4 HRESULT Detach(DETACH_VIRTUAL_DISK_FLAG Flags, DWORD ProviderSpecificFlags)

仮想ディスクをデタッチします。

Flags	DETACH_VIRTUAL_DISK_FLAG	in	仮想ディスクをどのようにデタッチするかを指定する DETACH_VIRTUAL_DISK_FLAG 列挙値。DETACH_VIRTUAL_DISK_FLAG_NONE に設定しなければなりません。
ProviderSpecificFlags	DWORD	in	デタッチする仮想ディスクの種類に固有のフラグ。Microsoft プロバイダーの場合、これは 0 でなければなりません。この値は、仮想ディスクが作成されたときに IVdsVdProvider::CreateVDisk メソッドの ProviderSpecificFlags パラメーターに指定された値と一致しなければなりません。

戻り値

戻り値	説明
S_OK	メソッドは正常に完了しました。

vtbl 5 HRESULT DetachAndDelete(DETACH_VIRTUAL_DISK_FLAG Flags, DWORD ProviderSpecificFlags)

仮想ディスクをデタッチし、バッキングファイルを削除します。

Flags	DETACH_VIRTUAL_DISK_FLAG	in	仮想ディスクをどのようにデタッチするかを指定する DETACH_VIRTUAL_DISK_FLAG 列挙値。DETACH_VIRTUAL_DISK_FLAG_NONE に設定しなければなりません。
ProviderSpecificFlags	DWORD	in	デタッチおよび削除する仮想ディスクの種類に固有のフラグ。Microsoft プロバイダーの場合、これは 0 でなければなりません。この値は、仮想ディスクが作成されたときに IVdsVdProvider::CreateVDisk メソッドの ProviderSpecificFlags パラメーターに指定された値と一致しなければなりません。

戻り値

戻り値	説明
S_OK	メソッドは正常に完了しました。

vtbl 6 HRESULT Compact(COMPACT_VIRTUAL_DISK_FLAG Flags, DWORD Reserved, IVdsAsync** ppAsync)

仮想ディスクを圧縮して、バッキングファイルの物理サイズを削減します。

Flags	COMPACT_VIRTUAL_DISK_FLAG	in	仮想ディスクをどのように圧縮するかを指定する COMPACT_VIRTUAL_DISK_FLAG 列挙値。COMPACT_VIRTUAL_DISK_FLAG_NONE に設定しなければなりません。
Reserved	DWORD	in	このパラメーターはシステムが使用するために予約されています。
ppAsync	IVdsAsync**	out	IVdsAsync インターフェイスへのポインター。正常に完了すると、この操作を監視および制御するための IVdsAsync インターフェイスを受け取ります。呼び出し側は、使用し終わったら受け取ったインターフェイスを解放しなければなりません。このインターフェイスで IVdsAsync::Wait メソッドを呼び出して成功を示す HRESULT 値が返された場合、VDS_ASYNC_OUTPUT 構造体で返されるインターフェイスは、各インターフェイスポインターに対して IUnknown::Release メソッドを呼び出して解放しなければなりません。ただし、Wait が失敗を示す HRESULT 値を返した場合、または Wait の pHrResult パラメーターが失敗を示す HRESULT 値を受け取った場合、VDS_ASYNC_OUTPUT 構造体内のインターフェイスポインターは NULL であり、解放する必要はありません。成功または失敗の HRESULT 値は、Winerror.h で定義されている SUCCEEDED および FAILED マクロを使用してテストできます。

戻り値

戻り値	説明
S_OK	メソッドは正常に完了しました。

解説(Remarks)

仮想ディスクを圧縮できるのは、次のいずれかの状態にある場合のみです。

デタッチされている(オフラインモード)
アタッチされ、読み取り専用アクセスで開かれている(オンラインモード)

それ以外の状態にある場合、圧縮操作は失敗します。

仮想ディスクは、拡張可能(ダイナミックとも呼ばれます)または差分仮想ディスクでなければなりません。

この操作は安全に中断して後で再実行できます。操作が中断されてバッキングファイルが再度開かれた場合、ファイルを開いたときにファイルのサイズが削減されることがあります。

この操作は、仮想ディスクの大きさや操作が必要な未使用ブロックの数に応じて、CPU 負荷が高い場合や I/O 負荷が高い場合、あるいはその両方の場合があります。

このメソッドは、未使用領域を回収することで仮想ディスクのバッキングストアファイルのサイズを削減します。デタッチされている仮想ディスクに対してこのメソッドを呼び出した場合、データの書き込みに一度も使用されなかったファイル内の領域のみを回収できます。アタッチされ、読み取り専用アクセスで開かれている仮想ディスクに対して呼び出した場合、かつて使用されたが後で解放された領域を回収できます。アタッチされ、読み取り専用アクセスで開かれている仮想ディスクに対してこのメソッドを呼び出すと、バッキングストアファイル内の空き領域を最大限回収します。

vtbl 7 HRESULT Merge(MERGE_VIRTUAL_DISK_FLAG Flags, DWORD MergeDepth, IVdsAsync** ppAsync)

差分チェーン内で子仮想ディスクをその親とマージします。

Flags	MERGE_VIRTUAL_DISK_FLAG	in	仮想ディスクをどのようにマージするかを指定する MERGE_VIRTUAL_DISK_FLAG 列挙値。MERGE_VIRTUAL_DISK_FLAG_NONE に設定しなければなりません。
MergeDepth	DWORD	in	マージする差分チェーン内の親ディスクの数。ディスクは、少なくともこの値と同じ ReadWriteDepth で開かれている必要があります。
ppAsync	IVdsAsync**	out	IVdsAsync インターフェイスへのポインター。正常に完了すると、この操作を監視および制御するための IVdsAsync インターフェイスを受け取ります。呼び出し側は、使用し終わったら受け取ったインターフェイスを解放しなければなりません。このインターフェイスで IVdsAsync::Wait メソッドを呼び出して成功を示す HRESULT 値が返された場合、VDS_ASYNC_OUTPUT 構造体で返されるインターフェイスは、各インターフェイスポインターに対して IUnknown::Release メソッドを呼び出して解放しなければなりません。ただし、Wait が失敗を示す HRESULT 値を返した場合、または Wait の pHrResult パラメーターが失敗を示す HRESULT 値を受け取った場合、VDS_ASYNC_OUTPUT 構造体内のインターフェイスポインターは NULL であり、解放する必要はありません。成功または失敗の HRESULT 値は、Winerror.h で定義されている SUCCEEDED および FAILED マクロを使用してテストできます。

戻り値

戻り値	説明
S_OK	メソッドは正常に完了しました。

解説(Remarks)

仮想ディスクをマージできるのは、デタッチされている場合のみです。

このメソッドは、子ディスクからすべてのデータブロックを親に移動します。ただし、操作の終了時に無効化された子ディスクは削除されません。

仮想ディスクは、読み取り/書き込みアクセスで開かれている必要があります。

vtbl 8 HRESULT Expand(EXPAND_VIRTUAL_DISK_FLAG Flags, ULONGLONG NewSize, IVdsAsync** ppAsync)

仮想ディスクのサイズを、固定ディスクまたは拡張可能ディスクで利用可能な最大サイズまで拡大します。

Flags	EXPAND_VIRTUAL_DISK_FLAG	in	仮想ディスクをどのように拡張するかを指定する EXPAND_VIRTUAL_DISK_FLAG 列挙値。EXPAND_VIRTUAL_DISK_FLAG_NONE に設定しなければなりません。
NewSize	ULONGLONG	in	拡張後の仮想ディスクの希望サイズ(バイト単位)。
ppAsync	IVdsAsync**	out	IVdsAsync インターフェイスへのポインター。正常に完了すると、この操作を監視および制御するための IVdsAsync インターフェイスを受け取ります。呼び出し側は、使用し終わったら受け取ったインターフェイスを解放しなければなりません。このインターフェイスで IVdsAsync::Wait メソッドを呼び出して成功を示す HRESULT 値が返された場合、VDS_ASYNC_OUTPUT 構造体で返されるインターフェイスは、各インターフェイスポインターに対して IUnknown::Release メソッドを呼び出して解放しなければなりません。ただし、Wait が失敗を示す HRESULT 値を返した場合、または Wait の pHrResult パラメーターが失敗を示す HRESULT 値を受け取った場合、VDS_ASYNC_OUTPUT 構造体内のインターフェイスポインターは NULL であり、解放する必要はありません。成功または失敗の HRESULT 値は、Winerror.h で定義されている SUCCEEDED および FAILED マクロを使用してテストできます。

戻り値

戻り値	説明
S_OK	メソッドは正常に完了しました。

解説(Remarks)

仮想ディスクを拡張できるのは、デタッチされている場合のみです。

仮想ディスクは、メタデータ操作を実行するためのアクセス権で開かれている必要があります。これは、VIRTUAL_DISK_ACCESS_MASK 列挙の VIRTUAL_DISK_ACCESS_METAOPS 値に相当します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

#define global IID_IVdsOpenVDisk "{75C8F324-F715-4FE3-A28E-F9011B61A4A1}"
#usecom global IVdsOpenVDisk IID_IVdsOpenVDisk "{}"
#comfunc global IVdsOpenVDisk_Attach           3 wstr,int,int,int,sptr
#comfunc global IVdsOpenVDisk_Detach           4 int,int
#comfunc global IVdsOpenVDisk_DetachAndDelete  5 int,int
#comfunc global IVdsOpenVDisk_Compact          6 int,int,sptr
#comfunc global IVdsOpenVDisk_Merge            7 int,int,sptr
#comfunc global IVdsOpenVDisk_Expand           8 int,int64,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。