3.1.4.1.7 PerflibV2ValidateCounters (Opnum 7)

This PerflibV2ValidateCounters method either adds or removes performance counters from the query.

 error_status_t PerflibV2ValidateCounters(
   [in] RPC_HQUERY hQuery,
   [in, range(0, 67108864)] DWORD dwInSize,
   [in, out, size_is(dwInSize)] unsigned char* lpData,
   [in] DWORD dwAdd
 );

hQuery: The handle that is created 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.

lpData: The buffer that contains the counter information to add to, or remove from, the query. The server will return this buffer after it has attempted to add or remove the specified counters; the Status field of each _PERF_COUNTER_IDENTIFIER structure will contain information about whether or not the server was successful.

dwAdd: A Boolean value that indicates if counters are being added to, or removed from, the query. If counters are being added, this MUST be set to TRUE; otherwise, it MUST be set to FALSE.

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.
0x00000057 ERROR_INVALID_PARAMETER	The server returns this value to the client for any of the following reasons: dwSize is less than the size of the _PERF_COUNTER_IDENTIFIER structure (this condition would prevent the server from returning information about one counter). The size of a single _PERF_COUNTER_IDENTIFIER structure that is passed into the buffer by the client is smaller than the expected size of a _PERF_COUNTER_IDENTIFIER structure.
0x0000000E ERROR_OUTOFMEMORY	The server will return this value to the client if, in the process of completing the client's request of adding or removing performance counters from the query, a memory allocation fails.

Errors are returned to the client by the server in one of two ways: the first is if the performance counter infrastructure on the server could not add or remove performance counters from the query; the second is if the provider that is exposing the performance counter returns an error, in which case the performance counter infrastructure passes the error back to the client.

When the PerflibV2ValidateCounters method returns, the Status field of each _PERF_COUNTER_IDENTIFIER sent to the server will have the result of whether or not the server was able to successfully add or remove that particular performance counter from the query that is identified by the handle hQuery.

If the performance counter infrastructure is setting the Status field to an error value, then it MUST be one of the following values.

Return value/code	Description
0x00000000 ERROR_STATUS	The return value indicates success. The counter was either successfully added or removed from the query.
0x00001068 ERROR_WMI_GUID_NOT_FOUND	The server cannot find the GUID that was passed by the client in the CounterSetGuid field of the _PERF_COUNTER_IDENTIFIER structure.
0x0000106A ERROR_WMI_ITEMID_NOT_ FOUND	The server cannot find the counter whose numeric identifier is in the CounterId field of the _PERF_COUNTER_IDENTIFIER structure.
0x00000003 ERROR_PATH_NOT_FOUND	The server cannot find an active instance with the name that was placed after the _PERF_COUNTER_IDENTIFIER structure.
0x000000B7 ERROR_ALREADY_EXISTS	The client tried to add a performance counter that has already been added in a previous call to PerflibV2ValidateCounters.
ERROR_INVALID_PARAMETER 0x00000057	The server will return this value in the Status field of the _PERF_COUNTER_IDENTIFIER either when the _PERF_COUNTER_IDENTIFIER is corrupt, or if the server cannot find the counter to delete from the query that is specified by the structure.
0x0000000E ERROR_OUTOFMEMORY	The server will return this value to the client if, either in the process of adding or removing a counter from a query, a memory allocation failure occurred.

When this method is called, the buffer MUST contain an array of _PERF_COUNTER_IDENTIFIER blocks that reference the performance counters to add to, or remove from, the query. Each _PERF_COUNTER_IDENTIFIER block MUST contain a _PERF_COUNTER_IDENTIFIER structure; a multiple-instance counter set _PERF_COUNTER_IDENTIFIER structure MUST be followed by a null-terminated Unicode string instance name, while a single-instance counter set _PERF_COUNTER_IDENTIFIER structure MUST be followed by a string instance name. Setting the CounterId field of the _PERF_COUNTER_IDENTIFIER structure to 0xFFFFFFFF indicates a wildcard character. Setting the instance name string to "*" indicates a wildcard character.

When the method returns, the Status field of each _PERF_COUNTER_IDENTIFIER structure in the array MUST specify if the operation succeeded for the counters that are referenced by that structure.