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 结尾的字符串，指定要打开的日志文件的名称。 名称可以包含绝对路径或相对路径。

如果 lpdwLogType 参数PDH_LOG_TYPE_SQL，请以 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 参数的值时，数据将换行到日志文件的开头。 仅当PDH_LOG_TYPE_BINARY lpdwLogType 参数时，才能指定此标志。
PDH_LOG_USER_STRING
 与 PDH_LOG_TYPE_TSV 一起使用，以编写由 PdhUpdateLog 或 PdhOpenLog 的 szUserString 参数指示的用户描述文字或日志文件说明。 用户描述文字或日志文件说明将作为文本日志第一行中的最后一列写入。

[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 结尾的字符串，指定日志文件的用户定义描述文字。 日志文件描述文字通常描述日志文件的内容。 打开现有日志文件时，将忽略此参数的值。

[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 [仅限桌面应用]
目标平台 Windows
标头 pdh.h
Library Pdh.lib
DLL Pdh.dll

另请参阅

PdhGetLogFileSize

PdhOpenQuery

PdhUpdateLog

PdhUpdateLogFileCatalog