Platform SDK: Hardware |
The FSCTL_MARK_HANDLE operation marks a specified file or directory and its change journal record with information about changes to that file or directory.
To perform this operation, call the DeviceIoControl function using the following parameters.
BOOL DeviceIoControl( (HANDLE) hDevice, // handle to file or directory FSCTL_MARK_HANDLE, // dwIoControlCode operation (LPVOID)lpInBuffer, // input buffer (DWORD)nInBufferSize, // size of input buffer NULL, // lpOutBuffer; must be NULL 0, // nOutBufferSize; must be zero (LPDWORD) lpBytesReturned, // number of bytes returned (LPOVERLAPPED) lpOverlapped // OVERLAPPED structure );
If lpOverlapped is NULL (nonoverlapped I/O), lpBytesReturned is used internally and cannot be NULL.
If lpOverlapped is not NULL (overlapped I/O), lpBytesReturned can be NULL.
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.
If the operation succeeds, DeviceIoControl returns a nonzero value.
If the operation fails, DeviceIoControl returns zero. To get extended error information, call GetLastError.
Possible return values include the following.
Value | Meaning |
---|---|
ERROR_INVALID_FUNCTION | The volume containing the specified file or directory 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 was invalid. For example, DeviceIoControl returns this error code if the handle supplied is not a file or directory handle. |
For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.
FSCTL_MARK_HANDLE is the only change journal operation that operates on an individual file or directory. It does not affect anything the user can do with the item. Instead, it adds information to the file or directory, either providing information on how the operating system changed the item or adding a private data stream to the item.
If there are any changes to the file or directory, then the information added with FSCTL_MARK_HANDLE is also copied into the USN record created for the file or directory. For details on the information with which FSCTL_MARK_HANDLE can mark an item, see MARK_HANDLE_INFO.
It is not an error to use FSCTL_MARK_HANDLE while the volume's change journal is being deleted or is inactive. The appropriate information is applied to the file or directory regardless of the state of the change journal, as long as the change journal exists.
Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Winioctl.h.
Device Input and Output Overview, Device Input and Output Control Codes, CreateFile, DeviceIoControl, MARK_HANDLE_INFO, OVERLAPPED