Platform SDK: Hardware

FSCTL_READ_USN_JOURNAL

The FSCTL_READ_USN_JOURNAL operation returns to the calling process the set of change journal records between two specified USN values.

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

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // handle to volume
  FSCTL_READ_USN_JOURNAL,      // 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 change journal data is to be returned. 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_READ_USN_JOURNAL for this operation.

lpInBuffer

[in] Pointer to the input buffer, a READ_USN_JOURNAL_DATA structure.

The structure member BytesToWaitFor, which indicates the size in bytes of unfiltered data to retrieve from the change journal, should not exceed the size of the output buffer pointed to by the lpOutBuffer parameter.

The structure member Timeout is ignored for asynchronously opened handles.

nInBufferSize

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

lpOutBuffer

[out] Pointer to the output buffer, which on completion of the call contains the USN of the record following the last record in the buffer. This USN can be used in a subsequent call to FSCTL_READ_USN_JOURNAL to get the next set of records. The following shows an example of this in C:

DWORDLONG NextUsn;

where NextUsn is the next USN value.

Following the next USN in the buffer are zero or more USN_RECORD structures aligned on packed 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. 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, 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 lpOutBuffer are meaningless. To get extended error information, call GetLastError.

Possible return values include the following.

Value	Meaning
ERROR_INVALID_FUNCTION	The specified volume does not support change journals. Change journals are only supported on Windows 2000. Where supported, change journals can also be deleted.
ERROR_INVALID_PARAMETER	One or more parameters is invalid. For example, DeviceIoControl returns this error code if the handle supplied is not a volume handle.
ERROR_JOURNAL_DELETE_IN_PROGRESS	An attempt was made to read from, create, delete, or modify the journal while a journal deletion was under way, or an attempt was made to write a USN record while a journal deletion was under way.
ERROR_JOURNAL_NOT_ACTIVE	An attempt was made to write a USN record or to read the change journal while the journal was inactive.
ERROR_JOURNAL_ENTRY_DELETED	A nonzero USN was specified that is less than the first USN in the change journal. The specified USN may have been valid at one time, but it has since been deleted.

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.

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.

FSCTL_READ_USN_JOURNAL

Parameters

Return Values

Remarks

Requirements

See Also