TraceMessageVa 함수(evntrace.h)

  • 아티클

RegisterTraceGuids 기반("클래식") 이벤트 공급자는 TraceMessageVa 함수를 사용하여 va_list 매개 변수를 사용하여 TMF 기반 WPP(메시지 기반) 이벤트를 이벤트 추적 세션으로 보냅니다.

구문

ULONG TraceMessageVa(
  [in] TRACEHANDLE LoggerHandle,
  [in] ULONG       MessageFlags,
  [in] LPCGUID     MessageGuid,
  [in] USHORT      MessageNumber,
  [in] va_list     MessageArgList
);

매개 변수

[in] LoggerHandle

이벤트를 기록하는 이벤트 추적 세션에 대한 핸들입니다. 공급자는 ControlCallback 구현에서 GetTraceLoggerHandle 함수를 호출할 때 핸들을 가져옵니다.

[in] MessageFlags

이벤트의 공급자별 데이터 섹션의 시작 부분에 추가 정보를 추가합니다. 이벤트의 공급자별 데이터 섹션에는 설정된 플래그에 대한 데이터만 포함됩니다. 인수 데이터의 변수 목록은 이 정보를 따릅니다. 이 매개 변수는 다음 값 중 하나 이상일 수 있습니다.

  • TRACE_MESSAGE_GUID: 메시지에 이벤트 추적 클래스 GUID를 포함합니다. MessageGuid 매개 변수에는 이벤트 추적 클래스 GUID가 포함되어 있습니다.

  • TRACE_MESSAGE_SEQUENCE: 메시지에 시퀀스 번호를 포함합니다. 시퀀스 번호는 1에서 시작됩니다. 이 플래그를 사용하려면 컨트롤러가 세션을 만들 때 EVENT_TRACE_USE_GLOBAL_SEQUENCE 또는 EVENT_TRACE_USE_LOCAL_SEQUENCE 로그 파일 모드를 설정해야 합니다.

  • TRACE_MESSAGE_SYSTEMINFO: 메시지에 스레드 식별자 및 프로세스 식별자를 포함합니다.

  • TRACE_MESSAGE_TIMESTAMP: 메시지에 타임스탬프를 포함합니다.

정보는 다음 순서로 이벤트 데이터에 포함됩니다.

  • 시퀀스 번호
  • 이벤트 추적 클래스 GUID
  • 타임스탬프
  • 스레드 식별자
  • 프로세스 식별자

[in] MessageGuid

이벤트 추적 메시지를 식별하는 클래스 GUID입니다.

[in] MessageNumber

메시지의 각 발생을 고유하게 식별하는 숫자입니다. 이 매개 변수에 대해 지정된 값을 정의해야 합니다. 값은 애플리케이션에 의미가 있어야 합니다.

[in] MessageArgList

메시지에 추가할 변수 인수 목록입니다. 목록은 다음과 같이 인수 쌍으로 구성되어야 합니다.

  • PVOID: 인수 데이터에 대한 포인터입니다.
  • size_t: 인수 데이터의 크기(바이트)입니다.

NULL 및 0에 대한 포인터로 구성된 인수 쌍을 사용하여 목록을 종료합니다.

호출자는 인수 + 72 크기의 합계가 이벤트 추적 세션 버퍼의 크기를 초과하지 않도록 해야 합니다.

반환 값

함수가 성공하면 반환 값이 ERROR_SUCCESS.

함수가 실패하면 반환 값은 시스템 오류 코드 중 하나입니다. 다음 표에는 몇 가지 일반적인 오류와 그 원인이 포함되어 있습니다.

  • ERROR_INVALID_HANDLE

    LoggerHandle이 NULL이거나 NT 커널 로거 세션 핸들을 지정합니다.

  • ERROR_NOT_ENOUGH_MEMORY

    세션에 기록할 여유 버퍼가 없습니다. 많은 이벤트가 발생할 때 디스크 하위 시스템에 과부하가 걸리거나 버퍼 수가 너무 적은 경우 이러한 현상이 발생할 수 있습니다. 더 많은 버퍼를 사용할 수 있게 될 때까지 차단하는 대신 TraceMessage 는 이벤트를 삭제합니다.

    Windows 2000 및 Windows XP: 지원되지 않습니다.

  • ERROR_OUTOFMEMORY

    버퍼 풀이 최대 크기에 도달하지는 않았지만 추가 버퍼를 할당하는 데 사용할 수 있는 메모리가 부족하고 이벤트를 받을 수 있는 버퍼가 없으므로 이벤트가 삭제됩니다.

  • ERROR_INVALID_PARAMETER

    MessageFlags 에는 유효하지 않은 값이 포함되어 있습니다.

  • ERROR_MORE_DATA

    단일 이벤트의 데이터는 여러 버퍼에 걸쳐서는 안 됩니다. 추적 이벤트는 이벤트 추적 세션 버퍼의 크기에서 EVENT_TRACE_HEADER 구조체의 크기를 뺀 값으로 제한됩니다.

설명

TMF 기반 WPP 공급자는 이 함수를 호출합니다.

참고

대부분의 개발자는 이 함수를 직접 호출하지 않습니다. WPP 공급자는 ETW API를 호출하는 대신 tracewpp.exe 생성된 래퍼 함수를 사용합니다.

래퍼 함수에서 메시지 추적 기능에 액세스할 필요가 없는 경우 이 함수의 TraceMessage 버전을 호출할 수 있습니다.

MessageFlags 매개 변수에 TRACE_MESSAGE_GUID 플래그가 포함되지 않은 경우 소비자는 EventCallback 콜백을 사용하여 이벤트를 수신하고 처리해야 합니다. TRACE_MESSAGE_GUID 플래그를 지정하지 않으면 EVENT_TRACE 구조체의 Header.Guid 멤버에 이벤트 추적 클래스 GUID가 포함되지 않으므로 소비자는 EventClassCallback을 사용할 수 없습니다.

MessageFlags 플래그에 해당하는 EVENT_TRACE 및 EVENT_TRACE_HEADER 구조체의 멤버는 해당 플래그가 지정된 경우에만 설정됩니다. 예를 들어 EVENT_TRACE_HEADER ThreadId 및 ProcessId 멤버는 TRACE_MESSAGE_SYSTEMINFO 플래그를 지정하는 경우에만 채워집니다.

요구 사항

   
지원되는 최소 클라이언트 Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버 Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼 Windows
헤더 evntrace.h
라이브러리 Advapi32.lib
DLL Advapi32.dll

추가 정보

TraceEvent

TraceEventInstance

TraceMessage