PerfAddCounters function (perflib.h)

Article
10/13/2021

Adds performance counter specifications to the specified query.

Syntax

ULONG PerfAddCounters(
  [in]      HANDLE                   hQuery,
  [in, out] PPERF_COUNTER_IDENTIFIER pCounters,
            DWORD                    cbCounters
);

Parameters

[in] hQuery

A handle to the query to which you want to add performance counter specifications.

[in, out] pCounters

A pointer to the performance counter specifications that you want to add.

cbCounters

The size of the buffer that the pCounters parameter specifies, in bytes.

Return value

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a system error code.

Remarks

The pCounters parameter should point to a sequence of PERF_COUNTER_IDENTIFIER blocks. Each PERF_COUNTER_IDENTIFIER block consists of a PERF_COUNTER_IDENTIFIER structure, optionally followed by a null-terminated UTF-16LE instance name string, followed by padding that makes the size of the block a multiple of 8 bytes.

For each PERF_COUNTER_IDENTIFIER block:

Set the CounterSetGuid member of the PERF_COUNTER_IDENTIFIER structure to the identifier of the counter set to be queried.
Set the Status member of the PERF_COUNTER_IDENTIFIER structure to 0.
Set Size member of the PERF_COUNTER_IDENTIFIER structure to the size of the PERF_COUNTER_IDENTIFIER block in bytes, including the PERF_COUNTER_IDENTIFIER structure, the instance name, and the padding. The value of Size must be a multiple of 8.
Set the CounterId member of the PERF_COUNTER_IDENTIFIER structure to the identifier of the counter that should be returned by the query. To return all counters, set CounterId to PERF_WILDCARD_COUNTER.
Set the InstanceId member of the PERF_COUNTER_IDENTIFIER structure to the identifier of the instance that should be returned by the query. If no filtering should be done based on instance identifier, set InstanceId to PERF_WILDCARD_COUNTER.
Set the Index member of the PERF_COUNTER_IDENTIFIER structure to 0.
Set the Reserved member of the PERF_COUNTER_IDENTIFIER structure to 0.
Include the instance name immediately after the PERF_COUNTER_IDENTIFIER structure.
- If the counter set is single-instance, do not set the instance name. In this case, the value of the Size member of the PERF_COUNTER_IDENTIFIER structure must be the size of the PERF_COUNTER_IDENTIFIER structure.
- If the counter set is multiple-instance, you must set the instance name. If you do not want to filter the performance counter specifications based on instance name, use PERF_WILDCARD_INSTANCE as the instance name.

PerfAddCounters attempts to add one counter specification to the query for each PERF_COUNTER_IDENTIFIER block, and updates the Status member of the PERF_COUNTER_IDENTIFIER structure in each block with the result of the attempt.

Requirements

Requirement	Value
Minimum supported client	Windows 10, version 1607 [desktop apps only]
Minimum supported server	Windows Server 2016 [desktop apps only]
Target Platform	Windows
Header	perflib.h
Library	AdvAPI32.lib
DLL	AdvAPI32.dll