FSCTL_QUERY_USN_JOURNAL

The FSCTL_QUERY_USN_JOURNAL operation queries for information on the current change journal, its records, and its capacity.

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

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to volume
  FSCTL_QUERY_USN_JOURNAL,     // dwIoControlCode operation
  NULL,                        // lpInBuffer; must be NULL
  0,                           // nInBufferSize; must be zero
  lpOutBuffer,                 // output buffer
  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_QUERY_USN_JOURNAL for this operation.

lpInBuffer

[in] Pointer to the input buffer. Not used; must be NULL.

nInBufferSize

[in] Size, in bytes, of the input buffer. Not used; must be zero.

lpOutBuffer

[out] Pointer to the output buffer, which on successful return contains a USN_JOURNAL_DATA structure, containing information on the current change journal, its records, and its capacity.

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 retrieve the number of bytes returned by calling the GetOverlappedResult function. If hDevice is associated with an I/O completion port, you can get the number of bytes returned by calling the GetQueuedCompletionStatus function.

lpOverlapped

[in] Pointer to an OVERLAPPED structure.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, this parameter 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, this parameter 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, and the output buffer pointed to by lpOutBuffer contains a valid USN_JOURNAL_DATA structure.

If the operation fails, DeviceIoControl returns zero, and the contents of the output buffer pointed to by lpOutBuffer 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 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.

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, GetOverlappedResult, GetQueuedCompletionStatus, OVERLAPPED, USN_JOURNAL_DATA