Поделиться через


Функция QueryDisplayConfig (winuser.h)

Функция QueryDisplayConfig извлекает сведения обо всех возможных путях отображения для всех устройств отображения или представлений в текущем параметре.

Синтаксис

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

Параметры

[in] flags

Тип извлекаемой информации. Значение параметра Flags должно использовать одно из следующих значений.

Значение Значение
QDC_ALL_PATHS
0x00000001
Возвращает все возможные сочетания путей из источников в целевые объекты.

Примечание

В случае любых временных режимов параметр QDC_ALL_PATHS означает, что возвращаемые данные режима могут отличаться от данных, хранящихся в базе данных сохраняемости.

Примечание

Вычисление этого флага может быть очень дорогостоящим. Не рекомендуется использовать этот флаг, если вызывающий объект не пытается определить набор допустимых соединений между источниками и целевыми объектами.

QDC_ONLY_ACTIVE_PATHS
0x00000002
Возвращает только текущие активные пути.

Примечание

В случае любых временных режимов параметр QDC_ONLY_ACTIVE_PATHS означает, что возвращаемые данные режима могут отличаться от данных, хранящихся в базе данных сохраняемости.

QDC_DATABASE_CURRENT
0x00000004
Возвращает активные пути, определенные в базе данных CCD для подключенных в данный момент дисплеев.

Параметр Flags также может иметь побитовое значение OR с нулевым или более из следующих значений.

Значение Значение
QDC_VIRTUAL_MODE_AWARE
0x00000010
Этот флаг должен быть побитовый ИЛИ с другими флагами, чтобы указать, что вызывающий объект знает о поддержке виртуального режима.

Поддерживается начиная с Windows 10.

QDC_INCLUDE_HMD
0x00000020
Этот флаг должен быть побитовый ИЛИ с QDC_ONLY_ACTIVE_PATHS, чтобы указать, что вызывающий объект хотел бы включить подключенные к голове дисплеи (HMD) в список активных путей. Дополнительные сведения см. в разделе "Примечания".

Поддерживается начиная с Windows 10 1703 Creators Update.

QDC_VIRTUAL_REFRESH_RATE_AWARE
0x00000040
Этот флаг должен быть побитовой or'ed с другими флагами, чтобы указать, что вызывающему объекту известно о поддержке виртуальной частоты обновления.

Поддерживается начиная с Windows 11.

[in, out] numPathArrayElements

Указатель на переменную, содержащую количество элементов в pPathInfoArray. Этот параметр не может иметь значение NULL. Если QueryDisplayConfig возвращает ERROR_SUCCESS, pNumPathInfoElements обновляется количеством допустимых записей в pPathInfoArray.

[out] pathArray

Указатель на переменную, содержащую массив элементов DISPLAYCONFIG_PATH_INFO . Каждый элемент pPathInfoArray описывает один путь от источника к целевому объекту. Индексы данных исходного и целевого режимов допустимы только в сочетании с таблицами pmodeInfoArray , которые возвращаются для API одновременно. Этот параметр не может иметь значение NULL. PPathInfoArray всегда возвращается в порядке приоритета пути. Дополнительные сведения о порядке приоритета пути см. в разделе Порядок приоритета пути.

[in, out] numModeInfoArrayElements

Указатель на переменную, указывающую число в элементе таблицы сведений о режиме. Этот параметр не может иметь значение NULL. Если QueryDisplayConfig возвращает ERROR_SUCCESS, pNumModeInfoArrayElements обновляется количеством допустимых записей в pModeInfoArray.

[out] modeInfoArray

Указатель на переменную, содержащую массив элементов DISPLAYCONFIG_MODE_INFO . Этот параметр не может иметь значение NULL.

[out, optional] currentTopologyId

Указатель на переменную, которая получает идентификатор активной в настоящее время топологии в базе данных CCD. Список возможных значений см . в DISPLAYCONFIG_TOPOLOGY_ID перечислимом типе.

Параметр pCurrentTopologyId задается, только если значение параметра Flags равно QDC_DATABASE_CURRENT.

Если для параметра Flags задано значение QDC_DATABASE_CURRENT, параметр pCurrentTopologyId не должен иметь значение NULL. Если для параметра Flags не задано значение QDC_DATABASE_CURRENT, значение параметра pCurrentTopologyId должно иметь значение NULL.

Возвращаемое значение

Функция возвращает один из следующих кодов возврата.

Код возврата Описание
ERROR_SUCCESS
Функция выполнена успешно.
ERROR_INVALID_PARAMETER
Недопустимое сочетание указанных параметров и флагов.
ERROR_NOT_SUPPORTED
В системе не работает графический драйвер, написанный в соответствии с моделью windows Display Driver Model (WDDM). Функция поддерживается только в системе с работающим драйвером WDDM.
ERROR_ACCESS_DENIED
Вызывающий объект не имеет доступа к сеансу консоли. Эта ошибка возникает, если вызывающий процесс не имеет доступа к текущему рабочему столу или выполняется в удаленном сеансе.
ERROR_GEN_FAILURE
Произошла неизвестная ошибка.
ERROR_INSUFFICIENT_BUFFER
Указанный путь и буфер режима слишком малы.

Комментарии

Так как функция GetDisplayConfigBufferSizes может определить только требуемый размер массива в определенный момент времени, возможно, что между вызовами GetDisplayConfigBufferSizes и QueryDisplayConfig конфигурация системы изменится и предоставленных размеров массива больше не будет достаточно для хранения новых данных пути. В этом случае QueryDisplayConfig завершается сбоем с ERROR_INSUFFICIENT_BUFFER, и вызывающий объект должен снова вызвать GetDisplayConfigBufferSizes , чтобы получить новые размеры массива. Затем вызывающий объект должен выделить правильный объем памяти.

QueryDisplayConfig возвращает пути в массиве путей, который указывает параметр pPathInfoArray , а также исходный и целевой режимы в массиве режимов, который указывает параметр pModeInfoArray . QueryDisplayConfig всегда возвращает пути в порядке приоритета пути. Если QDC_ALL_PATHS задано в параметре Flags , QueryDisplayConfig возвращает все неактивные пути после активных путей.

Полный путь, исходный и целевой режимы доступны для всех активных путей. Для этих активных путей настраиваются элементы ModeInfoIdx в DISPLAYCONFIG_PATH_SOURCE_INFO и DISPLAYCONFIG_PATH_TARGET_INFO структуры для источника и целевого объекта. Для неактивных путей возвращаемые сведения об исходном и целевом режимах недоступны; Поэтому для целевой информации в структуре пути заданы значения по умолчанию, а индексы исходного и целевого режима помечаются как недопустимые. Для запросов к базе данных, если текущие мониторы подключения имеют запись, QueryDisplayConfig возвращает полный путь, исходный режим и сведения о целевом режиме (так же, как для активных путей). Однако если в базе данных нет записи, QueryDisplayConfig возвращает только сведения о пути с сведениями о целевом объекте по умолчанию (так же, как для неактивных путей).

Пример того, как сведения об исходном и целевом режимах связаны с сведениями о пути, см. в разделе Связь сведений о режиме с данными о пути.

Вызывающий объект может использовать DisplayConfigGetDeviceInfo для получения дополнительных сведений об исходном или целевом устройстве, например имен монитора, предпочтительного режима монитора и имени исходного устройства.

Если целевой объект в настоящее время проецируется принудительно, член statusFlags структуры DISPLAYCONFIG_PATH_TARGET_INFO имеет один из DISPLAYCONFIG_TARGET_FORCED_XXX флагов.

Если флаг QDC_DATABASE_CURRENT задан в параметре Flags , QueryDisplayConfig возвращает идентификатор топологии активной топологии базы данных в переменной, на которую указывает параметр pCurrentTopologyId . Если флаг QDC_ALL_PATHS или QDC_ONLY_ACTIVE_PATHS задан в параметре Flags , параметру pCurrentTopologyId необходимо задать значение NULL; В противном случае QueryDisplayConfig возвращает ERROR_INVALID_PARAMETER.

Если вызывающий объект вызывает QueryDisplayConfig с флагом QDC_DATABASE_CURRENT, заданным в параметре Flags , QueryDisplayConfig инициализирует структуру DISPLAYCONFIG_2DREGION , указанную в элементе totalSize структуры DISPLAYCONFIG_VIDEO_SIGNAL_INFO , нулями и не завершает DISPLAYCONFIG_2DREGION.

Структура DEVMODE, возвращаемая функцией Win32 EnumDisplaySettings (описанная в документации windows SDK), содержит сведения, относящиеся как к исходному, так и к целевому режимам. Однако API CCD явно разделяют компоненты исходного и целевого режимов.

Головные и специализированные мониторы

QueryDisplayConfig и многие другие API-интерфейсы отображения Win32 имеют ограниченную осведомленность о подключенных к голове и специализированных мониторах, так как эти дисплеи не участвуют в среде рабочего стола Windows. Однако существуют сценарии, в которых необходимо понимать возможность подключения этих дисплеев (например, сценарии защиты содержимого). В этих ограниченных сценариях можно использовать для обнаружения подключения к мониторам, (QDC_INCLUDE_HMD | QDC_ONLY_ACTIVE_PATHS) подключенным к голове. Эти пути будут помечены флагом DISPLAYCONFIG_TARGET_IS_HMD в поле DISPLAYCONFIG_PATH_TARGET_INFO.statusFlags . Эта поддержка была добавлена в Windows 10 1703 Creators Update.

Виртуализация DPI

Этот API не участвует в виртуализации DPI. Все размеры в структуре DEVMODE имеют физические пиксели и не связаны с контекстом вызова.

Примеры

В следующем примере перечисляются активные пути отображения с помощью QueryDisplayConfig и GetDisplayConfigBufferSizes и выводится данные для каждого пути с помощью 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";
    }
}

Требования

   
Минимальная версия клиента Доступно в Windows 7 и более поздних версиях операционных систем Windows.
Целевая платформа Универсальное
Верхняя часть winuser.h (включая Windows.h)
Библиотека User32.lib; OneCoreUAP.lib в Windows 10
DLL User32.dll
Набор API ext-ms-win-ntuser-sysparams-ext-l1-1-1 (представлено в Windows 10, версия 10.0.14393)

См. также раздел

DISPLAYCONFIG_MODE_INFO

DISPLAYCONFIG_PATH_INFO

DISPLAYCONFIG_PATH_SOURCE_INFO

DISPLAYCONFIG_PATH_TARGET_INFO

DISPLAYCONFIG_TOPOLOGY_ID

DisplayConfigGetDeviceInfo

SetDisplayConfig