ホーム › Storage.DataDeduplication › IDedupReadFileCallback

IDedupReadFileCallback

COM

IID7bacc67a-2f1d-42d0-897e-6ff62dd533bb継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

バックアップアプリケーションが実装するコールバックインターフェイスで、バックアップストア内に存在するメタデータファイルおよびコンテナーファイルから、データ重複除去 (Data Deduplication) がコンテンツを読み取れるようにし、必要に応じて復元の効率を向上させます。

解説(Remarks)

IDedupReadFileCallback インターフェイスはバックアップアプリケーションによって実装され、IDedupBackupSupport::RestoreFiles メソッドのパラメーターとして渡されます。このコールバックは、バックアップストア内のデータ重複除去ストアコンテナーからデータを読み取るために、データ重複除去によって使用されます。IDedupReadFileCallback には、データ重複除去のファイル復元処理の効率を高めるためにアプリケーションが任意で実装できるメソッドも含まれています。

メソッド 3

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

vtbl 3 HRESULT ReadBackupFile(LPWSTR FileFullPath, LONGLONG FileOffset, DWORD SizeToRead, BYTE* FileBuffer, DWORD* ReturnedSize, DWORD Flags)

バックアップストア内にあるデータ重複除去ストアのメタデータファイルまたはコンテナーファイルからデータを読み取ります。

FileFullPath	LPWSTR	in	ボリュームのルートディレクトリからコンテナーファイルまでのフルパス。
FileOffset	LONGLONG	in	ファイルの先頭から、読み取り対象データの先頭までのオフセット (バイト単位)。
SizeToRead	DWORD	in	ファイルから読み取るバイト数。
FileBuffer	BYTE*	out	ファイルから読み取ったデータを受け取るバッファーへのポインター。バッファーのサイズは SizeToRead パラメーターで指定された値以上でなければなりません。
ReturnedSize	DWORD*	out	バックアップストアから読み取られたバイト数を受け取る ULONG 変数へのポインター。ReadBackupFile の呼び出しが成功した場合、この値は SizeToRead パラメーターで指定された値と等しくなります。
Flags	DWORD	in	このパラメーターは将来の使用のために予約されています。

戻り値

このメソッドは、S_OK などの標準的な HRESULT 値を返すことができます。また、HRESULT_FROM_WIN32 マクロを使用して変換されたシステムエラーコードを返すこともあります。返される可能性のある値は次のとおりです。

vtbl 4 HRESULT OrderContainersRestore(DWORD NumberOfContainers, LPWSTR* ContainerPaths, DWORD* ReadPlanEntries, DEDUP_CONTAINER_EXTENT** ReadPlan)

対象ファイルを取得するために必要な保留中の読み取りの順序に、アプリケーションが影響を与えられるようにするメソッドです。

NumberOfContainers	DWORD	in	ContainerPaths 配列内のコンテナーパスの数。
ContainerPaths	LPWSTR*	in	`<a href="/previous-versions/windows/desktop/api/ddpbackup/nf-ddpbackup-idedupbackupsupport-restorefiles">IDedupBackupSupport::RestoreFiles</a> の呼び出しで指定されたファイルを復元するために読み取る必要があるコンテナーファイルのパスの配列。各要素は、ボリュームのルートディレクトリからコンテナーファイルまでのフルパスです。`
ReadPlanEntries	DWORD*	out	ReadPlan パラメーターが指す配列内の DEDUP_CONTAINER_EXTENT 構造体の数を受け取る ULONG 変数へのポインター。
ReadPlan	DEDUP_CONTAINER_EXTENT**	out	`<a href="/windows/desktop/api/ddpbackup/ns-ddpbackup-dedup_container_extent">DEDUP_CONTAINER_EXTENT</a> 構造体の配列を受け取るバッファーへのポインター。`

戻り値

このメソッドは、 S_OK などの標準的な HRESULT 値を返すことができます。また、 HRESULT_FROM_WIN32 マクロを使用して変換されたシステムエラーコードを返すこともあります。返される可能性のある値は次のとおりです。

解説(Remarks)

復元対象ファイルのデータを保持しているコンテナーファイルの一覧が与えられると、アプリケーションは任意で、効率的なコンテナー横断の読み取りプランとなるように、コンテナーストアのファイルエクステントの一覧をソートされた順序で生成できます。バックアップストアがテープ上にある場合、通常はテープ順になります。

コンテナーがバックアップストア内で複数のエクステントに分割して格納されている場合 (たとえば増分バックアップの連鎖の結果として)、アプリケーションは論理的なコンテナーファイルごとに複数のコンテナーエクステントを返すこともできます。

アプリケーションは、 S_OK と NULL の出力パラメーターを返すことで、読み取りプランの最適化をスキップできます。この場合、コンテナーの読み取り順序はデータ重複除去によって選択されます。

vtbl 5 HRESULT PreviewContainerRead(LPWSTR FileFullPath, DWORD NumberOfReads, DDP_FILE_EXTENT* ReadOffsets)

指定されたコンテナーファイルエクステントに対して保留中となっている読み取りのシーケンスを、アプリケーションにプレビューとして提供します。

FileFullPath	LPWSTR	in	ボリュームのルートディレクトリからコンテナーファイルまでのフルパス。
NumberOfReads	DWORD	in	ReadOffsets パラメーターが指す配列内の DDP_FILE_EXTENT 構造体の数。
ReadOffsets	DDP_FILE_EXTENT*	in	DDP_FILE_EXTENT 構造体の配列へのポインター。

戻り値

解説(Remarks)

PreviewContainerRead は、IDedupReadFileCallback::OrderContainersRestore によって報告されたコンテナーファイルエクステントごとに呼び出されます。アプリケーションはこのプレビューを、コンテナーエクステント単位の読み取りプランとして利用し、保留中の読み取りの効率を高めることができます。たとえば、スループットを向上させるために先読みを行ったり、並列するファイル復元操作全体のパフォーマンスを向上させるために読み取りバッファーをキャッシュしたりすることが考えられます。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IDedupReadFileCallback "{7BACC67A-2F1D-42D0-897E-6FF62DD533BB}"
#usecom global IDedupReadFileCallback IID_IDedupReadFileCallback "{}"
#comfunc global IDedupReadFileCallback_ReadBackupFile          3 wstr,int64,int,var,var,int
#comfunc global IDedupReadFileCallback_OrderContainersRestore  4 int,var,var,var
#comfunc global IDedupReadFileCallback_PreviewContainerRead    5 wstr,int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IDedupReadFileCallback "{7BACC67A-2F1D-42D0-897E-6FF62DD533BB}"
#usecom global IDedupReadFileCallback IID_IDedupReadFileCallback "{}"
#comfunc global IDedupReadFileCallback_ReadBackupFile          3 wstr,int64,int,sptr,sptr,int
#comfunc global IDedupReadFileCallback_OrderContainersRestore  4 int,sptr,sptr,sptr
#comfunc global IDedupReadFileCallback_PreviewContainerRead    5 wstr,int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。