PM_COLLECT_PROC コールバック関数 (winperf.h)

パフォーマンス データを収集し、コンシューマーに返します。 パフォーマンス データを提供するパフォーマンス DLL を記述する場合は、この関数を実装してエクスポートします。 コンシューマーがレジストリに対してパフォーマンス データを照会するたびに、システムはこの関数を呼び出します。

CollectPerformanceData 関数は、アプリケーション定義関数名のプレースホルダーです。

構文

PM_COLLECT_PROC PmCollectProc;

DWORD PmCollectProc(
                 LPWSTR pValueName,
                 void **ppData,
                 DWORD *pcbTotalBytes,
                 DWORD *pNumObjectTypes
)
{...}

パラメーター

pValueName

ppData

pcbTotalBytes

pNumObjectTypes

戻り値

次のいずれかの値です。

リターン コード	説明
ERROR_MORE_DATA	lpcbTotalBytes で指定された pData バッファーのサイズ (pData は lppData が指すポインターを参照します) は、データを格納するのに十分な大きさではありません。 pData は変更せずに、lpcbTotalBytes と lpNumObjectTypes を 0 に設定します。 次の呼び出しの前に変更される可能性があるため、必要なバッファー サイズを示す試行は行われません。
ERROR_SUCCESS	データが返されない場合やエラーが発生した場合でも、 ERROR_MORE_DATA 以外のすべてのケースでこの値を返します。 バッファー サイズが不十分以外のエラーを報告するには、アプリケーション イベント ログを使用します。

注釈

lpValueName パラメーターで指定された要求されたオブジェクトが、パフォーマンス DLL でサポートされているオブジェクト インデックスのいずれにも対応しない場合は、pData パラメーターを変更せずに (ここで pData は lppData が指すポインターを参照)、lpcbTotalBytes パラメーターと lpNumObjectTypes パラメーターを 0 に設定します。 これは、データが返されなかったことを示します。

クエリ対象オブジェクトの 1 つ以上をサポートする場合は、lpcbTotalBytes で指定された pData バッファーのサイズが、データを格納するのに十分な大きさであるかどうかを判断します。 そうでない場合は、 pData を変更せずに、 lpcbTotalBytes と lpNumObjectTypes を 0 に設定します。 次の呼び出しの前に変更される可能性があるため、必要なバッファー サイズを示す試行は行われません。 ERROR_MORE_DATAを返 します。

データ収集に時間がかかる場合は、特定のオブジェクトまたはコストのかかるクエリに対してのみ応答する必要があります。 また、システムのパフォーマンスに悪影響を及ぼしないように、データを収集するスレッドの優先順位を下げる必要があります。 クエリ文字列形式については、「 レジストリ関数を使用してカウンター データを使用する」を参照してください。

コンシューマーが別のコンピューター (リモート) で実行されている場合、 OpenPerformanceData、 ClosePerformanceData、 CollectPerformanceData 関数は Winlogon プロセスのコンテキストで呼び出され、リモート接続のサーバー側が処理されます。 この区別は、リモートでのみ発生する問題のトラブルシューティングを行う場合に重要です。

関数が正常に戻った後、システムはいくつかの基本的なテストを実行して、データの整合性を確保できます。 既定では、テストは実行されません。 テストが失敗した場合、システムはイベント ログ メッセージを生成し、無効なポインターによるそれ以上の問題を防ぐためにデータが破棄されます。 次のレジストリ値は、テスト レベルを制御します。 HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Perflib\ExtCounterTestLevel

ExtCounterTestLevel で使用できるテスト レベルを次に示します。

レベル	意味
1	信頼されたカウンター DLL のポインターとバッファーをテストします。 ユーザーのバッファーのコピーを送信します。
2	ポインターとバッファー長をテストしますが、ポインター参照やバッファーの内容はテストしません。 ユーザーのバッファーのコピーを送信します。
3	ポインターまたはバッファーをテストしないでください。 ユーザーのバッファーのコピーを送信します。
4	ポインターまたはバッファーをテストしないでください。 コピーではなく、ユーザーのバッファーを送信します。 これが既定値です。

次のテストは、レベル 1 と 2 で実行されます。

• lpcbTotalBytes の値が、返されるバッファー ポインター pData と一致していることを確認します。 この関数に渡された元のバッファー ポインターに lpcbTotalBytes 値を追加すると、この関数によって返されるバッファー ポインターと同じになります。 同じでない場合は、エラー メッセージがログに記録され、データは無視されます。
• バッファー オーバーランが発生しなかったことを確認します。 システムは、コンシューマー割り当てバッファーの前後に 1 KB のガード ページを追加します。 返されたバッファー ポインター pData が追加されたガード ページの最初のバイトを指している場合、バッファーは無効であり、データは無視されると見なされます。 バッファー ポインターがバッファーの末尾を超え、ガード ページの末尾を超えない場合は、バッファー オーバーラン エラーがログに記録されます。 バッファー ポインターがガード ページの末尾を越えた場合、バッファーが割り当てられたヒープが破損し、他のメモリ エラーが発生したため、ヒープ エラーがログに記録されます。
• ガード ページが破損されていないことを確認します。 バッファーの前後に追加された 1 KB のガード ページは、この関数が呼び出される前にデータ パターンで初期化されます。 このデータ パターンは、収集プロシージャが戻った後にチェックされます。 不一致が検出された場合、バッファー オーバーランまたはその他のメモリ エラーが想定され、データは無視されます。

次のテストは、テスト レベル 1 が使用されている場合にのみ実行されます。

• 各オブジェクトの TotalByteLength メンバーの合計が lpcbTotalBytes の値と同じであることを確認します。 そうでない場合、データは無視されます。
• 各インスタンスの ByteLength メンバーに一貫性があることを確認します。 次のオブジェクトまたはバッファーの末尾が最後のインスタンスに続く場合、長さは一貫しています。 そうでない場合、データは無視されます。

例

CollectPerformanceData の実装に関するページを参照してください。

要件

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

こちらもご覧ください

• OpenPerformanceData
• ClosePerformanceData