ImmGetGuideLineA function (imm.h)
Retrieves information about errors. Applications use the information for user notifications.
Syntax
DWORD ImmGetGuideLineA(
[in] HIMC unnamedParam1,
[in] DWORD dwIndex,
[out, optional] LPSTR lpBuf,
[in] DWORD dwBufLen
);
Parameters
[in] unnamedParam1
Handle to the input context.
[in] dwIndex
Type of guideline information to retrieve. This parameter can have one of the following values.
| Value | Meaning |
|---|---|
|
Return the error level. |
|
Return the error index. |
|
Return the error message string. |
|
Return information about reverse conversion. |
[out, optional] lpBuf
Pointer to a buffer in which the function retrieves the error message string. This parameter contains NULL if dwIndex is not GGL_STRING or GGL_PRIVATE or if dwBufLen is set to 0.
[in] dwBufLen
Size, in bytes, of the output buffer. The application sets this parameter to 0 if the function is to return the buffer size needed to receive the error message string, not including the terminating null character.
Return value
Returns an error level, an error index, or the size of an error message string, depending on the value of the dwIndex parameter. If dwIndex is GGL_LEVEL, the return is one of the following values.
| Value | Meaning |
|---|---|
| GL_LEVEL_ERROR | Error. The IME might not be able to continue. |
| GL_LEVEL_FATAL | Fatal error. The IME cannot continue, and data might be lost. |
| GL_LEVEL_INFORMATION | No error. Information is available for the user. |
| GL_LEVEL_NOGUIDELINE | No error. Remove previous error message if still visible. |
| GL_LEVEL_WARNING | Unexpected input or other result. The user should be warned, but the IME can continue. |
If dwIndex is GGL_INDEX, the return value is one of the following values.
| Value | Meaning |
|---|---|
| GL_ID_CANNOTSAVE | The dictionary or the statistics data cannot be saved. |
| GL_ID_NOCONVERT | The IME cannot convert any more. |
| GL_ID_NODICTIONARY | The IME cannot find the dictionary, or the dictionary has an unexpected format. |
| GL_ID_NOMODULE | The IME cannot find the module that is needed. |
| GL_ID_READINGCONFLICT | A reading conflict occurred. For example, some vowels cannot be put together to form one character. |
| GL_ID_TOOMANYSTROKE | There are too many strokes for one character or one clause. |
| GL_ID_TYPINGERROR | Typing error. The IME cannot handle this typing. |
| GL_ID_UNKNOWN | Unknown error. Refer to the error message string. |
| GL_ID_INPUTREADING | The IME is accepting reading character input from the end user. |
| GL_ID_INPUTRADICAL | The IME is accepting radical character input from the end user. |
| GL_ID_INPUTCODE | The IME is accepting character code input from the end user. |
| GL_ID_CHOOSECANDIDATE | The IME is accepting candidate string selection from the end user. |
| GL_ID_REVERSECONVERSION | Information about reverse conversion is available by calling ImmGetGuideLine, specifying GGL_PRIVATE. The information retrieved is in CANDIDATELIST format. |
If dwIndex is GGL_STRING, the return value is the number of bytes of the string copied to the buffer. However, if dwBufLen is 0, the return value is the buffer size needed to receive the string, not including the terminating null character. For Unicode, if dwBufLen is 0, the return value is the size, in bytes not including the Unicode terminating null character.
If dwIndex is GGL_PRIVATE, the return value is the number of bytes of information copied to the buffer. If dwIndex is GGL_PRIVATE and dwBufLen is 0, the return value is the buffer size needed to receive the information.
Remarks
Applications typically call this function after receiving an IMN_GUIDELINE command.
Note
The imm.h header defines ImmGetGuideLine as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only],East Asian language support installed. |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | imm.h (include Immdev.h, Windows.h) |
| Library | Imm32.lib |
| DLL | Imm32.dll |