FSCTL_ENUM_USN_DATA

The FSCTL_ENUM_USN_DATA operation creates an enumeration that lists the change journal entries between two specified boundaries.

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

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to volume
  FSCTL_ENUM_USN_DATA,         // dwIoControlCode operation
  (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

[in] Handle to the local volume from which data is to be retrieved. To obtain a volume handle, call the CreateFile function.

dwIoControlCode

[in] Control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it. Use FSCTL_ENUM_USN_DATA for this operation.

lpInBuffer

[in] Pointer to the input buffer, an MFT_ENUM_DATA structure. The MFT_ENUM_DATA structure specifies the boundaries between which change journal entries are listed.

nInBufferSize

[in] Size, in bytes, of the input buffer.

lpOutBuffer

[out] Pointer to the output buffer, cast to a void pointer.

Initially, the output buffer may be of any size larger than a ULONGLONG. On completion of the call, the buffer contains the USN of the record following the last record in the buffer. This USN can be used in a subsequent call to FSCTL_ENUM_USN_DATA to get the next set of records. The following shows an example of this in C:

DWORDLONG NextFileReferenceNumber;

where NextFileReferenceNumber is the USN of the next record. Use NextFileReferenceNumber in any subsequent call to FSCTL_ENUM_USN_DATA to enumerate records following those in the current output buffer.

Following NextFileReferenceNumber in the buffer is a series of USN_RECORD structures aligned on 64-bit boundaries. Each structure contains a change journal record. For more information on navigating the output buffer, see Walking a Buffer of Change Journal Records.

nOutBufferSize

[in] Size, in bytes, of the output buffer.

lpBytesReturned

[out] Pointer to a variable that receives the size, in bytes, of output data returned. If the lpOutBuffer buffer is too small, lpBytesReturned receives the required buffer size.

If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned cannot be NULL.

If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL. If this is an overlapped operation, you can get the number of bytes returned by calling the GetOverlappedResult function.

lpOverlapped

[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, lpOverlapped must point to a valid OVERLAPPED structure. In this case, DeviceIoControl is performed as an overlapped (asynchronous) operation. If the device was opened with the FILE_FLAG_OVERLAPPED flag and lpOverlapped is NULL, the function fails in unpredictable ways.

If hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag, lpOverlapped is ignored and the DeviceIoControl function does not return until the operation has been completed, or until an error occurs.

Return Values

If the operation succeeds, DeviceIoControl returns a nonzero value.

If the operation fails, DeviceIoControl returns zero and the contents of the output buffer pointed to by the lpOutBuffer parameter are meaningless. To get extended error information, call GetLastError.

Possible return values include the following.

Remarks

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

To enumerate a volume's change journal, use the FSCTL_ENUM_USN_DATA operation one or more times. On the first call, set the starting point, the StartFileReferenceNumber element of the MFT_ENUM_DATA structure, to (DWORDLONG)0. Each call to FSCTL_ENUM_USN_DATA returns the starting point for the subsequent call as the first entry in the output buffer.

To obtain a handle to a volume, pass in the CreateFile parameter lpFileName a value of the following form:

\\.\X:

where X is the letter identifying the drive on which the volume appears. The volume must be an NTFS volume on Windows 2000.

There are two DeviceIoControl operations that return USN records, FSCTL_READ_USN_JOURNAL and FSCTL_ENUM_USN_DATA. Use the latter when you simply want a listing (enumeration) of the USN records between two USNs. Use the former when you want to select by USN.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winioctl.h.

See Also

Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, FSCTL_READ_USN_JOURNAL, GetOverlappedResult, MFT_ENUM_DATA, OVERLAPPED, USN_RECORD