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