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

Статья
08/22/2023

Создает или открывает журнал. Журнал может быть выделенным или мультиплексным, и это зависит от имени журнала. Используйте функцию 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".

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

[in] fDesiredAccess

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

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

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

Примечание Чтобы удалить журнал, необходимо указать доступ DELETE .

Windows Server 2003 R2: Для этого параметра необходимо задать значение GENERIC_WRITE.

[in] dwShareMode

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

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

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

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

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

[in, optional] psaLogFile

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

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

Член lpSecurityDescriptorSECURITY_ATTRIBUTES задает дескриптор безопасности для нового дескриптора журнала. Если psaLogFile имеет значение NULL, объект получает дескриптор безопасности по умолчанию. Списки управления доступом (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 [только классические приложения]
Целевая платформа	Windows
Header	clfsw32.h
Библиотека	Clfsw32.lib
DLL	Clfsw32.dll