This topic has not yet been rated - Rate this topic

FSCTL_SET_INTEGRITY_INFORMATION control code

Retrieves the integrity status of a file or directory on a ReFS volume.

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


BOOL 
WINAPI 
DeviceIoControl( (HANDLE) hDevice,                // handle to file or directory
                 FSCTL_SET_INTEGRITY_INFORMATION, // dwIoControlCode
                 (LPDWORD) pInBuffer,             // FSCTL_SET_INTEGRITY_INFORMATION_BUFFER 
                 (DWORD) InBufferSize,            // size of input buffer
                 (LPDWORD) NULL,                  // pOutBuffer
                 (DWORD) 0,                       // OutBufferSize
                 (LPDWORD) NULL,                  // lpBytesReturned
                 (LPOVERLAPPED) lpOverlapped );   // OVERLAPPED structure

Parameters

hDevice [in]

A handle to the file or directory. To obtain a handle, call the CreateFile function.

dwIoControlCode [in]

The control code for the operation. Use FSCTL_SET_INTEGRITY_INFORMATION for this operation.

lpInBuffer

Address of a FSCTL_SET_INTEGRITY_INFORMATION_BUFFER structure.

nInBufferSize [in]

The size of the input buffer, in bytes. Must be at least sizeof(FSCTL_SET_INTEGRITY_INFORMATION_BUFFER).

lpOutBuffer [out]

Not used with this operation; set to NULL.

nOutBufferSize [in]

Not used with this operation; set to 0.

lpBytesReturned [out]

Not used with this operation; set to NULL.

lpOverlapped [in]

A pointer to an OVERLAPPED structure.

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

If hDevice was 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. To get extended error information, call GetLastError.

Remarks

The integrity status can only be changed for empty files.

If the ReplaceFile is used to replace a file with integrity set, and the lpBackupFileName parameter points to a location that does not have integrity set, the integrity status of the original file will not be persisted.

Writes to integrity streams are always cluster-sized. Reads from integrity streams are always done in 16 KB blocks. This can lead to reads failing even when the corrupt area is outside the region being read. For example, if 4 KB is read at offset 0 in a file and there is corruption starting 12 KB into the file, a read would fail with ERROR_DATA_CHECKSUM_ERROR (0x143).

Requirements

Minimum supported client	None supported [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Header	WinIoCtl.h (include Windows.h)

Community Additions