通过

PdhOpenLogA 函数 （pdh.h）

  • 项目

打开指定的日志文件以读取或写入。

语法

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

参数

[in] szLogFileName

Null-terminated 字符串，指定要打开的日志文件的名称。 该名称可以包含绝对路径或相对路径。

如果 PDH_LOG_TYPE_SQLlpdwLogType 参数，请指定表单中日志文件的名称，SQL：DataSourceName！LogFileName。

[in] dwAccessFlags

用于打开日志文件的访问类型。 指定以下值之一。

价值 意义
PDH_LOG_READ_ACCESS
 打开日志文件进行读取。
PDH_LOG_WRITE_ACCESS
 打开新的日志文件进行写入。
PDH_LOG_UPDATE_ACCESS
 打开现有日志文件进行写入。
 

可以使用位非独占 OR 运算符 （|） 将访问类型与以下一个或多个创建标志组合在一起。

价值 意义
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 参数的值时，数据将换行到日志文件的开头。 仅当 lpdwLogType 参数 PDH_LOG_TYPE_BINARY时，才能指定此标志。
PDH_LOG_USER_STRING
 与 PDH_LOG_TYPE_TSV 一起使用，编写由 PdhUpdateLog 或 PdhOpenLogszUserString 参数指示的用户标题或日志文件说明。 用户标题或日志文件说明将编写为文本日志第一行中的最后一列。

[in] lpdwLogType

要打开的日志文件的类型。 此参数可以是下列值之一。

价值 意义
PDH_LOG_TYPE_UNDEFINED
 未定义的日志文件格式。 如果指定，PDH 将确定日志文件类型。 如果 dwAccessFlags 参数 PDH_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 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的 约定。

要求

要求 价值
最低支持的客户端 Windows XP [仅限桌面应用]
支持的最低服务器 Windows Server 2003 [仅限桌面应用]
目标平台 窗户
标头 pdh.h
库 Pdh.lib
DLL Pdh.dll

另请参阅

PdhGetLogFileSize

PdhOpenQuery

PdhUpdateLog

PdhUpdateLogFileCatalog