PdhGetFormattedCounterValue

The PdhGetFormattedCounterValue function returns the current value of a specified counter in the format requested by the caller.

PDH_STATUS PdhGetFormattedCounterValue(
  HCOUNTER hCounter,            
  DWORD dwFormat,               
  LPDWORD lpdwType,             
  PPDH_FMT_COUNTERVALUE pValue  
);

Parameters

hCounter

[in] A handle to the counter whose current value is to be formatted and returned.

dwFormat

[in] The formatting information sent by the caller to indicate how the data should be returned. This parameter can be one of the following values.

Value	Meaning
PDH_FMT_DOUBLE	Return data as a double-precision floating point real.
PDH_FMT_LARGE	Return data as a 64-bit integer.
PDH_FMT_LONG	Return data as a long integer.

The value selected from the previous table can be combined using the OR operator with one of the following scaling flags.

Value	Meaning
PDH_FMT_NOSCALE	Do not apply the default scaling factor.
PDH_FMT_NOCAP100	Counter values above 100 (for example, counter values measuring the processor load on multiprocessor machines) will not be reset to 100. The default behavior is that counter values are capped at a value of 100.
PDH_FMT_1000	Multiply the actual value by 1000.

lpdwType

[out] A pointer to a DWORD that receives the counter type. The possible counter types are described in WINPERF.H. This parameter is optional.

pValue

[out] A pointer to a PDH_FMT_COUNTERVALUE structure that receives the counter value.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMsg.h. The following are possible error values.

Remarks

The data for the counter is locked (protected) for the duration of the call to PdhGetFormattedCounterValue to prevent any changes during the processing of the call. Reading the data (calling this function successfully) clears the data-changed flag for the counter.

Obtaining the value of rate counters such as Page faults/sec requires that PdhCollectQueryData be called twice, with a specific time interval between the two calls, before calling PdhGetFormattedCounterValue. Call Sleep to implement the waiting period between the two calls to PdhCollectQueryData.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Header: Declared in Pdh.h.
  Library: Use Pdh.lib.

See Also

PdhGetRawCounterValue, PdhSetCounterScaleFactor, PdhCollectQueryData