PdhAddEnglishCounterA 函式（pdh.h）

發行項
11/20/2024

將指定的語言中性計數器新增至查詢。

語法

PDH_FUNCTION PdhAddEnglishCounterA(
  [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 結構 dwQueryUserData 成員。

[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 函式中指定的計數器路徑。

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

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

注意如果計數器路徑包含通配符，路徑的非通配符部分將會當地語系化，但通配符在將本地化的計數器路徑新增至查詢之前，將不會展開通配符。在此情況下，您將需要使用下列程式，將所有相符的計數器名稱新增至查詢。

建立查詢
搭配包含通配符的字串使用 PdhAddEnglishCounter
在 PdhAddEnglishCounter 傳回的計數器句柄上使用 PdhGetCounterInfo，以取得本地化的完整路徑（szFullPath.）此字串仍然包含通配符，但非通配符部分現在已當地語系化。
使用 PdhExpandWildCardPath 展開通配符。
在每個產生的路徑上使用 PdhAddCounter

注意

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

要求

要求	價值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	pdh.h
連結庫	Pdh.lib
DLL	Pdh.dll