Leer en inglés

Compartir a través de


Función QueryDisplayConfig (winuser.h)

La función QueryDisplayConfig recupera información sobre todas las rutas de visualización posibles para todos los dispositivos de visualización, o vistas, en la configuración actual.

Sintaxis

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

Tipo de información que se va a recuperar. El valor del parámetro Flags debe usar uno de los valores siguientes.

Value Significado
QDC_ALL_PATHS
0x00000001
Devuelve todas las combinaciones de rutas de acceso posibles de orígenes a destinos.

Nota

En el caso de los modos temporales, el valor de QDC_ALL_PATHS significa que los datos de modo devueltos no pueden ser los mismos que los almacenados en la base de datos de persistencia.

Nota

Esta marca puede ser muy costosa de calcular. No se recomienda usar esta marca a menos que el autor de la llamada intente determinar el conjunto de conexiones válidas entre orígenes y destinos.

QDC_ONLY_ACTIVE_PATHS
0x00000002
Devuelve solo las rutas de acceso activas actualmente.

Nota

En el caso de los modos temporales, el valor de QDC_ONLY_ACTIVE_PATHS significa que los datos de modo devueltos pueden no ser los mismos que los almacenados en la base de datos de persistencia.

QDC_DATABASE_CURRENT
0x00000004
Devuelve las rutas de acceso activas definidas en la base de datos CCD para las pantallas conectadas actualmente.

El parámetro Flags también puede ser or'ed bit a bit con cero o más de los valores siguientes.

Value Significado
QDC_VIRTUAL_MODE_AWARE
0x00000010
Esta marca debe estar or'ed bit a bit con otras marcas para indicar que el autor de la llamada es consciente de la compatibilidad con el modo virtual.

Se admite a partir de Windows 10.

QDC_INCLUDE_HMD
0x00000020
Esta marca debe estar or'ed bit a bit con QDC_ONLY_ACTIVE_PATHS para indicar que el autor de la llamada desea incluir pantallas montadas en la cabeza (HMD) en la lista de rutas de acceso activas. Vea Comentarios para obtener más información.

Se admite a partir de Windows 10 1703 Creators Update.

QDC_VIRTUAL_REFRESH_RATE_AWARE
0x00000040
Esta marca debe estar or'ed bit a bit con otras marcas para indicar que el autor de la llamada es consciente de la compatibilidad con la frecuencia de actualización virtual.

Se admite a partir de Windows 11.

[in, out] numPathArrayElements

Puntero a una variable que contiene el número de elementos de pPathInfoArray. Este parámetro no puede ser NULL. Si QueryDisplayConfig devuelve ERROR_SUCCESS, pNumPathInfoElements se actualiza con el número de entradas válidas en pPathInfoArray.

[out] pathArray

Puntero a una variable que contiene una matriz de elementos DISPLAYCONFIG_PATH_INFO . Cada elemento de pPathInfoArray describe una única ruta de acceso de un origen a un destino. Los índices de información del modo de origen y destino solo son válidos en combinación con las tablas pmodeInfoArray que se devuelven para la API al mismo tiempo. Este parámetro no puede ser NULL. PPathInfoArray siempre se devuelve en orden de prioridad de ruta de acceso. Para obtener más información sobre el orden de prioridad de ruta de acceso, consulte Orden de prioridad de ruta de acceso.

[in, out] numModeInfoArrayElements

Puntero a una variable que especifica el número en el elemento de la tabla de información de modo. Este parámetro no puede ser NULL. Si QueryDisplayConfig devuelve ERROR_SUCCESS, pNumModeInfoArrayElements se actualiza con el número de entradas válidas en pModeInfoArray.

[out] modeInfoArray

Puntero a una variable que contiene una matriz de elementos DISPLAYCONFIG_MODE_INFO . Este parámetro no puede ser NULL.

[out, optional] currentTopologyId

Puntero a una variable que recibe el identificador de la topología activa actualmente en la base de datos CCD. Para obtener una lista de los valores posibles, vea el DISPLAYCONFIG_TOPOLOGY_ID tipo enumerado.

El parámetro pCurrentTopologyId solo se establece cuando el valor del parámetro Flags es QDC_DATABASE_CURRENT.

Si el valor del parámetro Flags se establece en QDC_DATABASE_CURRENT, el parámetro pCurrentTopologyId no debe ser NULL. Si el valor del parámetro Flags no se establece en QDC_DATABASE_CURRENT, el valor del parámetro pCurrentTopologyId debe ser NULL.

Valor devuelto

La función devuelve uno de los siguientes códigos de retorno.

Código devuelto Descripción
ERROR_SUCCESS
La función se ha realizado correctamente.
ERROR_INVALID_PARAMETER
La combinación de parámetros y marcas que se especifican no es válida.
ERROR_NOT_SUPPORTED
El sistema no ejecuta un controlador de gráficos escrito según el modelo de controlador de pantalla de Windows (WDDM). La función solo se admite en un sistema con un controlador WDDM en ejecución.
ERROR_ACCESS_DENIED
El llamador no tiene acceso a la sesión de consola. Este error se produce si el proceso de llamada no tiene acceso al escritorio actual o se ejecuta en una sesión remota.
ERROR_GEN_FAILURE
Se ha producido un error no especificado.
ERROR_INSUFFICIENT_BUFFER
La ruta de acceso y el búfer de modo proporcionados son demasiado pequeños.

Comentarios

Como la función GetDisplayConfigBufferSizes solo puede determinar el tamaño de matriz necesario en un momento determinado en el tiempo, es posible que, entre las llamadas a GetDisplayConfigBufferSizes y QueryDisplayConfig , la configuración del sistema cambiará y los tamaños de matriz proporcionados ya no serán suficientes para almacenar los nuevos datos de ruta de acceso. En esta situación, QueryDisplayConfig produce un error ERROR_INSUFFICIENT_BUFFER y el autor de la llamada debe llamar a GetDisplayConfigBufferSizes de nuevo para obtener los nuevos tamaños de matriz. A continuación, el autor de la llamada debe asignar la cantidad correcta de memoria.

QueryDisplayConfig devuelve rutas de acceso en la matriz de rutas de acceso que el parámetro pPathInfoArray especifica y los modos de origen y destino de la matriz de modo que especifica el parámetro pModeInfoArray . QueryDisplayConfig siempre devuelve rutas de acceso en orden de prioridad de ruta de acceso. Si QDC_ALL_PATHS se establece en el parámetro Flags, QueryDisplayConfig devuelve todas las rutas de acceso inactivas después de las rutas de acceso activas.

La información completa sobre la ruta de acceso, el modo de origen y el modo de destino está disponible para todas las rutas de acceso activas. Los miembros ModeInfoIdx de las estructuras de DISPLAYCONFIG_PATH_SOURCE_INFO y DISPLAYCONFIG_PATH_TARGET_INFO para el origen y el destino están configurados para estas rutas de acceso activas. Para las rutas de acceso inactivas, la información de modo de origen y destino devuelta no está disponible; por lo tanto, la información de destino de la estructura de ruta de acceso se establece en valores predeterminados y los índices de modo de origen y destino se marcan como no válidos. En el caso de las consultas de base de datos, si los monitores de conexión actuales tienen una entrada, QueryDisplayConfig devuelve la ruta de acceso completa, el modo de origen y la información del modo de destino (igual que para las rutas de acceso activas). Sin embargo, si la base de datos no tiene una entrada, QueryDisplayConfig devuelve solo la información de ruta de acceso con los detalles de destino predeterminados (igual que para las rutas de acceso inactivas).

Para obtener un ejemplo de cómo se relaciona la información del modo de origen y destino con la información de ruta de acceso, vea Relación de información de modo con información de ruta de acceso.

El autor de la llamada puede usar DisplayConfigGetDeviceInfo para obtener información adicional sobre el dispositivo de origen o de destino, por ejemplo, los nombres de monitor y el modo preferido y el nombre del dispositivo de origen.

Si actualmente se fuerza un destino, el miembro statusFlags de la estructura de DISPLAYCONFIG_PATH_TARGET_INFO tiene una de las marcas de DISPLAYCONFIG_TARGET_FORCED_XXX establecidas.

Si la marca QDC_DATABASE_CURRENT se establece en el parámetro Flags , QueryDisplayConfig devuelve el identificador de topología de la topología de base de datos activa en la variable a la que apunta el parámetro pCurrentTopologyId . Si la marca QDC_ALL_PATHS o QDC_ONLY_ACTIVE_PATHS se establece en el parámetro Flags , el parámetro pCurrentTopologyId debe establecerse en NULL; De lo contrario, QueryDisplayConfig devuelve ERROR_INVALID_PARAMETER.

Si un llamador llama a QueryDisplayConfig con la marca QDC_DATABASE_CURRENT establecida en el parámetro Flags , QueryDisplayConfig inicializa la estructura DISPLAYCONFIG_2DREGION especificada en el miembro totalSize de la estructura DISPLAYCONFIG_VIDEO_SIGNAL_INFO en ceros y no completa DISPLAYCONFIG_2DREGION.

La estructura DEVMODE que devuelve la función Win32 EnumDisplaySettings (descrita en la documentación de Windows SDK) contiene información relacionada con los modos de origen y destino. Sin embargo, las API de CCD separan explícitamente los componentes del modo de origen y de destino.

Monitores montados en cabeza y especializados

QueryDisplayConfig y muchas otras API de visualización de Win32 tienen un conocimiento limitado de los monitores especializados y montados en la cabeza, ya que esas pantallas no participan en el entorno de escritorio de Windows. Sin embargo, hay escenarios en los que es necesario comprender la conectividad de estas pantallas (por ejemplo, escenarios de protección de contenido). En estos escenarios limitados, (QDC_INCLUDE_HMD | QDC_ONLY_ACTIVE_PATHS) se puede usar para detectar la conectividad de las pantallas montadas en la cabeza. Estas rutas de acceso se marcarán con la marca DISPLAYCONFIG_TARGET_IS_HMD en el campo DISPLAYCONFIG_PATH_TARGET_INFO.statusFlags . Esta compatibilidad se agregó en Windows 10 1703 Creators Update.

Virtualización de PPP

Esta API no participa en la virtualización de PPP. Todos los tamaños de la estructura DEVMODE se encuentran en términos de píxeles físicos y no están relacionados con el contexto de llamada.

Ejemplos

En el ejemplo siguiente se enumeran las rutas de visualización activas con QueryDisplayConfig y GetDisplayConfigBufferSizes y se imprimen los datos de cada ruta de acceso mediante 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

   
Cliente mínimo compatible Disponible en Windows 7 y versiones posteriores de los sistemas operativos Windows.
Plataforma de destino Universal
Encabezado winuser.h (incluir Windows.h)
Library User32.lib; OneCoreUAP.lib en Windows 10
Archivo DLL User32.dll
Conjunto de API ext-ms-win-ntuser-sysparams-ext-l1-1-1 (introducido en Windows 10, versión 10.0.14393)

Consulte también

DISPLAYCONFIG_MODE_INFO

DISPLAYCONFIG_PATH_INFO

DISPLAYCONFIG_PATH_SOURCE_INFO

DISPLAYCONFIG_PATH_TARGET_INFO

DISPLAYCONFIG_TOPOLOGY_ID

DisplayConfigGetDeviceInfo

SetDisplayConfig