Platform SDK: International Features

ImmGetGuideLine

The ImmGetGuideLine function gets information about errors. Applications use the information to notify users.

DWORD ImmGetGuideLine(
  HIMC hIMC,      
  DWORD dwIndex,  
  LPTSTR lpBuf,   
  DWORD dwBufLen  
);

Parameters

hIMC

[in] Handle to the input context.

dwIndex

[in] Specifies the type of guideline information to retrieve. This parameter can be one of the following values.

Value	Meaning
GGL_LEVEL	Returns the error level.
GGL_INDEX	Returns the error index.
GGL_STRING	Retrieves the error message string.
GGL_PRIVATE	Returns information about reverse conversion.

lpBuf

[out] Pointer to a buffer that receives the error message string. This parameter can be NULL if dwIndex is not GGL_STRING or GGL_PRIVATE if dwBufLen is zero.

dwBufLen

[in] Specifies the size, in bytes, of the buffer pointed to by lpBuf. If zero, the function returns the buffer size needed to receive the error message string, not including the terminating null character.

Return Values

The function 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 value is one of the following values.

Value	Meaning
GL_LEVEL_ERROR	Error. The IME may not be able to continue.
GL_LEVEL_FATAL	Fatal error. The IME cannot continue, and data may be lost.
GL_LEVEL_INFORMATION	No error, but 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 can not find the module that IME needs.
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 can not handle this typing.
GL_ID_UNKNOWN	Unknown error. The application should refer to the error message string.
GL_ID_INPUTREADING	IME is accepting reading character input from the end user.
GL_ID_INPUTRADICAL	IME is accepting radical character input from the end user.
GL_ID_INPUTCODE	IME is accepting character code input from the end user.
GL_ID_CHOOSECANDIDATE	IME is accepting candidate string selection from the end user.
GL_ID_REVERSECONVERSION	Information about reverse conversion is available by calling ImmGetGuideLine (hIMC, GGL_PRIVATE, lpBuf, dwBufLen). The information returned in lpBuf 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 zero, the return value is the buffer size needed to receive the string, not including the NULL terminator. For Unicode, if dwBufLen is 0, the return value is the size in bytes, not including the Unicode NULL terminator.

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 zero, the return value is the buffer size needed to receive the information.

Remarks

Applications typically call this function after receiving a IMN_GUIDELINE command.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Windows 95/98: Requires Windows 95 or later.
  Header: Declared in Imm.h.
  Library: Use Imm32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

ImmGetGuideLine

Parameters

Return Values

Remarks

Requirements

See Also