PdhAddCounterW function (pdh.h)
Adds the specified counter to the query.
Syntax
PDH_FUNCTION PdhAddCounterW(
[in] PDH_HQUERY hQuery,
[in] LPCWSTR szFullCounterPath,
[in] DWORD_PTR dwUserData,
[out] PDH_HCOUNTER *phCounter
);
Parameters
[in] hQuery
Handle to the query to which you want to add the counter. This handle is returned by the PdhOpenQuery function.
[in] szFullCounterPath
Null-terminated string that contains the counter path. For details on the format of a counter path, see Specifying a Counter Path. The maximum length of a counter path is PDH_MAX_COUNTER_PATH.
[in] dwUserData
User-defined value. This value becomes part of the counter information. To retrieve this value later, call the PdhGetCounterInfo function and access the dwUserData member of the PDH_COUNTER_INFO structure.
[out] phCounter
Handle to the counter that was added to the query. You may need to reference this handle in subsequent calls.
Return value
Return ERROR_SUCCESS if the function succeeds.
If the function fails, the return value is a system error code or a PDH error code. The following are possible values.
Return code | Description |
---|---|
|
The counter path could not be parsed or interpreted. |
|
Unable to find the specified counter on the computer or in the log file. |
|
The counter path is empty. |
|
The path did not contain a computer name, and the function was unable to retrieve the local computer name. |
|
Unable to find the specified object on the computer or in the log file. |
|
Unable to determine the calculation function to use for this counter. |
|
One or more arguments are not valid. |
|
The query handle is not valid. |
|
Unable to allocate memory required to complete the function. |
Remarks
If the counter path contains a wildcard character, all counter names matching the wildcard character are added to the query.
If a counter instance is specified that does not yet exist, PdhAddCounter does not report an error condition. Instead, it returns ERROR_SUCCESS. The reason for this behavior is that it is not known whether a nonexistent counter instance has been specified or whether one will exist but has not yet been created.
To remove the counter from the query, use the PdhRemoveCounter function.
Examples
For an example, see Browsing Performance Counters or Reading Performance Data from a Log File.
Note
The pdh.h header defines PdhAddCounter as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows XP [desktop apps only] |
Minimum supported server | Windows Server 2003 [desktop apps only] |
Target Platform | Windows |
Header | pdh.h |
Library | Pdh.lib |
DLL | Pdh.dll |