pdhGetFormattedCounterValue 函数 (pdh.h)

  • 项目

计算指定计数器的可显示值。

语法

PDH_FUNCTION PdhGetFormattedCounterValue(
  [in]  PDH_HCOUNTER          hCounter,
  [in]  DWORD                 dwFormat,
  [out] LPDWORD               lpdwType,
  [out] PPDH_FMT_COUNTERVALUE pValue
);

参数

[in] hCounter

要计算其可显示值的计数器的句柄。 PdhAddCounter 函数返回此句柄。

[in] dwFormat

确定格式化值的数据类型。 指定以下值之一。

值 含义
PDH_FMT_DOUBLE
 以双精度浮点实数的形式返回数据。
PDH_FMT_LARGE
 以 64 位整数的形式返回数据。
PDH_FMT_LONG
 以长整型的形式返回数据。
 

可以使用位非独占 OR 运算符 (|) 将数据类型与以下缩放因子之一组合在一起。

值 含义
PDH_FMT_NOSCALE
 不要应用计数器的默认缩放因子。
PDH_FMT_NOCAP100
 例如，大于 100 的计数器值 (，测量多处理器计算机上处理器负载的计数器值) 不会重置为 100。 默认行为是计数器值上限为 100。
PDH_FMT_1000
 将实际值乘以 1,000。

[out] lpdwType

接收计数器类型。 有关计数器类型的列表，请参阅 Windows Server 2003 部署工具包的计数器类型部分。 此参数是可选的。

[out] pValue

接收计数器值的 PDH_FMT_COUNTERVALUE 结构。

返回值

如果函数成功，则返回ERROR_SUCCESS。

如果函数失败，则返回值为 系统错误代码 或 PDH 错误代码。 以下是可能的值。

返回代码 说明
PDH_INVALID_ARGUMENT
 参数无效或格式不正确。
PDH_INVALID_DATA
 指定的计数器不包含有效数据或成功状态代码。
PDH_INVALID_HANDLE
 计数器句柄无效。

注解

在调用 PdhGetFormattedCounterValue 期间，计数器的数据被锁定 (受保护的) ，以防止在调用处理过程中发生任何更改。 读取数据 (成功调用此函数) 清除计数器的数据更改标志。

某些计数器（如速率计数器）需要两个计数器值才能计算可显示的值。 在这种情况下，必须在调用 PdhGetFormattedCounterValue 之前调用 PdhCollectQueryData 两次。 有关详细信息，请参阅 收集性能数据。

如果指定的计数器实例不存在，该方法将返回PDH_INVALID_DATA并将PDH_FMT_COUNTERVALUE结构的 CStatus 成员设置为PDH_CSTATUS_NO_INSTANCE。

在 Windows Server 2003 之前： 当找不到实例时，仅需要单个值的计数器的格式调用可能会失败。 尝试调用查询并再次格式化调用。 如果格式调用第二次失败，则找不到实例。 作为替代方法，可以在将 refresh 选项设置为 TRUE 的情况下调用 PdhEnumObjects 函数，以在查询计数器数据并设置计数器数据格式之前刷新计数器实例。

示例

有关示例，请参阅 浏览性能计数器 或 从日志文件读取性能数据。

要求

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

另请参阅

PdhCollectQueryData

PdhGetRawCounterValue

PdhSetCounterScaleFactor