Função QueryDisplayConfig (winuser.h)

A função QueryDisplayConfig recupera informações sobre todos os caminhos de exibição possíveis para todos os dispositivos de exibição ou exibições, na configuração atual.

Sintaxe

LONG QueryDisplayConfig(
  [in]            UINT32                    flags,
  [in, out]       UINT32                    *numPathArrayElements,
  [out]           DISPLAYCONFIG_PATH_INFO   *pathArray,
  [in, out]       UINT32                    *numModeInfoArrayElements,
  [out]           DISPLAYCONFIG_MODE_INFO   *modeInfoArray,
  [out, optional] DISPLAYCONFIG_TOPOLOGY_ID *currentTopologyId
);

Parameters

[in] flags

O tipo de informação a ser recuperada. O valor do parâmetro flags deve usar um dos valores a seguir.

O parâmetro flags também pode ser or'ed bit a bit com zero ou mais dos valores a seguir.

[in, out] numPathArrayElements

Ponteiro para uma variável que contém o número de elementos em pathArray. Esse parâmetro não pode ser NULL. Se QueryDisplayConfig retornar ERROR_SUCCESS, numPathArrayElements será atualizado com o número de entradas válidas no pathArray.

[out] pathArray

Ponteiro para uma variável que contém uma matriz de elementos DISPLAYCONFIG_PATH_INFO . Cada elemento em pathArray descreve um único caminho de uma origem para um destino. Os índices de informações do modo de origem e de destino só são válidos em combinação com as tabelas modeInfoArray retornadas para a API ao mesmo tempo. Esse parâmetro não pode ser NULL. O pathArray sempre é retornado na ordem de prioridade do caminho. Para obter mais informações sobre a ordem de prioridade do caminho, consulte a Ordem de Prioridade do Caminho.

[in, out] numModeInfoArrayElements

Ponteiro para uma variável que especifica o número no elemento da tabela de informações do modo. Esse parâmetro não pode ser NULL. Se QueryDisplayConfig retornar ERROR_SUCCESS, numModeInfoArrayElements será atualizado com o número de entradas válidas no modeInfoArray.

[out] modeInfoArray

Ponteiro para uma variável que contém uma matriz de elementos DISPLAYCONFIG_MODE_INFO . Esse parâmetro não pode ser NULL.

[out, optional] currentTopologyId

Ponteiro para uma variável que recebe o identificador da topologia atualmente ativa no banco de dados CCD. Para obter uma lista de valores possíveis, consulte o tipo enumerado DISPLAYCONFIG_TOPOLOGY_ID .

O parâmetro currentTopologyId só é definido quando o valor do parâmetro flags é QDC_DATABASE_CURRENT.

Se o valor do parâmetro flags for definido como QDC_DATABASE_CURRENT, o parâmetro currentTopologyId não deverá ser NULL. Se o valor do parâmetro flags não estiver definido como QDC_DATABASE_CURRENT, o valor do parâmetro currentTopologyId deverá ser NULL.

Valor de devolução

A função retorna um dos seguintes códigos de retorno.

Observações

Como a função GetDisplayConfigBufferSizes só pode determinar o tamanho da matriz necessária em um momento específico, é possível que entre chamadas para GetDisplayConfigBufferSizes e QueryDisplayConfig a configuração do sistema seja alterada e os tamanhos de matriz fornecidos não serão mais suficientes para armazenar os novos dados de caminho. Nessa situação, QueryDisplayConfig falha com ERROR_INSUFFICIENT_BUFFER e o chamador deve chamar GetDisplayConfigBufferSizes novamente para obter os novos tamanhos de matriz. Em seguida, o chamador deve alocar a quantidade correta de memória.

QueryDisplayConfig retorna caminhos na matriz de caminho especificada pelo parâmetro pathArray e os modos de origem e destino na matriz de modo especificada pelo parâmetro modeInfoArray . QueryDisplayConfig sempre retorna caminhos na ordem de prioridade do caminho. Se QDC_ALL_PATHS for definido no parâmetro flags , QueryDisplayConfig retornará todos os caminhos inativos após os caminhos ativos.

O caminho completo, o modo de origem e as informações do modo de destino estão disponíveis para todos os caminhos ativos. Os membros ModeInfoIdx no DISPLAYCONFIG_PATH_SOURCE_INFO e DISPLAYCONFIG_PATH_TARGET_INFO estruturas para a origem e o destino são configurados para esses caminhos ativos. Para caminhos inativos, as informações retornadas do modo de origem e de destino não estão disponíveis; portanto, as informações de destino na estrutura de caminho são definidas como valores padrão e os índices de modo de origem e de destino são marcados como inválidos. Para consultas de banco de dados, se os monitores de conexão atuais tiverem uma entrada, QueryDisplayConfig retornará informações completas de caminho, modo de origem e modo de destino (o mesmo que para caminhos ativos). No entanto, se o banco de dados não tiver uma entrada, QueryDisplayConfig retornará apenas as informações de caminho com os detalhes de destino padrão (o mesmo que para caminhos inativos).

Para obter um exemplo de como as informações de modo de origem e de destino se relacionam com informações de caminho, consulte Informações de relação do modo com informações de caminho.

O chamador pode usar DisplayConfigGetDeviceInfo para obter informações adicionais sobre o dispositivo de origem ou de destino, por exemplo, os nomes do monitor e monitorar o modo preferencial e o nome do dispositivo de origem.

Se um destino estiver sendo projetado, o membro statusFlags da estrutura DISPLAYCONFIG_PATH_TARGET_INFO terá um dos sinalizadores DISPLAYCONFIG_TARGET_FORCED_XXX definidos.

Se o sinalizador QDC_DATABASE_CURRENT estiver definido no parâmetro Flags , QueryDisplayConfig retornará o identificador de topologia da topologia de banco de dados ativa na variável à qual o parâmetro currentTopologyId aponta. Se o sinalizador QDC_ALL_PATHS ou QDC_ONLY_ACTIVE_PATHS estiver definido no parâmetro Flags , o parâmetro currentTopologyId deverá ser definido como NULL; caso contrário, QueryDisplayConfig retornará ERROR_INVALID_PARAMETER.

Se um chamador chamar QueryDisplayConfig com o sinalizador QDC_DATABASE_CURRENT definido no parâmetro flags , QueryDisplayConfig inicializará a estrutura de DISPLAYCONFIG_2DREGION especificada no membro totalSize da estrutura DISPLAYCONFIG_VIDEO_SIGNAL_INFO como zeros e não concluirá DISPLAYCONFIG_2DREGION.

A estrutura DEVMODE retornada pela função EnumDisplaySettings Win32 (descrita na documentação do SDK do Windows) contém informações relacionadas aos modos de origem e de destino. No entanto, as APIs CCD separam explicitamente os componentes do modo de origem e de destino.

Monitores especializados e montados na cabeça

QueryDisplayConfig e muitas outras APIs de exibição do Win32 têm reconhecimento limitado de monitores especializados e montados na cabeça, já que essas exibições não participam do ambiente de área de trabalho Windows. No entanto, há cenários em que é necessário entender a conectividade dessas exibições (por exemplo, cenários de proteção de conteúdo). Para esses cenários limitados, (QDC_INCLUDE_HMD | QDC_ONLY_ACTIVE_PATHS) pode ser usado para descobrir a conectividade de telas montadas na cabeça. Esses caminhos serão marcados com o sinalizador DISPLAYCONFIG_TARGET_IS_HMD no campo DISPLAYCONFIG_PATH_TARGET_INFO.statusFlags . Esse suporte foi adicionado na Atualização de Criadores do Windows 10 1703.

Virtualização de DPI

Essa API não participa da virtualização de DPI. Todos os tamanhos na estrutura DEVMODE estão em termos de pixels físicos e não estão relacionados ao contexto de chamada.

Exemplos

O exemplo a seguir enumera caminhos de exibição ativos com QueryDisplayConfig e GetDisplayConfigBufferSizes e imprime dados para cada caminho usando DisplayConfigGetDeviceInfo.

#include <windows.h>
#include <vector>
#include <iostream>
#include <string>

using namespace std;

int main()
{
    vector<DISPLAYCONFIG_PATH_INFO> paths;
    vector<DISPLAYCONFIG_MODE_INFO> modes;
    UINT32 flags = QDC_ONLY_ACTIVE_PATHS | QDC_VIRTUAL_MODE_AWARE;
    LONG result = ERROR_SUCCESS;

    do
    {
        // Determine how many path and mode structures to allocate
        UINT32 pathCount, modeCount;
        result = GetDisplayConfigBufferSizes(flags, &pathCount, &modeCount);

        if (result != ERROR_SUCCESS)
        {
            return HRESULT_FROM_WIN32(result);
        }

        // Allocate the path and mode arrays
        paths.resize(pathCount);
        modes.resize(modeCount);

        // Get all active paths and their modes
        result = QueryDisplayConfig(flags, &pathCount, paths.data(), &modeCount, modes.data(), nullptr);

        // The function may have returned fewer paths/modes than estimated
        paths.resize(pathCount);
        modes.resize(modeCount);

        // It's possible that between the call to GetDisplayConfigBufferSizes and QueryDisplayConfig
        // that the display state changed, so loop on the case of ERROR_INSUFFICIENT_BUFFER.
    } while (result == ERROR_INSUFFICIENT_BUFFER);

    if (result != ERROR_SUCCESS)
    {
        return HRESULT_FROM_WIN32(result);
    }

    // For each active path
    for (auto& path : paths)
    {
        // Find the target (monitor) friendly name
        DISPLAYCONFIG_TARGET_DEVICE_NAME targetName = {};
        targetName.header.adapterId = path.targetInfo.adapterId;
        targetName.header.id = path.targetInfo.id;
        targetName.header.type = DISPLAYCONFIG_DEVICE_INFO_GET_TARGET_NAME;
        targetName.header.size = sizeof(targetName);
        result = DisplayConfigGetDeviceInfo(&targetName.header);

        if (result != ERROR_SUCCESS)
        {
            return HRESULT_FROM_WIN32(result);
        }

        // Find the adapter device name
        DISPLAYCONFIG_ADAPTER_NAME adapterName = {};
        adapterName.header.adapterId = path.targetInfo.adapterId;
        adapterName.header.type = DISPLAYCONFIG_DEVICE_INFO_GET_ADAPTER_NAME;
        adapterName.header.size = sizeof(adapterName);

        result = DisplayConfigGetDeviceInfo(&adapterName.header);

        if (result != ERROR_SUCCESS)
        {
            return HRESULT_FROM_WIN32(result);
        }

        wcout
            << L"Monitor with name "
            << (targetName.flags.friendlyNameFromEdid ? targetName.monitorFriendlyDeviceName : L"Unknown")
            << L" is connected to adapter "
            << adapterName.adapterDevicePath
            << L" on target "
            << path.targetInfo.id
            << L"\n";
    }
}

Requirements

Consulte também

DISPLAYCONFIG_MODE_INFO

DISPLAYCONFIG_PATH_INFO

DISPLAYCONFIG_PATH_SOURCE_INFO

DISPLAYCONFIG_PATH_TARGET_INFO

DISPLAYCONFIG_TOPOLOGY_ID

DisplayConfigGetDeviceInfo

SetDisplayConfig