Какие новые API появились в связи с появлением ReFS

Файловая система Resilient File System (ReFS, ранее Protogon) появится в Windows Server 8, а вместе с ней в ядре Windows появятся дополнения к API для работы с этой системой. NTFS Stream Explorer начнёт поддерживать эти API через некоторое время после релиза Windows 8 Server.

Просто перечислю, что нового.

Новый запрос для DeviceIoControl — FSCTL_GET_INTEGRITY_INFORMATION. Служит для получения структуры FSCTL_GET_INTEGRITY_INFORMATION_BUFFER, которая содержит информацию о целостности файла.

typedef struct _FSCTL_GET_INTEGRITY_INFORMATION_BUFFER {
    USHORT ChecksumAlgorithm;
    USHORT Reserved;
    ULONG Flags;
    ULONG ChecksumChunkSizeInBytes;
    ULONG ClusterSizeInBytes;
} FSCTL_GET_INTEGRITY_INFORMATION_BUFFER, *PFSCTL_GET_INTEGRITY_INFORMATION_BUFFER;

ChecksumAlgorithm
Алгоритм контрольной суммы. Определены следующие значения:

CHECKSUM_TYPE_NONE  0x0000 Целостность для файла не обрабатывается.
CHECKSUM_TYPE_CRC64 0x0002 Используется алгоритм CRC64.

Все остальные значения 0x0002 — 0xFFFF зарезервированы.

Reserved
Зарезервировано.

Flags

FSCTL_INTEGRITY_FLAG_CHECKSUM_ENFORCEMENT_OFF 0x00000001 
// Контрольные суммы отключены для этого файла.

ChecksumChunkSizeinBytes
Размер каждого блока в потоке, содержащего данные целостности.

ClusterSizeinBytes
Размер кластера тома в байтах. Должно быть кратно 2.

Пример получения информации о целостности ReFS.

BOOLEAN GetIntegrity(
    IN HANDLE Handle, 
    OUT PUSHORT Algorithm,
    OUT PULONG Flags
    )
{
    FSCTL_GET_INTEGRITY_INFORMATION_BUFFER IntegrityInformationBuffer;
    ULONG Length;
    if ( !DeviceIoControl(Handle, FSCTL_GET_INTEGRITY_INFORMATION, NULL,
        0, &IntegrityInformationBuffer, sizeof(IntegrityInformationBuffer), 
        &Length, FALSE ) ) {
        return FALSE;
    }
    *Algorithm = IntegrityInformationBuffer.ChecksumAlgorithm;
    *Flags = IntegrityInformationBuffer.Flags;
    return TRUE;
}

Новый запрос для DeviceIoControl — FSCTL_SET_INTEGRITY_INFORMATION. Служит для установки или изменения информации о целостности файла на томе ReFS.

typedef struct _FSCTL_SET_INTEGRITY_INFORMATION_BUFFER {
    USHORT ChecksumAlgorithm;
    USHORT Reserved;
    ULONG Flags;
} FSCTL_SET_INTEGRITY_INFORMATION_BUFFER, *PFSCTL_SET_INTEGRITY_INFORMATION_BUFFER;

Поля структуры FSCTL_SET_INTEGRITY_INFORMATION_BUFFER аналогичны FSCTL_GET_INTEGRITY_INFORMATION_BUFFER.

Пример установки информации о целостности (допустимо только для пустых файлов):

BOOLEAN SetIntegrity(
    IN HANDLE Handle,
    IN USHORT Algorithm,
    IN ULONG Flags
    )
{
    FSCTL_SET_INTEGRITY_INFORMATION_BUFFER IntegrityInformationBuffer;
    ZeroMemory(&IntegrityInformationBuffer, sizeof(IntegrityInformationBuffer));
    IntegrityInformationBuffer.ChecksumAlgorithm = Algorithm;
    IntegrityInformationBuffer.Flags = Flags;
    return (BOOLEAN)DeviceIoControl(Handle, FSCTL_SET_INTEGRITY_INFORMATION, 
      &IntegrityInformationBuffer, sizeof(IntegrityInformationBuffer), NULL, 0, NULL, FALSE );
}

Новый запрос для DeviceIoControl — FSCTL_REPAIR_COPIES. Служит для восстановления данных из повреждённого файла. На ReFS этот код работает только для файлов, у которых целостность не включена. Для тех файлов, у которых целостность включена, восстановление выполняется автоматически, без необходимости самому вызывать какие-либо функции.

Структуры данных:

typedef struct _REPAIR_COPIES_INPUT {
    ULONG Size;
    ULONG Flags;
    LARGE_INTEGER FileOffset;
    ULONG Length;
    ULONG SourceCopy;
    ULONG NumberOfRepairCopies;
    ULONG RepairCopies[ANYSIZE_ARRAY];
} REPAIR_COPIES_INPUT, *PREPAIR_COPIES_INPUT;
typedef struct _REPAIR_COPIES_OUTPUT {
    ULONG Size;
    ULONG Status;
    LARGE_INTEGER ResumeFileOffset;
} REPAIR_COPIES_OUTPUT, *PREPAIR_COPIES_OUTPUT;

Size
Размер, равен sizeof(REPAIR_COPIES_INPUT). В выходном буфере будет установлен в sizeof(REPAIR_COPIES_OUTPUT).

Flags
Зарезервировано. Должно быть 0.

FileOffset
Позиция в файле, откуда начинать восстановление.

Length
Количество байт для восстановления.

SourceCopy
Номер копии.

NumberOfRepairCopies
Количество копий, сколько их нужно.

RepairCopies[ANYSIZE_ARRAY]
Номера всех восстановленных копий.

ResumeFileOffset
Позиция файла, с которой можно начать следующий запрос на восстановление. Области, где были найдены ошибки, исключаются из диапазона.

Status
Статус восстановления.

Пример:

BOOL Success;
//  Change the handle info to read from a copy
MARK_HANDLE_INFO HandleInfo;
ZeroMemory( &HandleInfo, sizeof(MARK_HANDLE_INFO) );
HandleInfo.HandleInfo = MARK_HANDLE_READ_COPY;
HandleInfo.CopyNumber = 1; /* or 0, 1, ... */
DWORD BytesReturned;
Success = DeviceIoControl(NonCachedFileHandle, FSCTL_MARK_HANDLE, &HandleInfo,
  sizeof(MARK_HANDLE_INFO), NULL, 0, &BytesReturned, NULL);
//  Normal read file call
Success = ReadFile(NonCachedFileHandle, Buffer, BytesToRead, &BytesReturned, NULL);
//  Repair call
union {
REPAIR_COPIES_INPUT RepairInput;
UCHAR RepairInputBuffer[FIELD_OFFSET(REPAIR_COPIES_INPUT, RepairCopies) + sizeof(ULONG) * 2];
};
REPAIR_COPIES_OUTPUT RepairOutput;
ZeroMemory( &RepairInput, sizeof(RepairInputBuffer) );
RepairInput.Size = sizeof(REPAIR_COPIES_INPUT);
RepairInput.Flags = 0;
RepairInput.FileOffset = 0x1000;
RepairInput.Length = 0x4000;
RepairInput.SourceCopy = 1;
RepairInput.NumberOfRepairCopies = 2;
RepairInput.RepairCopies[0] = 0;
RepairInput.RepairCopies[1] = 2;
 
Success = DeviceIoControl(FileHandle, FSCTL_REPAIR_COPIES, &RepairInput, 
(RepairInputBuffer), &RepairOutput, (REPAIR_COPIES_OUTPUT), &BytesReturned, NULL);

Новые флаги и структуры для FSCTL_MARK_HANDLE. Помечают хэндл так, что при чтении из него данные будут браться из заданной копии. Это доступно только для хэндлов без кэширования, например созданных с флагом FILE_FLAG_NO_BUFFERING.

#define MARK_HANDLE_READ_COPY               (0x00000080)
#define MARK_HANDLE_NOT_READ_COPY           (0x00000100)
typedef struct {
    union {
        ULONG UsnSourceInfo;
        ULONG CopyNumber;
    };
    HANDLE VolumeHandle;
    ULONG HandleInfo;
} MARK_HANDLE_INFO, *PMARK_HANDLE_INFO;
//
//  32/64 Bit thunking support structure
//
typedef struct {
    union {
        ULONG UsnSourceInfo;
        ULONG CopyNumber;
    };
    UINT32 VolumeHandle;
    ULONG HandleInfo;
} MARK_HANDLE_INFO32, *PMARK_HANDLE_INFO32;

USNSourceInfo
http://msdn.microsoft.com/en-us/library/aa365229(v=VS.85).aspx

CopyNumber
Номер копии.

VolumeHandle
Не используется с MARK_HANDLE_READ_COPY и MARK_HANDLE_NOT_READ_COPY

HandleInfo
http://msdn.microsoft.com/en-us/library/aa365229(v=VS.85).aspx

FILE_ATTRIBUTE_INTEGRITY_STREAM
Означает, что файл сконфигурирован так, что для него отслеживается целостность.

FILE_ATTRIBUTE_NO_SCRUB_DATA
Маркирует файл так, чтобы его пропускал скраббер. Скраббер ReFS это такой сервис, который периодически читает все файлы на диске, кроме помеченных этим атрибутом. Чтение нужно для того, чтобы высчитать или проверить контрольные суммы. Если файлы периодически не читать, данные могут испортиться ещё до того, как для них сформированы метаданные целостности.