PdhAddCounterA 函式（pdh.h）

發行項
11/20/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 錯誤碼。以下是可能的值。

傳回碼	描述
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 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	pdh.h
連結庫	Pdh.lib
DLL	Pdh.dll