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
GGL_LEVEL
Return the error level.
GGL_INDEX
Return the error index.
GGL_STRING
Return the error message string.
GGL_PRIVATE
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

See also

CANDIDATELIST

IMN_GUIDELINE

Input Method Manager

Input Method Manager Functions