3.1.1.5 Query Handles

Clients can perform two types of query operations on the server by using the Performance Counter Query Protocol: Browse the counterset and performance counter metadata on the server or query the performance counter values from the counterset instances. When a client requests browsing countersets or performance counter metadata (sections 3.1.4.1.1, 3.1.4.1.2, and 3.1.4.1.3), the server does not associate any state with these requests, but simply sends to the client the available metadata on the system.

When a client wants to query the server for performance counter values from counterset instances, it uses the Performance Counter Query Protocol to create an RPC_HQUERY handle on the server. The server maintains a single table of query handles associating client connections to internal server states related to the connection. For each handle, the server keeps a list of performance counter identifiers (for more information about performance counter identifiers see section 2.2.4.6). The client can add or remove performance counter identifiers from the list, as specified in section 3.1.4.1.7.

When the client makes the query operation (see section 3.1.4.1.6), the server retrieves the performance counter values from the system by using system interfaces; the server passes to these interfaces the list of performance counter identifiers associated with the query handle. For each performance counter identifier, the system retrieves the performance counter value from its corresponding provider and returns it to the server. The server accumulates the values and sends the data to the client.

In addition, the client can enumerate the performance counter metadata about the performance counters it added to the query handle. In that case, the server returns the performance counter information that is associated with the RPC_HQUERY handle passed from the client (section 3.1.4.1.5).

In certain cases, aggregation operations, such as addition or an average, can be performed by the client after it retrieves the performance counter values from the server. The counterset identifies whether an aggregation operation can be performed, and each performance counter in the counterset specifies a specific aggregation operation.

For example, a performance counter being queried by the client, associated with the RPC_HQUERY handle, can belong to a counterset of type Multiple Instance Aggregate. The AggregateFunc property of this performance counter, which is a member of the _PERF_COUNTER_REG_INFO structure, can be set to value 0x00000001. In this case, all instances that the client queries will be returned; the client component of the performance counter infrastructure will use these values to calculate the total sum of the instances of that performance counter, to pass back to the requesting application.

When the client no longer needs to query the server for performance counter values, it closes the RPC_HQUERY handle; afterward, the server can free any resources that are associated with the handle.