ToUnicode 함수(winuser.h)

  • 아티클

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

구문

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

매개 변수

[in] wVirtKey

형식: UINT

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

[in] wScanCode

형식: UINT

번역할 키의 하드웨어 검사 코드 입니다. 키가 있는 경우 이 값의 상위 비트가 설정됩니다.

[in, optional] 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 키패드 키 조합이 처리되지 않습니다.

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

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

반환 값

형식: int

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

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

설명

지정된 코드를 변환하는 데 사용할 키보드 레이아웃에 대한 핸들을 지정하려면 ToUnicodeEx 함수를 사용합니다.

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

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

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

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

요구 사항

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

추가 정보

개념

키보드 입력

참조

ToAscii

ToUnicodeEx

VkKeyScan