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
);

Parâmetros

[in] flags

O tipo de informações a serem recuperadas. 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 pPathInfoArray. Esse parâmetro não pode ser NULL. Se QueryDisplayConfig retornar ERROR_SUCCESS, pNumPathInfoElements será atualizado com o número de entradas válidas em pPathInfoArray.

[out] pathArray

Ponteiro para uma variável que contém uma matriz de elementos DISPLAYCONFIG_PATH_INFO . Cada elemento em pPathInfoArray 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 pmodeInfoArray retornadas para a API ao mesmo tempo. Esse parâmetro não pode ser NULL. O pPathInfoArray sempre é retornado na ordem de prioridade do caminho. Para obter mais informações sobre a ordem de prioridade do caminho, consulte 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, pNumModeInfoArrayElements será atualizado com o número de entradas válidas em pModeInfoArray.

[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 pCurrentTopologyId 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 pCurrentTopologyId 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 pCurrentTopologyId deverá ser NULL.

Valor retornado

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

Comentários

Como a função GetDisplayConfigBufferSizes só pode determinar o tamanho necessário da matriz 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 sejam 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 que o parâmetro pPathInfoArray especifica e os modos de origem e destino na matriz de modo especificada pelo parâmetro pModeInfoArray . QueryDisplayConfig sempre retorna caminhos na ordem de prioridade do caminho. Se QDC_ALL_PATHS estiver definido no parâmetro Flags , QueryDisplayConfig retornará todos os caminhos inativos após os caminhos ativos.

As informações de caminho completo, modo de origem e 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 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 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 de caminho completo, 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 do 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 com força, o membro statusFlags da estrutura DISPLAYCONFIG_PATH_TARGET_INFO terá um dos sinalizadores de 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 para a qual o parâmetro pCurrentTopologyId aponta. Se o sinalizador QDC_ALL_PATHS ou QDC_ONLY_ACTIVE_PATHS estiver definido no parâmetro Flags , o parâmetro pCurrentTopologyId 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 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 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 montados na cabeça e especializados, já que essas telas não participam do ambiente de área de trabalho do 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 com a 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";
    }
}

Requisitos

Confira também

DISPLAYCONFIG_MODE_INFO

DISPLAYCONFIG_PATH_INFO

DISPLAYCONFIG_PATH_SOURCE_INFO

DISPLAYCONFIG_PATH_TARGET_INFO

DISPLAYCONFIG_TOPOLOGY_ID

DisplayConfigGetDeviceInfo

SetDisplayConfig