共用方式為

PdhExpandCounterPathA 函式 （pdh.h）

  • 發行項

檢查計數器和計數器路徑中符合通配符字串的計數器和實例，檢查指定的計算機（如果沒有指定本機計算機）。

Note 此函式會由 PdhExpandWildCardPath 函式取代。
 

語法

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

TCHAR中 mszExpandedPathList 緩衝區的大小。 如果輸入為零，函式會傳回PDH_MORE_DATA，並將此參數設定為所需的緩衝區大小。 如果緩衝區大於所需的大小，函式會將此參數設定為使用之緩衝區的實際大小。 如果輸入上的指定大小大於零，但小於所需的大小，則不應該依賴傳回的大小來重新配置緩衝區。

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

傳回值

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

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

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

言論

您應該呼叫此函式兩次，第一次取得所需的緩衝區大小（將 mszExpandedPathList 設為 NULL，pcchPathListLength 為 0），第二次取得數據。

一般計數器路徑格式如下所示：

\computer\object（parent/instance#index）\counter

計數器路徑的父、實例、索引和計數器元件可能包含有效的名稱或通配符。 所有計數器都不需要計算機、父系、實例和索引元件。

您必須使用的計數器路徑是由計數器本身所決定。 例如，LogicalDisk 物件具有實例索引，因此您必須提供 #index 或通配符。 因此，您可以使用下列格式：

\LogicalDisk（/#*）*

相較之下，Process物件不需要實例索引。 因此，您可以使用下列格式：

\Process\\ID Process

以下是可能格式的清單：

  • \\computer\object（parent/instance#index）\counter
  • \\computer\object（parent/instance）\counter
  • \\computer\object（instance#index）\counter
  • \\computer\object（instance）\counter
  • \\computer\object\counter
  • \object（parent/instance#index）\counter
  • \object（parent/instance）\counter
  • \object（instance#index）\counter
  • \object（instance）\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 標頭會根據 UNICODE 預處理器常數的定義，將 PdhExpandCounterPath 定義為自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的 慣例。

要求

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

另請參閱

PdhExpandWildCardPath

PdhMakeCounterPath