SetFileBandwidthReservation 関数 (winbase.h)

指定したファイル ストリームの帯域幅を予約するように要求します。 この予約は、指定したファイル ハンドルでの I/O 要求のミリ秒単位の期間におけるバイト数として指定されます。

構文

BOOL SetFileBandwidthReservation(
  [in]  HANDLE  hFile,
  [in]  DWORD   nPeriodMilliseconds,
  [in]  DWORD   nBytesPerPeriod,
  [in]  BOOL    bDiscardable,
  [out] LPDWORD lpTransferSize,
  [out] LPDWORD lpNumOutstandingRequests
);

パラメーター

[in] hFile

ファイルへのハンドル。

[in] nPeriodMilliseconds

予約の期間 (ミリ秒単位)。 期間は、I/O が完了するまでにカーネルに対して I/O が発行される時間です。 ファイル ストリームでサポートされる最小値は、 lpPeriodMilliseconds パラメーターから GetFileBandwidthReservation 関数に返される値を、帯域幅予約が設定されていないハンドルで調べることで決定できます。

[in] nBytesPerPeriod

予約する帯域幅 (期間あたりのバイト単位)。 ファイル ストリームでサポートされる最大値は、 lpBytesPerPeriod パラメーターから GetFileBandwidthReservation 関数に返される値を、帯域幅予約が設定されていないハンドルで調べることで決定できます。

[in] bDiscardable

ドライバーが期限切れになる前に I/O 操作を満たすことができない場合に、エラーで I/O を完了する必要があるかどうかを示します。 指定したファイル ストリームのドライバーのいずれかがこの機能をサポートしていない場合、この関数は成功を返し、 フラグを無視する可能性があります。 設定が受け入れられるかどうかを確認するには、同じ hFile ハンドルを使用して GetFileBandwidthReservation 関数を呼び出し、*pDiscardable 戻り値を調べます。

[out] lpTransferSize

アプリケーションによって発行される可能性のある個々の I/O 要求の最小サイズを受け取る変数へのポインター。 すべての I/O 要求は 、TransferSize の倍数である必要があります。

[out] lpNumOutstandingRequests

アプリケーションがオペレーティング システムで未処理にできる TransferSize チャンクの数を受け取る変数へのポインター。 これにより、ストレージ スタックはデバイスをビジー状態に保ち、最大スループットを実現できます。

戻り値

成功した場合は 0 以外、それ以外の場合は 0 を返します。

既存の予約が原因でボリュームで使用可能な帯域幅が不足している場合、予約が失敗する可能性があります。この場合 、ERROR_NO_SYSTEM_RESOURCES が返されます。

詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

要求された帯域幅の予約は、期間ごとに 1 つのパケット以上である必要があります。 SetFileBandwidthReservation の呼び出しで使用されていないハンドルの GetFileBandwidthReservation に対する lpPeriodMilliseconds、lpBytesPerPeriod、lpTransferSize パラメーターを使用して、特定のボリュームの最小期間 (ミリ秒単位)、最大バイト数(バイト単位)、および最小転送サイズ (バイト単位) が返されます。 つまり、以下の要件が適用されます。

1 ≤ (nBytesPeriod)×(lpPeriodMilliseconds)/(lpTransferSize)/(nPeriodMilliseconds)

IIn Windows 8とWindows Server 2012、この関数は次のテクノロジでサポートされています。

テクノロジ	サポートされています
サーバー メッセージ ブロック (SMB) 3.0 プロトコル	いいえ
SMB 3.0 Transparent Failover (TFO)	いいえ
スケールアウト ファイル共有 (SO) を使う SMB 3.0	いいえ
クラスターの共有ボリューム ファイル システム (CsvFS)	いいえ
Resilient File System (ReFS)	はい

必要条件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップ アプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップ アプリのみ]
対象プラットフォーム	Windows
ヘッダー	winbase.h (Windows.h を含む)
Library	Kernel32.lib
[DLL]	Kernel32.dll

関連項目

File Management 関数

GetFileBandwidthReservation