EnumDisplaySettings

The EnumDisplaySettings function obtains information about one of a display device's graphics modes. You can obtain information for all of a display device's graphics modes by making a series of calls to this function.

BOOL EnumDisplaySettings(
  LPCTSTR lpszDeviceName,  // specifies the display device
  DWORD iModeNum,          // specifies the graphics mode
  LPDEVMODE lpDevMode      // points to structure to receive settings
);
 

Parameters

lpszDeviceName

Pointer to a null-terminated string that specifies the display device whose graphics mode the function will obtain information about.

This parameter can be NULL. A NULL value specifies the current display device on the computer that the calling thread is running on.

If lpszDeviceName is not NULL, the string must be of the form \\.\DisplayX, where X can have the values 1, 2, or 3.

Windows 95 and Windows 98: lpszDeviceName must be NULL.

iModeNum

Indicates the type of information to retrieve. This value can be a graphics mode index or one of the following values.

Value	Meaning
ENUM_CURRENT_SETTINGS	Retrieve the current settings for the display device.
ENUM_REGISTRY_SETTINGS	Retrieve the settings for the display device that are currently stored in the registry.

Graphics mode indexes start at zero. To obtain information for all of a display device's graphics modes, make a series of calls to EnumDisplaySettings, as follows: Set iModeNum to zero for the first call, and increment iModeNum by one for each subsequent call. Continue calling the function until the return value is zero.

When you call EnumDisplaySettings with iModeNum set to zero, the operating system initializes and caches information about the display device. When you call EnumDisplaySettings with iModeNum set to a non-zero value, the function returns the information that was cached the last time the function was called with iModeNum set to zero.

lpDevMode

Pointer to a DEVMODE structure into which the function stores information about the specified graphics mode. Before calling EnumDisplaySettings, set the dmSize member to sizeof(DEVMODE), and set the dmDriverExtra member to indicate the size, in bytes, of the additional space available to receive private driver-data.

The EnumDisplaySettings function sets values for the following five DEVMODE members:

• dmBitsPerPel
• dmPelsWidth
• dmPelsHeight
• dmDisplayFlags
• dmDisplayFrequency

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Windows NT: To get extended error information, call GetLastError.

Remarks

The function fails if iModeNum is greater than the index of the display device's last graphics mode. As noted in the description of the iModeNum parameter, you can use this behavior to enumerate all of a display device's graphics modes.

QuickInfo

  Windows NT: Requires version 3.51 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in winuser.h.
  Import Library: Use user32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Device Contexts Overview, Device Context Functions, ChangeDisplaySettings, ChangeDisplaySettingsEx, CreateDC, CreateDesktop, DEVMODE, EnumDisplayDevices