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으로 설정합니다. 이는 데이터가 반환되지 않음을 나타냅니다.

하나 이상의 쿼리된 개체를 지원하는 경우 lpcbTotalBytes에 지정된 pData 버퍼의 크기가 데이터를 저장할 수 있을 만큼 큰지 확인합니다. 그렇지 않은 경우 pData 를 변경하지 않고 lpcbTotalBytes 및 lpNumObjectTypes 를 0으로 설정합니다. 다음 호출 전에 변경 될 수 있으므로 필요한 버퍼 크기를 나타내려고 시도 하지 않습니다. ERROR_MORE_DATA 반환합니다.

데이터 수집에 시간이 많이 걸리는 경우 특정 개체 또는 비용이 많이 드는 쿼리에 대한 쿼리에만 응답해야 합니다. 또한 시스템 성능에 부정적인 영향을 주지 않도록 데이터를 수집하는 스레드의 우선 순위를 낮춰야 합니다. 쿼리 문자열 형식은 레지스트리 함수를 사용하여 카운터 데이터 사용을 참조하세요.

소비자가 다른 컴퓨터(원격)에서 실행되는 경우 원격 연결의 서버 쪽을 처리하는 Winlogon 프로세스의 컨텍스트에서 OpenPerformanceData, ClosePerformanceData 및 CollectPerformanceData 함수가 호출됩니다. 이러한 구분은 원격으로만 발생하는 문제를 해결할 때 중요합니다.

함수가 성공적으로 반환되면 시스템은 데이터의 무결성을 보장하기 위해 몇 가지 기본 테스트를 수행할 수 있습니다. 기본적으로 테스트는 수행되지 않습니다. 테스트가 실패하면 시스템에서 이벤트 로그 메시지를 생성하고 데이터가 삭제되어 유효하지 않은 포인터로 인한 추가 문제를 방지합니다. 다음 레지스트리 값은 테스트 수준을 HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Perflib\ExtCounterTestLevel제어합니다.

다음은 ExtCounterTestLevel에 대한 가능한 테스트 수준입니다.

Level	의미
1	신뢰할 수 있는 카운터 DLL의 포인터 및 버퍼를 테스트합니다. 사용자 버퍼의 복사본을 보냅니다.
2	포인터 및 버퍼 길이를 테스트하지만 포인터 참조 또는 버퍼 콘텐츠를 테스트하지는 않습니다. 사용자 버퍼의 복사본을 보냅니다.
3	포인터 또는 버퍼를 테스트하지 마세요. 사용자 버퍼의 복사본을 보냅니다.
4	포인터 또는 버퍼를 테스트하지 마세요. 복사본이 아닌 사용자의 버퍼를 보냅니다. 이것은 기본값입니다.

다음 테스트는 수준 1 및 2에서 수행됩니다.

• lpcbTotalBytes 값이 반환된 버퍼 포인터 pData와 일치하는지 확인합니다. 이 함수에 전달된 원래 버퍼 포인터에 lpcbTotalBytes 값을 추가하면 이 함수에서 반환된 것과 동일한 버퍼 포인터가 반환됩니다. 동일하지 않으면 오류 메시지가 기록되고 데이터가 무시됩니다.
• 버퍼 오버런이 발생하지 않았는지 확인합니다. 시스템은 소비자가 할당한 버퍼 전후에 1KB 가드 페이지를 추가합니다. 반환된 버퍼 포인터 인 pData가 추가된 가드 페이지의 첫 번째 바이트를 지나면 버퍼가 유효하지 않고 데이터가 무시되는 것으로 간주됩니다. 버퍼 포인터가 버퍼의 끝을 초과하지만 가드 페이지의 끝을 초과하지 않으면 버퍼 오버런 오류가 기록됩니다. 버퍼 포인터가 가드 페이지의 끝을 지나면 버퍼가 할당된 힙이 손상되어 다른 메모리 오류가 발생할 수 있으므로 힙 오류가 기록됩니다.
• 보호 페이지가 손상되지 않았는지 확인합니다. 버퍼 전후에 추가된 1KB 보호 페이지는 이 함수가 호출되기 전에 데이터 패턴으로 초기화됩니다. 이 데이터 패턴은 수집 프로시저가 반환된 후에 확인됩니다. 불일치가 감지되면 버퍼 오버런 또는 기타 메모리 오류가 가정되고 데이터가 무시됩니다.

다음 테스트는 테스트 수준 1이 사용되는 경우에만 수행됩니다.

• 각 개체의 TotalByteLength 멤버의 합계가 lpcbTotalBytes 값과 같은지 확인합니다. 그렇지 않으면 데이터가 무시됩니다.
• 각 instance ByteLength 멤버가 일관된지 확인합니다. 버퍼의 다음 개체 또는 끝이 마지막 instance 따르는 경우 길이가 일치합니다. 그렇지 않으면 데이터가 무시됩니다.

예제

CollectPerformanceData 구현을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	winperf.h

추가 정보

• OpenPerformanceData
• ClosePerformanceData