ProcessTrace 함수(evntrace.h)
ProcessTrace 함수는 하나 이상의 ETW 추적 처리 세션에서 소비자에게 이벤트를 제공합니다.
구문
ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI ProcessTrace(
[in] PTRACEHANDLE HandleArray,
[in] ULONG HandleCount,
[in] LPFILETIME StartTime,
[in] LPFILETIME EndTime
);
매개 변수
[in] HandleArray
OpenTrace 함수에 대한 이전 호출에서 가져온 추적 처리 세션 핸들 배열에 대한 포인터입니다.
배열은 파일 처리 세션에 대한 최대 64개의 핸들을 포함하거나 실시간 처리 세션에 대한 하나의 핸들을 포함할 수 있습니다. 배열에는 파일 처리 세션 핸들과 실시간 처리 세션 핸들이 모두 포함될 수 없습니다.
[in] HandleCount
HandleArray의 요소 수입니다.
[in] StartTime
이벤트를 수신하려는 시작 기간을 지정하는 선택적 FILETIME 구조체에 대한 포인터입니다. 함수는 StartTime 이전의 타임스탬프가 있는 이벤트를 제공하지 않습니다.
[in] EndTime
이벤트를 수신하려는 종료 기간을 지정하는 선택적 FILETIME 구조체에 대한 포인터입니다. 함수는 EndTime 이후에 타임스탬프가 있는 이벤트를 제공하지 않습니다.
Windows Server 2003: 실시간 이벤트 배달에는 이 값이 무시됩니다.
반환 값
함수가 성공하면 반환 값이 ERROR_SUCCESS.
함수가 실패하면 반환 값은 시스템 오류 코드 중 하나입니다. 다음은 몇 가지 일반적인 오류와 그 원인입니다.
ERROR_BAD_LENGTH
HandleCount 가 잘못되거나 핸들 수가 64보다 큽니다.
ERROR_INVALID_HANDLE
HandleArray의 요소는 유효한 이벤트 추적 세션 핸들이 아닙니다.
ERROR_INVALID_TIME
EndTime 이 StartTime보다 작습니다.
ERROR_INVALID_PARAMETER
HandleArray 는 NULL이거나, 파일 처리 세션과 실시간 처리 세션을 모두 포함하거나, 둘 이상의 실시간 처리 세션을 포함합니다.
ERROR_NOACCESS
이벤트를 수신하는 콜백 함수 중 하나에서 예외가 발생했습니다.
ERROR_CANCELLED
BufferCallback 함수에서 FALSE를 반환하여 소비자가 처리를 취소했음을 나타냅니다.
ERROR_WMI_INSTANCE_NOT_FOUND
이벤트를 실시간으로 사용하려고 하는 추적 컬렉션 세션이 실행되고 있지 않거나 실시간 추적 모드를 사용하도록 설정하지 않았습니다.
설명
추적 소비자는 이 함수를 호출하여 하나 이상의 추적 처리 세션에서 이벤트를 처리합니다. 이 함수는 처리가 끝날 때까지 차단합니다.
ProcessTrace를 호출하기 전에 OpenTrace를 사용하여 처리 세션을 추적하는 핸들을 엽니다.
ProcessTrace 함수는 소비자의 BufferCallback, EventCallback 및 EventRecordCallback 콜백 함수를 호출하여 세션의 이벤트를 제공합니다.
ProcessTrace 함수는 이벤트의 타임스탬프를 기반으로 이벤트를 순서대로 전달하려고 시도합니다(즉, 가장 오래된 이벤트를 최신으로 전달하려고 시도함). 경우에 따라 ProcessTrace 는 순서가 다른 이벤트를 제공할 수 있습니다.
- 추적 수집 중에 이벤트 타임스탬프에 사용된 클록이 뒤로 조정되면 이벤트의 배달 순서를 예측할 수 없습니다. 이 문제를 방지하려면 추적을 수집할 때 시스템 시간 클록 대신 QPC 클록을 사용합니다.
- 여러 이벤트가 다른 CPU에서 동일한 타임스탬프를 사용하여 수집되는 경우 이벤트의 배달 순서를 예측할 수 없습니다.
- 이벤트에 잘못된 타임스탬프(예: 파일 손상)가 있는 경우 해당 이벤트 및 추적의 다른 이벤트의 배달 순서를 예측할 수 없습니다.
ProcessTrace 함수는 모든 이벤트를 전달하거나 BufferCallback 함수가 FALSE를 반환하거나 CloseTrace를 호출할 때까지 스레드를 차단합니다. 또한 소비자가 실시간으로 이벤트를 사용하는 경우 컨트롤러가 추적 세션을 중지한 후 ProcessTrace 함수가 반환됩니다. 함수가 반환되기까지 몇 초 정도 지연될 수 있습니다.
Windows Server 2003: ProcessTrace가 반환된 후에만 CloseTrace를 호출할 수 있습니다.
예제
ProcessTrace를 사용하는 예제는 TdhFormatProperty를 사용하여 이벤트 데이터 사용을 참조하세요.
요구 사항
| 지원되는 최소 클라이언트 | Windows 2000 Professional [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows 2000 Server [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | evntrace.h |
| 라이브러리 | Windows 8.1 및 Windows Server 2012 R2의 Sechost.lib; Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista 및 Windows XP의 Advapi32.lib |
| DLL | Windows 8.1 및 Windows Server 2012 R2의 Sechost.dll. Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista 및 Windows XP의 Advapi32.dll |