PdhAddCounterA 函式 (pdh.h)

發行項
03/01/2024

將指定的計數器加入至查詢。

語法

PDH_FUNCTION PdhAddCounterA(
  [in]  PDH_HQUERY   hQuery,
  [in]  LPCSTR       szFullCounterPath,
  [in]  DWORD_PTR    dwUserData,
  [out] PDH_HCOUNTER *phCounter
);

參數

[in] hQuery

處理您要加入計數器的查詢。 PdhOpenQuery 函式會傳回這個句柄。

[in] szFullCounterPath

包含計數器路徑的 Null 終止字串。如需計數器路徑格式的詳細資訊，請參閱指定計數器路徑。計數器路徑的最大長度是PDH_MAX_COUNTER_PATH。

[in] dwUserData

用戶定義的值。這個值會成為計數器資訊的一部分。若要稍後擷取此值，請呼叫 PdhGetCounterInfo 函式，並存取 PDH_COUNTER_INFO 結構的 dwUserData 成員。

[out] phCounter

已新增至查詢的計數器句柄。您可能需要在後續呼叫中參考此句柄。

傳回值

如果函式成功，則傳回ERROR_SUCCESS。

如果函式失敗，傳回值為系統錯誤碼或 PDH 錯誤碼。以下是可能的值。

傳回碼	Description
PDH_CSTATUS_BAD_COUNTERNAME	無法剖析或解譯計數器路徑。
PDH_CSTATUS_NO_COUNTER	在電腦或記錄檔中找不到指定的計數器。
PDH_CSTATUS_NO_COUNTERNAME	計數器路徑是空的。
PDH_CSTATUS_NO_MACHINE	路徑未包含計算機名稱，而且函式無法擷取本機計算機名稱。
PDH_CSTATUS_NO_OBJECT	在電腦或記錄檔中找不到指定的物件。
PDH_FUNCTION_NOT_FOUND	無法判斷要用於這個計數器的計算函數。
PDH_INVALID_ARGUMENT	一或多個自變數無效。
PDH_INVALID_HANDLE	查詢句柄無效。
PDH_MEMORY_ALLOCATION_FAILURE	無法設定完成函式所需的記憶體。

備註

如果計數器路徑包含通配符，所有符合通配符的計數器名稱都會新增至查詢。

如果指定的計數器實例尚未存在， PdhAddCounter 不會報告錯誤狀況。相反地，它會傳回ERROR_SUCCESS。此行為的原因是，它不知道是否已指定不存在的計數器實例，或是否已存在，但尚未建立。

若要從查詢中移除計數器，請使用 PdhRemoveCounter 函式。

範例

如需範例，請參閱流覽性能計數器或從記錄檔讀取效能數據。

注意

pdh.h 標頭會將 PdhAddCounter 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	pdh.h
程式庫	Pdh.lib
Dll	Pdh.dll