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

Статья
08/25/2023

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

Синтаксис

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

Если параметр lpdwLogType имеет значение PDH_LOG_TYPE_SQL, укажите имя файла журнала в форме 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 для записи описания файла подпись пользователя или журнала, указанного параметром szUserStringpdhUpdateLog или 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, указывающая определяемую пользователем подпись файла журнала. В подпись файла журнала обычно описывается содержимое файла журнала. При открытии существующего файла журнала значение этого параметра игнорируется.

[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 или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	pdh.h
Библиотека	Pdh.lib
DLL	Pdh.dll