Share via

FSCTL_QUERY_ALLOCATED_RANGES (Compact 2013)

  • Article

3/26/2014

This I/O control scans a file or alternate stream looking for ranges that contain nonzero data. Only compressed or sparse files can have ranges set to zero known to the OS. For other files, the output buffer contains only a single entry that contains the starting point and the length requested.

Syntax

BOOL DeviceIoControl(
    HANDLE hDevice,           // handle to device
    DWORD dwIoControlCode,    // use FSCTL_QUERY_ALLOCATED_RANGES
    LPVOID lpInBuffer,        // pointer to input buffer
    DWORD nInBufferSize,      // input buffer size
    LPVOID lpOutBuffer,       // pointer to output buffer
    DWORD nOutBufferSize,     // output buffer size
    LPDWORD lpBytesReturned,  // number of bytes returned
    OVERLAPPED lpOverlapped   // pointer to OVERLAPPED structure
);

Parameters

  • hDevice
    [in] Handle to the file or alternate stream to be queried for allocated ranges. To obtain a handle, call the CreateFile function.
  • dwIoControlCode
    [in] Set to FSCTL_QUERY_ALLOCATED_RANGES.
  • lpInBuf
    [in] Pointer to a FILE_ALLOCATED_RANGE_BUFFER structure that indicates the portion of the file to search for allocated ranges. The FileOffset member indicates the offset, in bytes, to the first byte of the range to search, and the Length member indicates its size, in bytes.
  • nInBufSize
    [in] Size of the input buffer, in bytes.
  • lpOutBuf
    [out] Pointer to a buffer that receives an array of FILE_ALLOCATED_RANGE_BUFFER structures. Each structure in the array provides information about an allocated range within the file. The FileOffset member of each structure indicates the beginning of a range, and the Length member indicates its size, in bytes.
  • nOutBufSize
    [in] Size of the output buffer, in bytes.
  • lpBytesReturned
    [out] Pointer to a variable that receives the size of the data stored in the output buffer, in bytes.
  • lpOverlapped
    Not used.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero. For extended error information, call GetLastError.

Requirements

Header

fsioctl.h

See Also

Reference

FS I/O Controls
CreateFile
FILE_ALLOCATED_RANGE_BUFFER

Other Resources

DeviceIoControl