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

Статья
08/08/2023

Подпрограмма 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

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

Flag	Значение
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. rgcbReservation имеет значение NULL. CLFS_USE_RESERVATION задано.	Добавляет запись в область маршалинга, используя пространство, которое уже зарезервировано. Уменьшает количество зарезервированных пространств записей на единицу.
cWriteEntries > 0. Значение rgWriteEntries не равно NULL. значение plsn не равно NULL. cReserveRecords = 0. rgcbReservation имеет значение NULL. 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 (включая Wdm.h)
Библиотека	Clfs.lib
DLL	Clfs.sys
IRQL	<= APC_LEVEL

См. также раздел

CLFS_LSN

CLFS_WRITE_ENTRY

ClfsCreateMarshallingArea

ClfsReserveAndAppendLog

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