ホーム › Storage.Vss › IVssSoftwareSnapshotProvider

IVssSoftwareSnapshotProvider

COM

📘 Microsoft Learn (日本語) · English

IID609e123e-2c5a-44d3-8f01-0b1d9a47d1ff継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

VSS がシャドウコピーのボリュームを管理するために使用するメソッドを提供します。すべてのソフトウェアプロバイダーはこのインターフェイスをサポートする必要があります。

メソッド 10

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

vtbl 3 HRESULT SetContext(INT lContext)

以降のシャドウコピー関連の操作に使用するコンテキストを設定します。

lContext

INT

設定するコンテキストです。コンテキストは、_VSS_SNAPSHOT_CONTEXT のサポートされる値のいずれか、または _VSS_VOLUME_SNAPSHOT_ATTRIBUTES と _VSS_SNAPSHOT_CONTEXT の値のサポートされる組み合わせである必要があります。

戻り値

このメソッドの有効な戻り値は次のとおりです。

値	意味
S_OK	コンテキストが正常に設定されました。
E_ACCESSDENIED	呼び出し元に十分なバックアップ特権がないか、管理者ではありません。
E_INVALIDARG	いずれかのパラメーター値が有効ではありません。
E_OUTOFMEMORY	呼び出し元のメモリまたはその他のシステムリソースが不足しています。
VSS_E_BAD_STATE	コンテキストが凍結されており、変更できません。

解説(Remarks)

VSS のシャドウコピーの既定のコンテキストは VSS_CTX_BACKUP です。

Windows XP: サポートされるコンテキストは既定のコンテキストである VSS_CTX_BACKUP のみです。そのため、Windows XP で SetContext を呼び出すと E_NOTIMPL が返されます。

SetContext によって設定されるコンテキストが、シャドウコピーの作成と管理にどのように影響するかについては、 Implementation Details for Creating Shadow Copies を参照してください。

許可されるシャドウコピーのコンテキストの詳細については、 _VSS_SNAPSHOT_CONTEXT および _VSS_VOLUME_SNAPSHOT_ATTRIBUTES を参照してください。

vtbl 4 HRESULT GetSnapshotProperties(GUID SnapshotId, VSS_SNAPSHOT_PROP* pProp)

指定されたシャドウコピーのプロパティを取得します。

SnapshotId	GUID	in	シャドウコピーの識別子です。
pProp	VSS_SNAPSHOT_PROP*	out	シャドウコピーのプロパティを受け取る、呼び出し元が割り当てた VSS_SNAPSHOT_PROP 構造体のアドレスです。この構造体のメンバーを設定するのはプロバイダーの責任です。m_pwszExposedName と m_pwszExposedPath はプロバイダーが NULL に設定できますが、それ以外のすべてのメンバーは必須です。プロバイダーは、構造体内で設定するすべての文字列メンバーのメモリを割り当てます。構造体が不要になったら、呼び出し元は VssFreeSnapshotProperties 関数を呼び出してこれらの文字列を解放する必要があります。

戻り値

このメソッドの有効な戻り値は次のとおりです。

値	意味
S_OK	要求された情報が正常に返されました。
E_ACCESSDENIED	呼び出し元に十分なバックアップ特権がないか、管理者ではありません。
E_INVALIDARG	いずれかのパラメーター値が有効ではありません。
E_OUTOFMEMORY	呼び出し元のメモリまたはその他のシステムリソースが不足しています。
VSS_E_OBJECT_NOT_FOUND	指定されたボリュームが見つかりませんでした。
VSS_E_PROVIDER_VETO	プロバイダーのエラーです。プロバイダーはイベントログにエラーを記録しました。詳細については、 Event and Error Handling Under VSS を参照してください。
VSS_E_UNEXPECTED	予期しないエラーです。エラーコードはエラーログファイルに記録されます。詳細については、 Event and Error Handling Under VSS を参照してください。 Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: この値は Windows Server 2008 R2 および Windows 7 までサポートされません。代わりに E_UNEXPECTED が使用されます。

解説(Remarks)

呼び出し元は、GetSnapshotProperties メソッドを呼び出す前に、VSS_SNAPSHOT_PROP 構造体の内容をゼロに設定する必要があります。

VSS_SNAPSHOT_PROP 構造体内の文字列の割り当てと解放は、プロバイダーの責任です。

vtbl 5 HRESULT Query(GUID QueriedObjectId, VSS_OBJECT_TYPE eQueriedObjectType, VSS_OBJECT_TYPE eReturnedObjectsType, IVssEnumObject** ppEnum)

プロバイダーが完了したシャドウコピーに関する情報を、プロバイダーに照会します。

QueriedObjectId	GUID	in	システムでの使用のために予約されています。このパラメーターの値は GUID_NULL である必要があります。
eQueriedObjectType	VSS_OBJECT_TYPE	in	システムでの使用のために予約されています。このパラメーターの値は VSS_OBJECT_NONE である必要があります。
eReturnedObjectsType	VSS_OBJECT_TYPE	in	システムでの使用のために予約されています。このパラメーターの値は VSS_OBJECT_SNAPSHOT である必要があります。
ppEnum	IVssEnumObject**	out	IVssEnumObject インターフェイスポインターのアドレスで、戻り時に初期化されます。呼び出し元はこのインターフェイスを解放する必要があります。このパラメーターは必須であり、null にはできません。

戻り値

このメソッドの有効な戻り値は次のとおりです。

値	意味
S_OK	クエリ操作が成功しました。
E_ACCESSDENIED	呼び出し元に十分なバックアップ特権がないか、管理者ではありません。
E_INVALIDARG	いずれかのパラメーター値が有効ではありません。
E_OUTOFMEMORY	呼び出し元のメモリまたはその他のシステムリソースが不足しています。
VSS_E_PROVIDER_VETO	プロバイダーのエラーです。プロバイダーはイベントログにエラーを記録しました。詳細については、 Event and Error Handling Under VSS を参照してください。

解説(Remarks)

ppEnum パラメーターを通じて返される IVssEnumObject インターフェイスで IVssEnumObject::Next メソッドを呼び出すと、各シャドウコピーの VSS_SNAPSHOT_PROP 構造体を含む VSS_OBJECT_PROP 構造体が返されます。

vtbl 6 HRESULT DeleteSnapshots(GUID SourceObjectId, VSS_OBJECT_TYPE eSourceObjectType, BOOL bForceDelete, INT* plDeletedSnapshots, GUID* pNondeletedSnapshotID)

1 つ以上のシャドウコピー、またはシャドウコピーセットを削除します。

SourceObjectId	GUID	in	削除するシャドウコピーまたはシャドウコピーセットの識別子です。
eSourceObjectType	VSS_OBJECT_TYPE	in	削除するオブジェクトの種類です。このパラメーターの値は VSS_OBJECT_SNAPSHOT または VSS_OBJECT_SNAPSHOT_SET です。
bForceDelete	BOOL	in	このパラメーターの値が TRUE の場合、プロバイダーはシャドウコピー、またはシャドウコピーセット内のシャドウコピーを削除するために可能な限りの処理を行います。FALSE の場合、追加の処理は行われません。
plDeletedSnapshots	INT*	out	削除されたシャドウコピーの数を受け取る変数へのポインターです。
pNondeletedSnapshotID	GUID*	out	エラーが発生した場合、このパラメーターは削除できなかった最初のシャドウコピーの識別子へのポインターを受け取ります。それ以外の場合は GUID_NULL を指します。

戻り値

このメソッドの有効な戻り値は次のとおりです。

値	意味
S_OK	シャドウコピーが正常に削除されました。
E_ACCESSDENIED	呼び出し元に十分なバックアップ特権がないか、管理者ではありません。
E_INVALIDARG	いずれかのパラメーター値が有効ではありません。
E_OUTOFMEMORY	呼び出し元のメモリまたはその他のシステムリソースが不足しています。
VSS_E_OBJECT_NOT_FOUND	指定されたシャドウコピーが見つかりませんでした。
VSS_E_PROVIDER_VETO	プロバイダーのエラーです。プロバイダーはイベントログにエラーを記録しました。詳細については、 Event and Error Handling Under VSS を参照してください。

解説(Remarks)

シャドウコピーセット内の複数のシャドウコピーは順番に削除されます。個々の削除処理の途中でエラーが発生した場合、DeleteSnapshots は直ちに戻り、残りのシャドウコピーを削除する試みは行われません。削除されなかったシャドウコピーの VSS_ID は pNondeletedSnapshotID に返されます。

vtbl 7 HRESULT BeginPrepareSnapshot(GUID SnapshotSetId, GUID SnapshotId, WORD* pwszVolumeName, INT lNewContext)

VSS は、シャドウコピーセットに追加される各シャドウコピーについてこのメソッドを呼び出します。(IVssSoftwareSnapshotProvider.BeginPrepareSnapshot)

SnapshotSetId	GUID	in	シャドウコピーセットの識別子です。
SnapshotId	GUID	in	作成するシャドウコピーの識別子です。
pwszVolumeName	WORD*	in	ボリューム名を含む NULL 終端のワイド文字列です。名前は次のいずれかの形式でなければならず、末尾に円記号 (\) を含む必要があります。マウントされたフォルダーのパス (例: Y:\MountX\) ドライブ文字 (例: D:\) \\?\Volume{GUID}\ 形式のボリューム GUID パス (GUID はボリュームを識別します)
lNewContext	INT	in	シャドウコピーセットのコンテキストです。このコンテキストは _VSS_VOLUME_SNAPSHOT_ATTRIBUTES 値のビットマスクで構成されます。

戻り値

このメソッドの有効な戻り値は次のとおりです。

値	意味
S_OK	シャドウコピーが正常に作成されました。
E_ACCESSDENIED	呼び出し元に十分なバックアップ特権がないか、管理者ではありません。
E_INVALIDARG	いずれかのパラメーター値が有効ではありません。
E_OUTOFMEMORY	呼び出し元のメモリまたはその他のシステムリソースが不足しています。
VSS_E_OBJECT_NOT_FOUND	指定されたボリュームが見つかりませんでした。
VSS_E_PROVIDER_VETO	プロバイダーのエラーです。プロバイダーはイベントログにエラーを記録しました。詳細については、 Event and Error Handling Under VSS を参照してください。
VSS_E_UNSUPPORTED_CONTEXT	指定されたコンテキストはサポートされていません。
VSS_E_VOLUME_NOT_SUPPORTED_BY_PROVIDER	プロバイダーは指定されたボリュームをサポートしていません。
VSS_E_UNEXPECTED	予期しないエラーです。エラーコードはエラーログファイルに記録されます。詳細については、 Event and Error Handling Under VSS を参照してください。 Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: この値は Windows Server 2008 R2 および Windows 7 までサポートされません。代わりに E_UNEXPECTED が使用されます。

vtbl 8 HRESULT IsVolumeSupported(WORD* pwszVolumeName, BOOL* pbSupportedByThisProvider)

指定されたボリュームでプロバイダーがシャドウコピーをサポートするかどうかを判定します。

pwszVolumeName

WORD*

ボリューム名を含む NULL 終端のワイド文字列です。名前は次のいずれかの形式でなければならず、末尾に円記号 (\) を含む必要があります。

マウントされたフォルダーのパス (例: Y:\MountX\)
ドライブ文字 (例: D:\)
\\?\Volume{GUID}\ 形式のボリューム GUID パス (GUID はボリュームを識別します)

pbSupportedByThisProvider

BOOL*

out

指定されたボリュームでシャドウコピーがサポートされる場合、このパラメーターは TRUE を受け取ります。それ以外の場合は FALSE を受け取ります。

戻り値

このメソッドの有効な戻り値は次のとおりです。

値	意味
S_OK	要求された情報が正常に返されました。
E_ACCESSDENIED	呼び出し元に十分なバックアップ特権がないか、管理者ではありません。
E_INVALIDARG	いずれかのパラメーター値が有効ではありません。
VSS_E_NESTED_VOLUME_LIMIT	指定されたボリュームは入れ子が深すぎるため、VSS 操作に参加できません。 Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: この戻り値はサポートされていません。
E_OUTOFMEMORY	呼び出し元のメモリまたはその他のシステムリソースが不足しています。
VSS_E_OBJECT_NOT_FOUND	指定されたボリュームが見つかりませんでした。
VSS_E_PROVIDER_VETO	プロバイダーのエラーです。プロバイダーはイベントログにエラーを記録しました。詳細については、 Event and Error Handling Under VSS を参照してください。
VSS_E_UNEXPECTED	予期しないエラーです。エラーコードはエラーログファイルに記録されます。詳細については、 Event and Error Handling Under VSS を参照してください。 Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: この値は Windows Server 2008 R2 および Windows 7 までサポートされません。代わりに E_UNEXPECTED が使用されます。

解説(Remarks)

IsVolumeSupported メソッドは、指定されたボリューム上でシャドウコピーを作成することが可能であれば TRUE を返します。現在の構成ではそのボリューム上でのシャドウコピーの作成が現時点で許可されていない場合でも同様です。

たとえば、指定されたボリュームでシャドウコピーの最大数に達している場合 (したがって、そのボリューム上にこれ以上シャドウコピーを作成できない場合) でも、このメソッドはそのボリュームがシャドウコピー可能であることを示します。

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

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

vtbl 9 HRESULT IsVolumeSnapshotted(WORD* pwszVolumeName, BOOL* pbSnapshotsPresent, INT* plSnapshotCompatibility)

指定されたボリュームにシャドウコピーが存在するかどうかを判定します。

pwszVolumeName

WORD*

ボリューム名を含む NULL 終端のワイド文字列です。名前は次のいずれかの形式でなければならず、末尾に円記号 (\) を含む必要があります。

マウントされたフォルダーのパス (例: Y:\MountX\)
ドライブ文字 (例: D:\)
\\?\Volume{GUID}\ 形式のボリューム GUID パス (GUID はボリュームを識別します)

pbSnapshotsPresent

BOOL*

out

ボリュームにシャドウコピーがある場合、このパラメーターは TRUE を受け取ります。ボリュームにシャドウコピーがない場合は FALSE を受け取ります。

plSnapshotCompatibility

INT*

out

ボリュームにシャドウコピーがある場合に、特定のボリューム制御操作やファイル I/O 操作が無効化されるかどうかを示す VSS_SNAPSHOT_COMPATIBILITY 値のビットマスクです。

戻り値

このメソッドの有効な戻り値は次のとおりです。

値	意味
S_OK	要求された情報が正常に返されました。
E_ACCESSDENIED	呼び出し元に十分なバックアップ特権がないか、管理者ではありません。
E_INVALIDARG	いずれかのパラメーター値が有効ではありません。
E_OUTOFMEMORY	呼び出し元のメモリまたはその他のシステムリソースが不足しています。
VSS_E_OBJECT_NOT_FOUND	指定されたボリュームが見つかりませんでした。
VSS_E_PROVIDER_VETO	プロバイダーのエラーです。プロバイダーはイベントログにエラーを記録しました。詳細については、 Event and Error Handling Under VSS を参照してください。
VSS_E_UNEXPECTED	予期しないエラーです。エラーコードはエラーログファイルに記録されます。詳細については、 Event and Error Handling Under VSS を参照してください。 Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: この値は Windows Server 2008 R2 および Windows 7 までサポートされません。代わりに E_UNEXPECTED が使用されます。

解説(Remarks)

選択したボリュームで無効化されるボリューム制御操作やファイル I/O 操作がない場合、plSnapshotCapability が返す、選択したボリュームのシャドウコピー機能はゼロになります。

vtbl 10 HRESULT SetSnapshotProperty(GUID SnapshotId, VSS_SNAPSHOT_PROPERTY_ID eSnapshotPropertyId, VARIANT vProperty)

シャドウコピーのプロパティを設定します。

SnapshotId	GUID	in	シャドウコピーの識別子です。このパラメーターは必須であり、GUID_NULL にはできません。
eSnapshotPropertyId	VSS_SNAPSHOT_PROPERTY_ID	in	シャドウコピーに設定するプロパティを指定する VSS_SNAPSHOT_PROPERTY_ID 値です。
vProperty	VARIANT	in	プロパティに設定する値です。シャドウコピーに設定できるプロパティの有効なデータ型と説明については、VSS_SNAPSHOT_PROP 構造体を参照してください。

戻り値

このメソッドの有効な戻り値は次のとおりです。

値	意味
S_OK	プロパティが正常に設定されました。
E_ACCESSDENIED	呼び出し元に十分なバックアップ特権がないか、管理者ではありません。
E_INVALIDARG	いずれかのパラメーター値が有効ではありません。
E_OUTOFMEMORY	呼び出し元のメモリまたはその他のシステムリソースが不足しています。
VSS_E_OBJECT_NOT_FOUND	指定されたシャドウコピーが見つかりませんでした。

vtbl 11 HRESULT RevertToSnapshot(GUID SnapshotId)

ボリュームを以前のシャドウコピーに戻します。(IVssSoftwareSnapshotProvider.RevertToSnapshot)

SnapshotId

GUID

復元先となるシャドウコピーの識別子です。

戻り値

このメソッドの有効な戻り値は次のとおりです。

値	意味
S_OK	復元 (revert) 操作が成功しました。
E_ACCESSDENIED	呼び出し元に十分なバックアップ特権がないか、管理者ではありません。
E_INVALIDARG	いずれかのパラメーター値が有効ではありません。
E_OUTOFMEMORY	呼び出し元のメモリまたはその他のシステムリソースが不足しています。
VSS_E_REVERT_IN_PROGRESS	そのボリュームでは既に復元 (revert) 操作が進行中です。

解説(Remarks)

この操作はキャンセルできず、完了後に元に戻すこともできません。復元操作の実行中にコンピューターが再起動された場合、復元処理はシステムの再起動後に継続されます。

vtbl 12 HRESULT QueryRevertStatus(WORD* pwszVolume, IVssAsync** ppAsync)

復元 (revert) 操作の状態を判定するために使用できる IVssAsync インターフェイスポインターを返します。(IVssSoftwareSnapshotProvider.QueryRevertStatus)

pwszVolume

WORD*

ボリューム名を含む NULL 終端のワイド文字列です。名前は次のいずれかの形式でなければならず、末尾に円記号 (\) を含む必要があります。

マウントされたフォルダーのパス (例: Y:\MountX\)
ドライブ文字 (例: D:\)
\\?\Volume{GUID}\ 形式のボリューム GUID パス (GUID はボリュームを識別します)

ppAsync

IVssAsync**

out

復元 (revert) 操作の状態を取得するために使用できる IVssAsync インターフェイスポインターを受け取る場所へのポインターです。操作が完了したら、呼び出し元は IUnknown::Release メソッドを呼び出してインターフェイスポインターを解放する必要があります。

戻り値

このメソッドの有効な戻り値は次のとおりです。

値	意味
S_OK	復元 (revert) 操作の状態が正常に照会されました。
E_ACCESSDENIED	呼び出し元に十分なバックアップ特権がないか、管理者ではありません。
E_INVALIDARG	いずれかのパラメーター値が有効ではありません。
E_OUTOFMEMORY	呼び出し元のメモリまたはその他のシステムリソースが不足しています。
VSS_E_OBJECT_NOT_FOUND	pwszVolume パラメーターが有効なボリュームを指定していません。
VSS_E_VOLUME_NOT_SUPPORTED	このボリュームでは復元 (revert) 操作はサポートされていません。

解説(Remarks)

復元 (revert) 操作は、コンピューターが再起動されても継続され、別の方法で作成されたバックアップを復元する以外にキャンセルや取り消しはできません。復元操作は開始後にキャンセルできないため、IVssAsync::QueryStatus メソッドが VSS_S_ASYNC_CANCELLED を返すことはありません。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IVssSoftwareSnapshotProvider "{609E123E-2C5A-44D3-8F01-0B1D9A47D1FF}"
#usecom global IVssSoftwareSnapshotProvider IID_IVssSoftwareSnapshotProvider "{}"
#comfunc global IVssSoftwareSnapshotProvider_SetContext             3 int
#comfunc global IVssSoftwareSnapshotProvider_GetSnapshotProperties  4 int,var
#comfunc global IVssSoftwareSnapshotProvider_Query                  5 int,int,int,sptr
#comfunc global IVssSoftwareSnapshotProvider_DeleteSnapshots        6 int,int,int,var,var
#comfunc global IVssSoftwareSnapshotProvider_BeginPrepareSnapshot   7 int,int,var,int
#comfunc global IVssSoftwareSnapshotProvider_IsVolumeSupported      8 var,var
#comfunc global IVssSoftwareSnapshotProvider_IsVolumeSnapshotted    9 var,var,var
#comfunc global IVssSoftwareSnapshotProvider_SetSnapshotProperty    10 int,int,int
#comfunc global IVssSoftwareSnapshotProvider_RevertToSnapshot       11 int
#comfunc global IVssSoftwareSnapshotProvider_QueryRevertStatus      12 var,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IVssSoftwareSnapshotProvider "{609E123E-2C5A-44D3-8F01-0B1D9A47D1FF}"
#usecom global IVssSoftwareSnapshotProvider IID_IVssSoftwareSnapshotProvider "{}"
#comfunc global IVssSoftwareSnapshotProvider_SetContext             3 int
#comfunc global IVssSoftwareSnapshotProvider_GetSnapshotProperties  4 int,sptr
#comfunc global IVssSoftwareSnapshotProvider_Query                  5 int,int,int,sptr
#comfunc global IVssSoftwareSnapshotProvider_DeleteSnapshots        6 int,int,int,sptr,sptr
#comfunc global IVssSoftwareSnapshotProvider_BeginPrepareSnapshot   7 int,int,sptr,int
#comfunc global IVssSoftwareSnapshotProvider_IsVolumeSupported      8 sptr,sptr
#comfunc global IVssSoftwareSnapshotProvider_IsVolumeSnapshotted    9 sptr,sptr,sptr
#comfunc global IVssSoftwareSnapshotProvider_SetSnapshotProperty    10 int,int,int
#comfunc global IVssSoftwareSnapshotProvider_RevertToSnapshot       11 int
#comfunc global IVssSoftwareSnapshotProvider_QueryRevertStatus      12 sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。