PdhAddEnglishCounterA 函式 (pdh.h)

  • 發行項

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

語法

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 錯誤碼。 以下是可能的值。

傳回碼 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 函式中指定的計數器路徑必須當地語系化。

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

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

注意 如果計數器路徑包含通配符，路徑的非通配符部分將會當地語系化，但在將本地化的計數器路徑新增至查詢之前，將不會展開通配符。 在此情況下，您將需要使用下列程式，將所有相符的計數器名稱新增至查詢。
  1. 建立查詢
  2. 搭配包含通配符的字串使用 PdhAddEnglishCounter
  3. 在 PdhAddEnglishCounter 傳回的計數器句柄上使用 PdhGetCounterInfo，以取得本地化的完整路徑 (szFullPath.) 此字元串仍然包含通配符，但非通配符部分現在已當地語系化。
  4. 使用 PdhExpandWildCardPath 展開通配符。
  5. 在每個產生的路徑上使用 PdhAddCounter
 

注意

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

規格需求

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

另請參閱

PdhAddCounter

PdhBrowseCounters

PdhMakeCounterPath

PdhOpenQuery

PdhRemoveCounter