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

Статья
08/08/2023

Подпрограмма ClfsReserveAndAppendLog резервирует место в области маршалинга или добавляет запись в область маршалинга или выполняет оба атомарного действия.

Синтаксис

CLFSUSER_API NTSTATUS ClfsReserveAndAppendLog(
  [in]            PVOID             pvMarshalContext,
  [in, optional]  PCLFS_WRITE_ENTRY rgWriteEntries,
  [in]            ULONG             cWriteEntries,
  [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, этот параметр должен иметь значение null.

[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 должен иметь значение null, а rgcbReservation — NULL.

[out, optional] plsn

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

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

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

Подпрограмма ClfsReserveAndAppendLog изменяет свое основное поведение в зависимости от наличия необязательных параметров и состояния флага 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.

Вызов ClfsReserveAndAppendLog эквивалентен вызову ClfsReserveAndAppendLogAligned с параметром cbEntryAlignment , равным одному.

Описание основных понятий и терминологии 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

ClfsReserveAndAppendLogAligned

Share via