ホーム › Storage.Vss › IVssHardwareSnapshotProvider

IVssHardwareSnapshotProvider

COM

IID9593a157-44e9-4344-bbeb-44fbf9b06b10継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

ボリュームを LUN にマップし、シャドウコピー処理中に作成された LUN を検出し、SAN 上で LUN を転送するために VSS が使用するメソッドを提供します。

メソッド 6

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

vtbl 3 HRESULT AreLunsSupported(INT lLunCount, INT lContext, WORD** rgwszDevices, VDS_LUN_INFORMATION* pLunInformation, BOOL* pbIsSupported)

ボリュームを構成するすべての LUN について、ハードウェアプロバイダーがシャドウコピーの作成をサポートしているかどうかを判定します。

lLunCount	INT	in	このシャドウコピーボリュームを構成する LUN の数。
lContext	INT	in	_VSS_VOLUME_SNAPSHOT_ATTRIBUTES 列挙型のフラグのビットマスクで表される、現在のシャドウコピーセットのシャドウコピーコンテキスト。VSS_VOLSNAP_ATTR_TRANSPORTABLE フラグが設定されている場合、そのシャドウコピーセットは転送可能です。
rgwszDevices	WORD**	in	シャドウコピー対象の LUN に対応するデバイスの一覧。
pLunInformation	VDS_LUN_INFORMATION*	inout	lLunCount 個の VDS_LUN_INFORMATION 構造体の配列。このシャドウコピーボリュームを構成する LUN ごとに 1 つずつ格納されます。
pbIsSupported	BOOL*	out	BOOL 値へのポインター。すべてのデバイスがシャドウコピーをサポートしている場合、プロバイダーは pbIsSupported が指す場所に TRUE を格納する必要があります。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値/値	説明
S_OK 0x00000000L	操作は正常に完了しました。
E_OUTOFMEMORY 0x8007000EL	メモリまたはその他のシステムリソースが不足しています。
E_INVALIDARG 0x80070057L	いずれかのパラメーター値が無効です。
VSS_E_PROVIDER_VETO 0x80042306L	予期しないプロバイダーエラーが発生しました。プロバイダーは、問題の解決方法をユーザーに示す情報を含むイベントをアプリケーションイベントログに記録する必要があります。

解説(Remarks)

ハードウェアサブシステムが SCSI Inquiry Data と Vital Product Data のページ 80 (デバイスシリアル番号) およびページ 83 (デバイス ID) のガイドラインをサポートしている場合、プロバイダーは pLunInformation 配列内の構造体を変更する必要はありません。

いずれの場合でも、AreLunsSupported メソッドは pLunInformation 配列内の VDS_LUN_INFORMATION 構造体の m_rgInterconnects メンバーの値を変更してはなりません。

プロバイダーが pLunInformation 配列内のすべての LUN についてハードウェアシャドウコピーの作成をサポートしている場合は、pbIsSupported パラメーターが指す BOOL 値に TRUE を返す必要があります。1 つ以上の LUN についてハードウェアシャドウコピーをサポートしていない場合は、この BOOL 値を FALSE に設定しなければなりません。

プロバイダーは、シャドウコピーを作成できない場合、たとえそれが一時的な問題であっても、作成に同意してはなりません。リソース不足などの一時的な状況により、AreLunsSupported の呼び出し時に 1 つ以上の LUN を使用したシャドウコピーの作成が不可能な場合、プロバイダーは BOOL 値を FALSE に設定する必要があります。

vtbl 4 HRESULT FillInLunInfo(WORD* wszDeviceName, VDS_LUN_INFORMATION* pLunInfo, BOOL* pbIsSupported)

ハードウェアプロバイダーに対して、対応するディスクデバイスをサポートしているかどうかを示し、VDS_LUN_INFORMATION 構造体の不足情報を補完するよう求めます。

wszDeviceName	WORD*	in	シャドウコピー LUN に対応するデバイス。
pLunInfo	VDS_LUN_INFORMATION*	inout	シャドウコピー LUN の VDS_LUN_INFORMATION 構造体。
pbIsSupported	BOOL*	out	デバイスがサポートされている場合、プロバイダーは pbIsSupported パラメーターが指す場所に TRUE を返す必要があります。

戻り値

VSS はこのメソッドの戻り値を無視します。

Windows Server 2003: VSS は戻り値を無視せず、次のいずれかの値になります。

戻り値/値	説明
S_OK 0x00000000L	操作は正常に完了しました。
E_OUTOFMEMORY 0x8007000EL	メモリまたはその他のシステムリソースが不足しています。
E_INVALIDARG 0x80070057L	いずれかのパラメーター値が無効です。
VSS_E_PROVIDER_VETO 0x80042306L	予期しないプロバイダーエラーが発生しました。プロバイダーは、問題の解決方法をユーザーに示す情報を含むイベントをアプリケーションイベントログに記録する必要があります。

解説(Remarks)

VSS は、プロバイダーが GetTargetLuns メソッドで事前に初期化した VDS_LUN_INFORMATION 構造体ごとに FillInLunInfo メソッドを呼び出します。また、インポート処理中にシステムに新たに現れたディスクデバイスごとにも FillInLunInfo メソッドを呼び出します。

プロバイダーは、pLunInfo パラメーターで受け取った VDS_LUN_INFORMATION 構造体の不足情報を補完できます。ただし、この構造体の m_rgInterconnects メンバーの値を変更してはなりません。

VDS_LUN_INFORMATION 構造体のメンバーは、SCSI Inquiry Data と Vital Product Data のページ 80 (デバイスシリアル番号) の情報に対応しますが、次の例外があります。

m_version メンバーは VER_VDS_LUN_INFORMATION に設定する必要があります。
m_BusType メンバーはインポート時の比較では無視されます。この値は、対応するディスクデバイスの PnP ストレージスタックに依存します。通常は VDSBusTypeScsi です。
m_diskSignature メンバーはインポート時の比較では無視されます。プロバイダーはこのメンバーを GUID_NULL に設定する必要があります。

VDS_STORAGE_DEVICE_ID_DESCRIPTOR 構造体 (VDS_LUN_INFORMATION 構造体の m_deviceIdDescriptor メンバー内) のメンバーは、ページ 83 の情報に対応します。この構造体において、各 VDS_STORAGE_IDENTIFIER 構造体は、デバイス識別子 (すなわち、関連付けタイプが 0 のストレージ識別子) を表す STORAGE_IDENTIFIER 構造体に対応します。STORAGE_IDENTIFIER 構造体の詳細については、Windows Driver Kit (WDK) のドキュメントを参照してください。

プロバイダーが認識していない LUN に対して FillInLunInfo メソッドが呼び出された場合、プロバイダーはエラーを返すべきではありません。代わりに、pbIsSupported パラメーターが指す BOOL 値に FALSE を返し、成功を返す必要があります。プロバイダーがその LUN を認識している場合は、この BOOL 値を TRUE に設定します。

vtbl 5 HRESULT BeginPrepareSnapshot(GUID SnapshotSetId, GUID SnapshotId, INT lContext, INT lLunCount, WORD** rgDeviceNames, VDS_LUN_INFORMATION* rgLunInformation)

シャドウコピーセットに追加されるシャドウコピーごとに呼び出されます。

SnapshotSetId	GUID	in	シャドウコピーセットの識別子。
SnapshotId	GUID	in	作成されるシャドウコピーの識別子。
lContext	INT	in	_VSS_VOLUME_SNAPSHOT_ATTRIBUTES で列挙される、現在のシャドウコピーセットのシャドウコピーコンテキスト。
lLunCount	INT	in	このシャドウコピーボリュームを構成する LUN の数。
rgDeviceNames	WORD**	in	lLunCount 個の文字列ポインターの配列へのポインター。各文字列には、シャドウコピー対象の LUN の名前が格納されます。
rgLunInformation	VDS_LUN_INFORMATION*	inout	lLunCount 個の VDS_LUN_INFORMATION 構造体の配列へのポインター。このシャドウコピーボリュームを構成する LUN ごとに 1 つずつ格納されます。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値/値	説明
S_OK 0x00000000L	操作は正常に完了しました。
E_OUTOFMEMORY 0x8007000EL	メモリまたはその他のシステムリソースが不足しています。
E_INVALIDARG 0x80070057L	いずれかのパラメーター値が無効です。
VSS_E_MAXIMUM_NUMBER_OF_VOLUMES_REACHED 0x80042312L	プロバイダーがサポートできるボリュームの最大数に達しました。
VSS_E_NESTED_VOLUME_LIMIT	指定されたボリュームは入れ子が深すぎるため、VSS 操作に参加できません。 Windows Server 2008、Windows Vista、Windows Server 2003 および Windows XP: この戻り値はサポートされていません。
VSS_E_PROVIDER_VETO 0x80042306L	予期しないプロバイダーエラーが発生しました。プロバイダーは、問題の解決方法をユーザーに示す情報を含むイベントをアプリケーションイベントログに記録する必要があります。
VSS_E_VOLUME_NOT_SUPPORTED_BY_PROVIDER 0x8004230EL	プロバイダーはこのボリュームをサポートしていません。
VSS_E_UNSUPPORTED_CONTEXT 0x8004231BL	lContext で指定されたコンテキストはサポートされていません。

解説(Remarks)

このメソッドは、別の仮想ハードディスク (VHD) 内に入れ子になった VHD に対しては呼び出せません。

Windows Server 2008、Windows Vista、Windows Server 2003 および Windows XP: VHD はサポートされていません。

vtbl 6 HRESULT GetTargetLuns(INT lLunCount, WORD** rgDeviceNames, VDS_LUN_INFORMATION* rgSourceLuns, VDS_LUN_INFORMATION* rgDestinationLuns)

ハードウェアプロバイダーに対して、新たに作成されたシャドウコピー LUN の VDS_LUN_INFORMATION 構造体を初期化するよう求めます。

lLunCount	INT	in	元のボリュームを構成する LUN の数。
rgDeviceNames	WORD**	in	lLunCount 個の文字列ポインターの配列へのポインター。各文字列には、シャドウコピー対象となる元の LUN の名前が格納されます。
rgSourceLuns	VDS_LUN_INFORMATION*	in	lLunCount 個の VDS_LUN_INFORMATION 構造体の配列へのポインター。元のボリュームを構成する LUN ごとに 1 つずつ格納されます。
rgDestinationLuns	VDS_LUN_INFORMATION*	inout	lLunCount 個の VDS_LUN_INFORMATION 構造体の配列へのポインター。シャドウコピー処理中に作成された新しいシャドウコピー LUN ごとに 1 つずつ格納されます。 rgSourceLuns 配列と rgDestinationLuns 配列の要素は 1 対 1 で対応している必要があります。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値/値	説明
S_OK 0x00000000L	操作は正常に完了しました。
E_OUTOFMEMORY 0x8007000EL	メモリまたはその他のシステムリソースが不足しています。
E_INVALIDARG 0x80070057L	いずれかのパラメーター値が無効です。
VSS_E_PROVIDER_VETO 0x80042306L	予期しないプロバイダーエラーが発生しました。プロバイダーは、問題の解決方法をユーザーに示す情報を含むイベントをアプリケーションイベントログに記録する必要があります。

解説(Remarks)

rgDestinationLuns パラメーターでは、VSS は新たに作成された各シャドウコピー LUN に対して空の VDS_LUN_INFORMATION 構造体を提供します。シャドウコピー LUN は公開されず、システムからは見えません。プロバイダーは、VDS_LUN_INFORMATION 構造体のメンバーを、適切な SCSI Inquiry Data と Vital Product Data のページ 80 (デバイスシリアル番号) およびページ 83 (デバイス ID) の情報で初期化する必要があります。この構造体には、元のコンピューターや SAN に接続された他の任意のコンピューターから Windows がシャドウコピー LUN を特定できるように、正しいメンバー値を格納する必要があります。

VDS_LUN_INFORMATION 構造体のメンバーは、ページ 80 の情報に対応しますが、次の例外があります。

m_version メンバーは VER_VDS_LUN_INFORMATION に設定する必要があります。
m_BusType メンバーはインポート時の比較では無視されます。この値は、対応するディスクデバイスの PnP ストレージスタックに依存します。通常は VDSBusTypeScsi です。
m_diskSignature メンバーはインポート時の比較では無視されます。プロバイダーはこのメンバーを GUID_NULL に設定する必要があります。

ここで返される VDS_LUN_INFORMATION 構造体は、インポート時に IVssHardwareSnapshotProvider::FillInLunInfo メソッドで提供される構造体と同一でなければなりません。これにより、VSS はこの情報を使用して、インポート時に新たに現れるシャドウコピー LUN を識別できます。これらと同じ構造体が、 IVssHardwareSnapshotProvider::LocateLuns メソッドでプロバイダーに渡されます。

vtbl 7 HRESULT LocateLuns(INT lLunCount, VDS_LUN_INFORMATION* rgSourceLuns)

ハードウェアプロバイダーに対して、シャドウコピー LUN をコンピューターから見えるようにするよう求めます。

lLunCount	INT	in	このシャドウコピーセットを構成する LUN の数。
rgSourceLuns	VDS_LUN_INFORMATION*	in	iLunCount 個の VDS_LUN_INFORMATION 構造体の配列へのポインター。インポート対象のシャドウコピーセットに含まれる LUN ごとに 1 つずつ格納されます。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値/値	説明
S_OK 0x00000000L	操作は正常に完了しました。
E_OUTOFMEMORY 0x8007000EL	メモリまたはその他のシステムリソースが不足しています。
E_INVALIDARG 0x80070057L	いずれかのパラメーター値が無効です。
VSS_E_PROVIDER_VETO 0x80042306L	予期しないプロバイダーエラーが発生しました。プロバイダーは、問題の解決方法をユーザーに示す情報を含むイベントをアプリケーションイベントログに記録する必要があります。

解説(Remarks)

rgSourceLuns パラメーターでは、VSS はプロバイダーが IVssHardwareSnapshotProvider::GetTargetLuns メソッドで事前に初期化したものと同じ VDS_LUN_INFORMATION 構造体の配列を提供します。配列内の各 VDS_LUN_INFORMATION 構造体について、プロバイダーは対応するシャドウコピー LUN のマスクを解除して、コンピューターに「公開 (surface)」する必要があります。

このメソッドから制御が戻った直後、VSS は再スキャンと列挙を行い、新たに現れたデバイスを検出します。これにより、公開された LUN が PnP マネージャーによって検出されます。ディスクの到着を監視すると同時に、VSS は隠しボリュームの到着も監視します。VSS は、シャドウコピーセットを構成するすべてのボリュームがシステムに現れるか、タイムアウトが発生した時点で監視を停止します。この待機期間内に一部のディスクデバイスまたはボリュームデバイスが現れなかった場合、VSS はリクエスターに VSS_S_SOME_SNAPSHOTS_NOT_IMPORTED を返し、一部のシャドウコピーのみがインポートされたことを通知します。また、 GetTargetLuns メソッドと IVssHardwareSnapshotProvider::FillInLunInfo メソッドから受け取った VDS_LUN_INFORMATION 構造体が一致しない場合にも、リクエスターは VSS から同じエラーを受け取ります。

このメソッドを使用して、シャドウコピー LUN を読み取り専用としてマップすることはできません。

vtbl 8 HRESULT OnLunEmpty(WORD* wszDeviceName, VDS_LUN_INFORMATION* pInformation)

シャドウコピー LUN に有用なデータが含まれていないと VSS が判断したときに呼び出されます。

wszDeviceName	WORD*	in	削除対象のシャドウコピーを含む LUN に対応するデバイス。
pInformation	VDS_LUN_INFORMATION*	in	削除対象のシャドウコピーを含む LUN に関する情報を格納した VDS_LUN_INFORMATION 構造体へのポインター。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値/値	説明
S_OK 0x00000000L	操作は正常に完了しました。
E_OUTOFMEMORY 0x8007000EL	メモリまたはその他のシステムリソースが不足しています。
E_INVALIDARG 0x80070057L	いずれかのパラメーター値が無効です。
VSS_E_PROVIDER_VETO 0x80042306L	予期しないプロバイダーエラーが発生しました。プロバイダーは、問題の解決方法をユーザーに示す情報を含むイベントをアプリケーションイベントログに記録する必要があります。

解説(Remarks)

ハードウェアプロバイダーは、OnLunEmpty が呼び出された場合に限り、シャドウコピーを削除して LUN を再利用する必要があります。ハードウェアシャドウコピー自体がバックアップメディアとして使用される場合があるため、LUN はストレージアレイが通常のディスク用 LUN を扱うのと同じ慎重さで扱う必要があります。OnLunEmpty の処理以外で LUN を再利用することは、緊急時、または管理者が明示的に手動操作を行う場合に限定すべきです。

永続的なシャドウコピーの場合、リクエスターは不要になった時点でシャドウコピーを削除します。非永続の自動解放シャドウコピーの場合、VSS サービスは、リクエスターが IVssBackupComponents オブジェクトに対して IUnknown::Release を呼び出した時点でシャドウコピーを削除します。非永続かつ非自動解放のシャドウコピーの場合、VSS サービスはコンピューターの再起動時にシャドウコピーを削除します。いずれの場合も、VSS サービスは各シャドウコピー LUN について必要に応じてプロバイダーの OnLunEmpty メソッドを呼び出します。

OnLunEmpty はベストエフォートで呼び出される点に注意してください。VSS は、LUN が空であることが保証される場合にのみこのメソッドを呼び出します。LUN が空であっても、エラーや外部要因により VSS がそれを検出できないケースが多数存在する可能性があります。その場合、ユーザーはストレージ管理ソフトウェアを使用してこの状態を解消する必要があります。

例:

シャドウコピー LUN が別のホストに移動されたものの、実際には VSS を通じて転送もインポートもされていない場合、その LUN は他の LUN と同様に見え、VSS に何の通知もなくボリュームが削除される可能性があります。
シャドウコピー作成の途中でクラッシュや予期しない再起動が発生した場合。
インポートがキャンセルされた場合。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IVssHardwareSnapshotProvider "{9593A157-44E9-4344-BBEB-44FBF9B06B10}"
#usecom global IVssHardwareSnapshotProvider IID_IVssHardwareSnapshotProvider "{}"
#comfunc global IVssHardwareSnapshotProvider_AreLunsSupported      3 int,int,var,var,var
#comfunc global IVssHardwareSnapshotProvider_FillInLunInfo         4 var,var,var
#comfunc global IVssHardwareSnapshotProvider_BeginPrepareSnapshot  5 int,int,int,int,var,var
#comfunc global IVssHardwareSnapshotProvider_GetTargetLuns         6 int,var,var,var
#comfunc global IVssHardwareSnapshotProvider_LocateLuns            7 int,var
#comfunc global IVssHardwareSnapshotProvider_OnLunEmpty            8 var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IVssHardwareSnapshotProvider "{9593A157-44E9-4344-BBEB-44FBF9B06B10}"
#usecom global IVssHardwareSnapshotProvider IID_IVssHardwareSnapshotProvider "{}"
#comfunc global IVssHardwareSnapshotProvider_AreLunsSupported      3 int,int,sptr,sptr,sptr
#comfunc global IVssHardwareSnapshotProvider_FillInLunInfo         4 sptr,sptr,sptr
#comfunc global IVssHardwareSnapshotProvider_BeginPrepareSnapshot  5 int,int,int,int,sptr,sptr
#comfunc global IVssHardwareSnapshotProvider_GetTargetLuns         6 int,sptr,sptr,sptr
#comfunc global IVssHardwareSnapshotProvider_LocateLuns            7 int,sptr
#comfunc global IVssHardwareSnapshotProvider_OnLunEmpty            8 sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。