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

추가 정보

BufferCallback

EventCallback

EventRecordCallback

OpenTrace