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 で終わるカウンター パスの一覧を受け取る呼び出し元割り当てバッファー。 リストは 2 つの NULL 文字で終了します。 pcchPathListLength が 0 の場合は NULL に設定します。

[in, out] pcchPathListLength

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

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

[in] dwFlags

展開しないワイルドカード文字を示すフラグ。 1 つ以上のフラグを指定できます。

値 説明
PDH_NOEXPANDCOUNTERS
 パスにカウンター名のワイルドカード文字が含まれている場合は、カウンター名を展開しないでください。
PDH_NOEXPANDINSTANCES
 パスに親インスタンス、インスタンス名、またはインスタンス インデックスのワイルドカード文字が含まれている場合は、インスタンス名を展開しないでください。
PDH_REFRESHCOUNTERS
 カウンターリストを更新します。

戻り値

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

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

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

解説

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

PdhExpandWildCardPath は 、次の点で PdhExpandCounterPath と異なります。

  1. 展開するワイルドカード文字を制御できます。
  2. ログ ファイルの内容は、カウンター名のソースとして使用できます。
一般的なカウンター パスの形式は次のとおりです。

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

カウンター パスの親、インスタンス、インデックス、およびカウンター コンポーネントには、有効な名前またはワイルドカード文字を含めることがあります。 コンピューター、親、インスタンス、およびインデックスのコンポーネントでは、すべてのカウンタは必要ありません。

使用できる形式の一覧を次に示します。

  • \\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
ワイルドカード文字としてアスタリスク (*) を使用します (たとえば、\object(*)\counter)。

ワイルドカード文字が、親の名前で指定されている場合は、指定したインスタンスおよびカウンター フィールドに一致する指定したオブジェクトのすべてのインスタンスが返されます。 たとえば、\object(*/instance)\counter です。

インスタンス名にワイルドカード文字を指定すると場合、は、指定したインデックスに対応するすべてのインスタンス名にワイルドカード文字が一致する場合に指定されたオブジェクトと親オブジェクトのすべてのインスタンスが返されます。 たとえば、\object(parent/*)\counter です。 オブジェクトにインスタンスが含まれていない場合は、エラーが発生します。

カウンター名にワイルドカード文字を指定すると、指定したオブジェクトのすべてのカウンターが返されます。

部分的なカウンター パス文字列の一致 (例: "pro*") がサポートされています。

Windows Vista より前: 部分的なワイルドカードの一致はサポートされていません。

注意

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

要件

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

関連項目

PdhEnumObjectItems

PdhEnumObjects

PdhExpandCounterPath

PdhExpandWildCardPathH