3.1.4.1.3 PerflibV2EnumerateCounterSetInstances (Opnum 2)

The PerflibV2EnumerateCounterSetInstances method retrieves all active instances of the client-specified counterset on the server.

 error_status_t PerflibV2EnumerateCounterSetInstances(
   [in, string] wchar_t* szMachine,
   [in] GUID* CounterSetGuid,
   [in, range(0, 67108864)] DWORD dwInSize,
   [out] DWORD* pdwOutSize,
   [out] DWORD* pdwRtnSize,
   [out, size_is(dwInSize), length_is(* pdwOutSize)] 
     unsigned char* lpData
 );

szMachine: A Unicode string specifying a server name, which is passed directly to the counter providers. Counter providers can ignore the server name provided by szMachine.

CounterSetGuid: The GUID of the counterset whose instances are to be enumerated.

Return value/code	Description
0x00000000 ERROR_SUCCESS	The return value indicates success.
0x00000005 ERROR_ACCESS_DENIED	The server returns this value to the client if the authentication level of the client is less than RPC_C_AUTHN_LEVEL_PKT_PRIVACY.
0x00001068 ERROR_WMI_GUID_NOT_FOUND	The server returns this value when it cannot find a counterset with the GUID that was specified by the client in the CounterSetGuid parameter.
0x00000008 ERROR_NOT_ENOUGH_MEMORY	The server returns this value to the client when the buffer the client has provided is not large enough to accommodate the instance information.
0x00001069 ERROR_WMI_INSTANCE_NOT_FOUND	The server returns this value to the client when there are no active instances of the counterset whose information can be returned.
0x00001073 ERROR_WMI_INVALID_REGINFO	The server returns this to the client if, for any reason when trying to enumerate counterset instances, the information that the server expected was different than what the applications exposing performance counters returned. For example, the server (through some standard repository), expected information about one instance of a counterset to be returned (because it was specified as a single-instance counterset), but the application actually maintaining the information returned instance information about multiple instances of the counterset.
0x0000000E ERROR_OUTOFMEMORY	The server returns this value to the client if, for any reason as it tries to return the instance information of the specified counterset, it fails to allocate memory.

dwInSize: The size, in bytes, of the buffer.

pdwOutSize: The total size, in bytes, of the data that is returned and written to the buffer.

pdwRtnSize: The necessary size, in bytes, to retrieve all the requested data.

lpData: The buffer that contains the instances information for the counterset.

Return Values: This method MUST return zero (ERROR_SUCCESS) for success; otherwise, it MUST return one of the standard Windows errors, as specified in [MS-ERREF] section 2.2.

The server MUST return a data array in which each element is a _PERF_INSTANCE_HEADER structure that is followed by a null-terminated Unicode string instance name. The size field of the _PERF_INSTANCE_HEADER structure MUST be the size of the _PERF_INSTANCE_HEADER structure plus the space that is occupied by the instance name string; and MUST be an 8-byte multiple.

Figure 3: PerflibV2EnumerateCounterSetInstances return

The following diagram illustrates data size, alignment, and endianness. In this example, information about two instances of the counterset is returned by the server. The first instance name is 6 bytes in length, and the second instance name is 8 bytes in length. The two bytes in padding between the end of the first instance name string and the beginning of the next _PERF_INSTANCE_HEADER structure MUST be uninitialized and MUST be ignored by the client.