共用方式為

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

傳回值

下列其中一個值：

傳回碼 Description
ERROR_MORE_DATA pData 緩衝區的大小 (其中 pData 參考 lppData 所指向的指標，) l) ，不足以儲存數據。 讓 pData 保持不變，並將 lmicrosoftTotalBytes 和 lpNumObjectTypes 設定為零。 不會嘗試指出所需的緩衝區大小，因為這可能會在下次呼叫之前變更。
ERROR_SUCCESS 在 ERROR_MORE_DATA 案例以外的所有案例中傳回此值，即使未傳回任何數據或發生錯誤也一樣。 若要報告緩衝區大小不足以外的錯誤，請使用應用程式事件記錄檔。

備註

如果 lpValueName 參數中指定的要求對象未對應至效能 DLL 所支援的任何物件索引，請將 pData 參數維持不變 (其中 pData 參考 lppData 所指向的指標) ，並將 lvpTotalBytes 和 lpNumObjectTypes 參數設定為零。 這表示未傳回任何數據。

如果您支援一或多個查詢的物件，請判斷lTotalBytes 所指定的 pData 緩衝區大小是否足以儲存數據。 如果沒有，請將 pData 保持不變，並將 lmicrosoftTotalBytes 和 lpNumObjectTypes 設定為零。 不會嘗試指出所需的緩衝區大小，因為這可能會在下次呼叫之前變更。 傳回 ERROR_MORE_DATA。

如果您的資料收集相當耗時，您應該只回應特定對象的查詢，或成本高昂的查詢。 您也應該降低線程收集數據的優先順序，使其不會對系統效能造成負面影響。 如需查詢字串格式，請參閱 使用登錄函式取用計數器數據。

如果取用者在另一部計算機上 (遠端) ，則會在 Winlogon 進程的內容中呼叫 OpenPerformanceData、 ClosePerformanceData 和 CollectPerformanceData 函式，以處理遠端連線的伺服器端。 這項區別在只針對遠端發生的問題進行疑難解答時很重要。

在函式成功傳回之後，系統可以執行一些基本測試，以確保數據的完整性。 根據預設，不會執行任何測試。 如果測試失敗，系統會產生事件記錄檔訊息，並捨棄數據，以防止因指標無效而發生任何進一步的問題。 下列登錄值會控制測試層級： HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Perflib\ExtCounterTestLevel。

以下是 ExtCounterTestLevel 的可能測試層級。

層級 意義
1 測試受信任計數器 DLL 的指標和緩衝區。 傳送用戶緩衝區的複本。
2 測試指標和緩衝區長度，但不會測試指標參考或緩衝區內容。 傳送用戶緩衝區的複本。
3 請勿測試指標或緩衝區。 傳送用戶緩衝區的複本。
4 請勿測試指標或緩衝區。 傳送用戶的緩衝區，而非複本。 這是預設值。

下列測試會在層級 1 和 2 上執行：

  • 確認 lmicrosoftTotalBytes 的值與傳回的緩衝區指標 pData 一致。 如果您將 lmicrosoftTotalBytes 值新增至傳遞至此函式的原始緩衝區指標，則最後應該包含此函式所傳回的相同緩衝區指標。 如果它們不相同，則會記錄錯誤訊息，並忽略數據。
  • 確認緩衝區溢出未發生。 系統會在取用者配置的緩衝區前後新增 1 KB 防護頁面。 如果傳回的緩衝區指標 pData 會指向附加防護頁面的第一個字節，則會假設緩衝區無效，而且會忽略數據。 如果緩衝區指標超過緩衝區的結尾，但未超過防護頁面的結尾，則會記錄緩衝區溢出錯誤。 如果緩衝區指標超過防護頁面的結尾，則會記錄堆積錯誤，因為已配置緩衝區的堆積可能已損毀，導致其他記憶體錯誤。
  • 確認防護頁面尚未損毀。 在呼叫此函式之前，緩衝區之前和之後新增的 1 KB 防護頁面會使用數據模式初始化。 收集程式傳回之後，會檢查此數據模式。 如果偵測到任何差異，則會假設緩衝區溢出或其他記憶體錯誤，並忽略數據。

只有在使用測試層級 1 時，才會執行下列測試：

  • 確認每個物件的 TotalByteLength 成員總和與 lmicrosoftTotalBytes 的值相同。 如果沒有，則會忽略數據。
  • 確認每個實例的 ByteLength 成員都一致。 如果下一個物件或緩衝區結尾遵循最後一個實例，則長度會一致。 如果沒有，則會忽略數據。

範例

請參閱 實作 CollectPerformanceData。

規格需求

需求 值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限傳統型應用程式]
目標平台 Windows
標頭 winperf.h

另請參閱