Функция 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:c:\myLog создает или открывает выделенный журнал и один поток.
- Log:c:\myCommonLog::" создает мультиплексированные журналы, которые еще не имеют потоков.
- "Log:c:\myCommonLog::Stream1" создает или открывает один из потоков (Stream1) мультиплексированного журнала.
[in] fDesiredAccess
ACCESS_MASK, предоставляющий тип доступа, который будет иметь клиент (с помощью указателя, возвращенного в pplfoLog) в поток. Если этот параметр равен нулю, клиенты могут запрашивать поток для его атрибутов, но не могут считывать из потока или записывать их в поток. Этот параметр может быть нулевым или любым сочетанием следующих флагов:
| Флаг | Значение |
|---|---|
| GENERIC_READ | Клиент имеет доступ на чтение к потоку. |
| GENERIC_WRITE | Клиент имеет доступ на запись к потоку. |
| УДАЛИТЬ | Клиент может пометить поток для удаления. |
[in] dwShareMode
Режим общего доступа потока, который может быть нулевым (не общим) или любым сочетанием следующих флагов:
| Флаг | Значение |
|---|---|
| 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
Набор флагов, определяющих параметры, применяемые при создании или открытии потока. Этот параметр может быть нулевым или совместимым сочетанием следующих флагов:
| Флаг | Значение |
|---|---|
| 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, отличный от 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 (include Wdm.h) |
| библиотеки | Clfs.lib |
| DLL | Clfs.sys |
| IRQL | <= APC_LEVEL |