Функция 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 должно использовать одно из следующих значений.
Параметр Flags также может иметь побитовое значение OR с нулевым или более из следующих значений.
[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.
Возвращаемое значение
Функция возвращает один из следующих кодов возврата.
| Код возврата | Описание |
|---|---|
|
Функция выполнена успешно. |
|
Недопустимое сочетание указанных параметров и флагов. |
|
В системе не работает графический драйвер, написанный в соответствии с моделью windows Display Driver Model (WDDM). Функция поддерживается только в системе с работающим драйвером WDDM. |
|
Вызывающий объект не имеет доступа к сеансу консоли. Эта ошибка возникает, если вызывающий процесс не имеет доступа к текущему рабочему столу или выполняется в удаленном сеансе. |
|
Произошла неизвестная ошибка. |
|
Указанный путь и буфер режима слишком малы. |
Комментарии
Так как функция 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_PATH_SOURCE_INFO