PdhExpandCounterPathA 関数 (pdh.h)

[アーティクル]
03/01/2024

カウンターパス内のワイルドカード文字列に一致するカウンターとカウンターのインスタンスについて、指定されたコンピューター (または指定されていない場合はローカルコンピューター) を調べます。

メモこの関数は 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 文字で終了します。リストは 2 つの NULL 文字で終了します。 pcchPathListLength が 0 の場合は NULL に設定します。

[in, out] pcchPathListLength

TCHAR の mszExpandedPathList バッファーのサイズ。入力時に 0 の場合、関数は PDH_MORE_DATAを返し、このパラメーターを必要なバッファーサイズに設定します。バッファーが必要なサイズより大きい場合、関数は、このパラメーターを使用したバッファーの実際のサイズに設定します。入力時に指定したサイズが 0 より大きく、必要なサイズより小さい場合は、返されたサイズに依存してバッファーを再割り当てしないでください。

メモ Windows XP では、必要なサイズに追加する必要があります。

戻り値

関数が成功すると、ERROR_SUCCESSが返されます。

関数が失敗した場合、戻り値はシステムエラーコードまたは PDH エラーコードです。

リターンコード	説明
PDH_MORE_DATA	mszExpandedPathList バッファーが小さすぎてパスの一覧が含められません。この戻り値は、入力時に pcchPathListLength が 0 の場合に想定されます。入力時に指定したサイズが 0 より大きく、必要なサイズより小さい場合は、返されたサイズに依存してバッファーを再割り当てしないでください。
PDH_INVALID_ARGUMENT	パラメーターが無効です。たとえば、一部のリリースでは、入力の指定されたサイズが 0 より大きく、必要なサイズより小さい場合に、このエラーが発生する可能性があります。
PDH_MEMORY_ALLOCATION_FAILURE	この関数をサポートするためにメモリを割り当てることができません。

注釈

この関数は 2 回呼び出す必要があります。最初に必要なバッファーサイズを取得し ( mszExpandedPathList を NULL に設定し、 pcchPathListLength を 0 に設定)、2 回目にデータを取得します。

一般的なカウンターパスの形式は次のとおりです。

\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 プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして PdhExpandCounterPath を定義します。エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows XP (デスクトップアプリのみ)
サポートされている最小のサーバー	Windows Server 2003 (デスクトップアプリのみ)
対象プラットフォーム	Windows
ヘッダー	pdh.h
Library	Pdh.lib
[DLL]	Pdh.dll

こちらもご覧ください

PdhExpandWildCardPath

PdhMakeCounterPath

PdhExpandCounterPathA 関数 (pdh.h)

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース