SHSipInfo

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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.

Syntax

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

Parameters

• uiAction
  [in] Unsigned integer containing a system-wide parameter to query or set. For descriptions of the flags that can be set for this parameter, see Remarks.

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

• pvParam
  [in, out] 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
  [in] Reserved for future use; set to 0.

Return Value

This function returns TRUE if it is successful and FALSE if it fails. 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.

The following flags can be set for uiAction:

• 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 member 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 input method (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 set. 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 member is usually set to zero and pvImData is usually set to NULL.
  Depending on the Windows Embedded CE device, some aspects of the input panel state cannot 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.

To avoid changing the input panel state too often, use the SPI_SETSIPINFO value sparingly.

When called in response to a WM_SETTINGCHANGE message, setting the input panel or IM with SHSipInfo causes the shell to send out a WM_SETTINGCHANGE message, therefore entering an infinite loop.

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 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.

Code Example

The following code example demonstrates how to use SHSipInfo.

// Use SHSipInfo to obtain information about an input panel.
BOOL SHSipInfoExample1 (SIPINFO * si)
{
    // Setup the SIPINFO structure.
    memset(si, 0, sizeof(SIPINFO));
    si->cbSize = sizeof(SIPINFO);
    return SHSipInfo(SPI_GETSIPINFO, 0, si, 0);
}
// Use SHSipInfo to set Input Panel properties.
BOOL SHSipInfoExample2(SIPINFO * si)
{
    // Set up the SIPINFO structure.
    memset(si, 0, sizeof(SIPINFO));
    si->cbSize = sizeof(SIPINFO);
    SHSipInfo(SPI_GETSIPINFO, 0, si, 0);
    // Set the input panel to "on".
    si->fdwFlags = SIPF_ON;
    si->cbSize = sizeof(SIPINFO);
    return SHSipInfo(SPI_SETSIPINFO, 0, si, 0);
}
// Use SPI_GETCURRENTIM to find the CLSID of an available input method.
BOOL SHSipInfoExample3 (CLSID * clsidIM)
{
    memset(clsidIM, 0, sizeof(CLSID));
   
    return SHSipInfo(SPI_GETCURRENTIM, 0, clsidIM, 0);
}
// Use SPI_SETCURRENTIM to set the CLSID of an available input method.
void SHSipInfoExample4(CLSID * clsidIM)
{
    SHSipInfo(SPI_SETCURRENTIM, 0, clsidIM, 0);
}

Requirements