Retrieves the first file record that is in use and is of a lesser than or equal ordinal value to the requested file reference number.

To perform this operation, call the DeviceIoControl function with the following parameters.

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

Parameters

hDevice

A handle to the volume from which the file record information is to be retrieved.

To open a volume and retrieve a volume handle, call the CreateFile function. Opening the volume with either read or write access is sufficient to retrieve the file record. For more information, see File Security and Access Rights.

dwIoControlCode

The control code for the operation.

Use FSCTL_GET_NTFS_FILE_RECORD for this operation.

lpInBuffer

A pointer to the input buffer, an NTFS_FILE_RECORD_INPUT_BUFFER structure.

The file identifier corresponding to the NTFS file system file record for which information is returned is included in this buffer.

nInBufferSize

The size of the input buffer, in bytes.

lpOutBuffer

A pointer to the output buffer, an NTFS_FILE_RECORD_OUTPUT_BUFFER structure.

The file record associated with the file identifier specified in the input buffer is returned in this buffer. Refer to the Remarks section for specific information on how to determine the correct size of this buffer.

nOutBufferSize

The size of the output buffer, in bytes.

lpBytesReturned

A pointer to a variable that receives the size of the data stored in the output buffer, in bytes.

If the output buffer is too small, the call fails, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and lpBytesReturned is zero (0).

If lpOverlapped is NULL, lpBytesReturned cannot be NULL. Even when an operation returns no output data and lpOutBuffer is NULL, DeviceIoControl makes use of lpBytesReturned. After such an operation, the value of lpBytesReturned is meaningless.

If lpOverlapped is not NULL, lpBytesReturned can be NULL. If this parameter is not NULL and the operation returns data, lpBytesReturned is meaningless until the overlapped operation has completed. To retrieve the number of bytes returned, call GetOverlappedResult. If hDevice is associated with an I/O completion port, you can retrieve the number of bytes returned by calling GetQueuedCompletionStatus.

lpOverlapped

A pointer to an OVERLAPPED structure.

If hDevice is opened without specifying FILE_FLAG_OVERLAPPED, lpOverlapped is ignored.

If hDevice is opened with the FILE_FLAG_OVERLAPPED flag, the operation is performed as an overlapped (asynchronous) operation. In this case, lpOverlapped must point to a valid OVERLAPPED structure that contains a handle to an event object. Otherwise, the function fails in unpredictable ways.

For overlapped operations, DeviceIoControl returns immediately, and the event object is signaled when the operation has been completed. Otherwise, the function does not return until the operation has been completed or an error occurs.

Return Value

If the operation completes successfully, DeviceIoControl returns a nonzero value.

If the operation fails or is pending, DeviceIoControl returns zero (0). To get extended error information, call GetLastError.

Remarks

This control code enumerates file identifiers in a downward fashion, and always returns a file record that is in use. This means that the file identifier returned by this control code may not be the same as the file identifier specified in the input buffer. For example, if file identifiers 1 through 9 and 15 are in use, file identifiers 10 through 14 are not in use, and the file record corresponding to file identifier 15 is requested, that file record is returned.

If the file records that correspond to file identifiers 10 through 14 are requested, then the file record corresponding to file identifier 9 is returned. If any of the file records corresponding to file identifiers 1 through 9 are requested, those file records is returned.

To determine the correct size of the output buffer pointed to by lpOutBuffer, first call the FSCTL_GET_NTFS_VOLUME_DATA control code to get the size of one file record. This is the value of the BytesPerFileRecordSegment member of the returned NTFS_VOLUME_DATA_BUFFER structure. Then set the size of the output buffer to the following expression:

sizeof (NTFS_FILE_RECORD_OUTPUT_BUFFER) + sizeof (one file record) - 1

If a file consists of multiple file records, they must be retrieved individually.

Requirements

See Also

DeviceIoControl

File Management Control Codes

NTFS_FILE_RECORD_INPUT_BUFFER

NTFS_FILE_RECORD_OUTPUT_BUFFER

Send comments about this topic to Microsoft

Build date: 11/12/2009