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。

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

備註

您應該呼叫此函式兩次，第一次取得所需的緩衝區大小， (將 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);
    }
}

規格需求

另請參閱

PdhExpandWildCardPath

PdhMakeCounterPath