Функция ClfsCreateLogFile (wdm.h)
Подпрограмма ClfsCreateLogFile создает или открывает поток CLFS. При необходимости ClfsCreateLogFile также создает базовый физический журнал, содержащий записи потока.
Синтаксис
CLFSUSER_API NTSTATUS ClfsCreateLogFile(
[out] PPLOG_FILE_OBJECT pplfoLog,
[in] PUNICODE_STRING puszLogFileName,
[in] ACCESS_MASK fDesiredAccess,
[in] ULONG dwShareMode,
[in, optional] PSECURITY_DESCRIPTOR psdLogFile,
[in] ULONG fCreateDisposition,
[in] ULONG fCreateOptions,
[in] ULONG fFlagsAndAttributes,
[in] ULONG fLogOptionFlag,
[in, optional] PVOID pvContext,
[in] ULONG cbContext
);
Параметры
[out] pplfoLog
Указатель на переменную, получающую указатель на структуру LOG_FILE_OBJECT , представляющую открытый экземпляр потока.
[in] puszLogFileName
Указатель на структуру UNICODE_STRING , которая предоставляет имя потока или базового физического журнала.
Если поток уже существует и является единственным потоком выделенного журнала, имя имеет форму log:physical log name, где имя физического журнала — это имя пути в базовой файловой системе существующего физического журнала, содержащего записи потока.
Если поток еще не существует и должен стать единственным потоком выделенного журнала (который еще не существует), имя будет иметь форму log:physical log name, где физическое имя журнала — это имя пути в базовой файловой системе физического журнала, который будет создан для хранения записей потока.
Если поток является (или должен стать) одним из потоков мультиплексированного журнала, имя имеет форму log:physical log name::stream name, где физическое имя журнала — это имя пути в базовой файловой системе физического журнала, в котором хранятся записи потока, а имя потока — это имя потока, который совместно использует (или будет совместно использовать) этот физический журнал.
Если вы хотите создать мультиплексируемый журнал без потоков на данный момент, используйте имя формы log:physical log name::, где физическое имя журнала — это имя пути в базовой файловой системе создаваемого физического журнала.
В следующем списке приведены примеры допустимых имен.
- Log:c:\myLog создает или открывает выделенный журнал и его один поток.
- "Log:c:\myCommonLog::" создает мультиплексный журнал, который еще не содержит потоков.
- "Log:c:\myCommonLog::Stream1" создает или открывает один из потоков (Stream1) мультиплексированного журнала.
[in] fDesiredAccess
ACCESS_MASK, предоставляющий тип доступа, который будет иметь клиент (с помощью указателя, возвращенного в pplfoLog) к потоку. Если этот параметр равен нулю, клиенты могут запрашивать у потока его атрибуты, но не могут выполнять чтение или запись в поток. Этот параметр может иметь нулевое значение или любое сочетание следующих флагов:
| Flag | Значение |
|---|---|
| GENERIC_READ | Клиент имеет доступ на чтение к потоку. |
| GENERIC_WRITE | Клиент имеет доступ на запись к потоку. |
| DELETE | Клиент может пометить поток для удаления. |
[in] dwShareMode
Режим совместного использования потока, который может быть нулевым (не общим) или любым сочетанием следующих флагов:
| Flag | Значение |
|---|---|
| FILE_SHARE_DELETE | Последующие запросы на открытие потока с доступом на удаление будут выполнены успешно. |
| FILE_SHARE_READ | Последующие запросы на открытие потока с доступом на чтение будут выполнены успешно. |
| FILE_SHARE_WRITE | Последующие запросы на открытие потока с доступом на запись будут выполнены успешно. |
[in, optional] psdLogFile
Указатель на структуру SECURITY_DESCRIPTOR , которая предоставляет атрибуты безопасности для потока. Этот параметр может принимать значение NULL.
[in] fCreateDisposition
Действие, которое необходимо выполнить, зависит от того, существует ли поток. Для этого параметра необходимо задать одно из следующих значений:
| Значение | Значение |
|---|---|
| CREATE_NEW | Создайте новый поток, если поток еще не завершает работу. Сбой, если поток уже существует. |
| OPEN_EXISTING | Откройте существующий поток. Сбой, если поток еще не существует. |
| OPEN_ALWAYS | Откройте существующий поток. Создайте поток, если он еще не существует. |
[in] fCreateOptions
Набор флагов, указывающих параметры, применяемые при создании или открытии потока. Этот параметр может быть равен нулю или совместимой комбинации следующих флагов:
| Flag | Значение |
|---|---|
| FILE_NO_INTERMEDIATE_BUFFERING | Записи потока нельзя кэшировать во внутренних буферах драйвера. |
| FILE_SYNCHRONOUS_IO_ALERT | Все операции с потоком выполняются синхронно. Любое ожидание от имени звонящего зависит от преждевременного завершения оповещений. Если этот флаг установлен, флаг FILE_SYNCHRONOUS_IO_NONALERT должен быть снят. |
| FILE_SYNCHRONOUS_IO_NONALERT | Все операции с потоком выполняются синхронно. Ожидания в системе, которые синхронизируют очередь ввода-вывода и завершение, не подлежат оповещениям. Если этот флаг установлен, необходимо очистить флаг FILE_SYNCHRONOUS_IO_ALERT. |
[in] fFlagsAndAttributes
Значение типа , указывающее, открыт ли поток для обычного доступа или только для чтения. Для этого параметра необходимо задать значение :
FILE_ATTRIBUTE_NORMAL или FILE_ATTRIBUTE_READONLY.
[in] fLogOptionFlag
Указание о связи между CLFS и компонентом, создающий или открывающий поток. Для этого параметра необходимо задать одно из следующих значений:
| Значение | Значение |
|---|---|
| CLFS_FLAG_NO_FLAGS | CLFS и компонент создания имеют стандартную нормальную связь. Компоненты режима ядра используют это значение, если они не относятся к одной из трех других категорий, перечисленных в этой таблице. Если параметр pvContext не равен NULL, CLFS проверяет, что значение cbContext больше нуля. В противном случае pvContext и cbContext игнорируются. |
| CLFS_FLAG_REENTRANT_FILE_SYSTEM | Компонент создания — это файловая система, которая предоставляет базовое хранилище для CLFS. CLFS использует файловую систему для выделения контейнеров, а файловая система — потоки CLFS. В этом случае файловая система может вызвать CLFS, а CLFS — обратные вызовы к файловой системе в том же потоке или в разных потоках. Если параметр pvContext не равен NULL, CLFS проверяет, что значение cbContext больше нуля. В противном случае pvContext и cbContext игнорируются. |
| CLFS_FLAG_NON_REENTRANT_FILTER | Компонент создания — это драйвер фильтра файловой системы, который отправляет все свои clFS-ввод-вывод на указанный уровень ниже самого себя в стеке фильтров. Этот параметр позволяет драйверу фильтра создавать журналы CLFS без просмотра собственных операций ввода-вывода в журнале. Вызывающий объект передает объект целевого устройства, отличный от NULL , в параметре pvContext с параметром cbContext , имеющим соответствующий размер. CLFS использует подпрограмму IoCreateFileSpecifyDeviceObjectHint для создания контейнеров на целевом уровне в стеке фильтров ввода-вывода, заданном объектом устройства. |
| CLFS_FLAG_REENTRANT_FILTER | Компонент создания — это драйвер фильтра файловой системы, который отправляет все свои clFS-ввод-вывод в верхнюю часть стека фильтров. Фильтр имеет рекурсивную связь с CLFS, так как он фильтрует собственный ввод-вывод ведения журнала, когда CLFS выполняет какие-либо операции файловой системы с контейнерами. Параметр pvContext предоставляет фильтрам средства для связывания распознаваемого контекста с контейнерами CLFS по мере того, как в стеке фильтров выполняется ввод-вывод журнала. Параметр cbContext указывает размер непрозрачного контекста в байтах. |
| CLFS_FLAG_MINIFILTER_LEVEL | Компонент создания — это драйвер минифильтра файловой системы, который отправляет все свои clFS-ввод-вывод на указанный уровень ниже самого себя в стеке фильтров. Этот параметр позволяет минифильтру создавать журналы CLFS без просмотра собственного ввода-вывода журнала. Вызывающий объект передает объект контекста минифильтра, отличный от NULL , в параметре pvContext с соответствующим размером cbContext . CLFS использует подпрограмму IoCreateFileSpecifyDeviceObjectHint для создания контейнеров на высоте (указанной в контексте минифильтра) в стеке минифильтров диспетчера фильтров. |
[in, optional] pvContext
Указатель на контекст. Способ интерпретации контекста зависит от значения, переданного в fLogOptionsFlag.
[in] cbContext
Размер (в байтах) контекста, на который указывает pvContext. Если pvContext не равно NULL, этот параметр должен быть больше нуля.
Возвращаемое значение
ClfsCreateLogFile возвращает STATUS_SUCCESS в случае успешного выполнения; в противном случае возвращается один из кодов ошибок, определенных в ntstatus.h.
Комментарии
При создании потока CLFS он поддерживается базовым физическим журналом CLFS. Базовый журнал может быть выделенным (поддерживает только один поток) или мультиплексирован (поддерживает несколько потоков). Выделенный журнал не может быть преобразован в мультиплексируемый журнал, а мультиплексный журнал не может быть преобразован в выделенный журнал.
Физическое имя журнала CLFS не включает расширение BLF.
Описание концепций и терминологии CLFS см. в разделе Common Log File System.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Доступно в Windows Server 2003 R2, Windows Vista и более поздних версиях Windows. |
| Целевая платформа | Персональный компьютер |
| Верхняя часть | wdm.h (включая Wdm.h) |
| Библиотека | Clfs.lib |
| DLL | Clfs.sys |
| IRQL | <= APC_LEVEL |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по