ホーム › Networking.BackgroundIntelligentTransferService › IBitsPeerCacheAdministration

IBitsPeerCacheAdministration

COM

📘 Microsoft Learn (日本語) · English

IID659cdead-489e-11d9-a9cd-000d56965251継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IBitsPeerCacheAdministration は、コンテンツのダウンロード元となるピアのプールを管理するために使用します。

解説(Remarks)

ピアキャッシュを自分で管理する必要は通常ありません。BITS がキャッシュを管理します。

キャッシュを変更するには管理者権限が必要です。

メソッド 14

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

vtbl 3 HRESULT GetMaximumCacheSize(DWORD* pBytes)

キャッシュの最大サイズを取得します。

pBytes

DWORD*

out

キャッシュの最大サイズ。利用可能なハードディスクドライブ領域に対する割合 (パーセント) で表されます。

戻り値

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

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

vtbl 4 HRESULT SetMaximumCacheSize(DWORD Bytes)

キャッシュの最大サイズを指定します。

Bytes

DWORD

キャッシュの最大サイズ。利用可能なハードディスクドライブ領域に対する割合 (パーセント) で表されます。

戻り値

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

戻り値	説明
S_OK	成功しました。
S_FALSE	構成の設定値は正常に保存されましたが、設定されているグループポリシーが優先されるため、この設定値は使用されません。

解説(Remarks)

この値は、MaxCacheSize グループポリシーが設定されていない場合にのみ使用されます。

キャッシュが最大サイズに達すると、BITS は必要なディスク領域が確保されるまで、最後にアクセスされた時期が最も古いファイルから順に削除します。現在のキャッシュサイズより小さい値を指定した場合、BITS は要求されたサイズになるまでキャッシュからファイルを削除します。BITS は経過時間に基づいてファイルを削除します。キャッシュサイズより大きいファイルはキャッシュされません。

既定では、キャッシュの最大サイズはディスクサイズの 1% です。BITS はこの上限を使ってキャッシュ用のディスク領域を予約するわけではありません。ディスク領域に空きがある場合に、指定した上限までをキャッシュに使用します。指定できる最大値はディスクサイズの 80% です。

キャッシュサイズを縮小する要求が行われた時点で、BITS がキャッシュ内のファイルをダウンロード中である場合、BITS はそのダウンロードが完了するまでファイルを削除しません。

vtbl 5 HRESULT GetMaximumContentAge(DWORD* pSeconds)

ファイルがキャッシュから削除されるまでの経過時間を取得します。

pSeconds

DWORD*

out

経過時間 (秒単位)。ファイルに最後にアクセスされた時点からの経過時間がこの値を超えると、BITS はそのファイルをキャッシュから削除します。

戻り値

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

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

vtbl 6 HRESULT SetMaximumContentAge(DWORD Seconds)

経過時間に基づいて、ファイルをキャッシュから削除するタイミングを指定します。

Seconds

DWORD

経過時間 (秒単位)。ファイルに最後にアクセスされた時点からの経過時間がこの値を超えると、BITS はそのファイルをキャッシュから削除します。経過時間はファイルにアクセスされるたびにリセットされます。最大値は 10,368,000 秒 (120 日)、最小値は 86,400 秒 (1 日) です。既定値は 7,776,000 秒 (90 日) です。

戻り値

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

戻り値	説明
S_OK	成功しました。
S_FALSE	構成の設定値は正常に保存されましたが、設定されているグループポリシーが優先されるため、この設定値は使用されません。

解説(Remarks)

この値は、MaxContentAge グループポリシーが設定されていない場合にのみ使用されます。

vtbl 7 HRESULT GetConfigurationFlags(DWORD* pFlags)

コンピューターがピアにコンテンツを提供できるかどうか、およびピアからコンテンツをダウンロードできるかどうかを決定する構成フラグを取得します。

pFlags

DWORD*

out

コンピューターがピアにコンテンツを提供できるかどうか、およびピアからコンテンツをダウンロードできるかどうかを決定するフラグです。設定できるフラグは次のとおりです。

値	意味
BG_ENABLE_PEERCACHING_CLIENT 0x0001	コンピューターはピアからコンテンツをダウンロードできます。
BG_ENABLE_PEERCACHING_SERVER 0x0002	コンピューターはピアにコンテンツを提供できます。

戻り値

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

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

解説(Remarks)

BITS がピアからダウンロードできるのは、コンピューターレベルとジョブレベルの両方でピアキャッシュが有効になっている場合のみです。この API はコンピューターレベルにのみ影響します。詳細については、IBitsPeerCacheAdministration::SetConfigurationFlags を参照してください。

ピアキャッシュは、グループポリシーによって有効化される場合と、IBitsPeerCacheAdministration::SetConfigurationFlags メソッドの呼び出しによって有効化される場合があります。

vtbl 8 HRESULT SetConfigurationFlags(DWORD Flags)

コンピューターがピアにコンテンツを提供できるかどうか、およびピアからコンテンツをダウンロードできるかどうかを決定する構成フラグを設定します。

Flags

DWORD

値

意味

BG_ENABLE_PEERCACHING_CLIENT
0x0001

コンピューターはピアからコンテンツをダウンロードできます。

クライアントコンピューターとジョブの両方がピアからのダウンロードを許可していない限り、BITS はピアからファイルをダウンロードしません。ジョブがピアからファイルをダウンロードできるようにするには、IBackgroundCopyJob4::SetPeerCachingFlags メソッドを呼び出して BG_JOB_ENABLE_PEERCACHING_CLIENT フラグを設定します。

この値を変更すると、コンピューター上のすべてのジョブに影響する可能性があることに注意してください。次のいずれかの状況が発生した場合、BITS はダウンロードを停止し、ジョブとキャッシュの値に応じて、ピアまたは配信元サーバーのいずれかから転送を開始するようジョブを再スケジュールします。

キャッシュ側のこの値が TRUE で、ジョブ側の値が TRUE と FALSE の間で切り替わった場合。
ジョブ側のプロパティのこの値が TRUE で、キャッシュ側の値が TRUE と FALSE の間で切り替わった場合。

その後、ダウンロードは BITS がジョブを停止する前の位置から再開されます。

BG_ENABLE_PEERCACHING_SERVER
0x0002

コンピューターはピアにコンテンツを提供できます。

クライアントコンピューターとジョブの両方がファイルのキャッシュと提供を許可していない限り、BITS はファイルをキャッシュしてピアに提供することはありません。ジョブのファイルをキャッシュできるようにするには、IBackgroundCopyJob4::SetPeerCachingFlags メソッドを呼び出して BG_JOB_ENABLE_PEERCACHING_SERVER フラグを設定します。

戻り値

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

戻り値	説明
S_OK	成功しました。
BG_S_OVERRIDDEN_BY_POLICY	構成の設定値は正常に保存されましたが、設定されているグループポリシーが優先されるため、この設定値は使用されません。このメソッドは、設定した値がグループポリシーの値と異なる場合にこの値を返します。値が同じ場合は S_OK を返します。

解説(Remarks)

この値は、EnablePeerCaching グループポリシーが設定されていない場合にのみ使用されます。

ピアからコンテンツをダウンロードするか、ピアにコンテンツを提供するかは、ジョブ側でも決定されます。詳細については、IBackgroundCopyJob4::SetPeerCachingFlags メソッドを参照してください。

vtbl 9 HRESULT EnumRecords(IEnumBitsPeerCacheRecords** ppEnum)

キャッシュ内のレコードを列挙するために使用する IEnumBitsPeerCacheRecords インターフェイスポインターを取得します。この列挙は、キャッシュ内のレコードのスナップショットです。

ppEnum

IEnumBitsPeerCacheRecords**

out

キャッシュ内のレコードを列挙するために使用する IEnumBitsPeerCacheRecords インターフェイスポインターです。使用が終わったら ppEnum を解放してください。

戻り値

このメソッドは、成功した場合は S_OK を、エラーの場合は標準 COM の HRESULT 値のいずれかを返します。

vtbl 10 HRESULT GetRecord(GUID* id, IBitsPeerCacheRecord** ppRecord)

キャッシュからレコードを取得します。

id	GUID*	in	キャッシュから取得するレコードの識別子です。識別子は IBitsPeerCacheRecord::GetId メソッドで取得できます。
ppRecord	IBitsPeerCacheRecord**	out	キャッシュレコードの IBitsPeerCacheRecord インターフェイスです。使用が終わったら ppRecord を解放してください。

戻り値

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

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

vtbl 11 HRESULT ClearRecords()

キャッシュからすべてのレコードとファイルを削除します。

戻り値

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

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

解説(Remarks)

現在実行中のキャッシュ操作がすべて完了するまで、キャッシュはクリアされません。

vtbl 12 HRESULT DeleteRecord(GUID* id)

キャッシュからレコードとファイルを削除します。このメソッドは、レコードの識別子を使用して削除対象のレコードを特定します。

GUID*

キャッシュから削除するレコードの識別子です。識別子は IBitsPeerCacheRecord::GetId メソッドで取得できます。

戻り値

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

戻り値	説明
S_OK	成功しました。
BG_E_BUSYCACHERECORD	キャッシュレコードが使用中のため、変更または削除できません。数秒後に再試行してください。

解説(Remarks)

そのキャッシュレコードに対する現在の操作がすべて完了するまで、キャッシュレコードは削除されません。

vtbl 13 HRESULT DeleteUrl(LPWSTR url)

指定した URL に対応するすべてのキャッシュレコードとファイルをキャッシュから削除します。

url

LPWSTR

キャッシュレコードとファイルをキャッシュから削除する対象ファイルの URL を含む、null 終端文字列です。

戻り値

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

戻り値	説明
S_OK	成功しました。
S_FALSE	指定された URL は存在しません。
BG_E_BUSYCACHERECORD	キャッシュレコードが使用中のため、変更または削除できません。数秒後に再試行してください。

解説(Remarks)

そのファイルのキャッシュレコードに対する現在の操作がすべて完了するまで、キャッシュレコードは削除されません。

vtbl 14 HRESULT EnumPeers(IEnumBitsPeers** ppEnum)

コンテンツを提供できるピアを列挙するために使用する IEnumBitsPeers インターフェイスポインターを取得します。この列挙は、キャッシュ内のレコードのスナップショットです。

ppEnum

IEnumBitsPeers**

out

コンテンツを提供できるピアを列挙するために使用する IEnumBitsPeers インターフェイスポインターです。使用が終わったら ppEnum を解放してください。

戻り値

このメソッドは、成功した場合は S_OK を、エラーの場合は標準 COM の HRESULT 値のいずれかを返します。

vtbl 15 HRESULT ClearPeers()

コンテンツを提供できるピアの一覧から、すべてのピアを削除します。

戻り値

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

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

解説(Remarks)

このメソッドを呼び出す必要は通常ありません。

BITS は、ジョブがピアにコンテンツを要求したときに新しいピアを自動的に検出します。また、IBitsPeerCacheAdministration::DiscoverPeers メソッドを呼び出して、ピアの検出を強制することもできます。

vtbl 16 HRESULT DiscoverPeers()

コンテンツを提供できるピアの一覧を生成します。

戻り値

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

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

解説(Remarks)

このメソッドを呼び出す必要は通常ありません。

BITS は、ジョブがピアにコンテンツを要求した際にクライアントのピア一覧に十分なピアがない場合、新しいピアを自動的に検出します。ピアは、クライアントと同じ Windows ドメインおよびサブネットに属し、ピアへのコンテンツ提供が有効になっている必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IBitsPeerCacheAdministration "{659CDEAD-489E-11D9-A9CD-000D56965251}"
#usecom global IBitsPeerCacheAdministration IID_IBitsPeerCacheAdministration "{}"
#comfunc global IBitsPeerCacheAdministration_GetMaximumCacheSize    3 var
#comfunc global IBitsPeerCacheAdministration_SetMaximumCacheSize    4 int
#comfunc global IBitsPeerCacheAdministration_GetMaximumContentAge   5 var
#comfunc global IBitsPeerCacheAdministration_SetMaximumContentAge   6 int
#comfunc global IBitsPeerCacheAdministration_GetConfigurationFlags  7 var
#comfunc global IBitsPeerCacheAdministration_SetConfigurationFlags  8 int
#comfunc global IBitsPeerCacheAdministration_EnumRecords            9 sptr
#comfunc global IBitsPeerCacheAdministration_GetRecord              10 var,sptr
#comfunc global IBitsPeerCacheAdministration_ClearRecords           11
#comfunc global IBitsPeerCacheAdministration_DeleteRecord           12 var
#comfunc global IBitsPeerCacheAdministration_DeleteUrl              13 wstr
#comfunc global IBitsPeerCacheAdministration_EnumPeers              14 sptr
#comfunc global IBitsPeerCacheAdministration_ClearPeers             15
#comfunc global IBitsPeerCacheAdministration_DiscoverPeers          16
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IBitsPeerCacheAdministration "{659CDEAD-489E-11D9-A9CD-000D56965251}"
#usecom global IBitsPeerCacheAdministration IID_IBitsPeerCacheAdministration "{}"
#comfunc global IBitsPeerCacheAdministration_GetMaximumCacheSize    3 sptr
#comfunc global IBitsPeerCacheAdministration_SetMaximumCacheSize    4 int
#comfunc global IBitsPeerCacheAdministration_GetMaximumContentAge   5 sptr
#comfunc global IBitsPeerCacheAdministration_SetMaximumContentAge   6 int
#comfunc global IBitsPeerCacheAdministration_GetConfigurationFlags  7 sptr
#comfunc global IBitsPeerCacheAdministration_SetConfigurationFlags  8 int
#comfunc global IBitsPeerCacheAdministration_EnumRecords            9 sptr
#comfunc global IBitsPeerCacheAdministration_GetRecord              10 sptr,sptr
#comfunc global IBitsPeerCacheAdministration_ClearRecords           11
#comfunc global IBitsPeerCacheAdministration_DeleteRecord           12 sptr
#comfunc global IBitsPeerCacheAdministration_DeleteUrl              13 wstr
#comfunc global IBitsPeerCacheAdministration_EnumPeers              14 sptr
#comfunc global IBitsPeerCacheAdministration_ClearPeers             15
#comfunc global IBitsPeerCacheAdministration_DiscoverPeers          16
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。