Функция PdhOpenLogW (pdh.h)

Статья
11/20/2024

Открывает указанный файл журнала для чтения или записи.

Синтаксис

PDH_FUNCTION PdhOpenLogW(
  [in]  LPCWSTR    szLogFileName,
  [in]  DWORD      dwAccessFlags,
  [in]  LPDWORD    lpdwLogType,
  [in]  PDH_HQUERY hQuery,
  [in]  DWORD      dwMaxSize,
  [in]  LPCWSTR    szUserCaption,
  [out] PDH_HLOG   *phLog
);

Параметры

[in] szLogFileName

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

Если PDH_LOG_TYPE_SQLпараметр lpdwLogType, укажите имя файла журнала в форме, SQL:DataSourceName!LogFileName.

[in] dwAccessFlags

Тип доступа, используемый для открытия файла журнала. Укажите одно из следующих значений.

Ценность	Значение
PDH_LOG_READ_ACCESS	Откройте файл журнала для чтения.
PDH_LOG_WRITE_ACCESS	Откройте новый файл журнала для записи.
PDH_LOG_UPDATE_ACCESS	Откройте существующий файл журнала для записи.

Для объединения типа доступа с одним или несколькими флагами создания можно использовать побитовую или оператор (|).

Ценность	Значение
PDH_LOG_CREATE_NEW	Создает новый файл журнала с указанным именем.
PDH_LOG_CREATE_ALWAYS	Создает новый файл журнала с указанным именем. Если файл журнала уже существует, функция удаляет существующий файл журнала перед созданием нового файла.
PDH_LOG_OPEN_EXISTING	Открывает существующий файл журнала с указанным именем. Если файл журнала с указанным именем не существует, это равно PDH_LOG_CREATE_NEW.
PDH_LOG_OPEN_ALWAYS	Открывает существующий файл журнала с указанным именем или создает новый файл журнала с указанным именем.
PDH_LOG_OPT_CIRCULAR	Создает циклический файл журнала с указанным именем. Когда файл достигает значения параметра dwMaxSize, данные упаковываются в начало файла журнала. Этот флаг можно указать, только если параметр lpdwLogTypePDH_LOG_TYPE_BINARY.
PDH_LOG_USER_STRING	Используется с PDH_LOG_TYPE_TSV для записи описания заголовка пользователя или файла журнала, указанного параметром szUserString PdhUpdateLog или PdhOpenLog. Описание заголовка пользователя или файла журнала записывается как последний столбец в первой строке текстового журнала.

[in] lpdwLogType

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

Ценность	Значение
PDH_LOG_TYPE_UNDEFINED	Неопределенный формат файла журнала. Если задано, PDH определяет тип файла журнала. Это значение нельзя указать, если параметр dwAccessFlagsPDH_LOG_WRITE_ACCESS.
PDH_LOG_TYPE_CSV	Текстовый файл, содержащий заголовки столбцов в первой строке и отдельные записи данных в каждой следующей строке. Поля каждой записи данных разделены запятыми. Первая строка также содержит сведения о формате файла, версии PDH, используемой для создания файла журнала, а также имена и пути каждого счетчика.
PDH_LOG_TYPE_SQL	Источником данных файла журнала является база данных SQL.
PDH_LOG_TYPE_TSV	Текстовый файл, содержащий заголовки столбцов в первой строке и отдельные записи данных в каждой следующей строке. Поля каждой записи данных разделены табуляции. Первая строка также содержит сведения о формате файла, версии PDH, используемой для создания файла журнала, а также имена и пути каждого счетчика.
PDH_LOG_TYPE_BINARY	Формат файла двоичного журнала.

[in] hQuery

Укажите дескриптор запроса, если вы записываете данные запроса в файл журнала. Функция PdhOpenQuery возвращает этот дескриптор.

Этот параметр игнорируется и должен быть NULL при чтении из файла журнала.

[in] dwMaxSize

Максимальный размер файла журнала в байтах. Укажите максимальный размер, если требуется ограничить размер файла или если dwAccessFlags указывает PDH_LOG_OPT_CIRCULAR; в противном случае задайте значение 0.

Для циклических файлов журнала необходимо указать достаточно большое значение, чтобы содержать по крайней мере один пример. Размер выборки зависит от собираемых данных. Однако указание значения по крайней мере одного мегабайта будет охватывать большинство примеров.

[in] szUserCaption

строка null-terminated, указывающая определяемую пользователем подпись файла журнала. Заголовок файла журнала обычно описывает содержимое файла журнала. При открытии существующего файла журнала значение этого параметра игнорируется.

[out] phLog

Обработка открытого файла журнала.

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

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

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

Замечания

Чтобы использовать эту функцию для записи данных производительности в файл журнала, необходимо открыть запрос с помощью PdhOpenQuery и добавить в него нужные счетчики перед вызовом этой функции.

Новые операционные системы могут считывать файлы журналов, созданные в старых операционных системах; однако файлы журналов, созданные в Windows Vista и более поздних операционных системах, не могут быть прочитаны в более ранних операционных системах.

Следующие правила применяются к файлам журналов

READ_ACCESS требуется OPEN_EXISTING.
UPDATE_ACCESS нельзя использовать с журналами на основе файлов. Его можно использовать только с журналами базы данных.
WRITE_ACCESS требуется один из CREATE_NEW, CREATE_ALWAYS, OPEN_EXISTING, OPEN_ALWAYS.

Примеры

Пример см. в разделе записи данных о производительности в файл журнала.

Заметка

Заголовок pdh.h определяет PdhOpenLog как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

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

См. также

PdhGetLogFileSize

PdhOpenQuery

PdhUpdateLog

PdhUpdateLogFileCatalog

Поделиться через