pdhExpandWildCardPathA 函式 (pdh.h)

檢查指定的電腦或記錄檔,並傳回符合包含萬用字元之指定計數器路徑的計數器路徑。

若要使用資料來源的控制碼,請使用 PdhExpandWildCardPathH 函式。

語法

PDH_FUNCTION PdhExpandWildCardPathA(
  [in]      LPCSTR  szDataSource,
  [in]      LPCSTR  szWildCardPath,
  [out]     PZZSTR  mszExpandedPathList,
  [in, out] LPDWORD pcchPathListLength,
  [in]      DWORD   dwFlags
);

參數

[in] szDataSource

包含記錄檔名稱的 Null 終止字串。 函式會使用記錄檔中定義的效能物件和計數器來展開 szWildCardPath 參數中指定的路徑。

如果 為 Null,函式會搜尋 szWildCardPath中指定的電腦。

[in] szWildCardPath

以 Null結束的字串,指定要展開的計數器路徑。 計數器路徑的最大長度是PDH_MAX_COUNTER_PATH。

如果 szDataSource 參數為 Null,函式會在路徑中指定的電腦搜尋相符專案。 如果路徑未指定電腦,函式會搜尋本機電腦。

[out] mszExpandedPathList

呼叫端配置的緩衝區,接收符合szWildCardPath中萬用字元規格的Null終止計數器路徑清單。 清單會以兩 個 Null 字元終止。 如果pcchPathListLength為零,則設定為Null

[in, out] pcchPathListLength

mszExpandedPathList緩衝區的大小,以TCHAR為單位。 如果輸入和物件存在零,函式會傳回PDH_MORE_DATA,並將此參數設定為所需的緩衝區大小。 如果緩衝區大於所需的大小,函式會將此參數設定為所使用緩衝區的實際大小。 如果輸入上的指定大小大於零,但小於所需的大小,您就不應該依賴傳回的大小來重新配置緩衝區。

注意 您必須將一個新增至 Windows XP 上所需的大小。
 

[in] dwFlags

旗標,指出要展開的萬用字元。 您可以指定一或多個旗標。

意義
PDH_NOEXPANDCOUNTERS
如果路徑包含計數器名稱的萬用字元,請勿展開計數器名稱。
PDH_NOEXPANDINSTANCES
如果路徑包含父實例、實例名稱或實例索引的萬用字元,請勿展開實例名稱。
PDH_REFRESHCOUNTERS
重新整理計數器清單。

傳回值

如果函式成功,則會傳回ERROR_SUCCESS。

如果函式失敗,傳回值為 系統錯誤碼PDH 錯誤碼

傳回碼 描述
PDH_MORE_DATA
mszExpandedPathList緩衝區不夠大,無法包含路徑清單。 如果 輸入上的 pcchPathListLength 為零,則預期傳回值。 如果輸入上的指定大小大於零,但小於所需的大小,您就不應該依賴傳回的大小來重新配置緩衝區。
PDH_INVALID_ARGUMENT
參數無效。 例如,在某些版本中,如果輸入上的指定大小大於零,但小於所需的大小,您可能會收到此錯誤。
PDH_INVALID_PATH
指定的 物件不包含 實例。
PDH_MEMORY_ALLOCATION_FAILURE
無法配置記憶體以支援此函式。
PDH_CSTATUS_NO_OBJECT
在電腦或記錄檔中找不到指定的物件。

備註

您應該呼叫此函式兩次,第一次取得所需的緩衝區大小, (將 mszExpandedPathList 設定為 Null並將 pcchPathListLength 設定為 0) ,第二次取得資料。

PdhExpandWildCardPathPdhExpandCounterPath 有下列不同之處:

  1. 可讓您控制要展開的萬用字元。
  2. 記錄檔的內容可作為計數器名稱的來源。
一般計數器路徑格式如下:

\computer\object (parent/instance#index) \counter

計數器路徑的父系、實例、索引和計數器元件可能包含有效的名稱或萬用字元。 所有計數器都不需要電腦、父系、實例和索引元件。

以下是可能的格式清單:

  • \\computer\object (parent/instance#index) \counter
  • \\computer\object (父/實例) \counter
  • \\computer\object (instance#index) \counter
  • \\computer\object (實例) \counter
  • \\computer\object\counter
  • \object (parent/instance#index) \counter
  • \object (父/實例) \counter
  • \object (instance#index) \counter
  • \object (實例) \counter
  • \object\counter
使用星號 (*) 作為萬用字元,例如 \object (*) \counter。

如果在父名稱中指定萬用字元,則會傳回符合指定實例和計數器欄位之指定物件的所有實例。 例如,\object (*/instance) \counter。

如果在實例名稱中指定萬用字元,如果對應至指定索引的所有實例名稱符合萬用字元,則會傳回指定物件和父物件的所有實例。 例如,\object (parent/*) \counter。 如果物件不包含 實例,就會發生錯誤。

如果在計數器名稱中指定萬用字元,則會傳回指定物件的所有計數器。

部分計數器路徑字串符合 (例如,支援 「pro*」) 。

在 Windows Vista 之前: 不支援部分萬用字元比對。

注意

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

需求

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

另請參閱

PdhEnumObjectItems

PdhEnumObjects

PdhExpandCounterPath

PdhExpandWildCardPathH