ToUnicodeEx 함수(winuser.h)

아티클
03/04/2024

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

구문

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

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

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

설명

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

일부 키보드 레이아웃은 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