ホーム › Storage.VirtualDiskService › IVdsService

IVdsService

COM

📘 Microsoft Learn (日本語) · English

IID0818a8ef-9ba9-40d8-a6f9-e22833cc771e継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

VDS を照会し、VDS と対話するためのメソッドを提供します。

メソッド 17

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

vtbl 3 HRESULT IsServiceReady()

VDS の初期化状態を返します。

戻り値

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

リターンコード/値	説明
S_OK	初期化が正常に完了しました。
S_FALSE	VDS は初期化を完了しておらず、サービスの準備ができていません。
VDS_E_INITIALIZED_FAILED 0x80042401L	初期化に失敗しました。

解説(Remarks)

呼び出し側は、他の VDS メソッドを呼び出す前に、初期化処理が完了するまで待機する必要があります。

vtbl 4 HRESULT WaitForServiceReady()

VDS の初期化が完了するまで待機し、VDS の初期化状態を返します。

戻り値

リターンコード/値	説明
S_OK	VDS は正常に初期化されました。
VDS_E_INITIALIZED_FAILED 0x80042401L	VDS の初期化に失敗しました。

解説(Remarks)

アプリケーションが VDS オブジェクトによって公開されるメソッドを呼び出す前に、VDS が正常に初期化されている必要があります。

vtbl 5 HRESULT GetProperties(VDS_SERVICE_PROP* pServiceProp)

VDS のプロパティを返します。

pServiceProp

VDS_SERVICE_PROP*

out

呼び出し側が割り当てて渡す VDS_SERVICE_PROP 構造体のアドレス。VDS は pwszVersion メンバー文字列用のメモリを割り当てます。呼び出し側は CoTaskMemFree 関数を使用してこの文字列を解放する必要があります。

戻り値

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

リターンコード/値	説明
S_OK	メソッドが正常に完了しました。
VDS_S_PROPERTIES_INCOMPLETE 0x00042715L	一部のプロパティは正常に取得されましたが、すべてではありません。デバイスの取り外しなど、すべてのプロパティの取得に失敗する原因は多数あることに注意してください。

vtbl 6 HRESULT QueryProviders(DWORD masks, IEnumVdsObject** ppEnum)

VDS に認識されているハードウェアプロバイダーおよびソフトウェアプロバイダーの一覧を含む列挙オブジェクトを返します。

masks	DWORD	in	VDS_QUERY_PROVIDER_FLAG によって列挙されるプロバイダーマスク。呼び出し側は、ソフトウェアプロバイダーマスク、ハードウェアプロバイダーマスク、またはその両方を指定できます。
ppEnum	IEnumVdsObject**	out	プロバイダーをプロバイダーオブジェクトとして列挙するために使用できる IEnumVdsObject インターフェイスポインターのアドレス。詳細については、「列挙オブジェクトの操作」を参照してください。呼び出し側は、インターフェイスと各プロバイダーオブジェクトが不要になったら、IUnknown::Release メソッドを呼び出して解放する必要があります。

戻り値

リターンコード/値	説明
S_OK	列挙が正常に返されました。
VDS_E_INITIALIZED_FAILED 0x80042401L	VDS の初期化に失敗しました。アプリケーションがサービスの初期化完了前にこのメソッドを呼び出した場合、初期化が完了するまでメソッドはブロックされます。初期化に失敗した場合、このエラーが返されます。

解説(Remarks)

ハードウェアプロバイダーのプロバイダーの種類を判別するには、各プロバイダーオブジェクトに対して IVdsHwProviderType2::GetProviderType2 メソッドまたは IVdsHwProviderType::GetProviderType メソッドを呼び出します。

vtbl 7 HRESULT QueryMaskedDisks(IEnumVdsObject** ppEnum)

サポートされていません。このメソッドは将来の使用のために予約されています。(IVdsService.QueryMaskedDisks)

ppEnum

IEnumVdsObject**

out

IEnumVdsObject インターフェイスポインターのアドレス。VDS は戻り時にこれを初期化します。呼び出し側はインターフェイスを解放する必要があります。

戻り値

リターンコード	説明
E_NOTIMPL	このメソッドは実装されていません。

vtbl 8 HRESULT QueryUnallocatedDisks(IEnumVdsObject** ppEnum)

VDS が管理する未割り当てディスクの一覧を含む列挙オブジェクトを返します。

ppEnum

IEnumVdsObject**

out

ディスクをディスクオブジェクトとして列挙するために使用できる IEnumVdsObject インターフェイスポインターのアドレス。詳細については、「列挙オブジェクトの操作」を参照してください。呼び出し側は、インターフェイスと各ディスクオブジェクトが不要になったら、IUnknown::Release メソッドを呼び出して解放する必要があります。

戻り値

リターンコード/値	説明
S_OK	列挙が正常に返されました。
VDS_E_INITIALIZED_FAILED 0x80042401L	VDS の初期化に失敗しました。アプリケーションがサービスの初期化完了前にこのメソッドを呼び出した場合、初期化が完了するまでメソッドはブロックされます。初期化に失敗した場合、このエラーが返されます。

解説(Remarks)

未割り当てディスクは、どのプロバイダーにも要求されていません。MBR または GPT のパーティション形式情報を含む場合と含まない場合があります。多くの場合、初期化されていないディスクです。ディスクの状態が VDS_DS_ONLINE または VDS_DS_OFFLINE の場合、そのディスクは未割り当てかつ未初期化です。VDS_DS_UNKNOWN、VDS_DS_NOT_READY、VDS_DS_FAILED、または VDS_DS_MISSING の場合、そのディスクは未割り当てですが、ディスクの問題などが原因で、VDS サービスは初期化されているかどうかを判別できません。

ディスクの状態を判別するには、そのディスクの VDS_DISK_PROP または VDS_DISK_PROP2 構造体の status メンバーを参照してください。

ディスクの状態が VDS_DS_ONLINE の場合、そのディスクはパックに追加できます。

ディスクの状態が VDS_DS_OFFLINE の場合、IVdsDiskOnline::Online を呼び出してディスクをオンラインにしてみてください。Online メソッドの呼び出しが成功した場合、そのディスクはパックに追加できます。Online の呼び出しが失敗した場合、そのディスクは使用できません。

vtbl 9 HRESULT GetObject(GUID ObjectId, VDS_OBJECT_TYPE type, IUnknown** ppObjectUnk)

指定されたオブジェクトのオブジェクトポインターを返します。

ObjectId	GUID	in	目的のオブジェクトの GUID。
type	VDS_OBJECT_TYPE	in	オブジェクトの種類を指定する VDS_OBJECT_TYPE 列挙値。 VDS_OT_UNKNOWN、VDS_OT_PROVIDER、 VDS_OT_ASYNC、VDS_OT_ENUM、VDS_OT_OPEN_VDISK はサポートされていません。
ppObjectUnk	IUnknown**	out	オブジェクトへの IUnknown ポインターを受け取るバッファーへのポインター。ポインターが不要になったら、呼び出し側は IUnknown::Release メソッドを呼び出して解放する必要があります。

戻り値

リターンコード/値	説明
VDS_E_OBJECT_NOT_FOUND 0x80042405L	指定された識別子と種類のオブジェクトが見つかりません。
VDS_E_INITIALIZED_FAILED 0x80042401L	VDS の初期化に失敗しました。アプリケーションがサービスの初期化完了前にこのメソッドを呼び出した場合、初期化が完了するまでメソッドはブロックされます。初期化に失敗した場合、このエラーが返されます。

解説(Remarks)

VDS の通知は、オブジェクトポインターではなくオブジェクト識別子を返します。呼び出し側は、このメソッドを使用して、通知で参照されているオブジェクトへのポインターを取得します。

vtbl 10 HRESULT QueryDriveLetters(WCHAR wcFirstLetter, DWORD count, VDS_DRIVE_LETTER_PROP* pDriveLetterPropArray)

一連のドライブ文字のプロパティの詳細を返します。

wcFirstLetter	WCHAR	in	取得する最初のドライブ文字。
count	DWORD	in	取得するドライブ文字の総数。
pDriveLetterPropArray	VDS_DRIVE_LETTER_PROP*	out	VDS_DRIVE_LETTER_PROP 構造体の配列のアドレス。配列のサイズは count です。呼び出し側はこの配列のメモリを割り当てる必要があります。

戻り値

リターンコード/値	説明
S_OK	メソッドが正常に完了しました。
VDS_E_INITIALIZED_FAILED 0x80042401L	VDS の初期化に失敗しました。アプリケーションがサービスの初期化完了前にこのメソッドを呼び出した場合、初期化が完了するまでメソッドはブロックされます。初期化に失敗した場合、このエラーが返されます。

vtbl 11 HRESULT QueryFileSystemTypes(VDS_FILE_SYSTEM_TYPE_PROP** ppFileSystemTypeProps, INT* plNumberOfFileSystems)

VDS に認識されているすべてのファイルシステムのプロパティの詳細を返します。

ppFileSystemTypeProps	VDS_FILE_SYSTEM_TYPE_PROP**	out	VDS_FILE_SYSTEM_TYPE_PROP 構造体の配列を保持するバッファーへのポインターのアドレス。呼び出し側は、CoTaskMemFree 関数を使用して、配列と pwszIllegalLabelCharSet 文字列のメモリを解放する必要があります。
plNumberOfFileSystems	INT*	out	ファイルシステムの総数。

戻り値

リターンコード/値	説明
S_OK	メソッドが正常に完了しました。
VDS_E_INITIALIZED_FAILED 0x80042401L	VDS の初期化に失敗しました。アプリケーションがサービスの初期化完了前にこのメソッドを呼び出した場合、初期化が完了するまでメソッドはブロックされます。初期化に失敗した場合、このエラーが返されます。

vtbl 12 HRESULT Reenumerate()

新たに追加されたディスクおよび新たに削除されたディスクを検出します。

戻り値

リターンコード/値	説明
S_OK	メソッドが正常に完了しました。
VDS_E_INITIALIZED_FAILED 0x80042401L	VDS の初期化に失敗しました。アプリケーションがサービスの初期化完了前にこのメソッドを呼び出した場合、初期化が完了するまでメソッドはブロックされます。初期化に失敗した場合、このエラーが返されます。

解説(Remarks)

このメソッドは、バスの再スキャン要求が発行された直後に戻ります。メソッドが戻った時点では、操作が完了していない場合があります。RAID サブシステム内のドライブに対して同じ操作を実行するには、IVdsSubSystem::Reenumerate メソッドを使用します。

vtbl 13 HRESULT Refresh()

ディスクの所有権情報とディスクのレイアウト情報を更新します。

戻り値

リターンコード/値	説明
S_OK	メソッドが正常に完了しました。
S_FALSE	この操作中にエラーが発生しました。
VDS_E_INITIALIZED_FAILED 0x80042401L	VDS の初期化に失敗しました。アプリケーションがサービスの初期化完了前にこのメソッドを呼び出した場合、初期化が完了するまでメソッドはブロックされます。初期化に失敗した場合、このエラーが返されます。

解説(Remarks)

このメソッドは、ディスクのレイアウトを、ディスクドライバーが認識しているレイアウトに同期させます。ドライバーにディスクからレイアウトを読み取らせることを強制するものではありません。さらに、このメソッドは VDS キャッシュ内のすべてのオブジェクトのビューを更新します。VDS とプロバイダーはすべてのオブジェクトを照会し、呼び出し側を同期させるためにオブジェクトの到着、変更、削除の通知を送信します。VDS は、通知を発生させる変更を検出するたびに、自動的にキャッシュを更新することに注意してください。このため、また Refresh の呼び出しが追加の通知を発生させる可能性があるため、アプリケーションは通知への応答としてこのメソッドを呼び出すべきではありません。Refresh は、キャッシュが適切に更新されていないと思われる場合にのみ呼び出す必要があります。

vtbl 14 HRESULT CleanupObsoleteMountPoints()

存在しなくなったボリュームのユーザーモードパスとマウントされたフォルダーを削除します。

戻り値

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

リターンコード/値	説明
S_OK	古くなったユーザーモードパスとマウントされたフォルダーが正常に削除されました。
VDS_E_INITIALIZED_FAILED 0x80042401L	VDS の初期化に失敗しました。アプリケーションがサービスの初期化完了前にこのメソッドを呼び出した場合、初期化が完了するまでメソッドはブロックされます。初期化に失敗した場合、このエラーが返されます。

解説(Remarks)

既定では、レジストリはアンインストールされたボリュームのドライブ文字マッピング情報を保持します。ボリュームを含むディスクがコンピューターから取り外されても、レジストリエントリは保持されます。これにより、そのディスクとボリュームが同じコンピューターに戻された場合、ボリュームは同じドライブ文字を受け取ります。ディスクが新しいコンピューターに移動された場合、レジストリエントリは一緒に移動しないため、ボリュームは別のドライブ文字とボリューム GUID を受け取る可能性があります。

CleanupObsoleteMountPoints メソッドは、これらのレジストリエントリを削除します。削除されるレジストリエントリには次の 3 種類があります。

ボリュームにドライブ文字もボリューム GUID もない場合、そのボリュームには「ドライブ文字なし」のレジストリエントリがあり、このメソッドによって削除されます。
それ以外の場合、ボリュームにはボリューム GUID のレジストリエントリと、場合によってはドライブ文字のレジストリエントリがあります。どちらもこのメソッドによって削除されます。

さらに、ボリュームにマウントされたフォルダーが含まれている場合、 CleanupObsoleteMountPoints はそれらを削除します。たとえば、Disk1 上の Volume1 が削除されようとしており、Volume1 が Disk2 上に x:\MountVolume1 としてマウントされている場合、Disk2 上の \MountVolume1 フォルダーも削除されます。

vtbl 15 HRESULT Advise(IVdsAdviseSink* pSink, DWORD* pdwCookie)

呼び出し側が VDS サービスから通知を受け取れるように、呼び出し側の IVdsAdviseSink インターフェイスを VDS に登録します。

pSink	IVdsAdviseSink*	in	IVdsAdviseSink インターフェイスへのポインター。
pdwCookie	DWORD*	out	後でインターフェイスの登録を解除するために使用できる Cookie へのポインター。

戻り値

リターンコード/値	説明
S_OK	登録が正常に完了しました。
VDS_E_INITIALIZED_FAILED 0x80042401L	VDS の初期化に失敗しました。アプリケーションがサービスの初期化完了前にこのメソッドを呼び出した場合、初期化が完了するまでメソッドはブロックされます。初期化に失敗した場合、このエラーが返されます。

解説(Remarks)

VDS サービスから通知を受け取るには、アプリケーションは IVdsAdviseSink インターフェイスを実装し、Advise メソッドを使用してそのインターフェイスを登録する必要があります。

VDS サービスからの通知の受信を停止するには、IVdsService::Unadvise メソッドを使用して IVdsAdviseSink インターフェイスの登録を解除します。

注意 Advise を呼び出したアプリケーションは、最終的に Unadvise を呼び出す必要があります。通知を受け取る必要がなくなったら、できるだけ早く Unadvise を呼び出すのが理想的です。

基盤のソフトウェアプロバイダーおよびハードウェアプロバイダーから通知を受け取るために、VDS は各プロバイダーに対して IVdsProviderPrivate::OnLoad メソッドのパラメーターとして通知コールバック関数を渡します。

vtbl 16 HRESULT Unadvise(DWORD dwCookie)

呼び出し側が VDS サービスから通知を受け取らなくなるように、呼び出し側の IVdsAdviseSink インターフェイスの登録を解除します。

dwCookie

DWORD

IVdsAdviseSink インターフェイスが登録されたときに IVdsService::Advise メソッドによって返された Cookie。

戻り値

リターンコード/値	説明
S_OK	メソッドが正常に完了しました。
VDS_E_BAD_COOKIE 0x80042411L	Cookie が存在しません。
VDS_E_INITIALIZED_FAILED 0x80042401L	VDS の初期化に失敗しました。アプリケーションがサービスの初期化完了前にこのメソッドを呼び出した場合、初期化が完了するまでメソッドはブロックされます。初期化に失敗した場合、このエラーが返されます。

解説(Remarks)

Advise メソッドを使用して、VDS アプリケーションの IVdsAdviseSink インターフェイスを登録し、VDS からの通知を受け取ります。Advise は Cookie を返し、これを Unadvise メソッドのパラメーターとして渡す必要があります。

注意 Advise を呼び出したアプリケーションは、最終的に Unadvise を呼び出す必要があります。通知を受け取る必要がなくなったら、できるだけ早く Unadvise を呼び出すのが理想的です。

Unadvise メソッドは、登録されているクライアントアプリケーションの一覧を更新するためのロックを待機し、クライアントに通知を送信している通知スレッドが終了するのを待機するため、すぐには戻らない場合があります。アプリケーションに送信すべき未処理の通知がある場合、通知スレッドは終了する前にそれらを送信しようとします。

vtbl 17 HRESULT Reboot()

プロバイダーをホストしているコンピューターを再起動します。

戻り値

リターンコード/値	説明
S_OK	メソッドが正常に完了しました。
VDS_E_INITIALIZED_FAILED 0x80042401L	VDS の初期化に失敗しました。アプリケーションがサービスの初期化完了前にこのメソッドを呼び出した場合、初期化が完了するまでメソッドはブロックされます。初期化に失敗した場合、このエラーが返されます。

解説(Remarks)

このメソッドは、次のメッセージをユーザーに表示します。

「仮想ディスクサービス: この操作を行うにはコンピューターを再起動する必要があります。」

VDS は、システムがシャットダウンする前に、現在の作業を保存して終了するようユーザーに求めます。Reboot は、動作中のアプリケーションを強制的に閉じることはありません。

vtbl 18 HRESULT SetFlags(DWORD ulFlags)

サービスオブジェクトのフラグを設定します。

ulFlags

DWORD

VDS_SERVICE_FLAG によって列挙されるフラグ。呼び出し側は VDS_SVF_AUTO_MOUNT_OFF フラグを設定できます。

戻り値

リターンコード/値	説明
S_OK	フラグが正常に設定されました。
VDS_E_INITIALIZED_FAILED 0x80042401L	VDS の初期化に失敗しました。アプリケーションがサービスの初期化完了前にこのメソッドを呼び出した場合、初期化が完了するまでメソッドはブロックされます。初期化に失敗した場合、このエラーが返されます。

解説(Remarks)

Windows 8 および Windows Server 2012 以降、VDS_SVF_AUTO_MOUNT_OFF は非推奨です。代わりに、既定のディスクマウント動作を制御するには VDS_SAN_POLICY 列挙を使用してください。

vtbl 19 HRESULT ClearFlags(DWORD ulFlags)

サービスオブジェクトのフラグをクリアします。

ulFlags

DWORD

VDS_SERVICE_FLAG によって列挙されるフラグ。呼び出し側は VDS_SVF_AUTO_MOUNT_OFF フラグをクリアできます。

戻り値

リターンコード/値	説明
S_OK	フラグが正常にクリアされました。
VDS_E_INITIALIZED_FAILED 0x80042401L	VDS の初期化に失敗しました。アプリケーションがサービスの初期化完了前にこのメソッドを呼び出した場合、初期化が完了するまでメソッドはブロックされます。初期化に失敗した場合、このエラーが返されます。

解説(Remarks)

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IVdsService "{0818A8EF-9BA9-40D8-A6F9-E22833CC771E}"
#usecom global IVdsService IID_IVdsService "{7D1933CB-86F6-4A98-8628-01BE94C9A575}"
#comfunc global IVdsService_IsServiceReady              3
#comfunc global IVdsService_WaitForServiceReady         4
#comfunc global IVdsService_GetProperties               5 var
#comfunc global IVdsService_QueryProviders              6 int,sptr
#comfunc global IVdsService_QueryMaskedDisks            7 sptr
#comfunc global IVdsService_QueryUnallocatedDisks       8 sptr
#comfunc global IVdsService_GetObject                   9 int,int,sptr
#comfunc global IVdsService_QueryDriveLetters           10 int,int,var
#comfunc global IVdsService_QueryFileSystemTypes        11 var,var
#comfunc global IVdsService_Reenumerate                 12
#comfunc global IVdsService_Refresh                     13
#comfunc global IVdsService_CleanupObsoleteMountPoints  14
#comfunc global IVdsService_Advise                      15 sptr,var
#comfunc global IVdsService_Unadvise                    16 int
#comfunc global IVdsService_Reboot                      17
#comfunc global IVdsService_SetFlags                    18 int
#comfunc global IVdsService_ClearFlags                  19 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IVdsService "{0818A8EF-9BA9-40D8-A6F9-E22833CC771E}"
#usecom global IVdsService IID_IVdsService "{7D1933CB-86F6-4A98-8628-01BE94C9A575}"
#comfunc global IVdsService_IsServiceReady              3
#comfunc global IVdsService_WaitForServiceReady         4
#comfunc global IVdsService_GetProperties               5 sptr
#comfunc global IVdsService_QueryProviders              6 int,sptr
#comfunc global IVdsService_QueryMaskedDisks            7 sptr
#comfunc global IVdsService_QueryUnallocatedDisks       8 sptr
#comfunc global IVdsService_GetObject                   9 int,int,sptr
#comfunc global IVdsService_QueryDriveLetters           10 int,int,sptr
#comfunc global IVdsService_QueryFileSystemTypes        11 sptr,sptr
#comfunc global IVdsService_Reenumerate                 12
#comfunc global IVdsService_Refresh                     13
#comfunc global IVdsService_CleanupObsoleteMountPoints  14
#comfunc global IVdsService_Advise                      15 sptr,sptr
#comfunc global IVdsService_Unadvise                    16 int
#comfunc global IVdsService_Reboot                      17
#comfunc global IVdsService_SetFlags                    18 int
#comfunc global IVdsService_ClearFlags                  19 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。