Partager via

SystemParametersInfo (Compact 2013)

  • Article

3/28/2014

This function queries or sets system-wide parameters, and can also update the user profile by setting a parameter.

Syntax

BOOL SystemParametersInfo( 
    UINT uiAction, 
    UINT uiParam, 
    PVOID pvParam, 
    UINT fWinIni
);

Parameters

  • uiAction
    [in] Specifies the system-wide parameter to query or set. This parameter can be one of the following values, depending on the SYSGEN variable that is set. For more information, see the Remarks section.

    Value

    Description

    SPI_APPBUTTONCHANGE

    Retrieves the application button mappings.

    SPI_GETACCESSTIMEOUT

    Retrieves information about the time-out period associated with the accessibility options. The pvParam parameter must point to an ACCESSTIMEOUT structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(ACCESSTIMEOUT).

    SPI_GETBATTERYIDLETIMEOUT

    Retrieves the amount of time that Windows Embedded Compact remains on with battery power before it suspends due to user inaction. The pvParam parameter points to a DWORD that returns the time in seconds. This flag is ignored if pvParam is 0 (zero).

    If you disable GWES suspend management, then the function returns 0 (zero).

    SPI_GETBOOTMENAME

    Returns the device BOOTME name (for example "CEPC53902").

    This value is synonymous with using the SPI codes in IOCTL_HAL_GET_DEVICE_INFO.

    SPI_GETDEFAULTINPUTLANG

    Retrieves the locale identifier for the default input language. The pvParam parameter must point to an HKL variable that receives this value.

    For more information, see Locale Identifiers at MSDN.

    SPI_GETEXTERNALIDLETIMEOUT

    Retrieves the amount of time that Windows Embedded Compact remains on with AC power before it suspends due to user inaction. The pvParam parameter points to a DWORD that returns the time in seconds. This flag is ignored if pvParam is 0 (zero).

    If you disable GWES suspend management, then the function returns 0 (zero).

    SPI_GETFONTSMOOTHING

    Determines whether the font smoothing feature is enabled. This capability uses font antialiasing to make font curves appear smoother by painting pixels at different gray levels. Microsoft ClearType requires font smoothing.

    The pvParam parameter must point to a BOOL variable that receives TRUE if the feature is enabled or FALSE if it is not.

    SPI_GETFONTSMOOTHINGCONTRAST

    Retrieves a contrast value that Windows Embedded Compact uses in smoothing text displayed using Microsoft ClearType. The pvParam parameter must point to a UINT that receives the information.

    SPI_GETGESTUREMETRICS

    Retrieves information about gesture metrics. The pvParam parameter must point to a GESTUREMETRICS structure that receives the information. Set the cbSize member of this structure to sizeof(GESTUREMETRICS). The uiParam parameter is not supported and must be set to 0 (zero).

    SPI_GETGUIDPATTERN

    Returns a platform-specific GUID pattern.

    SPI_GETHIGHCONTRAST

    Retrieves information about the high-contrast accessibility option. The pvParam parameter must point to a HIGHCONTRAST structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(HIGHCONTRAST).

    SPI_GETMOUSE

    Retrieves the two mouse threshold values and the mouse speed.

    SPI_GETMOUSEKEYS

    Retrieves information about the mouse keys accessibility option. The pvParam parameter must point to a MOUSEKEYS structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(MOUSEKEYS).

    SPI_GETOEMINFO

    Returns a string containing the model number and manufacturer name. The uiParam parameter specifies the length of the buffer in pvParam, which on successful return contains the string in Unicode characters.

    The value returned by SPI_GETOEMINFO must be set exactly once and never change for the lifetime of the device.

    SPI_GETPLATFORMMANUFACTURER

    Returns a human readable, not-null text string for the platform manufacturer (OEM) name.

    The string must be at least one character in length.

    SPI_GETPLATFORMNAME

    Returns a human readable, not-null text string for the platform (product) release name (for example, "CEPC").

    The string must be at least one character in length.

    SPI_GETPLATFORMTYPE

    The uiParam parameter specifies the number of characters in the buffer in pvParam, which on successful return contains the string in Unicode characters. Applications use this string to determine the device type.

    This parameter is deprecated as of Windows Embedded Compact 2013. Use SPI_GETPROJECTNAME instead.

    Returns a string specifying the type of Windows Embedded Compact device.

    SPI_GETPLATFORMVERSION

    Retrieves the version number of an OEM OS design. The pvParam parameter must point to a PLATFORMVERSION structure that receives the information. Set uiParam to sizeof(PLATFORMVERSION).

    SPI_GETPROJECTNAME

    Returns a project description string (for example, "CEBase").

    SPI_GETSCREENSAVETIMEOUT

    Retrieves the screen saver time-out value, in seconds. The pvParam parameter must point to an integer that receives the value.

    SPI_GETSHOWSOUNDS

    Retrieves whether the show sounds option is on or off. If the option is on, the user requires an application to present information visually in situations where the application otherwise only presents the information audibly. The pvParam parameter must point to a parameter of type BOOL that receives TRUE if the feature is on or FALSE if the feature is off.

    SPI_GETSOUNDSENTRY

    Retrieves information about the accessibility option that displays a visual signal when Windows Embedded Compact generates a sound. The pvParam parameter must point to a SOUNDSENTRY structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(SOUNDSENTRY).

    SPI_GETSTICKYKEYS

    Retrieves information about the accessibility option that users use to type key combinations such as CTRL+ALT+DEL. The pvParam parameter must point to a STICKYKEYS structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(STICKYKEYS).

    SPI_GETTOGGLEKEYS

    Retrieves information about the toggle keys accessibility option. The pvParam parameter must point to a TOGGLEKEYS structure that receives the information. Set the cbSize member of this structure and the uiParam parameter to sizeof(TOGGLEKEYS).

    SPI_GETUUID

    Returns hardware-unique bytes for the platform.

    SPI_GETWAKEUPIDLETIMEOUT

    Retrieves the amount of time that Windows Embedded Compact remains on after a user notification that reactivates a suspended device. The pvParam parameter points to a DWORD that returns the time in seconds. This flag is ignored if pvParam is 0 (zero).

    If you disable GWES suspend management, then the function will return 0 (zero).

    SPI_GETWHEELSCROLLLINES

    Gets the number of lines to scroll when the mouse wheel is rotated. The pvParam parameter must point to a UINT variable that receives the number of lines. The default value is 3.

    SPI_GETWORKAREA

    Retrieves the size of the work area on the primary screen. The work area is the portion of the screen not obscured by the system task bar or by toolbars displayed on the desktop by applications. The pvParam parameter must point to a RECT structure that receives the coordinates of the work area, expressed in virtual screen coordinates.

    To get the work area of a screen other than the primary screen, call the GetMonitorInfo function.

    SPI_SETACCESSTIMEOUT

    Sets the time-out period associated with the accessibility options. The pvParam parameter must point to an ACCESSTIMEOUT structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof (ACCESSTIMEOUT).

    SPI_SETBATTERYIDLETIMEOUT

    Sets the amount of time that Windows Embedded Compact remains on with battery power before it suspends due to user inaction. The Windows Embedded Compact operating system remains on, with battery power, as long as the keyboard or touch screen is active. The uiParam parameter specifies the time to set in seconds. This flag is ignored if uiParam is set to 0 (zero).

    If you disable GWES suspend management, then attempts to set this parameter will fail, returning ERROR_RESOURCE_DISABLED.

    SPI_SETDEFAULTINFPUTLANG

    Sets the default input language for the operating system. The system's character set must support this language. The pvParam parameter must point to an HKL variable that contains the input locale identifier for the default language.

    For more information, see Locale Identifiers at MSDN.

    SPI_SETEXTERNALIDLETIMEOUT

    Sets the amount of time that Windows Embedded Compact remains on with AC power before it suspends due to user inaction. The Windows Embedded Compact operating system remains on, with AC power, as long as the keyboard or touch screen is active. The uiParam parameter specifies the time in seconds. This flag is ignored if uiParam is set to 0 (zero).

    If you disable GWES suspend management, then attempts to set this parameter will fail, returning ERROR_RESOURCE_DISABLED.

    SPI_SETFONTSMOOTHING

    Enables or disables font smoothing, which uses font antialiasing to make font curves appear smoother by painting pixels at different gray levels. Microsoft ClearType requires font smoothing.

    To enable this capability, set the uiParam parameter to TRUE. To disable it, set uiParam to FALSE.

    SPI_SETFONTSMOOTHINGCONTRAST

    Sets the contrast value that Windows Embedded Compact uses when displaying text in a ClearType font. The pvParam parameter points to a UINT that holds the contrast value. Valid contrast values are from 1000 to 2200. These values correspond to physical contrast values from 1.0 to 2.2. The default value is 1400.

    SPI_SETGESTUREMETRICS

    Sets the properties of gestures. The pvParam parameter must point to a GESTUREMETRICS structure that contains the new values. Set the cbSize member of this structure to sizeof(GESTUREMETRICS). uiParam parameter is not supported and must be set to 0 (zero).

    SPI_SETHIGHCONTRAST

    Sets the properties of the high-contrast accessibility option. The pvParam parameter must point to a HIGHCONTRAST structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(HIGHCONTRAST).

    SPI_SETMOUSE

    Sets the two mouse threshold values and the mouse speed. When you make this call, GWES performs the following tasks:

    • GWES updates a global variable with the speed setting.
    • GWES writes the speed value to HKCU\Control Panel\Mouse\MouseSpeed. (The other two values update MouseThreshold1 and MouseThreshold2.)

    When a relative mouse movement event occurs (not a MOUSEEVENTF_ABSOLUTE event), GWES accelerates large movements if the MouseSpeed setting is nonzero. The movement is a delta in the X and Y range.

    During acceleration, if the delta is larger than MouseThreshold1, it is doubled.

    During acceleration, if the delta is larger than MouseThreshold1 and MouseThreshold2, and if MouseSpeed is 2, it is doubled again.

    Depending on the size of the mouse movement and the settings of MouseThreshold1, MouseThreshold2, and MouseSpeed, the actual position delta will be unchanged, doubled, or quadrupled. This calculation is carried out independently for the X and Y coordinates.

    SPI_SETMOUSEKEYS

    Sets the properties of the mouse keys accessibility option. The pvParam parameter must point to a MOUSEKEYS structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(MOUSEKEYS).

    SPI_SETSCREENSAVETIMEOUT

    Sets the screen saver time-out value to the value of the uiParam parameter. This value is the amount of time, in seconds, that the system must remain idle before the screen saver activates.

    SPI_SETSHOWSOUNDS

    Turns the show sounds accessibility option on or off. Set the pvParam parameter to TRUE to turn the option on or to FALSE the turn the feature off.

    SPI_SETSOUNDSENTRY

    Sets the properties of the accessibility option that displays a visual signal when Windows Embedded Compact generates a sound. The pvParam parameter must point to a SOUNDSENTRY structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(SOUNDSENTRY).

    SPI_SETSTICKYKEYS

    Sets the properties of the accessibility option that users use to type key combinations such as CTRL+ALT+DEL.. The pvParam parameter must point to a STICKYKEYS structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(STICKYKEYS).

    SPI_SETTOGGLEKEYS

    Sets the properties of the toggle keys accessibility option. The pvParam parameter must point to a TOGGLEKEYS structure that contains the new parameters. Set the cbSize member of this structure and the uiParam parameter to sizeof(TOGGLEKEYS).

    SPI_SETWAKEUPIDLETIMEOUT

    Sets the amount of time that Windows Embedded Compact remains on after a user notification that reactivates the suspended device. The uiParam parameter specifies the time in seconds. This flag is ignored if uiParam is set to 0 (zero).

    If you disable GWES suspend management, then attempts to set this parameter will fail, returning ERROR_RESOURCE_DISABLED.

    SPI_SETWHEELSCROLLLINES

    Sets the number of lines to scroll when the mouse wheel is rotated. The number of lines is set from the uiParam parameter.

    The number of lines is the suggested number of lines to scroll when the mouse wheel is rolled without using modifier keys. If the number is 0 (zero), then no scrolling should occur. If the number of lines to scroll is greater than the number of lines viewable, and especially if it is WHEEL_PAGESCROLL (whose value is UINT_MAX), the scroll operation should be interpreted as clicking once in the page down or page up regions of the scroll bar.

    SPI_SETWORKAREA

    Sets the size of the work area - the portion of the screen not obscured by the system taskbar or by toolbars displayed on the desktop by applications. The pvParam parameter is a pointer to a RECT structure that specifies the new work area rectangle, expressed in virtual screen coordinates. In a system with multiple screens, the function sets the work area of the monitor that contains the specified rectangle.

    If pvParam is NULL, the function sets the work area of the primary screen to the full screen.
  • uiParam
    [in] The value of this parameter depends on which system parameter that SystemParametersInfo is querying or setting. For more information about system-wide parameters, see the uiAction parameter. If the system parameter does not indicate a required value for uiParam, you must specify 0 (zero) for this parameter.

  • pvParam
    [out] The value of this parameter depends on which system parameter that SystemParametersInfo is querying or setting. For more information about system-wide parameters, see the uiAction parameter. If the system parameter does not indicate a required value for uiParam, you must specify NULL for this parameter.

    If the pvParam buffer is used to get the platform type or OEM information string and the buffer is too small, this function fails with ERROR_INSUFFICIENT_BUFFER in the last error.

  • fWinIni
    [in] Boolean that, if a system parameter is being set, specifies whether the user profile must be updated, and if so, whether the WM_SETTINGCHANGE message is to be broadcast to all top-level windows to notify them of the change. This parameter can be 0 (zero) or it can be one of the following values.

    Value

    Description

    SPIF_UPDATEINIFILE

    Writes the new system-wide parameter setting to the user profile.

    SPIF_SENDCHANGE

    Broadcasts the WM_SETTINGCHANGE message.

Return Value

Nonzero indicates success. Zero indicates failure. This function will return 0 (zero) if you attempt to set the values SPI_SETBATTERYIDLETIMEOUT, SPI_SETEXTERNALIDLETIMEOUT, or SPI_SETWAKEUPIDLETIMEOUT when GWES suspend management is disabled.

To get extended error information, call GetLastError.

Remarks

Windows Embedded Compact supports only the Unicode version of this function.

This function is intended for use with applications, such as Control Panel, that the user uses to customize the environment.

If you have both sticky keys and high contrast enabled, the HIGHCONTRAST keyboard shortcut keys have to be pressed sequentially and not simultaneously to toggle HIGHCONTRAST on or off. The correct key sequence is to press and release the Left Alt key, then press and release the Left Shift key, and then press and release Print Screen.

The values of parameter uiActiondepend on the SYSGEN values that are set when building the run-time image. The following table shows which values are available for a given SYSGEN variable.

Sysgen

Value

SYSGEN_TOUCH or SYSGEN_CURSOR

SPI_SETMOUSE SPI_GETMOUSE

SYSGEN_TOUCHGESTURE

SPI_GETGESTUREMETRICS SPI_SETGESTUREMETRICS

SYSGEN_ACCESSIB

SPI_GETTOGGLEKEYS SPI_SETTOGGLEKEYS SPI_GETMOUSEKEYS SPI_SETMOUSEKEYS SPI_GETSTICKYKEYS SPI_SETSTICKYKEYS SPI_GETACCESSTIMEOUT SPI_SETACCESSTIMEOUT SPI_GETSOUNDSENTRY SPI_SETSOUNDSENTRY SPI_GETHIGHCONTRAST SPI_SETHIGHCONTRAST

SYSGEN_MININPUT

SPI_GETSCREENSAVETIMEOUT SPI_SETSCREENSAVETIMEOUT SPI_SETBATTERYIDLETIMEOUT SPI_GETBATTERYIDLETIMEOUT SPI_SETEXTERNALIDLETIMEOUT SPI_GETEXTERNALIDLETIMEOUT SPI_SETWAKEUPIDLETIMEOUT SPI_GETWAKEUPIDLETIMEOUT

Requirements

Header

winuser.h

Library

coredll.lib

See Also

Reference

System Information Functions
GetSystemMetrics
WM_SETTINGCHANGE
ACCESSTIMEOUT
HIGHCONTRAST
MOUSEKEYS
SIPINFO
SOUNDSENTRY
STICKYKEYS
TOGGLEKEYS

Other Resources

GetMonitorInfo