PdhComputeCounterStatistics

The PdhComputeCounterStatistics function computes statistics for a counter from an array of raw values.

PDH_STATUS PdhComputeCounterStatistics(
  IN HCOUNTER hCounter,  // handle of the counter
  IN DWORD dwFormat,     // format code
  IN DWORD dwFirstEntry, // first entry in the array
  IN DWORD dwNumEntries, // number of entries in the array
  IN PPDH_RAW_COUNTER lpRawValueArray,
                         // array of raw counter values
  IN PPDH_STATISTICS data  // buffer for counter statistics
);
 

Parameters

hCounter

The handle of the counter used for the computation. This determines how the data will be computed.

dwFormat

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

PDH_FMT_DOUBLE

Return the calculated value as a double-precision floating point real.

PDH_FMT_LARGE

Return the calculated value as a 64-bit integer.

PDH_FMT_LONG

Return the calculated value 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 counter's scaling factors in the calculation.

PDH_FMT_1000

Multiply the final value by 1000.

dwFirstEntry

The zero-based index of the first raw counter buffer to look at. This value must point to the oldest entry in the buffer. The PdhComputeCounterStatistics function starts at this entry and scans through the buffer, wrapping at the last entry back to the beginning of the buffer and up to the dwFirstEntry-1 entry, which is assumed to be the newest or most recent data.

dwNumEntries

The number of raw counter entries in the lpRawValueArray buffer.

lpRawValueArray

A pointer to the raw counter value or values used to compute the counter value. Some counters (for example, rate counters) require two values for a calculation. The format of the buffer is assumed to be an array of PDH_RAW_COUNTER structures that contain dwNumEntries entries.

data

A pointer to the PDH_STATISTICS buffer to receive the counter statistics.

Return Values

If the function succeeds, it returns ERROR_SUCCESS. The function can return successfully, but the returned data buffer can contain invalid data. Always check the CStatus member of the data buffer before using the returned statistics.

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_HANDLE

The counter handle is not valid.

See Also

Performance Data Helper Overview, Performance Data Functions, , PdhCalculateCounterFromRawValue, PdhGetRawCounterValue, PDH_RAW_COUNTER, PdhSetCounterScaleFactor, PDH_STATISTICS