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 매개 변수는 다음 값 중 0개 이상인 비트 OR'ed일 수도 있습니다.
[in, out] numPathArrayElements
pPathInfoArray의 요소 수를 포함하는 변수에 대한 포인터입니다. 이 매개 변수는 NULL일 수 없습니다. QueryDisplayConfig가 ERROR_SUCCESS 반환하는 경우 pNumPathInfoElements는 pPathInfoArray의 유효한 항목 수로 업데이트됩니다.
[out] pathArray
DISPLAYCONFIG_PATH_INFO 요소의 배열을 포함하는 변수에 대한 포인터입니다. pPathInfoArray의 각 요소는 원본에서 대상으로의 단일 경로를 설명합니다. 원본 및 대상 모드 정보 인덱스는 API에 대해 동시에 반환되는 pmodeInfoArray 테이블과 함께만 유효합니다. 이 매개 변수는 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이어야 합니다.
반환 값
함수는 다음 반환 코드 중 하나를 반환합니다.
| 반환 코드 | 설명 |
|---|---|
|
함수가 성공했습니다. |
|
지정된 매개 변수와 플래그의 조합이 잘못되었습니다. |
|
시스템에서 WDDM(Windows 디스플레이 드라이버 모델)에 따라 작성된 그래픽 드라이버를 실행하고 있지 않습니다. 함수는 WDDM 드라이버가 실행되는 시스템에서만 지원됩니다. |
|
호출자는 콘솔 세션에 액세스할 수 없습니다. 이 오류는 호출 프로세스에서 현재 데스크톱에 액세스할 수 없거나 원격 세션에서 실행 중인 경우에 발생합니다. |
|
지정되지 않은 오류가 발생했습니다. |
|
제공된 경로 및 모드 버퍼가 너무 작습니다. |
설명
GetDisplayConfigBufferSizes 함수는 특정 순간에만 필요한 배열 크기를 결정할 수 있으므로 GetDisplayConfigBufferSizes와 QueryDisplayConfig 호출 사이에 시스템 구성이 변경되고 제공된 배열 크기가 더 이상 새 경로 데이터를 저장하기에 충분하지 않을 수 있습니다. 이 경우 QueryDisplayConfig 는 ERROR_INSUFFICIENT_BUFFER 실패하고 호출자는 GetDisplayConfigBufferSizes 를 다시 호출하여 새 배열 크기를 가져와야 합니다. 그런 다음 호출자는 올바른 양의 메모리를 할당해야 합니다.
QueryDisplayConfig는 pPathInfoArray 매개 변수가 지정하는 경로 배열의 경로와 pModeInfoArray 매개 변수가 지정하는 모드 배열 의 원본 및 대상 모드를 반환합니다. QueryDisplayConfig 는 항상 경로 우선 순위 순서로 경로를 반환합니다. Flags 매개 변수에 QDC_ALL_PATHS 설정되면 QueryDisplayConfig는 활성 경로 다음에 모든 비활성 경로를 반환합니다.
전체 경로, 소스 모드 및 대상 모드 정보는 모든 활성 경로에 사용할 수 있습니다. 원본 및 대상에 대한 DISPLAYCONFIG_PATH_SOURCE_INFO 및 DISPLAYCONFIG_PATH_TARGET_INFO 구조체의 ModeInfoIdx 멤버가 이러한 활성 경로에 대해 설정됩니다. 비활성 경로의 경우 반환된 원본 및 대상 모드 정보를 사용할 수 없습니다. 따라서 경로 구조의 대상 정보는 기본값으로 설정되고 원본 및 대상 모드 인덱스는 잘못된 것으로 표시됩니다. 데이터베이스 쿼리의 경우 현재 연결 모니터에 항목이 있는 경우 QueryDisplayConfig 는 전체 경로, 원본 모드 및 대상 모드 정보(활성 경로의 경우와 동일)를 반환합니다. 그러나 데이터베이스에 항목이 없는 경우 QueryDisplayConfig 는 기본 대상 세부 정보가 포함된 경로 정보만 반환합니다(비활성 경로의 경우와 동일).
원본 및 대상 모드 정보가 경로 정보와 어떻게 관련되는지에 대한 예제는 경로 정보에 대한 모드 정보의 관계를 참조하세요.
호출자는 DisplayConfigGetDeviceInfo 를 사용하여 원본 또는 대상 디바이스(예: 모니터 이름 및 모니터 기본 모드 및 원본 디바이스 이름)에 대한 추가 정보를 얻을 수 있습니다.
대상이 현재 강제로 프로젝팅되는 경우 DISPLAYCONFIG_PATH_TARGET_INFO 구조체의 statusFlags 멤버에는 DISPLAYCONFIG_TARGET_FORCED_XXX 플래그 집합 중 하나가 있습니다.
flags 매개 변수 에 QDC_DATABASE_CURRENT 플래그가 설정된 경우 QueryDisplayConfig 는 pCurrentTopologyId 매개 변수가 가리키는 변수에서 활성 데이터베이스 토폴로지의 토폴로지 식별자를 반환합니다. flags 매개 변수 에 QDC_ALL_PATHS 또는 QDC_ONLY_ACTIVE_PATHS 플래그가 설정된 경우 pCurrentTopologyId 매개 변수를 NULL로 설정해야 합니다. 그렇지 않으면 QueryDisplayConfig 는 ERROR_INVALID_PARAMETER 반환합니다.
호출자가 Flags 매개 변수에 설정된 QDC_DATABASE_CURRENT 플래그를 사용하여 QueryDisplayConfig를 호출하는 경우 QueryDisplayConfig는 DISPLAYCONFIG_VIDEO_SIGNAL_INFO 구조체의 totalSize 멤버에 지정된 DISPLAYCONFIG_2DREGION 구조를 0으로 초기화하고 DISPLAYCONFIG_2DREGION 완료하지 않습니다.
EnumDisplaySettings Win32 함수(Windows SDK 설명서에 설명됨)에서 반환되는 DEVMODE 구조체에는 원본 모드와 대상 모드 모두와 관련된 정보가 포함되어 있습니다. 그러나 CCD API는 소스 및 대상 모드 구성 요소를 명시적으로 분리합니다.
헤드 탑재 및 특수 모니터
QueryDisplayConfig 및 다른 많은 Win32 디스플레이 API는 Windows 데스크톱 환경에 참여하지 않으므로 헤드 탑재 및 특수 모니터에 대한 인식이 제한적입니다. 그러나 이러한 디스플레이의 연결을 이해해야 하는 시나리오(예: 콘텐츠 보호 시나리오)가 있습니다. 이러한 제한된 시나리오의 경우 헤드 (QDC_INCLUDE_HMD | QDC_ONLY_ACTIVE_PATHS) 탑재 디스플레이의 연결을 검색하는 데 사용할 수 있습니다. 이러한 경로는 DISPLAYCONFIG_PATH_TARGET_INFO.statusFlags 필드에 DISPLAYCONFIG_TARGET_IS_HMD 플래그로 표시됩니다. 이 지원은 Windows 10 1703 크리에이터 업데이트에 추가되었습니다.
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; Windows 10 OneCoreUAP.lib |
| DLL | User32.dll |
| API 세트 | ext-ms-win-ntuser-sysparams-ext-l1-1-1(Windows 10 버전 10.0.14393에 도입됨) |
추가 정보
DISPLAYCONFIG_PATH_SOURCE_INFO