Win32 API 日本語リファレンス
ホーム › Networking.BackgroundIntelligentTransferService › IBackgroundCopyFile3

IBackgroundCopyFile3

COM
📘 Microsoft Learn (日本語) · English
IID659cdeaa-489e-11d9-a9cd-000d56965251継承元IBackgroundCopyFile2自前メソッド開始 vtbl8

公式ドキュメント

このインターフェイスは、ダウンロードしたコンテンツを格納する一時ファイルの名前を取得したり、ピアがそのコンテンツを要求できるようにファイルを検証したりするために使用します。

メソッド 4

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

vtbl 8 HRESULT GetTemporaryName(LPWSTR* pFilename)

ダウンロードのコンテンツを格納する一時ファイルのフルパスを取得します。

pFilenameLPWSTR*out一時ファイルのフルパスを格納する NULL 終端文字列。使用後は CoTaskMemFree 関数を呼び出して ppFileName を解放してください。

戻り値

このメソッドは次の戻り値を返します。

戻り値 説明
S_OK
 成功しました。

解説(Remarks)

アプリケーションはこのメソッドを使用して、ジョブの完了前にデータへアクセスできます。ファイルは共有書き込みアクセス (FILE_SHARE_WRITE) で開いてください。何バイトが転送済みで読み取り可能かを確認するには、IBackgroundCopyFile::GetProgress メソッドを呼び出します。なお、URL のタイムスタンプが変化した場合、進行状況の情報はゼロにリセットされます。

BITS がファイルの転送を開始するまでは、ファイルを読み取り用に開かないでください。開いた場合、ジョブは一時的なエラー状態になります。

一時ファイルは、アプリケーションが IBackgroundCopyJob::Complete または IBackgroundCopyJob::Cancel メソッドを呼び出すまで、あるいは JobInactivityTimeout グループポリシーの期限が切れるまで利用できます。Complete または Cancel メソッドを呼び出す前に、一時ファイルのハンドルを解放する必要があります。

Complete が呼び出された時点で、一時ファイルの ACL は最終的なファイルの ACL と同じになります (ACL はフォルダーから継承されます)。

BITS がファイルの転送を完了したかどうかを判断するには、次の方法があります。

vtbl 9 HRESULT SetValidationState(BOOL state)

このファイルの検証状態を設定します。

stateBOOLinファイルの内容が有効な場合は TRUE、そうでない場合は FALSE を設定します。

戻り値

このメソッドは次の戻り値を返します。

戻り値 説明
S_OK
 成功しました。
E_PENDING
 ダウンロードが完了するまでファイルを検証することはできません。
BG_E_RECORD_DELETED
 このファイルに関連付けられたキャッシュ済みレコードは削除されています。

解説(Remarks)

検証状態を FALSE に設定し、そのファイルがオリジンサーバーからダウンロードされたものである場合、ジョブはエラーコード BG_E_VALIDATION_FAILED でエラー状態に移行し、ファイルの進行状況はゼロに設定されます。その後、IBackgroundCopyJob::Resume メソッドを呼び出して、ファイルを再度ダウンロードできます。

BITS 3.0: ファイルを再度ダウンロードするために IBackgroundCopyJob::Resume メソッドを呼び出さないでください。代わりに、IBackgroundCopyJob::Complete または IBackgroundCopyJob::Cancel メソッドを呼び出して現在のジョブをクリーンアップし、ファイルをダウンロードするための新しいジョブを作成してください。

検証状態を FALSE に設定し、そのファイルがピアからダウンロードされたものである場合、BITS はそのファイルをキャッシュから削除し、ファイルの進行状況をゼロにリセットして、オリジンサーバーからファイルを再度ダウンロードします。

このメソッドは、BITS がファイルの転送を完了した後にのみ呼び出せます。転送完了時に通知を受け取るには、IBackgroundCopyCallback2::FileTransferred メソッドを実装してください。

IBackgroundCopyJob::Complete メソッドを呼び出すと、暗黙的にファイルが検証されます。

キャッシュ内のファイルを検証した後に IBackgroundCopyJob4::SetPeerCachingFlags を呼び出してキャッシュを無効化した場合 (またはグループポリシーによってピアキャッシュが無効化されている場合)、ファイルはキャッシュ内に残ります。ファイルを検証する前にキャッシュを無効化した場合、BITS はそのファイルをキャッシュから削除します。

vtbl 10 HRESULT GetValidationState(BOOL* pState)

このファイルの現在の検証状態を取得します。

pStateBOOL*outファイルの内容が有効な場合は TRUE、そうでない場合は FALSE。

戻り値

このメソッドは次の戻り値を返します。

戻り値 説明
S_OK
 成功しました。

解説(Remarks)

FALSE はファイルが無効であることを意味するとは限らず、IBackgroundCopyFile3::SetValidationState がまだ呼び出されていないことを意味する場合もある点に注意してください。

vtbl 11 HRESULT IsDownloadedFromPeer(BOOL* pVal)

ファイルの一部でもピアからダウンロードされたかどうかを示す値を取得します。

pValBOOL*outファイルの一部でもピアからダウンロードされた場合は TRUE、そうでない場合は FALSE。

戻り値

このメソッドは次の戻り値を返します。

戻り値 説明
S_OK
 成功しました。
出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IBackgroundCopyFile3 "{659CDEAA-489E-11D9-A9CD-000D56965251}"
#usecom global IBackgroundCopyFile3 IID_IBackgroundCopyFile3 "{}"
#comfunc global IBackgroundCopyFile3_GetTemporaryName      8 var
#comfunc global IBackgroundCopyFile3_SetValidationState    9 int
#comfunc global IBackgroundCopyFile3_GetValidationState    10 var
#comfunc global IBackgroundCopyFile3_IsDownloadedFromPeer  11 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。