pdhExpandCounterPathA 函式 (pdh.h)
如果未針對計數器路徑中符合通配符字串的計數器和計數器實例) ，檢查指定的計算機 (或本機計算機。
語法
PDH_FUNCTION PdhExpandCounterPathA(
[in] LPCSTR szWildCardPath,
[out] PZZSTR mszExpandedPathList,
[in, out] LPDWORD pcchPathListLength
);
參數
[in] szWildCardPath
包含要展開之計數器路徑的 Null 終止字串。 函式會搜尋路徑中指定的電腦是否有相符專案。 如果路徑未指定計算機，函式會搜尋本機計算機。 計數器路徑的最大長度是PDH_MAX_COUNTER_PATH。
[out] mszExpandedPathList
呼叫端配置的緩衝區，接收 符合 szWildCardPath 中通配符規格的展開計數器路徑清單。 此清單中的每個計數器路徑都會以 Null 字元終止。 清單會以兩個 NULL 字元終止。 如果pcchPathListLength為零，則設定為NULL。
[in, out] pcchPathListLength
mszExpandedPathList 緩衝區的大小，以 TCHAR 為單位。 如果輸入為零，函式會傳回PDH_MORE_DATA，並將此參數設定為所需的緩衝區大小。 如果緩衝區大於所需的大小，函式會將此參數設定為所使用緩衝區的實際大小。 如果輸入上的指定大小大於零，但小於所需的大小，您就不應該依賴傳回的大小來重新配置緩衝區。
傳回值
如果函式成功，則會傳回ERROR_SUCCESS。
| 傳回碼 | Description |
|---|---|
|
mszExpandedPathList 緩衝區太小，無法包含路徑清單。 如果 輸入上的pcchPathListLength 為零，則預期傳回值。 如果輸入上的指定大小大於零，但小於所需的大小，您就不應該依賴傳回的大小來重新配置緩衝區。 |
|
參數無效。 例如，在某些版本中，如果輸入上的指定大小大於零，但小於所需的大小，您可能會收到此錯誤。 |
|
無法配置記憶體以支援此函式。 |
備註
您應該呼叫此函式兩次，第一次取得所需的緩衝區大小， (將 mszExpandedPathList 設定為 NULL ， 並將 pcchPathListLength 設定為 0) ，第二次取得數據。
一般計數器路徑格式如下：
\computer\object (parent/instance#index) \counter
計數器路徑的父系、實例、索引和計數器元件可能包含有效的名稱或通配符。 所有計數器都不需要計算機、父系、實例和索引元件。
您必須使用的計數器路徑是由計數器本身決定。 例如，LogicalDisk 物件具有實例索引，因此您必須提供 #index 或通配符。 因此，您可以使用下列格式：
\LogicalDisk (/#*) *
相較之下，Process物件不需要實例索引。 因此，您可以使用下列格式：
\Process (*) \ID 進程
以下是可能的格式清單：
- \\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
如果在實例名稱中指定通配符，如果對應至指定索引的所有實例名稱符合通配符，則會傳回指定物件和父物件的所有實例。
如果在計數器名稱中指定通配符，則會傳回指定物件的所有計數器。
部分計數器路徑字串符合 (例如，不支援 “pro*”) 。
範例
下列範例示範如何執行此函式。
#include <windows.h>
#include <stdio.h>
#include <stdlib.h>
#include <pdh.h>
#include <pdhmsg.h>
#pragma comment(lib, "pdh.lib")
CONST PWSTR WILDCARD_PATH = L"\\Processor(*)\\*";
void wmain(void)
{
PDH_STATUS Status;
PWSTR EndOfPaths;
PWSTR Paths = NULL;
DWORD BufferSize = 0;
Status = PdhExpandCounterPath(WILDCARD_PATH, Paths, &BufferSize);
while (Status == PDH_MORE_DATA)
{
Paths = (PWSTR)malloc(BufferSize * sizeof(WCHAR));
Status = PdhExpandCounterPath(WILDCARD_PATH, Paths, &BufferSize);
}
if (Status != ERROR_SUCCESS)
{
wprintf(L"\nPdhExpandCounterPath failed with status 0x%x", Status);
goto Cleanup;
}
if (Paths == NULL)
{
wprintf(L"\nThe counter path %s cannot be expanded.", WILDCARD_PATH);
goto Cleanup;
}
EndOfPaths = Paths + BufferSize;
// On Vista and later operating systems, the buffer is terminated with two
// null-terminator characters; however, on earlier systems, the buffer is
// not terminated with two null-terminator characters. This covers both cases.
for (PWSTR p = Paths; ((p != EndOfPaths) && (*p != L'\0')); p += wcslen(p) + 1)
{
wprintf(L"\n%s", p);
}
Cleanup:
if (Paths)
{
free(Paths);
}
}
注意
pdh.h 標頭會將 PdhExpandCounterPath 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [僅限桌面應用程式] |
| 目標平台 | Windows |
| 標頭 | pdh.h |
| 程式庫 | Pdh.lib |
| Dll | Pdh.dll |