PerfEnumerateCounterSetInstances function (perflib.h)

Article
10/13/2021

Gets the names and identifiers of the active instances of a counter set on the

specified system.

Syntax

ULONG PerfEnumerateCounterSetInstances(
  [in, optional]  LPCWSTR               szMachine,
  [in]            LPCGUID               pCounterSetId,
  [out, optional] PPERF_INSTANCE_HEADER pInstances,
                  DWORD                 cbInstances,
  [out]           LPDWORD               pcbInstancesActual
);

Parameters

[in, optional] szMachine

The name of the machine for which to get the information about the active instances of the counter set that the pCounterSet parameter specifies. If NULL, the function retrieves information about the active instances of the specified counter set for the local machine.

[in] pCounterSetId

The counter set identifier of the counter set for which you want to get the information about of the active instances.

[out, optional] pInstances

Pointer to a buffer that is large enough to receive the amount of data that the cbInstances parameter specifies. May be

NULL if cbInstances is 0.

cbInstances

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

[out] pcbInstancesActual

The size of the buffer actually required to get the information about of the active instances. The meaning depends on the value that the function

returns.

Function Return Value	Meaning of pcbInstancesActual
ERROR_SUCCESS	The number of bytes of information about the active instances of the specified counter set that the function stored in the buffer that pInstances specified.
ERROR_NOT_ENOUGH_MEMORY	The size of the buffer required to store the information about the active instances of the counter set on the specified machine, in bytes. Enlarge the buffer to the required size and call the function again.
Other	The value is undefined and should not be used.

Function Return Value

Meaning of pcbInstancesActual

ERROR_SUCCESS

The number of

bytes of information about the active instances of the specified counter set that the function stored in the buffer that pInstances specified.

ERROR_NOT_ENOUGH_MEMORY

The

size of the buffer required to store the information about the active instances of the counter set on the specified machine, in bytes. Enlarge the buffer to the required

size and call the function again.

Other

The value is undefined and should not be used.

Return value

Return code	Description
ERROR_SUCCESS	The function successfully stored all of the information about the active instances of the counter set in the buffer that pInstances specified. The value that pcbInstancesActual points to indicates amount of information actually stored in the buffer, in bytes.
ERROR_NOT_ENOUGH_MEMORY	The buffer that pInstances specified was not large enough to store all of the information about the active instances of the counter set. The value that pcbInstancesActual points to indicates the size of the buffer required to store all of the information. Enlarge the buffer to the required size and call the function again.

For other types of failures, the return value is a system error code.

Remarks

The information about the active instances of the specified counter set is written to the buffer that pInstances specifies as a sequence of PERF_INSTANCE_HEADER blocks. The size in bytes of

the sequence of blocks is written to pcbInstancesActual. Each PERF_INSTANCE_HEADER block consists

of a PERF_INSTANCE_HEADER structure, immediately followed by a null-terminated UTF-16LE

instance name, followed by padding so that the size of the

PERF_INSTANCE_HEADER block is a multiple of 8 bytes.

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