IME 개발을 위한 Win32 다국어 IME 개요
버전 1.32
최종 수정일: 1998년 4월 1일, 번역: Luciano Jeong
IME 파일 포맷과 데이터 구조체 (Part 2)
IMM 및 IME의 데이터 구조체
아래 구조체들은 IMM 및 IME와의 통신에 사용됩니다. IME는 이들 구조체에 직접 접근할 수 있지만 어플리케이션을 그럴 수 없습니다.
INPUTCONTEXT
INPUTCONTEXT 구조체는 입력 컨텍스트와 관련된 데이터를 보관하는 내부 데이터 구조체입니다.
/* INPUTCONTEXT */
typedef struct tagINPUTCONTEXT {
HWND hWnd;
BOOL fOpen;
POINT ptStatusWndPos;
POINT ptSoftKbdPos;
DWORD fdwConversion;
DWORD fdwSentence;
union { LOGFONTA A; LOGFONTW W; } lfFont;
COMPOSITIONFORM cfCompForm;
CANDIDATEFORM cfCandForm[4];
HIMCC hCompStr;
HIMCC hCandInfo;
HIMCC hGuideLine
HIMCC hPrivate;
DWORD dwNumMsgBuf;
HIMCC hMsgBuf;
DWORD fdwInit
DWORD dwReserve[3];
} INPUTCONTEXT;
INPUTCONTEXT 멤버의 설명
hWnd
이 입력 컨텍스트를 사용하는 윈도우의 핸들입니다. 이 입력 컨텍스트를 여러 윈도우에서 공유하고 있다면, 이 값은 현재 활성화 된 윈도우의 핸들을 나타냅니다. 이 값은 ImmSetActiveContext에 의해 재설정 될 수 있습니다.
fOpen
IME의 현재 상태가 열려있는지 닫혀있는지를 나타냅니다.
ptStatusWndPos
IME 상태 윈도우의 위치를 나타냅니다.
ptSoftKbdPos
소프트 키보드의 위치를 나타냅니다.
fdwConversion
IME 컴포지션 윈도우가 사용하는 변환 모드를 나타냅니다.
fdwSentence
IME 컴포지션 엔진이 사용하게 될 문장 모드입니다.
lfFont
IME 사용자 인터페이스가 컴포지션 문자열을 화면에 출력할 때 사용할 글꼴로서 LOGFONT 구조체입니다.
cfCompForm
컴포지션 윈도우를 생성할 때 IME 사용자 인터페이스가 사용할 COMPOSITIONFORM 구조체입니다.
cfCandForm[4]
후보 목록 윈도우를 생성할 때 IME 사용자 인터페이스가 사용할 CANDIDATEFORM 구조체입니다. 4가지의 형태를 지원합니다.
hCompStr
COMPOSITIONSTR 구조체가 있는 메모리 핸들입니다. 이 핸들은 컴포지션 문자열이 있을 때만 사용 가능합니다.
hCandInfo
후보 문자열이 있는 메모리 핸들입니다. 이 메모리 블록은 CANDIDATEINFO 구조체와 CANDIDATELIST 구조체를 기억하고 있습니다. 이 메모리 핸들은 후보 문자열이 있을때만 사용 가능합니다.
hGuideLine
가이드라인의 메모리 핸들입니다. 이 메모리 블록은 GUIDELINE 구조체를 가지고 있습니다. 이 핸들은 가이드라인 정보가 있을 때만 사용 가능합니다.
hPrivate
IME가 내부적으로 필요한 데이터를 보관하는 메모리의 핸들입니다.
dwNumMsgBuf
hMsgBuf에 저장된 메시지의 총 수입니다.
hMsgBuf
메시지를 보관하는 메모리 블록입니다. 메모리 블록에는 ([메시지]-[wParam]-[lParam]) * n개의 형식으로 메시지가 기억되어 있습니다. 값들은 모두 DWORD 형식입니다.
fdwinit
초기화 작업과 관련된 설정 플래그입니다. IME가 INPUTCONTEXT 구조체의 멤버를 초기화할 때 IME는 이 멤버의 비트들을 확인해야 합니다. 여기에 올 수 있는 비트는 아래와 같습니다.
| 이름 | 값 |
| INIT_STATUSWNDPOS | ptStatusWndPos 멤버를 초기화합니다. |
| INIT_CONVERSION | fdwConversion 멤버를 초기화합니다. |
| INIT_SENTENCE | fdwSentence 멤버를 초기화합니다. |
| INIT_LOGFONT | lfFont 멤버를 초기화합니다. |
| INIT_COMPFORM | cfCompForm 멤버를 초기화합니다. |
| INIT_SOFTKBDPOS | ptSoftKbdPos 멤버를 초기화합니다. |
dwReserve[3]
차기 버전을 위해 예약된 공간입니다.
알림
ImeToAsciiEx가 호출되어 이를 실행하는 동안 IME는 lpdwTransKey 버퍼를 사용해 메시지를 생성할 수 있습니다. 그러나 IME가 어플리케이션에게 메시지를 생성하고자 할 때는 hMsgBuf에 메시지를 저장하고 ImmGenerateMessage를 호출하십시오. ImmGenerateMessage 함수는 이들 메시지를 어플리케이션으로 보냅니다.
COMPOSITIONSTR
COMPOSITIONSTR 구조체는 컴포지션에 대한 정보를 보환합니다. 변환 과정 동안 IME는 이 구조체에 변환 정보를 기억시킵니다.
/* COMPOSITIONSTR */
typedef struct tagCOMPOSITIONSTR {
DWORD dwSize;
DWORD dwCompReadAttrLen;
DWORD dwCompReadAttrOffset;
DWORD dwCompReadClsLen;
DWORD dwCompReadClsOffset;
DWORD dwCompReadStrLen;
DWORD dwCompReadStrOffset;
DWORD dwCompAttrLen;
DWORD dwCompAttrOffset;
DWORD dwCompClsLen;
DWORD dwCompClsOffset;
DWORD dwCompStrLen;
DWORD dwCompStrOffset;
DWORD dwCursorPos;
DWORD dwDeltaStart;
DWORD dwResultReadClsLen;
DWORD dwResultReadClsOffset;
DWORD dwResultReadStrLen;
DWORD dwResultReadStrOffset;
DWORD dwResultClsLen;
DWORD dwResultClsOffset;
DWORD dwResultStrLen;
DWORD dwResultStrOffset;
DWORD dwPrivateSize;
DWORD dwPrivateOffset;
} COMPOSITIONSTR;
COMPOSITIONSTR 멤버의 설명
dwSize
이 구조체의 메모리 블록 크기입니다.
dwCompReadAttrLen
컴포지션 문자열의 발음 문자열에 대한 속성의 길이입니다.
dwCompReadAttrOffset
이 구조체의 시작 위치로부터의 오프셋입니다. 속성은 이 곳에서 명시한 위치부터 기억되어 있습니다.
dwCompReadClsLen
컴포지션 문자열의 발음 문자열에 대한 절(clause) 정보의 길이입니다.
dwCompReadClsOffset
이 구조체의 시작 위치로부터의 오프셋입니다. 절 정보는 이 곳에서 명시한 위치부터 기억되어 있습니다.
dwCompReadStrLen
컴포지션 문자열의 발음 문자열의 길이입니다.
dwCompReadStrOffset
이 구조체의 시작 위치로부터의 오프셋입니다. 컴포지션 문자열의 발음 문자열은 이 곳에서 명시한 위치부터 기억되어 있습니다.
dwCompAttrLen
컴포지션 문자열의 속성의 길이입니다.
dwCompAttrOffset
이 구조체의 시작 위치로부터의 오프셋입니다. 컴포지션 문자열의 속성은 이 곳에서 명시한 위치부터 기억되어 있습니다.
dwCompClsLen
컴포지션 문자열의 절(clause) 정보의 길이입니다.
dwCompClsOffset
이 구조체의 시작 위치로부터의 오프셋입니다. 절 정보는 이 곳에서 명시한 위치부터 기억되어 있습니다.
dwCompStrLen
컴포지션 문자열의 길이입니다.
dwCompStrOffset
이 구조체의 시작 위치로부터의 오프셋입니다. 컴포지션 문자열은 이 곳에서 명시한 위치부터 기억되어 있습니다.
dwCursorPos
컴포지션 문자열에서 커서가 놓인 위치입니다.
dwDeltaStart
컴포지션 문자열에서 수정이 시작된 위치입니다. 컴포지션 문자열이 이전 상태와 달라졌을 경우 달라진 문자가 시작되는 가장 처음의 위치가 기억되어 있습니다.
dwResultReadClsLen
결과 문자열의 발음 문자열에 대한 절 정보의 길이입니다.
dwResultReadClsOffset
이 구조체의 시작 위치로부터의 오프셋입니다. 절 정보는 이 곳에서 명시한 위치부터 기억되어 있습니다.
dwResultRieadStrLen
결과 문자열에 대한 발음 문자열의 길이입니다.
dwResultReadStrOffset
이 구조체의 시작 위치로부터의 오프셋입니다. 결과 문자열의 발음 문자열은 이 곳에서 명시한 위치부터 기억되어 있습니다.
dwResultClsLen
결과 문자열의 절 정보의 길이입니다.
dwResultClsOffset
이 구조체의 시작 위치로부터의 오프셋입니다. 절 정보는 이 곳에서 명시한 위치부터 기억되어 있습니다.
dwResultStrLen
결과 문자열의 길이입니다.
dwResultStrOffset
이 구조체의 시작 위치로부터의 오프셋입니다. 결과 문자열은 이 곳에서 명시한 위치부터 기억되어 있습니다.
dwPrivateSize
IME가 자체적으로 필요하여 확보한 메모리의 크기입니다.
dwPrivateOffset
이 구조체의 시작 위치로부터의 오프셋입니다. IME 자체 메모리는 이 곳에서 명시한 위치부터 기억되어 있습니다.
알림
유니코드 버전에서 dwXXXStrLen 멤버는 각각의 버퍼의 크기를 재는 단위가 '문자의 수'입니다. 그 외 dwXXXLen 및 dwXXXOffset의 단위는 바이트입니다.
속성 정보의 기억 형식은 싱글 바이트 배열이며 문자열의 속성을 지정합니다. 아래 비트들이 조합되며 여기 명기되지 않은 비트들은 차기 버전을 위해 예약되었습니다.
| 이름 | 내용 |
| ATTR_INPUT | 문자가 현재 입력되고 있는 중입니다. |
| ATTR_TERGET_CONVERTED | 문자가 현재 변환되고 있는 중이거나 이미 변환되었습니다. |
| ATTR_CONVERTED | 변환 작업으로부터 문자를 얻었습니다. |
| ATTR_TERGET_NOTCONVERTED | 문자가 현재 변환되고 있는 중이거나 곧 변환될 예정입니다. |
| ATTR_FIXEDCONVERTED | 문자가 더이상 변환되지 않을 것입니다. |
| ATTR_INPUT_ERROR | 문자에 오류가 있어 IME가 이를 변환하지 않습니다. |
덧붙임
속성의 길이는 문자열의 길이와 같습니다. 각 바이트는 문자열의 각 바이트에 일대일로 대응합니다. 문자열이 DBCS 문자로 구성되었다 해고 속성 정보는 문자의 상위 1바이트와 하위 1바이트에 대응되는 정보를 따로 갖습니다.
Windows NT/Windows 2000 유니코드 버전에서 속성 정보의 길이는 유니코드 문자의 수와 일치합니다. 긱 바이트가 나타내는 속성은 유니코드 문자열을 구성하는 각 문자에 대응됩니다.
절 정보의 포맷은 DWORD 배열이며 절의 위치를 지정하는 수가 지정되어 있습니다. 절의 위치는 컴포지션 문자열의 위치입니다. 이 위치로부터 절이 시작됩니다. 최소한 정보의 길이는 2개의 DWORD 이상이어야 합니다. 즉 절 정보의 크기는 최소 8바이트여야 합니다. 처음 DWORD는 0이어야 하고 이는 첫 번째 절의 시작 위치입니다. 그 다음 DWORD는 이 문자열의 길이입니다. 예를 들어 문자열이 3개의 절로 구성된 경우 절 정보는 4개의 DWORD값으로 구성됩니다. 첫 번쨰 DWORD는 0이고, 두 번째 DWORD는 문자열에서 두 번째 절이 시작되는 위치입니다. 세 번쨰 DWORD는 문자열에서 세 번째 절이 시작되는 위치입니다. 마지막 DWORD는 이 문자열의 전체 길이입니다.
Windows NT/Windows 2000 유니코드 버전에서 각 절의 위치와 문자열의 길이를 세는 단위는 바이트가 아니라 유니코드 문자 수입니다.
dwCursorPos 멤버는 커서의 위치, 즉 컴포지션 문자열에서 커서가 놓여진 위치를 지시합니다. 단위는 문자 수입니다. 이 위치는 0부터 시작합니다. 컴포지션 문자열 바로 뒤에 커서가 놓여질 경우 이 값은 컴포지션 문자열의 길이와 같습니다. 커서가 놓이지 않은 경우 -1이 지정되며, 컴포지션 문자열이 존재하지 않는 경우 이 값은 무의미합니다.
Windows NT/Windows 2000 유니코드 버전에서 커서의 위치는 바이트가 아닌 유니코드 문자 수입니다.
CANDIDATEINFO
CANDIDATEINFO 구조체는 전체 후보 목록의 헤더 역할을 합니다. 이 구조체는 한번에 최대 32개의 후보 목록을 포함할 수 있고 이러한 후보 목록은 같은 메모리 블록에 연속적으로 놓입니다.
/* CANDIDATEINFO 구조체 */
typedef struct tagCANDIDATEINFO {
DWORD dwSize;
DWORD dwCount;
DWORD dwOffset[32];
DWORD dwPrivateSize;
DWORD dwPrivateOffset;
} CANDIDATEINFO;
CANDIDATEINFO 멤버의 설명
dwSize
이 구조체의 메모리 블록의 크기입니다.
dwCount
이 메모리 블록에 포함된 후보 문자열의 수입니다.
dwOffset[32]
이 구조체의 시작 위치로부터의 오프셋들을 기억하고 있습니다. 각 오프셋은 후보 목록이 시작되는 위치를 의미합니다.
dwPrivateSize
사적인 용도로 쓸 수 있는 메모리 영역의 크기입니다.
dwPrivateOffset
이 구조체의 시작 위치로부터의 오프셋입니다. 사적인 용도의 메모리는 이 값이 지시하는 위치부터 시작됩니다.
GUIDELINE
GUIDELINE 구조체는 IME가 내보내는 가이드라인 정보를 포함합니다.
/* GUIDELINE */
typedef struct tagGUIDELINE {
DWORD dwSize;
DWORD dwLevel; // the error level.(오류 레벨)
// GL_LEVEL_NOGUIDELINE,
// GL_LEVEL_FATAL,
// GL_LEVEL_ERROR,
// GL_LEVEL_WARNNING,
// GL_LEVEL_INFORMATION
DWORD dwIndex; // GL_ID_NODICTIONARY and so on. (GL_ID_NODICTIONARY 및 그 외)
DWORD dwStrLen; // Error Strings, if this is 0, there is no error string. (오류 문자열로서 0이면 오류 문자열이 없음을 의미)
DWORD dwStrOffset;
DWORD dwPrivateSize;
DWORD dwPrivateOffset;
} GUIDELINE;
알림
유니코드에서 dwStrLen 멤버가 나타내는 크기는 오류 문자열의 문자 수입니다. 그 외 dwSize, dwStrOffset, dwPrivateSize와 같이 크기를 지정하는 멤버 변수는 단위가 바이트입니다.
GUIDELINE 구조체의 멤버
dwLevel 오류 레벨을 지정합니다. 아래 값들이 제공됩니다.
| 이름 | 설명 |
| GL_LEVEL_NOGUIDELINE | 가이드라인이 없습니다. 기존의 가이드라인이 보여지고 있다면 사용자 인터페이스는 해당 가이드라인을 숨깁니다. |
| GL_LEVEL_FATAL | 치명적인 오류가 발생했습니다. 일부 데이터는 손실될 수 있습니다. |
| GL_LEVEL_ERROR | 오류가 발생되어 더 이상의 처리는 진행되지 않습니다. |
| GL_LEVEL_WARNING | IME 경고가 사용자에게 발생하였습니다. 예기치 못한 상황이 발생하였지만 IME는 작업 처리를 계속 할 수 있습니다. |
| GL_LEVEL_INFORMATION | 사용자에게 정보를 제공하려 합니다. |
dwIndex 아래와 같은 값들이 제공됩니다.
| 이름 | 설명 |
| GL_ID_UNKNOWN | 알 수 없는 오류가 발생하였습니다 어플리케이션은 이 오류 문자열을 참조해야 합니다. |
| GL_ID_NOMODULE | IME가 필요로하는 모듈을 찾지 못하였습니다. |
| GL_ID_NODICTIONARY | IME가 딕셔너리를 찾지 못하였거나 알 수 없는 형식입니다. |
| GL_ID_CANNOTSAVE | 딕셔너리 또는 통계 데이터가 저장되지 않았습니다. |
| GL_ID_NOCONVERT | IME가 더이상 변환할 수 없습니다. |
| GL_ID_TYPINGERROR | 타이핑 오류입니다. IME가 이 타자를 처리할 수 없습니다. |
| GL_ID_TOOMANYSTROKE | 한 글자 또는 한 절에 너무 많은 글쇠가 눌려졌습니다. |
| GL_ID_READINGCONFLICT | 발음 혼동 오류가 발생하였습니다. 예를 들어 몇몇 모음은 조합이 불가능합니다. |
| GL_ID_INPUTREADING | IME가 사용자에게 현재 발음 입력으로 문장을 작성하고 있음을 알려줍니다. |
| GL_ID_INPUTRADICAL | IME가 사용자에게 현재 부수 입력으로 문장을 작성하고 있음을 알려줍니다. |
| GL_ID_INPUTCODE | IME가 사용자에게 현재 문자 코드 입력으로 문장을 작성하고 있음을 알려줍니다. |
| GL_ID_CHOOSECANIDATE | IME가 사용자에게 현재 후보 문자열을 선택하는 상태임을 알려줍니다. |
| GL_ID_REVERSECONVERSION | IME가 사용자에게 역변환에 대한 정보를 제공해 줄 것을 요청합니다. 역변환 정보는 ImmGetGuideLine(hIMC, GGL_PRIVATE. lpBuf, dwBufLen) 함수 호출로 얻을 수 있습니다. lpBuf에 기억된 정보는 CANDIDATELIST 형식으로 기억되어 있습니다. |
| GL_ID_PRIVATE_FIRST | GL_ID_PRIVATE_FIRST와 GL_ID_PRIVATE_LAST 사이에 있는 ID 값들은 IME를 위해 예약되었습니다. 여러분이 IME를 작성할 때 이 사이의 값들은 개발자가 자유롭게 의미를 부여하여 사용할 수 있습니다. |
| GL_ID_PRIVATE_LAST | GL_ID_PRIVATE_FIRST와 GL_ID_PRIVATE_LAST 사이에 있는 ID 값들은 IME를 위해 예약되었습니다. 여러분이 IME를 작성할 때 이 사이의 값들은 개발자가 자유롭게 의미를 부여하여 사용할 수 있습니다. |
dwPrivateSize
메모리 블록의 사적 이용 공간입니다.
dwPrivateOffset
이 구조체의 시작위치로부터의 오프셋입니다. 사적 영역은 이 값에서 명시한 위치부터 시작됩니다.