ToUnicodeEx 함수(winuser.h)

지정된 가상 키 코드 및 키보드 상태를 해당 유니코드 문자 또는 문자로 변환합니다.

통사론

int ToUnicodeEx(
  [in]           UINT       wVirtKey,
  [in]           UINT       wScanCode,
  [in]           const BYTE *lpKeyState,
  [out]          LPWSTR     pwszBuff,
  [in]           int        cchBuff,
  [in]           UINT       wFlags,
  [in, optional] HKL        dwhkl
);

매개 변수

[in] wVirtKey

형식: UINT

번역할 가상 키 코드입니다. Virtual-Key 코드참조하세요.

[in] wScanCode

형식: UINT

하드웨어 변환할 키의 코드 검사합니다. 키가 올 경우 이 값의 상위 비트가 설정됩니다.

[in] lpKeyState

형식: const BYTE*

현재 키보드 상태를 포함하는 256 바이트 배열에 대한 포인터입니다. 배열의 각 요소(바이트)에는 하나의 키의 상태가 포함됩니다.

바이트의 상위 비트가 설정되면 키가 다운됩니다. 낮은 비트(설정된 경우)는 키가 설정됨을 나타냅니다. 이 함수에서는 CAPS LOCK 키의 토글 비트만 관련이 있습니다. NUM LOCK 및 SCROLL LOCK 키의 토글 상태는 무시됩니다. 자세한 내용은 GetKeyboardState 참조하세요.

[out] pwszBuff

형식: LPWSTR

번역된 문자 또는 문자를 UTF-16 코드 단위의 배열로 받는 버퍼입니다. 변수 이름이 null로 종료되었음을 시사하는 경우에도 이 버퍼는 null로 종료되지 않고 반환될 수 있습니다. 이 메서드의 반환 값을 사용하여 작성된 문자 수를 확인할 수 있습니다.

[in] cchBuff

형식: int

pwszBuff 매개 변수가 가리키는 버퍼의 크기(문자)입니다.

[in] wFlags

형식: UINT

함수의 동작입니다.

비트 0이 설정되면 메뉴가 활성화됩니다. 이 모드에서는 Alt+Numeric 키패드 키 조합이 처리되지 .

비트 1이 설정되면 ToUnicodeEx 키 만들기 이벤트의 일반적인 처리 외에도 키 중단 이벤트로 표시된 스캔 코드를 변환합니다.

비트 2가 설정되면 키보드 상태가 변경되지 않습니다(Windows 10, 버전 1607 이상).

다른 모든 비트(~31)는 예약되어 있습니다.

[in, optional] dwhkl

형식: HKL

지정된 코드를 번역하는 데 사용되는 입력 로캘 식별자입니다. 이 매개 변수는 LoadKeyboardLayout 함수에서 이전에 반환한 입력 로캘 식별자일 수 있습니다.

반환 값

형식: int

함수는 다음 값 중 하나를 반환합니다.

반환 값	묘사
값 < 0	지정된 가상 키는 데드 키 문자(악센트 또는 발음)입니다. 이 값은 여러 문자가 입력되어 키보드 상태에 저장된 경우에도 키보드 레이아웃에 관계없이 반환됩니다. 가능하면 유니코드 키보드 레이아웃을 사용하더라도 함수는 pwszBuff지정된 버퍼에 데드 키 문자의 간격 버전을 작성했습니다. 예를 들어 함수는 급성 악센트를 결합하는 문자(U+0301)가 아닌 급성 악센트(U+00B4)를 씁니다.
0	지정된 가상 키에 키보드의 현재 상태에 대한 변환이 없습니다. pwszBuff지정한 버퍼에 아무것도 기록되지 않았습니다.
값 > 0	하나 이상의 UTF-16 코드 단위가 pwszBuff지정된 버퍼에 기록되었습니다. 반환된 pwszBuff 반환 값이 지정하는 것보다 많은 문자를 포함할 수 있습니다. 이 경우 추가 문자는 유효하지 않으므로 무시해야 합니다.

발언

입력 로캘 식별자는 음성 텍스트 변환기, IME(입력 메서드 편집기) 또는 다른 형식의 입력을 포함할 수도 있으므로 키보드 레이아웃보다 더 광범위한 개념입니다.

일부 키보드 레이아웃은 pwszBuff 서로게이트 쌍으로 여러 문자 및/또는 보조 문자를 반환할 수 있습니다. 키보드 레이아웃에 저장된 데드 키 문자(악센트 또는 발음)를 지정된 가상 키와 결합하여 단일 문자를 형성할 수 없는 경우 이전에 입력한 데드 문자를 현재 문자와 결합할 수 있습니다.

ToUnicodeEx 함수에 제공된 매개 변수는 이전 데드 키 키보드 레이아웃에 저장되기 때문에 가상 키 코드를 변환하기에 충분하지 않을 수 있습니다.

일반적으로 ToUnicodeEx 가상 키 코드를 기반으로 변환을 수행합니다. 그러나 경우에 따라 wScanCode 매개 변수의 비트 15를 사용하여 키 누름과 키 릴리스(예: ALT+numpad 키 항목)를 구분할 수 있습니다.

ToUnicodeEx 가상 키 코드를 변환하므로 커널 모드 키보드 버퍼의 상태도 변경됩니다. 이 상태 변경은 데드 키, 합자, Alt+숫자 키패드 키 항목 등에 영향을 줍니다. 또한 TranslateMessage 함께 사용하는 경우 원치 않는 부작용이 발생할 수 있습니다(커널 모드 키보드 버퍼의 상태도 변경됨).

요구 사항

요구	값
지원되는 최소 클라이언트	Windows 2000 Professional [데스크톱 앱만 해당]
지원되는 최소 서버	Windows 2000 Server [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	winuser.h(Windows.h 포함)
라이브러리	User32.lib
DLL	User32.dll

참고 항목

개념

키보드 입력

LoadKeyboardLayout

참조

toAsciiEx

VkKeyScan