Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function retrieves information about the composition string.

Syntax 

LONG ImmGetCompositionString(
  HIMC 
hIMC, 
  DWORD 
dwIndex, 
  LPVOID 
lpBuf, 
  DWORD 
dwBufLen
);

Parameters

hIMC

[in] Handle to the input context. In Windows CE 2.10 and later, if hIMCis NULL, then the length of the composition string, dwBufLen, is returned for the current active context.

dwIndex

[in] Index of the information to retrieve. This parameter can be one of the values specified in IME Composition String Values. For each value except GCS_CURSORPOS and GCS_DELTASTART, the function copies the requested information to the specified buffer. The function returns the cursor and delta position values in the low 16-bits of the return value.

lpBuf

[out] Long pointer to the buffer that receives the requested information.

dwBufLen

[in] Size of the buffer, in bytes. If zero, the ImmGetCompositionStringfunction returns the buffer size needed for the complete information.

Return Value

The number of bytes copied to the destination buffer or, if dwBufLenis zero, the buffer size, in bytes, needed to receive all of the requested information indicates success. IMM_ERROR_NODATA indicates that the composition data is not ready in the input context. IMM_ERROR_GENERAL indicates that a general error was detected by IME.

Remarks

An application calls this function in response to the WM_IME_COMPOSITIONor WM_IME_STARTCOMPOSITIONmessage. The IMM removes the information when an application calls the ImmReleaseContextfunction.

Code Example

The following code example demonstrates how to use ImmGetCompositionString.

Note:
To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.
Copy Code 
BOOL GetCompositionString( HWND hWnd, LPTSTR *pszCompStr, UINT
*cchCompStr )
{
	ASSERT(hWnd);
	DWORD dwBufLen = NULL;
	HIMC hImc = ImmGetContext(hWnd);
	if (!hImc)
	{
		DEBUGMSG(1, (_T("Failed to get handle to current input
context.\r\n")));
		return FALSE;
}
	// Determine how much space is required to store the
composition string.
	if ( (dwBufLen = ImmGetCompositionString( hImc, GCS_COMPSTR,
NULL, 0l)) < 0 )
	{
		DEBUGMSG(1, (_T("No composition string.\r\n")));
		return FALSE;
}

	if ( *cchCompStr < (dwBufLen/sizeof(TCHAR)) + 1 )
	{
		DEBUGMSG(1, (_T("pszCompStr needs to be at least %i
characters large.\r\n"), 
				 (dwBufLen/sizeof(TCHAR)) + 1));

		*cchCompStr = (dwBufLen/sizeof(TCHAR)) + 1;

		return FALSE;
}
	ImmGetCompositionString(hImc, GCS_COMPSTR, *pszCompStr,
dwBufLen );
	(*pszCompStr)[dwBufLen] = NULL;
	return TRUE;
   
}

Requirements

Header imm.h
Library Coreimm.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also