Функция ClfsReserveAndAppendLog (wdm.h)
Подпрограмма 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 |