다음을 통해 공유


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

    EndTimeStartTime보다 작습니다.

  • ERROR_INVALID_PARAMETER

    HandleArrayNULL이거나, 파일 처리 세션과 실시간 처리 세션을 모두 포함하거나, 둘 이상의 실시간 처리 세션을 포함합니다.

  • ERROR_NOACCESS

    이벤트를 수신하는 콜백 함수 중 하나에서 예외가 발생했습니다.

  • ERROR_CANCELLED

    BufferCallback 함수에서 FALSE를 반환하여 소비자가 처리를 취소했음을 나타냅니다.

  • ERROR_WMI_INSTANCE_NOT_FOUND

    이벤트를 실시간으로 사용하려고 하는 추적 컬렉션 세션이 실행되고 있지 않거나 실시간 추적 모드를 사용하도록 설정하지 않았습니다.

설명

추적 소비자는 이 함수를 호출하여 하나 이상의 추적 처리 세션에서 이벤트를 처리합니다. 이 함수는 처리가 끝날 때까지 차단합니다.

ProcessTrace를 호출하기 전에 OpenTrace를 사용하여 처리 세션을 추적하는 핸들을 엽니다.

ProcessTrace 함수는 소비자의 BufferCallback, EventCallbackEventRecordCallback 콜백 함수를 호출하여 세션의 이벤트를 제공합니다.

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

추가 정보

BufferCallback

EventCallback

EventRecordCallback

OpenTrace