EvtFormatMessage 함수(winevt.h)

메시지 문자열의 형식을 지정합니다.

구문

BOOL EvtFormatMessage(
  [in]  EVT_HANDLE   PublisherMetadata,
  [in]  EVT_HANDLE   Event,
  [in]  DWORD        MessageId,
  [in]  DWORD        ValueCount,
  [in]  PEVT_VARIANT Values,
  [in]  DWORD        Flags,
  [in]  DWORD        BufferSize,
  [in]  LPWSTR       Buffer,
  [out] PDWORD       BufferUsed
);

매개 변수

[in] PublisherMetadata

EvtOpenPublisherMetadata 함수가 반환하는 공급자의 메타데이터에 대한 핸들입니다. 핸들은 이벤트 또는 메시지 식별자에 대한 서식 컨텍스트 역할을 합니다.

Windows 이벤트 수집기 서비스에서 이벤트를 전달한 경우 이 매개 변수를 NULL 로 설정할 수 있습니다. 전달된 이벤트에는 렌더링된 메시지 문자열이 포함된 RenderingInfo 섹션이 포함됩니다. 서식을 지정하는 이벤트 속성이 Winmeta.xml 파일에 정의된 경우(예: 수준이 win:Error로 설정된 경우) 이 매개 변수를 NULL 로 설정할 수도 있습니다. 후자의 경우 서비스는 Winmeta 공급자를 서식 지정 컨텍스트로 사용하고 Winmeta.xml 파일에 정의된 이벤트에서 참조하는 메시지 문자열의 형식만 지정합니다.

[in] Event

이벤트에 대한 핸들입니다. Flags 매개 변수는 서식을 지정하려는 이벤트의 메시지 문자열을 지정합니다. Flags 매개 변수가 EvtFormatMessageId로 설정된 경우 이 매개 변수는 NULL이어야 합니다.

[in] MessageId

서식을 지정할 메시지 문자열의 리소스 식별자입니다. 메시지 문자열에 대한 리소스 식별자를 얻으려면 GetPublisherMetadataProperty 함수를 호출합니다. Flags 매개 변수가 EvtFormatMessageId로 설정된 경우에만 이 매개 변수를 설정합니다.

[in] ValueCount

Values 매개 변수의 값 수입니다.

[in] Values

이벤트의 메시지 문자열에 서식을 지정할 때 사용할 삽입 값의 배열입니다. 일반적으로 이 매개 변수를 NULL 로 설정하고 함수는 이벤트 데이터 자체에서 삽입 값을 가져옵니다. 이 매개 변수를 사용하여 기본 동작을 재정의하고 사용할 삽입 값을 입력합니다. 예를 들어 값을 삽입하기 전에 SID를 보안 주체 이름으로 resolve 하려는 경우 이 매개 변수를 사용할 수 있습니다.

삽입 값을 재정의하려면 Flags 매개 변수를 EvtFormatMessageEvent, EvtFormatMessageXML 또는 EvtFormatMessageId로 설정해야 합니다. Flags가 EvtFormatMessageId로 설정된 경우 리소스 식별자는 이벤트의 메시지 문자열을 식별해야 합니다.

[in] Flags

형식을 지정할 이벤트의 메시지 문자열을 지정하는 플래그입니다. 가능한 값은 EVT_FORMAT_MESSAGE_FLAGS 열거형을 참조하세요.

[in] BufferSize

버퍼 버퍼의 크기(문자)입니다.

[in] Buffer

형식이 지정된 메시지 문자열을 수신할 호출자가 할당한 버퍼입니다. 이 매개 변수를 NULL 로 설정하여 필요한 버퍼 크기를 확인할 수 있습니다.

[out] BufferUsed

함수가 사용한 호출자 할당 버퍼의 문자 또는 함수가 ERROR_INSUFFICIENT_BUFFER 실패하는 경우 필요한 버퍼 크기의 크기입니다.

반환 값

반환 코드/값	설명
TRUE	함수가 성공했습니다.
FALSE	함수가 실패했습니다. GetLastError 함수를 호출하여 오류 코드를 가져옵니다.

설명

서비스에서 이벤트에 대한 메시지를 찾으려고 하면 서비스는 PublisherMetadata 매개 변수로 표시된 게시자의 메시지 테이블 리소스를 찾습니다. 메시지 ID를 찾은 후 다음 검색 알고리즘이 사용됩니다.

이벤트 메시지의 경우:

1. 공급자 요소의 messageFileName 특성에 지정된 파일을 검색합니다.
2. 찾을 수 없는 경우 시스템 메시지를 검색합니다.

이벤트 요소의 Level, Opcode 및 Keyword 특성의 경우:

1. Winmeta 공급자 리소스를 검색합니다.
2. 공급자 요소의 messageFileName 특성에 지정된 파일을 검색합니다.

이벤트 요소의 Task 특성에 대해 다음을 수행합니다.

1. 공급자 요소의 messageFileName 특성에 지정된 파일을 검색합니다.
2. 찾을 수 없는 경우 Winmeta 공급자 리소스를 검색합니다.

이벤트 메시지에서 %%n (여기서 n 은 메시지 ID임)으로 참조되는 지역화 가능한 매개 변수의 경우:

1. 공급자 요소의 parameterFileName 특성에 나열된 파일을 왼쪽에서 오른쪽으로 검색합니다.
2. 찾을 수 없는 경우 시스템 메시지를 검색합니다.

예제

이 함수를 사용하는 방법을 보여 주는 예제는 이벤트 메시지 서식 지정 및 공급자의 메타데이터 가져오기를 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	winevt.h
라이브러리	Wevtapi.lib
DLL	Wevtapi.dll

추가 정보

FormatMessage