Функция CreateLogFile (clfsw32.h)

Статья
11/20/2024

Создает или открывает журнал. Журнал может быть выделен или мультиплексирован, и это зависит от имени журнала. Чтобы закрыть журнал, используйте функцию CloseHandle.

Синтаксис

CLFSUSER_API HANDLE CreateLogFile(
  [in]           LPCWSTR               pszLogFileName,
  [in]           ACCESS_MASK           fDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES psaLogFile,
  [in]           ULONG                 fCreateDisposition,
  [in]           ULONG                 fFlagsAndAttributes
);

Параметры

[in] pszLogFileName

Имя журнала.

Это имя указывается при создании журнала с помощью CreateLogFile. В следующем примере определяется используемый формат.

журнал :<LogName>[::<LogStreamName>]

Например, путь "LOG:c:\MyDirectory\MyLog" создает файл "c:\MyDirectory\MyLog.blf". Путь "?? \LOG:\HarddiskVolume1\MyDirectory\MyLog" создает файл "\.\HarddiskVolume1\MyDirectory\MyLog.blf", как и путь "\clfs\Device\HarddiskVolume1\MyDirectory\MyLog".

< LogName> соответствует допустимому пути к файлу в файловой системе, а <> LogStreamName — уникальное имя потока журнала в журнале. Дополнительные сведения см. втипов журналов .

[in] fDesiredAccess

Тип доступа, который возвращенный дескриптор имеет к объекту журнала.

Ценность	Значение
GENERIC_READ	Указывает доступ на чтение к объекту.
GENERIC_WRITE	Указывает доступ на запись к объекту.
DELETE	Указание доступа к удалению журнала

Побитовая OR двух или более этих флагов позволяет сочетаниям операций чтения, записи и удаления доступа к объекту.

Примечание Необходимо указать, ДОСТУП DELETE для удаления журнала.

Windows Server 2003 R2: Этот параметр должен иметь значение GENERIC_WRITE.

[in] dwShareMode

Режим общего доступа файла.

Клиент не может запрашивать режим общего доступа, который конфликтует с любым режимом, указанным в любом предыдущем открытом запросе, который имеет открытый дескриптор.

Если этот параметр равен нулю, а функция выполнена успешно, объект не может быть предоставлен общий доступ и не может быть открыт снова, пока дескриптор не будет закрыт.

Этот параметр может быть одним или несколькими из следующих значений.

Ценность	Значение
FILE_SHARE_DELETE	Позволяет открывать операции с объектом для запроса доступа к удалению. Без этого значения другие процессы не могут открыть объект, если запрашивается доступ к удалению.
FILE_SHARE_READ	Позволяет открывать операции с объектом для запроса доступа на чтение. Без этого значения другие процессы не могут открыть объект, если требуется доступ на чтение.
FILE_SHARE_WRITE	Позволяет открывать операции с объектом для запроса доступа на запись. Без этого значения другие процессы не могут открыть объект, если требуется доступ на запись.

[in, optional] psaLogFile

Указатель на структуру SECURITY_ATTRIBUTES, указывающую атрибуты безопасности журнала.

Определяет, может ли возвращаемый дескриптор наследоваться дочерними процессами. Если этот параметр null, то дескриптор не может быть унаследован.

Элемент SECURITY_ATTRIBUTES lpSecurityDescriptor задает дескриптора безопасности для нового дескриптора журнала. Если psaLogFileNULL, объект получает дескриптор безопасности по умолчанию. Списки управления доступом (ACL) в дескрипторе безопасности по умолчанию для журнала поступают из основного или олицетворения маркера создателя.

[in] fCreateDisposition

Действие, выполняемое.

Этот параметр может быть одним из следующих значений.

Ценность	Значение
CREATE_NEW	Создает новый файл и завершается ошибкой, если файл уже существует.
OPEN_EXISTING	Открывает существующий файл и завершается ошибкой, если файл не существует.
OPEN_ALWAYS	Открывает существующий файл или создает файл, если он не существует.

[in] fFlagsAndAttributes

Атрибуты и флаги файла.

Этот параметр может принимать следующие значения.

Ценность	Значение
FILE_ATTRIBUTE_ARCHIVE	Этот неэфемерный журнал должен быть архивирован. Если этот флаг не указан, журнал не должен быть архивирован, а архивный хвост не поддерживается для контейнеров журналов переработки.
FILE_FLAG_OVERLAPPED	Если установлен флаг FILE_FLAG_OVERLAPPED, все остальные значения флага игнорируются. Указание FILE_FLAG_OVERLAPPED означает, что файл открыт для перекрывающихся операций ввода-вывода, что позволяет выполнять несколько операций ввода-вывода в дескрипторе журнала. Если этот флаг задан при создании журнала, все асинхронные вызовы ввода-вывода в этот журнал должны указывать перекрывающуюся структуру и синхронизировать с отложенным завершением вызова.

Ценность

Значение

FILE_ATTRIBUTE_ARCHIVE

Этот неэфемерный журнал должен быть архивирован.

Если этот флаг не указан, журнал не должен быть архивирован, а архивный хвост не поддерживается для контейнеров журналов переработки.

FILE_FLAG_OVERLAPPED

Если установлен флаг FILE_FLAG_OVERLAPPED, все остальные значения флага игнорируются.

Указание FILE_FLAG_OVERLAPPED означает, что файл открыт для перекрывающихся операций ввода-вывода, что позволяет выполнять несколько операций ввода-вывода в дескрипторе журнала. Если этот флаг задан при создании журнала, все асинхронные вызовы ввода-вывода в этот журнал должны указывать перекрывающуюся структуру и синхронизировать с отложенным завершением вызова.

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

Если функция выполнена успешно, возвращаемое значение является дескриптором журнала.

Если функция завершается ошибкой, возвращаемое значение INVALID_HANDLE_VALUE. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

Следующий список определяет возможные коды ошибок:

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 R2 [только классические приложения]
целевая платформа	Виндоус
заголовка	clfsw32.h
библиотеки	Clfsw32.lib
DLL	Clfsw32.dll