UpdateTraceW 함수(evntrace.h)

UpdateTrace 함수는 지정된 이벤트 추적 세션의 속성 설정을 업데이트합니다.

이 함수는 사용되지 않습니다. ControlTrace 함수는 이 함수를 대체합니다.

구문

ULONG WMIAPI UpdateTraceW(
  TRACEHANDLE             TraceHandle,
  LPCWSTR                 InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

매개 변수

TraceHandle

업데이트할 이벤트 추적 세션 또는 0에 대한 핸들입니다. InstanceName이 NULL인 경우 0이 아닌 TraceHandle을 지정해야 합니다. 이 매개 변수는 InstanceName 이 NULL인 경우에만 사용됩니다. 핸들은 StartTrace에서 반환됩니다.

InstanceName

업데이트할 이벤트 추적 세션의 이름 또는 NULL입니다. TraceHandle이 0인 경우 InstanceName을 지정해야 합니다.

NT 커널 로거 세션을 지정하려면 InstanceName 을 KERNEL_LOGGER_NAME 설정합니다.

Properties

초기화된 EVENT_TRACE_PROPERTIES 구조체에 대한 포인터입니다.

입력에서 멤버는 업데이트할 속성에 대한 새 값을 지정해야 합니다. 업데이트할 수 있는 속성에 대한 자세한 내용은 비고를 참조하세요.

출력 시 구조체 멤버에는 이벤트 추적 세션에 대한 업데이트된 설정 및 통계가 포함됩니다.

반환 값

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

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

• ERROR_BAD_LENGTH

  Properties의 Wnode 멤버의 BufferSize 멤버는 잘못된 크기를 지정합니다.

• ERROR_INVALID_PARAMETER

  다음 중 하나에 해당합니다.

  • 속성 은 NULL입니다.
  • InstanceName 과 TraceHandle 은 모두 NULL입니다.
  • InstanceName 은 NULL 이고 TraceHandle 은 유효한 핸들이 아닙니다.
  • 속성의 LogFileNameOffset 멤버가 잘못되었습니다.
  • 속성의 LoggerNameOffset 멤버가 잘못되었습니다.

  Windows Server 2003 및 Windows XP:Wnode 구조체의 Guid 멤버는 SystemTraceControlGuid이지만 InstanceName 매개 변수는 KERNEL_LOGGER_NAME 않습니다.

• ERROR_ACCESS_DENIED

  관리자 권한이 있는 사용자, 성능 로그 사용자 그룹의 사용자 및 LocalSystem, LocalService, NetworkService로 실행되는 서비스만 이벤트 추적 세션을 제어할 수 있습니다. 제한된 사용자에게 추적 세션을 제어할 수 있는 기능을 부여하려면 성능 로그 사용자 그룹에 추가합니다.

  Windows XP 및 Windows 2000: 누구나 추적 세션을 제어할 수 있습니다.

설명

이벤트 추적 컨트롤러는 이 함수를 호출합니다.

이 함수는 사용되지 않습니다. 대신 ControlCode가 EVENT_TRACE_CONTROL_UPDATE 설정된 ControlTrace를 사용합니다.

입력에서 멤버는 업데이트할 속성에 대한 새 값을 지정해야 합니다. 다음 속성을 업데이트할 수 있습니다.

• EnableFlags: 모든 커널 공급자를 사용하지 않도록 설정하려면 이 멤버를 0으로 설정합니다. 그렇지 않으면 사용하거나 사용하도록 설정할 커널 공급자를 지정해야 합니다. 시스템 로거 세션에만 적용됩니다.

• FlushTimer: 버퍼를 플러시하기 전에 대기할 시간을 변경하려면 이 멤버를 설정합니다. 이 멤버가 0이면 멤버가 업데이트되지 않습니다.

• LogFileNameOffset: 다른 로그 파일로 전환하려면 이 멤버를 설정합니다. 이 멤버가 0이면 파일 이름이 업데이트되지 않습니다. 오프셋이 0이 아니고 로그 파일 이름을 변경하지 않으면 함수는 오류를 반환합니다.

• LogFileMode: EVENT_TRACE_REAL_TIME_MODE 켜고 끄려면 이 멤버를 설정합니다. 실시간 소모를 끄려면 이 멤버를 0으로 설정합니다. 실시간 사용 시간을 설정하려면 이 멤버를 EVENT_TRACE_REAL_TIME_MODE 설정하면 현재 모드에서 OR가 됩니다.

• MaximumBuffers: ETW에서 사용하는 최대 버퍼 수를 변경하려면 이 멤버를 설정합니다. 이 멤버가 0이면 멤버가 업데이트되지 않습니다.

프라이빗 로거 세션의 경우 LogFileNameOffset 및 FlushTimer만 업데이트할 수 있습니다.

새로 초기화된 EVENT_TRACE_PROPERTIES 구조를 사용하는 경우 업데이트 중인 멤버 외에 지정해야 하는 멤버는 Wnode.BufferSize, Wnode.Guid 및 Wnode.Flags뿐입니다.

StartTrace에 전달한 속성 구조를 사용하는 경우 로그 파일 이름을 변경하지 않는 한 LogFileNameOffset 멤버가 0인지 확인합니다.

ControlTrace 함수를 호출하여 현재 세션 속성을 쿼리한 다음 해당 속성을 업데이트하여 세션을 업데이트하는 경우 LogFileNameOffset을 0으로 설정하고(로그 파일 이름을 변경하지 않는 한) EVENT_TRACE_PROPERTIES 설정합니다. Wnode.Flags를 WNODE_FLAG_TRACED_GUID.

이벤트 추적 세션에 대한 속성 설정 및 세션 통계를 가져오려면 ControlTrace 함수를 호출합니다.

예제

UpdateTrace를 사용하는 예제는 이벤트 추적 세션 업데이트를 참조하세요.

참고

evntrace.h 헤더는 UPDATETrace를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

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

추가 정보

ControlTrace