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.

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 Values

This function returns TRUE if it is successful and FALSE if it fails. To get extended error information, call GetLastError.

Remarks

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

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, setting the input panel or IM with SHSipInfo causes the shell to send out a WM_SETTINGCHANGE message, therefore entering an infinite loop.

Requirements

OS Versions: Windows CE .NET 4.2 and later.
Header: Aygshell.h.
Link Library: Aygshell.lib.

See Also

AYGShell Functions | SIPINFO | WM_SETTINGCHANGE | WM_ACTIVATE

Last updated on Wednesday, April 13, 2005

© 2005 Microsoft Corporation. All rights reserved.