SetFileBandwidthReservation function (winbase.h)

Requests that bandwidth for the specified file stream be reserved. The reservation is specified as a number of bytes in a period of milliseconds for I/O requests on the specified file handle.

Syntax

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

Parameters

[in] hFile

A handle to the file.

[in] nPeriodMilliseconds

The period of the reservation, in milliseconds. The period is the time from which the I/O is issued to the kernel until the time the I/O should be completed. The minimum supported value for the file stream can be determined by looking at the value returned through the lpPeriodMilliseconds parameter to the GetFileBandwidthReservation function, on a handle that has not had a bandwidth reservation set.

[in] nBytesPerPeriod

The bandwidth to reserve, in bytes per period. The maximum supported value for the file stream can be determined by looking at the value returned through the lpBytesPerPeriod parameter to the GetFileBandwidthReservation function, on a handle that has not had a bandwidth reservation set.

[in] bDiscardable

Indicates whether I/O should be completed with an error if a driver is unable to satisfy an I/O operation before the period expires. If one of the drivers for the specified file stream does not support this functionality, this function may return success and ignore the flag. To verify whether the setting will be honored, call the GetFileBandwidthReservation function using the same hFile handle and examine the *pDiscardable return value.

[out] lpTransferSize

A pointer to a variable that receives the minimum size of any individual I/O request that may be issued by the application. All I/O requests should be multiples of TransferSize.

[out] lpNumOutstandingRequests

A pointer to a variable that receives the number of TransferSize chunks the application should allow to be outstanding with the operating system. This allows the storage stack to keep the device busy and allows maximum throughput.

Return value

Returns nonzero if successful or zero otherwise.

A reservation can fail if there is not enough bandwidth available on the volume because of existing reservations; in this case ERROR_NO_SYSTEM_RESOURCES is returned.

To get extended error information, call GetLastError.

Remarks

The requested bandwidth reservation must be greater than or equal to one packet per period. The minimum period, in milliseconds, maximum bytes per period, and minimum transfer size, in bytes, for a specific volume are returned through the lpPeriodMilliseconds, lpBytesPerPeriod, and lpTransferSize parameters to GetFileBandwidthReservation on a handle that has not been used in a call to SetFileBandwidthReservation. In other words:

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

IIn Windows 8 and Windows Server 2012, this function is supported by the following technologies.

Requirements

See also

File Management Functions

GetFileBandwidthReservation