PdhGetFormattedCounterValue

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

PDH_STATUS PdhGetFormattedCounterValue(
  IN HCOUNTER hCounter,            // handle of the counter
  IN DWORD dwFormat,               // formatting flag
  IN LPDWORD lpdwType,             // counter type
  IN PPDH_FMT_COUNTERVALUE pValue  // counter value
);
 

Parameters

hCounter

The handle of the counter whose current value is to be formatted and returned.

dwFormat

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

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:

PDH_FMT_NOSCALE

Do not apply the default scaling factor.

PDH_FMT_1000

Multiply the actual value by 1000.

lpdwType

A pointer to a DWORD buffer that will receive the counter type. The possible counter types are described in winperf.h. This parameter is optional.

pValue

A pointer to the data buffer that will receive 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:

PDH_INVALID_ARGUMENT

An argument is not correct or is incorrectly formatted.

PDH_INVALID_DATA

The specified counter does not contain valid data or a successful status code.

PDH_INVALID_HANDLE

The counter handle is not valid.

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.

See Also

Performance Data Helper Overview, Performance Data Functions, , PdhGetRawCounterValue, PdhSetCounterScaleFactor