SHSipInfo

This function queries the shell for information about the input panel and input methods (IM). It can also set system-wide parameters regarding the input panel and IM.

At a Glance

Header file:	Aygshell.h
Windows CE Versions:	2.01 and later

Syntax

BOOL WINAPI SHSipInfo( UINT uiAction, UINT uiParam,
PVOID pvParam, UINT fWinIni);

Parameters

uiAction

Unsigned integer containing a system-wide parameter to query or set. It is one of the following flags:

SPI_GETSIPINFO: The pvParam parameter points to a SIPINFO structure. The cbSize, dwImDataSize, and pvImData members of the SIPINFO structure should be filled in with default values before calling SHSipInfo. When called, SHSipInfo fills in the SIPINFO structure with the current input panel size, state, and visible desktop rectangle. The dwImDataSize parameter is usually set to zero and pvImData is usually set to NULL. However, if both dwImDataSize and pvImData are nonzero, SHSipInfo sends these values to the IM. The IM fills the buffer pointed to by pvImData with information specific to that IM. SHSipInfo returns a zero if the IM cannot process the data contained within dwImDataSize or pvImData.
SPI_SETSIPINFO: The pvParam parameter points to a SIPINFO structure. The input panel size and state are set to the values specified in the SIPINFO structure. First, get the current input panel state by calling SHSipInfo with SPI_GETSIPINFO. Then, change the desired input panel state values in the SIPINFO structure. Use the resulting SIPINFO structure in a SHSipInfo call using SPI_SETSIPINFO. To use SPI_SETSIPINFO, the cbSize member of the SIPINFO structure must be set to the size of the SIPINFO structure. If both dwImDataSize and pvImData are nonzero, SHSipInfo passes the data size and the pointer on to the IM. The SHSipInfo call fails if the IM does not allow the shell to set IM-specific data, or if the IM does not recognize the format of the data passed in by dwImDataSize or pvImData. If the IM supports the data size and format, the IM uses the data to set IM-specific information. The dwImDataSize parameter is usually set to zero and pvImData is usually set to NULL. Depending on the type of Palm-size PC, some aspects of the input panel state may not be set by applications.
SPI_SETCURRENTIM: The pvParam parameter points to a CLSID structure that specifies the class identifier (CLSID) of the IM to switch to. If the CLSID is invalid, or the specified IM could not be loaded, the return value is zero and the default IM is loaded.
SPI_GETCURRENTIM: The pvParam parameter points to a CLSID structure that receives the CLSID of the current IM.

uiParam

Unsigned integer that is set to zero for the SPI_SETSIPINFO, SPI_GETSIPINFO, SPI_SETCURRENTIM, and SPI_GETCURRENTIM actions. To improve the response time of SHSipInfo, set uiParam to the lParam of WM_SETTINGCHANGE.

pvParam

Void pointer to a SIPINFO structure when uiAction is SPI_SETSIPINFO or SPI_GETSIPINFO. Pointer to a CLSID structure when uiAction is SPI_SETCURRENTIM or SPI_GETCURRENTIM.

fWinIni

Reserved; set to zero.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError.

Remarks

This function is called by an application to determine the size and state of the input panel at startup or in response to a WM_ACTIVATE message. To avoid changing the input panel state too often, use the SPI_SETSIPINFO value sparingly.

When called in response to a WM_SETTINGCHANGE message, SHSipInfo makes a PSL call to Device.exe. In doing so, it also makes a call to the input panel thread. Because this call can take up to 100 milliseconds, WM_SETTINGCHANGE is sent to all running applications. Therefore, a WM_SETTINGCHANGE message can freeze the system for up to a second as all the running applications respond to the message by calling SHSipInfo. To avoid this delay, pass the lParam of the WM_SETTINGCHANGE in to the uiParam of SHSipInfo. The lParam contains a code that lets SHSipInfo get information directly from the input panel instead of going through the input panel thread.