Função EnumDisplaySettingsA (winuser.h)

Artigo
08/27/2023

A função EnumDisplaySettings recupera informações sobre um dos modos gráficos de um dispositivo de exibição. Para recuperar informações para todos os modos gráficos de um dispositivo de exibição, faça uma série de chamadas para essa função.

Nota Os aplicativos que você projeta para o Windows 8 e posterior não podem mais consultar ou definir modos de exibição com menos de 32 bits por pixel (bpp); essas operações falharão. Esses aplicativos têm um manifesto de compatibilidade direcionado ao Windows 8. O Windows 8 ainda dá suporte a modos de cores de 8 e 16 bits para aplicativos da área de trabalho que foram criados sem um manifesto do Windows 8; O Windows 8 emula esses modos, mas ainda é executado no modo de cor de 32 bits.

Sintaxe

BOOL EnumDisplaySettingsA(
  [in]  LPCSTR   lpszDeviceName,
  [in]  DWORD    iModeNum,
  [out] DEVMODEA *lpDevMode
);

Parâmetros

[in] lpszDeviceName

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o dispositivo de exibição sobre qual modo gráfico a função obterá informações.

Esse parâmetro é NULL ou um DISPLAY_DEVICE. DeviceName retornado de EnumDisplayDevices. Um valor NULL especifica o dispositivo de exibição atual no computador no qual o thread de chamada está em execução.

[in] iModeNum

O tipo de informação a ser recuperada. Esse valor pode ser um índice de modo gráfico ou um dos valores a seguir.

Valor	Significado
ENUM_CURRENT_SETTINGS	Recupere as configurações atuais do dispositivo de exibição.
ENUM_REGISTRY_SETTINGS	Recupere as configurações do dispositivo de exibição que estão atualmente armazenados no registro.

Os índices do modo gráfico começam em zero. Para obter informações para todos os modos gráficos de um dispositivo de exibição, faça uma série de chamadas para EnumDisplaySettings, da seguinte maneira: Defina iModeNum como zero para a primeira chamada e incremente iModeNum em um para cada chamada subsequente. Continue chamando a função até que o valor retornado seja zero.

Quando você chama EnumDisplaySettings com iModeNum definido como zero, o sistema operacional inicializa e armazena em cache informações sobre o dispositivo de exibição. Quando você chama EnumDisplaySettings com iModeNum definido como um valor diferente de zero, a função retorna as informações que foram armazenadas em cache na última vez que a função foi chamada com iModeNum definido como zero.

[out] lpDevMode

Um ponteiro para uma estrutura DEVMODE na qual a função armazena informações sobre o modo gráfico especificado. Antes de chamar EnumDisplaySettings, defina o membro sizeof(DEVMODE)dmSize como e defina o membro dmDriverExtra para indicar o tamanho, em bytes, do espaço adicional disponível para receber dados de driver privados.

A função EnumDisplaySettings define valores para os cinco membros DEVMODE a seguir:

dmBitsPerPel
dmPelsWidth
dmPelsHeight
dmDisplayFlags
dmDisplayFrequency

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero.

Comentários

A função falhará se iModeNum for maior que o índice do último modo gráfico do dispositivo de exibição. Conforme observado na descrição do parâmetro iModeNum , você pode usar esse comportamento para enumerar todos os modos gráficos de um dispositivo de exibição.

Virtualização de DPI

Essa API não participa da virtualização de DPI. A saída fornecida é sempre em termos de pixels físicos e não está relacionada ao contexto de chamada.

Observação

O cabeçalho winuser.h define EnumDisplaySettings como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll
Conjunto de APIs	ext-ms-win-ntuser-sysparams-ext-l1-1-0 (introduzido no Windows 8)