TraceMessage 함수(evntrace.h)
RegisterTraceGuids 기반("클래식") 이벤트 공급자는 TraceMessage 함수를 사용하여 TMF 기반 WPP(메시지 기반) 이벤트를 이벤트 추적 세션으로 보냅니다.
구문
ULONG TraceMessage(
[in] TRACEHANDLE LoggerHandle,
[in] ULONG MessageFlags,
[in] LPCGUID MessageGuid,
[in] USHORT MessageNumber,
...
);
매개 변수
[in] LoggerHandle
이벤트를 기록하는 이벤트 추적 세션에 대한 핸들입니다. 공급자는 ControlCallback 구현에서 GetTraceLoggerHandle 함수를 호출할 때 핸들을 가져옵니다.
[in] MessageFlags
이벤트의 공급자별 데이터 섹션 시작 부분에 추가 정보를 추가합니다. 이벤트의 공급자별 데이터 섹션에는 설정된 플래그에 대한 데이터만 포함됩니다. 인수 데이터의 변수 목록은 이 정보를 따릅니다. 이 매개 변수는 다음 값 중 하나 이상일 수 있습니다.
TRACE_MESSAGE_COMPONENTID
메시지에 구성 요소 식별자를 포함합니다. MessageGuid 매개 변수에는 구성 요소 식별자가 포함됩니다.
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
메시지에 타임스탬프를 포함합니다.
TRACE_MESSAGE_COMPONENTID 및 TRACE_MESSAGE_GUID 함께 사용할 수 없습니다.
정보는 다음 순서로 이벤트 데이터에 포함됩니다.
- 시퀀스 번호
- 이벤트 추적 클래스 GUID(또는 구성 요소 식별자)
- 타임스탬프
- 스레드 식별자
- 프로세스 식별자
[in] MessageGuid
메시지를 식별하는 클래스 GUID 또는 구성 요소 ID입니다. MessageFlags에 TRACE_MESSAGE_COMPONENTID 또는 TRACE_MESSAGE_GUID 플래그가 포함되어 있는지 여부에 따라 다릅니다.
[in] MessageNumber
메시지의 각 발생을 고유하게 식별하는 숫자입니다. 이 매개 변수에 지정된 값을 정의해야 합니다. 값은 애플리케이션에 의미가 있어야 합니다.
...
메시지에 추가할 변수 인수 목록입니다. 이 목록을 사용하여 공급자별 이벤트 데이터를 지정합니다. 목록은 다음과 같이 인수 쌍으로 구성되어야 합니다.
- 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 생성된 래퍼 함수를 사용합니다.
래퍼 함수에서 메시지 추적 기능에 액세스해야 하는 경우 이 함수의 TraceMessageVa 버전을 호출합니다.
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 [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | evntrace.h |
| 라이브러리 | Advapi32.lib |
| DLL | Advapi32.dll |