3.1.4.1.6 PerflibV2QueryCounterData (Opnum 6)

The PerflibV2QueryCounterData method retrieves data for the performance counters associated with the query. Performance counters can be added or removed from queries by calling PerflibV2ValidateCounters.

 error_status_t PerflibV2QueryCounterData(
   [in] RPC_HQUERY hQuery,
   [in, range(0, 1073741824)] DWORD dwInSize,
   [out] DWORD* pdwOutSize,
   [out] DWORD* pdwRtnSize,
   [out, size_is(dwInSize), length_is(* pdwOutSize)] 
     unsigned char* lpData
 );

hQuery: The handle returned by the PerflibV2OpenQueryHandle method; an exception is thrown or an error is returned by RPC if the handle did not originate from the PerflibV2OpenQueryHandle method.

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

pdwOutSize: The 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 requested counter information.

Return Values: This method MUST return zero (ERROR_SUCCESS) for success; otherwise, it MUST return one of the standard Windows error codes, 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.
0x00000008 ERROR_NOT_ENOUGH_MEMORY	The server will return this value to the client if the size of the buffer pointed to by lpData is not of sufficient size to return the performance counter values to the client.

The server MUST return a _PERF_DATA_HEADER structure that is followed by a set of _PERF_COUNTER_HEADER blocks. The format of the _PERF_COUNTER_HEADER block MUST be determined by the dwType field of the _PERF_COUNTER_HEADER structure.

Figure 5: PerflibV2QueryCounterData return

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_DATA_HEADER (row 1, dwTotalSize)
_PERF_DATA_HEADER (row 2, dwNumCounter)
_PERF_DATA_HEADER (row 3, PerfTimeStamp)
_PERF_DATA_HEADER (row 4, PerfTimeStamp)
_PERF_DATA_HEADER (row 5, PerfTime100NSec)
_PERF_DATA_HEADER (row 6, PerfTime100NSec)
_PERF_DATA_HEADER (row 7, PerfFreq)
_PERF_DATA_HEADER (row 8, PerfFreq)
_PERF_DATA_HEADER (row 9, SystemTime)
_PERF_DATA_HEADER (row 10, SystemTime)
_PERF_DATA_HEADER (row 11, SystemTime)
_PERF_DATA_HEADER (row 12, SystemTime)
_PERF_DATA_HEADER (row 13, SystemTime)
_PERF_DATA_HEADER (row 14, SystemTime)
_PERF_DATA_HEADER (row 15, SystemTime)
_PERF_DATA_HEADER (row 16, SystemTime)
_PERF_COUNTER_HEADER blocks

• If dwType = PERF_ERROR_RETURN (0x00000000), the _PERF_COUNTER_HEADER block MUST contain one _PERF_COUNTER_HEADER structure, and the dwStatus field of the structure indicates the error by using a Win32 error code. Win32 error codes are specified in [MS-ERREF].

• If dwType = PERF_SINGLE_COUNTER (0x00000001), the _PERF_COUNTER_HEADER block MUST contain a _PERF_COUNTER_HEADER structure that is followed by a _PERF_COUNTER_DATA structure and then followed by the counter value.

Figure 6: PerflibV2QueryCounterData return if dwType = PERF_SINGLE_COUNTER

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_HEADER (row 1, dwStatus)
_PERF_COUNTER_HEADER (row 2, dwType)
_PERF_COUNTER_HEADER (row 3, dwSize)
_PERF_COUNTER_HEADER (row 4, Reserved)
_PERF_COUNTER_DATA (row 1, dwDataSize)
_PERF_COUNTER_DATA (row 2, dwSize)
Counter value (Will be two rows if the counter value is 64-bits)

• If dwType = PERF_MULTI_COUNTERS (0x00000002), the _PERF_COUNTER_HEADER block MUST contain a _PERF_COUNTER_HEADER structure that is followed by a _PERF_MULTI_COUNTERS structure, followed by an array of performance counter IDs, followed by a sequence of _PERF_COUNTER_DATA blocks. Each _PERF_COUNTER_DATA block MUST contain a _PERF_COUNTER_DATA structure that is followed by the performance counter value. The order of the elements in the array of counter IDs MUST be the same as the order of the corresponding performance counter values. The number of _PERF_COUNTER_DATA structures and the length of the performance counter ID array MUST be equal to the dwCounters field of the _PERF_MULTI_COUNTERS structure.

Figure 7: PerflibV2QueryCounterData return if dwType = _PERF_MULTI_COUNTERS

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_HEADER (row 1, dwStatus)
_PERF_COUNTER_HEADER (row 2, dwType)
_PERF_COUNTER_HEADER (row 3, dwSize)
_PERF_COUNTER_HEADER (row 4, Reserved)
_PERF_MULTI_COUNTERS (row 1, dwSize)
_PERF_MULTI_COUNTERS (row 2, dwCounters)
Counter ID array (Each element is one row, number of rows depends on number of counters)
_PERF_COUNTER_DATA (row 1, dwDataSize)
_PERF_COUNTER_DATA (row 2, dwSize)
Counter value (Will be two rows if the counter value is 64-bits)

• If dwType = _PERF_MULTI_INSTANCES (0x00000004), the _PERF_COUNTER_HEADER block MUST contain a _PERF_COUNTER_HEADER structure that is followed by a _PERF_MULTI_INSTANCES structure and then followed by a sequence of _PERF_INSTANCE_HEADER blocks. Each _PERF_INSTANCE_HEADER block MUST contain a _PERF_INSTANCE_HEADER structure that is followed by a _PERF_COUNTER_DATA structure and then followed by the performance counter value. The number of _PERF_INSTANCE_HEADER blocks MUST be equal to the dwInstances field of the _PERF_MULTI_INSTANCES structure.

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

Figure 8: PerflibV2QueryCounterData return if dwType = _PERF_MULTI_INSTANCES

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_HEADER (row 1, dwStatus)
_PERF_COUNTER_HEADER (row 2, dwType)
_PERF_COUNTER_HEADER (row 3, dwSize)
_PERF_COUNTER_HEADER (row 4, Reserved)
_PERF_MULTI_INSTANCES (row 1, dwTotalSize)
_PERF_MULTI_INSTANCES (row 2, dwInstances)
_PERF_INSTANCE_HEADER (row 1, Size)
_PERF_INSTANCE_HEADER (row 2, InstanceId)
Unicode string of Instance Name (row 1)
Instance Name (row 2)																Padding (MUST be set to 0)
_PERF_COUNTER_DATA (row 1, dwDataSize)
_PERF_COUNTER_DATA (row 2, dwSize)
Counter value (Will be two rows if the counter value is 64-bits)

• If dwType = PERF_COUNTERSET (0x00000006), the _PERF_COUNTER_HEADER block MUST contain the following, in order: a _PERF_COUNTER_HEADER structure, a _PERF_MULTI_COUNTERS structure, the performance counter ID array, a _PERF_MULTI_INSTANCES structure, and a set of _PERF_INSTANCE_HEADER blocks. Each _PERF_INSTANCE_HEADER block MUST contain a _PERF_INSTANCE_HEADER structure that is followed by a sequence of _PERF_COUNTER_DATA blocks, and each _PERF_COUNTER_DATA block MUST contain a _PERF_COUNTER_DATA structure that is followed by the performance counter value. The number of _PERF_COUNTER_DATA blocks MUST be equal to the dwCounters field of the _PERF_MULTI_COUNTERS structure and the length of the performance counter ID array. The order of the elements in the array of counter IDs MUST be the same as the order of the corresponding performance counter values. The number of _PERF_INSTANCE_HEADER blocks MUST be equal to the dwInstances field of the _PERF_MULTI_INSTANCES structure.

Figure 9: PerflibV2QueryCounterData return if dwType = PERF_COUNTERSET

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_HEADER (row 1, dwStatus)
_PERF_COUNTER_HEADER (row 2, dwType)
_PERF_COUNTER_HEADER (row 3, dwSize)
_PERF_COUNTER_HEADER (row 4, Reserved)
_PERF_MULTI_COUNTERS (row 1, dwSize)
_PERF_MULTI_COUNTERS (row 2, dwCounters)
Counter ID array (Each element is one row; number of rows depends on number of counters)
_PERF_MULTI_INSTANCES (row 1, dwTotalSize)
_PERF_MULTI_INSTANCES (row 2, dwInstances)
_PERF_INSTANCE_HEADER (row 1, Size)
_PERF_INSTANCE_HEADER (row 2, InstanceId)
_PERF_COUNTER_DATA (row 1, dwDataSize)
_PERF_COUNTER_DATA (row 2, dwSize)
Counter value (Will be two rows if the counter value is 64-bits)