Функция ClfsReserveAndAppendLogAligned (wdm.h)

Статья
02/07/2025

ClfsReserveAndAppendLogAligned обычно резервирует пространство в области маршаллинга или добавляет запись в область маршаллинга или делает оба атомарно. Данные записи выравниваются по указанным границам.

Синтаксис

CLFSUSER_API NTSTATUS ClfsReserveAndAppendLogAligned(
  [in]            PVOID             pvMarshalContext,
  [in, optional]  PCLFS_WRITE_ENTRY rgWriteEntries,
  [in]            ULONG             cWriteEntries,
  [in]            ULONG             cbEntryAlignment,
  [in, optional]  PCLFS_LSN         plsnUndoNext,
  [in, optional]  PCLFS_LSN         plsnPrevious,
  [in]            ULONG             cReserveRecords,
  [in, out]       PLONGLONG         rgcbReservation,
  [in]            ULONG             fFlags,
  [out, optional] PCLFS_LSN         plsn
);

Параметры

[in] pvMarshalContext

Указатель на непрозрачный контекст, представляющий область маршаллинга, связанную с потоком CLFS. Вызывающий объект ранее получил этот указатель путем вызова ClfsCreateMarshallingArea.

[in, optional] rgWriteEntries

Указатель на массив структур CLFS_WRITE_ENTRY, каждый из которых содержит указатель на буфер данных, который станет частью записи, добавляемой в журнал. Этот параметр может быть NULL, если cWriteEntries равно нулю.

[in] cWriteEntries

Количество элементов в массиве, на которое указывает rgWriteEntries. Этот параметр должен быть равен нулю, если rgWriteEntries NULL.

[in] cbEntryAlignment

Выравнивание байтов записей данных, на которые указывает rgWriteEntries, так как они маршалируются в одну запись. Значение одного указывает простую объединение (см. ClfsReserveAndAppendLog). Значение, превышающее одно, может привести к тому, что в записи помещаются нули между записями. Значение этого параметра должно быть больше нуля.

[in, optional] plsnUndoNext

Указатель на структуру CLFS_LSN, которая предоставляет добавленный номер LSN отмены.

[in, optional] plsnPrevious

Указатель на структуру CLFS_LSN, которая предоставляет предыдущий LSN записи, добавляемой.

[in] cReserveRecords

Количество элементов в массиве, на которое указывает rgcbReservation. Этот параметр должен быть равен нулю, если rgcbReservation NULL или флаг CLFS_FLAG_USE_RESERVATION fFlags.

[in, out] rgcbReservation

Указатель на массив переменных с типом LONGLONG. Вызывающий объект задает каждому элементу массива размер в байтах записи, которая должна иметь резерв места для него. При возврате каждый элемент массива получает фактический размер пространства, зарезервированного для записи. Это включает пространство, необходимое для заголовков и выравнивания. Если значение резервирования отрицательное, зарезервированная запись, которая почти соответствует абсолютному значению предоставленного отрицательного значения, будет освобождена. Этот параметр может быть null, если cReserveRecords равно нулю и должен быть null, если установлен флаг CLFS_FLAG_USE_RESERVATION fFlags.

[in] fFlags

Этот параметр может быть любым сочетанием следующих флагов.

Флаг	Значение
CLFS_FLAG_FORCE_APPEND	После добавления текущей записи к блоку ввода-вывода журнала блок блокируется в последовательности LSN в стабильное хранилище. Этот флаг не гарантирует, что запись вынуждена стабильно хранить (см. CLFS_FLAG_FORCE_FLUSH).
CLFS_FLAG_FORCE_FLUSH	После добавления текущей записи к блоку ввода-вывода журнала блок принудительно выполняется стабильное хранение.
CLFS_FLAG_USE_RESERVATION	Текущая запись помещается в зарезервированное пространство в блоке ввода-вывода. Количество зарезервированных записей в области маршалинга уменьшается на один. Если этот флаг задан, cReserveRecords должно быть равно нулю, а rgcbReservation должно быть NULL.

[out, optional] plsn

Указатель на структуру CLFS_LSN, которая получает LSN добавленной записи. Этот параметр может быть NULL, если cWriteEntries равно нулю.

Возвращаемое значение

ClfsReserveAndAppendLogAligned возвращает STATUS_SUCCESS в случае успешного выполнения; в противном случае возвращается один из кодов ошибок, определенных в Ntstatus.h.

Замечания

ClfsReserveAndAppendLogAligned изменяет его основное поведение на основе наличия необязательных параметров и состояния флага CLFS_USE_RESERVATION. В следующей таблице приведены общие сценарии.

Значения параметров и флагов	Действия, выполненные
cWriteEntries = 0. rgWriteEntries = NULL. plsn = NULL.	Резервирует пространство для набора записей, но не добавляет записи в область маршаллинга. Параметр rgcbReservation предоставляет размер части данных каждой записи, требующей зарезервированного места.
cWriteEntries > 0. rgWriteEntries не NULL. plsn не NULL. cReserveRecords = 0. rgcbReservationNULL. CLFS_USE_RESERVATION задано.	Добавляет запись в область маршаллинга с помощью пространства, которое уже зарезервировано. Уменьшает количество зарезервированных записей на один.
cWriteEntries > 0. rgWriteEntries не NULL. plsn не NULL. cReserveRecords = 0. rgcbReservationNULL. CLFS_USE_RESERVATION очищается.	Добавляет запись в область маршаллинга, резервируя новое пространство. Остается без изменений количество зарезервированных пространств записей.
cWriteEntries > 0. rgWriteEntries не NULL. plsn не NULL. cReserveRecords> 0. rgcbReservation не NULL. CLFS_USE_RESERVATION флаг очищается.	Добавляет запись в область маршаллинга, резервируя новое пространство. Кроме того, резервирует место для набора записей, которые в настоящее время не добавляются. Параметр rgcbReservation предоставляет размер каждой записи, требующей зарезервированного места. Увеличивает количество зарезервированных записей по значению cReserveRecords.

Описание концепций и терминологии CLFS см. в common Log File System.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно в Windows Server 2003 R2, Windows Vista и более поздних версиях Windows.
целевая платформа	Настольный
заголовка	wdm.h (include Wdm.h)
библиотеки	Clfs.lib
DLL	Clfs.sys
IRQL	<= APC_LEVEL

См. также

CLFS_LSN

CLFS_WRITE_ENTRY

ClfsCreateMarshallingArea

ClfsReserveAndAppendLog

Поделиться через