PM_COLLECT_PROC
コールバックシグネチャ
DWORD PM_COLLECT_PROC(
LPWSTR pValueName,
void** ppData,
DWORD* pcbTotalBytes,
DWORD* pNumObjectTypes
);パラメーター
| フィールド | 型 |
|---|---|
| pValueName | LPWSTR |
| ppData | void** |
| pcbTotalBytes | DWORD* |
| pNumObjectTypes | DWORD* |
公式ドキュメント
パフォーマンスデータを収集し、コンシューマーに返します。パフォーマンスデータを提供するパフォーマンス DLL を作成する場合は、この関数を実装してエクスポートします。システムは、コンシューマーがレジストリにパフォーマンスデータを照会するたびに、この関数を呼び出します。
CollectPerformanceData 関数は、アプリケーション定義の関数名のプレースホルダーです。
戻り値
次のいずれかの値を返します。
| 戻り値 | 説明 |
|---|---|
| ERROR_MORE_DATA | lpcbTotalBytes で指定された pData バッファー(pData は lppData が指すポインターを表します)のサイズが、データを格納するのに十分ではありません。pData は変更せず、lpcbTotalBytes と lpNumObjectTypes を 0 に設定してください。必要なバッファーサイズは次回の呼び出しまでに変化する可能性があるため、そのサイズを示すことは行いません。 |
| ERROR_SUCCESS | ERROR_MORE_DATA の場合以外は、データを返さなかった場合やエラーが発生した場合でも、この値を返します。バッファーサイズ不足以外のエラーを報告するには、アプリケーションイベントログを使用してください。 |
解説(Remarks)
lpValueName パラメーターで指定された要求オブジェクトが、パフォーマンス DLL がサポートするオブジェクトインデックスのいずれにも該当しない場合は、pData パラメーター(pData は lppData が指すポインターを表します)を変更せず、lpcbTotalBytes パラメーターと lpNumObjectTypes パラメーターを 0 に設定してください。これは、データが返されなかったことを示します。
照会されたオブジェクトを 1 つ以上サポートする場合は、lpcbTotalBytes で指定された pData バッファーのサイズが、データを格納するのに十分かどうかを判断します。十分でない場合は、pData は変更せず、lpcbTotalBytes と lpNumObjectTypes を 0 に設定します。必要なバッファーサイズは次回の呼び出しまでに変化する可能性があるため、そのサイズを示すことは行いません。そして ERROR_MORE_DATA を返します。
データの収集に時間がかかる場合は、特定のオブジェクトに対する照会、またはコストの高い照会にのみ応答するようにしてください。また、システムのパフォーマンスに悪影響を与えないように、データを収集するスレッドの優先度を下げてください。照会文字列の形式については、Using the Registry Functions to Consume Counter 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 メンバーが整合していることを検証します。最後のインスタンスの後ろに次のオブジェクトまたはバッファーの末尾が続いていれば、長さは整合しています。そうでない場合、データは無視されます。
例
Implementing CollectPerformanceData を参照してください。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)