3.1.4.1.2 PerflibV2QueryCounterSetRegistrationInfo (Opnum 1)

  • Article

The PerflibV2QueryCounterSetRegistrationInfo method allows a client to enumerate metadata about a counterset or performance counter on a server. 

 error_status_t PerflibV2QueryCounterSetRegistrationInfo(
   [in, string] wchar_t* szMachine,
   [in] GUID* CounterSetGuid,
   [in] DWORD RequestCode,
   [in] DWORD RequestLCID,
   [in, range(0, 134217728)] 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 information needs to be retrieved; this can also be the GUID of the counterset to which the performance counters whose information is being queried belong.

RequestCode: The type of information on the counterset to retrieve. The value MUST be one of the following.

Value

Meaning

0x00000001

Return information about the counterset.

0x00000002

Return information about a performance counter.

0x00000003

Return the name of the counterset.

0x00000004

Return the description of the counterset.

0x00000005

Return the names of the performance counters.

0x00000006

Return the descriptions of the performance counters.

0x00000007

Return the name of the provider.

0x00000008

Return the GUID of the provider.

0x00000009

Return the English-language name of the counterset.

0x0000000A

Return the English-language names of the performance counters.

RequestLCID: When the value of RequestCode is 0x00000003, 0x00000004, 0x00000005, or 0x00000006, RequestLCID specifies the locale ID (as specified in [MS-LCID]), or is set to 0 to instruct the server to use its default language.

When the value of RequestCode is 0x00000002, RequestLCID specifies the counter ID.

When the value of RequestCode is 0x00000001, 0x00000007, 0x00000008, 0x00000009, or 0x0000000A, RequestLCID MUST be set to zero and ignored upon receipt.<4>

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

pdwOutSize: The size, in bytes, of the data in the buffer pointed to by lpData.

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

lpData: The buffer that returns the requested data.

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.

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.

0x00000057

ERROR_INVALID_PARAMETER

This return value indicates that there was a problem with the parameter that was passed by the client to the server. The server MUST return this value when:

  • RequestCode (the RequestCode is not between 0x00000001 and 0x0000000A inclusive).

0x00001068

ERROR_WMI_GUID_NOT_FOUND

The server returns this value if it does not have a counterset with the same GUID as the one passed by the client through the CounterSetGuid parameter of the method.

The server will also return this value if it cannot find the GUID of the provider to which the counterset belongs.

0x00000008

ERROR_NOT_ENOUGH_MEMORY

The server will return this value to the client if the RequestCode parameter is valid, but the buffer pointed to by lpData is not of sufficient size.

0x0000106A

ERROR_WMI_ITEMID_NOT_FOUND

The server returns this error code when the value of RequestCode is 0x02 and a counterset with the GUID provided through the CounterSetGuid parameter exists, but the counter identifier is not found in the counterset.

The data that this method returns depends on the type of information that is requested, as denoted by the RequestCode parameter.

  • If the value of RequestCode is 0x00000003, 0x00000004, 0x00000005, or 0x00000006, and the language specified by RequestLCID is not installed on the server, an error MUST be returned.

  • If RequestCode = 0x00000001, the server returns information about the counterset. The server MUST return a _PERF_COUNTERSET_REG_INFO structure that is followed by a set of _PERF_COUNTER_REG_INFO structures. The number of _PERF_COUNTER_REG_INFO structures MUST be equal to the NumCounters field of the PERF_COUNTERSET_REG_INFO structure.

PerflibV2QueryCounterSetRegistrationInfo return if RequestCode = 0x00000001

Figure 1: PerflibV2QueryCounterSetRegistrationInfo return if RequestCode = 0x00000001

The following diagram illustrates data size, alignment, and endianness.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

_PERF_COUNTERSET_REG_INFO (row 1, CounterSetGuid)

_PERF_COUNTERSET_REG_INFO (row 2, CounterSetGuid)

_PERF_COUNTERSET_REG_INFO (row 3, CounterSetGuid)

_PERF_COUNTERSET_REG_INFO (row 4, CounterSetGuid)

_PERF_COUNTERSET_REG_INFO (row 5, CounterSetType)

_PERF_COUNTERSET_REG_INFO (row 6, DetailLevel)

_PERF_COUNTERSET_REG_INFO (row 7, NumCounters)

_PERF_COUNTERSET_REG_INFO (row 8, InstanceType)

_PERF_COUNTER_REG_INFO (row 1, CounterId)

_PERF_COUNTER_REG_INFO (row 2, Type)

_PERF_COUNTER_REG_INFO (row 3, Attrib)

_PERF_COUNTER_REG_INFO (row 4, Attrib)

_PERF_COUNTER_REG_INFO (row 5, DetailLevel)

_PERF_COUNTER_REG_INFO (row 6, DefaultScale)

_PERF_COUNTER_REG_INFO (row 7, BaseCounterId)

_PERF_COUNTER_REG_INFO (row 8, PerfTimeId)

_PERF_COUNTER_REG_INFO (row 9, PerfFreqId)

_PERF_COUNTER_REG_INFO (row 10, MultiId)

_PERF_COUNTER_REG_INFO (row 11, AggregateFunc)

_PERF_COUNTER_REG_INFO (row 12, Reserved)

  • If RequestCode = 0x00000002, the server returns information about a performance counter. The server MUST return a _PERF_COUNTER_REG_INFO structure.

The following diagram illustrates data size, alignment, and endianness.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

_PERF_COUNTER_REG_INFO (row 1, CounterId)

_PERF_COUNTER_REG_INFO (row 2, Type)

_PERF_COUNTER_REG_INFO (row 3, Attrib)

_PERF_COUNTER_REG_INFO (row 4, Attrib)

_PERF_COUNTER_REG_INFO (row 5, DetailLevel)

_PERF_COUNTER_REG_INFO (row 6, DefaultScale)

_PERF_COUNTER_REG_INFO (row 7, BaseCounterId)

_PERF_COUNTER_REG_INFO (row 8, PerfTimeId)

_PERF_COUNTER_REG_INFO (row 9, PerfFreqId)

_PERF_COUNTER_REG_INFO (row 10, MultiId)

_PERF_COUNTER_REG_INFO (row 11, AggregateFunc)

_PERF_COUNTER_REG_INFO (row 12, Reserved)

  • If RequestCode = 0x00000003, 0x00000004, or 0x00000009, the server returns either the localized name (RequestCode = 0x00000003) or description (RequestCode = 0x00000004). The RequestCode 0x00000009 specifies returning the name as an English-language string. The server MUST return a null-terminated Unicode string.

  • If RequestCode = 0x00000005, 0x00000006, or 0x0000000A, the server returns either the localized names (RequestCode = 0x00000005) or descriptions (RequestCode = 0x00000006). The RequestCode 0x0000000A specifies returning the names of the counters as English-language strings. The server MUST return a _STRING_BUFFER_HEADER structure that is followed by a set of _STRING_COUNTER_HEADER structures and then a set of null-terminated Unicode strings and MUST be 8-byte aligned. The number of _STRING_COUNTER_HEADER structures MUST be equal to the dwCounters field of the _STRING_BUFFER_HEADER structure. The offset to the beginning of a string is the size of the _STRING_BUFFER_HEADER plus the size of the _STRING_COUNTER_HEADER structures that are multiplied by the number of counters plus the dwOffset value of the _STRING_COUNTER_HEADER structure.

PerflibV2QueryCounterSetRegistrationInfo return if RequestCode = 0x00000005

Figure 2: PerflibV2QueryCounterSetRegistrationInfo return if RequestCode = 0x00000005

The following diagram illustrates data size, alignment, and endianness. In this example, the names of two performance counters are returned (STRING_BUFFER_HEADER.dwCounters == 2). The name of the first counter is 6 bytes in length, while the name of the second counter is 8 bytes in length.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

_STRING_BUFFER_HEADER (row 1, dwSize)

_STRING_BUFFER_HEADER (row 2, dwCounters)

_STRING_COUNTER_HEADER (row 1, dwCounterId)

_STRING_COUNTER_HEADER (row 2, dwOffset)

_STRING_COUNTER_HEADER (row 1, dwCounterId)

_STRING_COUNTER_HEADER (row 2, dwOffset)

Unicode String Name of the first counter

Name of the First Counter

Unicode String Name of the Second Counter

Unicode String Name of the second counter

Name of the Second Counter

Padding (MUST be uninitialized)

  • If RequestCode = 0x00000007, the server returns the name of the performance counter provider. The server MUST return a null-terminated Unicode string.

  • If RequestCode = 0x00000008, the server returns the GUID of the performance counter provider. The server MUST return a GUID.