ホーム › Devices.Display › QueryDisplayConfig

QueryDisplayConfig

関数

ディスプレイのパスとモードの現在構成を取得する。

DLLUSER32.dll呼出規約winapi対応OSWindows 7 以降

シグネチャ

// USER32.dll
#include <windows.h>

WIN32_ERROR QueryDisplayConfig(
    QUERY_DISPLAY_CONFIG_FLAGS flags,
    DWORD* numPathArrayElements,
    DISPLAYCONFIG_PATH_INFO* pathArray,
    DWORD* numModeInfoArrayElements,
    DISPLAYCONFIG_MODE_INFO* modeInfoArray,
    DISPLAYCONFIG_TOPOLOGY_ID* currentTopologyId   // optional
);

パラメーター

名前

型

方向

説明

flags

QUERY_DISPLAY_CONFIG_FLAGS

取得する情報の種類です。flags パラメーターの値には、次のいずれかの値を指定する必要があります。

値	意味
QDC_ALL_PATHS 0x00000001	ソースからターゲットへの、考えられるすべてのパスの組み合わせを返します。メモ一時的なモードが存在する場合、QDC_ALL_PATHS 設定で返されるモードデータは、永続化データベースに格納されているものと一致しないことがあります。メモこのフラグの計算は非常にコストが高い場合があります。ソースとターゲットの間の有効な接続の組を特定しようとする場合を除き、このフラグの使用は推奨されません。
QDC_ONLY_ACTIVE_PATHS 0x00000002	現在アクティブなパスのみを返します。メモ一時的なモードが存在する場合、QDC_ONLY_ACTIVE_PATHS 設定で返されるモードデータは、永続化データベースに格納されているものと一致しないことがあります。
QDC_DATABASE_CURRENT 0x00000004	現在接続されているディスプレイについて、CCD データベースで定義されているアクティブなパスを返します。

flags パラメーターには、次の値の 0 個以上をビット単位の OR で組み合わせて指定することもできます。

値	意味
QDC_VIRTUAL_MODE_AWARE 0x00000010	このフラグは、呼び出し元が仮想モードのサポートを認識していることを示すために、他のフラグとビット単位の OR で組み合わせて指定します。 Windows 10 以降でサポートされます。
QDC_INCLUDE_HMD 0x00000020	このフラグは、呼び出し元がアクティブなパスの一覧にヘッドマウントディスプレイ (HMD) を含めたいことを示すために、QDC_ONLY_ACTIVE_PATHS とビット単位の OR で組み合わせて指定します。詳細については「解説」を参照してください。 Windows 10 1703 Creators Update 以降でサポートされます。
QDC_VIRTUAL_REFRESH_RATE_AWARE 0x00000040	このフラグは、呼び出し元が仮想リフレッシュレートのサポートを認識していることを示すために、他のフラグとビット単位の OR で組み合わせて指定します。 Windows 11 以降でサポートされます。

numPathArrayElements

DWORD*

inout

pathArray の要素数を格納する変数へのポインターです。このパラメーターを NULL にすることはできません。QueryDisplayConfig が ERROR_SUCCESS を返した場合、numPathArrayElements は pathArray 内の有効なエントリ数で更新されます。

pathArray

DISPLAYCONFIG_PATH_INFO*

out

DISPLAYCONFIG_PATH_INFO 要素の配列を格納する変数へのポインターです。pathArray の各要素は、ソースからターゲットへの 1 つのパスを表します。ソースおよびターゲットのモード情報のインデックスは、同時に API から返される modeInfoArray テーブルと組み合わせた場合にのみ有効です。このパラメーターを NULL にすることはできません。pathArray は常にパス優先順位順に返されます。パス優先順位順の詳細については、Path Priority Order を参照してください。

numModeInfoArrayElements

DWORD*

inout

モード情報テーブルの要素数を指定する変数へのポインターです。このパラメーターを NULL にすることはできません。QueryDisplayConfig が ERROR_SUCCESS を返した場合、numModeInfoArrayElements は modeInfoArray 内の有効なエントリ数で更新されます。

modeInfoArray

DISPLAYCONFIG_MODE_INFO*

out

DISPLAYCONFIG_MODE_INFO 要素の配列を格納する変数へのポインターです。このパラメーターを NULL にすることはできません。

currentTopologyId

DISPLAYCONFIG_TOPOLOGY_ID*

inoutoptional

CCD データベース内で現在アクティブなトポロジの識別子を受け取る変数へのポインターです。指定できる値の一覧については、DISPLAYCONFIG_TOPOLOGY_ID 列挙型を参照してください。

currentTopologyId パラメーターは、flags パラメーターの値が QDC_DATABASE_CURRENT の場合にのみ設定されます。

flags パラメーターの値が QDC_DATABASE_CURRENT に設定されている場合、currentTopologyId パラメーターを NULL にすることはできません。flags パラメーターの値が QDC_DATABASE_CURRENT に設定されていない場合、currentTopologyId パラメーターの値は NULL でなければなりません。

戻り値の型: WIN32_ERROR

公式ドキュメント

QueryDisplayConfig 関数は、現在の設定におけるすべてのディスプレイデバイス(ビュー)について、考えられるすべての表示パスに関する情報を取得します。

戻り値

この関数は、次のいずれかの戻りコードを返します。

戻りコード	説明
ERROR_SUCCESS	関数は成功しました。
ERROR_INVALID_PARAMETER	指定されたパラメーターとフラグの組み合わせが無効です。
ERROR_NOT_SUPPORTED	システムが Windows Display Driver Model (WDDM) に従って書かれたグラフィックスドライバーで動作していません。この関数は、WDDM ドライバーが動作しているシステムでのみサポートされます。
ERROR_ACCESS_DENIED	呼び出し元がコンソールセッションにアクセスできません。このエラーは、呼び出し元のプロセスが現在のデスクトップにアクセスできない場合、またはリモートセッションで実行されている場合に発生します。
ERROR_GEN_FAILURE	原因不明のエラーが発生しました。
ERROR_INSUFFICIENT_BUFFER	指定されたパスバッファーおよびモードバッファーが小さすぎます。

解説(Remarks)

GetDisplayConfigBufferSizes 関数は特定の時点で必要な配列サイズしか判定できないため、GetDisplayConfigBufferSizes と QueryDisplayConfig の呼び出しの間にシステム構成が変化し、提供された配列サイズでは新しいパスデータを格納するのに不十分になる可能性があります。この場合、QueryDisplayConfig は ERROR_INSUFFICIENT_BUFFER で失敗するため、呼び出し元は GetDisplayConfigBufferSizes を再度呼び出して新しい配列サイズを取得する必要があります。その後、呼び出し元は適切な量のメモリを割り当てる必要があります。

QueryDisplayConfig は、pathArray パラメーターで指定されたパス配列にパスを返し、modeInfoArray パラメーターで指定されたモード配列にソースモードとターゲットモードを返します。QueryDisplayConfig は常にパスをパス優先順位順に返します。flags パラメーターに QDC_ALL_PATHS が設定されている場合、QueryDisplayConfig はアクティブなパスの後にすべての非アクティブなパスを返します。

完全なパス、ソースモード、ターゲットモードの情報は、すべてのアクティブなパスについて利用できます。ソースとターゲットの DISPLAYCONFIG_PATH_SOURCE_INFO および DISPLAYCONFIG_PATH_TARGET_INFO 構造体の ModeInfoIdx メンバーは、これらのアクティブなパスに対して設定されます。非アクティブなパスについては、返されるソースモードおよびターゲットモードの情報が利用できないため、パス構造体内のターゲット情報は既定値に設定され、ソースおよびターゲットのモードインデックスは無効としてマークされます。データベースクエリの場合、現在接続されているモニターのエントリが存在すれば、QueryDisplayConfig は完全なパス、ソースモード、ターゲットモードの情報を返します(アクティブなパスの場合と同じ)。ただし、データベースにエントリが存在しない場合、QueryDisplayConfig は既定のターゲット詳細を伴うパス情報のみを返します(非アクティブなパスの場合と同じ)。

ソースモードおよびターゲットモードの情報がパス情報とどのように関係するかの例については、Relationship of Mode Information to Path Information を参照してください。

呼び出し元は、DisplayConfigGetDeviceInfo を使用して、ソースまたはターゲットデバイスに関する追加情報(たとえばモニター名、モニターの推奨モード、ソースデバイス名など)を取得できます。

ターゲットが現在強制的にプロジェクション(投影)されている場合、DISPLAYCONFIG_PATH_TARGET_INFO 構造体の statusFlags メンバーには、DISPLAYCONFIG_TARGET_FORCED_XXX フラグのいずれかが設定されます。

Flags パラメーターに QDC_DATABASE_CURRENT フラグが設定されている場合、QueryDisplayConfig は currentTopologyId パラメーターが指す変数に、アクティブなデータベーストポロジのトポロジ識別子を返します。Flags パラメーターに QDC_ALL_PATHS または QDC_ONLY_ACTIVE_PATHS フラグが設定されている場合、currentTopologyId パラメーターは NULL に設定する必要があります。そうでない場合、QueryDisplayConfig は ERROR_INVALID_PARAMETER を返します。

呼び出し元が flags パラメーターに QDC_DATABASE_CURRENT フラグを設定して QueryDisplayConfig を呼び出した場合、QueryDisplayConfig は DISPLAYCONFIG_VIDEO_SIGNAL_INFO 構造体の totalSize メンバーで指定される DISPLAYCONFIG_2DREGION 構造体をゼロで初期化し、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 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";
    }
}

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// USER32.dll
#include <windows.h>

WIN32_ERROR QueryDisplayConfig(
    QUERY_DISPLAY_CONFIG_FLAGS flags,
    DWORD* numPathArrayElements,
    DISPLAYCONFIG_PATH_INFO* pathArray,
    DWORD* numModeInfoArrayElements,
    DISPLAYCONFIG_MODE_INFO* modeInfoArray,
    DISPLAYCONFIG_TOPOLOGY_ID* currentTopologyId   // optional
);

[DllImport("USER32.dll", ExactSpelling = true)]
static extern uint QueryDisplayConfig(
    uint flags,   // QUERY_DISPLAY_CONFIG_FLAGS
    ref uint numPathArrayElements,   // DWORD* in/out
    IntPtr pathArray,   // DISPLAYCONFIG_PATH_INFO* out
    ref uint numModeInfoArrayElements,   // DWORD* in/out
    IntPtr modeInfoArray,   // DISPLAYCONFIG_MODE_INFO* out
    IntPtr currentTopologyId   // DISPLAYCONFIG_TOPOLOGY_ID* optional, in/out
);

<DllImport("USER32.dll", ExactSpelling:=True)>
Public Shared Function QueryDisplayConfig(
    flags As UInteger,   ' QUERY_DISPLAY_CONFIG_FLAGS
    ByRef numPathArrayElements As UInteger,   ' DWORD* in/out
    pathArray As IntPtr,   ' DISPLAYCONFIG_PATH_INFO* out
    ByRef numModeInfoArrayElements As UInteger,   ' DWORD* in/out
    modeInfoArray As IntPtr,   ' DISPLAYCONFIG_MODE_INFO* out
    currentTopologyId As IntPtr   ' DISPLAYCONFIG_TOPOLOGY_ID* optional, in/out
) As UInteger
End Function

' flags : QUERY_DISPLAY_CONFIG_FLAGS
' numPathArrayElements : DWORD* in/out
' pathArray : DISPLAYCONFIG_PATH_INFO* out
' numModeInfoArrayElements : DWORD* in/out
' modeInfoArray : DISPLAYCONFIG_MODE_INFO* out
' currentTopologyId : DISPLAYCONFIG_TOPOLOGY_ID* optional, in/out
Declare PtrSafe Function QueryDisplayConfig Lib "user32" ( _
    ByVal flags As Long, _
    ByRef numPathArrayElements As Long, _
    ByVal pathArray As LongPtr, _
    ByRef numModeInfoArrayElements As Long, _
    ByVal modeInfoArray As LongPtr, _
    ByVal currentTopologyId As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

QueryDisplayConfig = ctypes.windll.user32.QueryDisplayConfig
QueryDisplayConfig.restype = wintypes.DWORD
QueryDisplayConfig.argtypes = [
    wintypes.DWORD,  # flags : QUERY_DISPLAY_CONFIG_FLAGS
    ctypes.POINTER(wintypes.DWORD),  # numPathArrayElements : DWORD* in/out
    ctypes.c_void_p,  # pathArray : DISPLAYCONFIG_PATH_INFO* out
    ctypes.POINTER(wintypes.DWORD),  # numModeInfoArrayElements : DWORD* in/out
    ctypes.c_void_p,  # modeInfoArray : DISPLAYCONFIG_MODE_INFO* out
    ctypes.c_void_p,  # currentTopologyId : DISPLAYCONFIG_TOPOLOGY_ID* optional, in/out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('USER32.dll')
QueryDisplayConfig = Fiddle::Function.new(
  lib['QueryDisplayConfig'],
  [
    -Fiddle::TYPE_INT,  # flags : QUERY_DISPLAY_CONFIG_FLAGS
    Fiddle::TYPE_VOIDP,  # numPathArrayElements : DWORD* in/out
    Fiddle::TYPE_VOIDP,  # pathArray : DISPLAYCONFIG_PATH_INFO* out
    Fiddle::TYPE_VOIDP,  # numModeInfoArrayElements : DWORD* in/out
    Fiddle::TYPE_VOIDP,  # modeInfoArray : DISPLAYCONFIG_MODE_INFO* out
    Fiddle::TYPE_VOIDP,  # currentTopologyId : DISPLAYCONFIG_TOPOLOGY_ID* optional, in/out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "user32")]
extern "system" {
    fn QueryDisplayConfig(
        flags: u32,  // QUERY_DISPLAY_CONFIG_FLAGS
        numPathArrayElements: *mut u32,  // DWORD* in/out
        pathArray: *mut DISPLAYCONFIG_PATH_INFO,  // DISPLAYCONFIG_PATH_INFO* out
        numModeInfoArrayElements: *mut u32,  // DWORD* in/out
        modeInfoArray: *mut DISPLAYCONFIG_MODE_INFO,  // DISPLAYCONFIG_MODE_INFO* out
        currentTopologyId: *mut i32  // DISPLAYCONFIG_TOPOLOGY_ID* optional, in/out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("USER32.dll")]
public static extern uint QueryDisplayConfig(uint flags, ref uint numPathArrayElements, IntPtr pathArray, ref uint numModeInfoArrayElements, IntPtr modeInfoArray, IntPtr currentTopologyId);
"@
$api = Add-Type -MemberDefinition $sig -Name 'USER32_QueryDisplayConfig' -Namespace Win32 -PassThru
# $api::QueryDisplayConfig(flags, numPathArrayElements, pathArray, numModeInfoArrayElements, modeInfoArray, currentTopologyId)

#uselib "USER32.dll"
#func global QueryDisplayConfig "QueryDisplayConfig" sptr, sptr, sptr, sptr, sptr, sptr
; QueryDisplayConfig flags, varptr(numPathArrayElements), varptr(pathArray), varptr(numModeInfoArrayElements), varptr(modeInfoArray), varptr(currentTopologyId)   ; 戻り値は stat
; flags : QUERY_DISPLAY_CONFIG_FLAGS -> "sptr"
; numPathArrayElements : DWORD* in/out -> "sptr"
; pathArray : DISPLAYCONFIG_PATH_INFO* out -> "sptr"
; numModeInfoArrayElements : DWORD* in/out -> "sptr"
; modeInfoArray : DISPLAYCONFIG_MODE_INFO* out -> "sptr"
; currentTopologyId : DISPLAYCONFIG_TOPOLOGY_ID* optional, in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "USER32.dll"
#cfunc global QueryDisplayConfig "QueryDisplayConfig" int, var, var, var, var, var
; res = QueryDisplayConfig(flags, numPathArrayElements, pathArray, numModeInfoArrayElements, modeInfoArray, currentTopologyId)
; flags : QUERY_DISPLAY_CONFIG_FLAGS -> "int"
; numPathArrayElements : DWORD* in/out -> "var"
; pathArray : DISPLAYCONFIG_PATH_INFO* out -> "var"
; numModeInfoArrayElements : DWORD* in/out -> "var"
; modeInfoArray : DISPLAYCONFIG_MODE_INFO* out -> "var"
; currentTopologyId : DISPLAYCONFIG_TOPOLOGY_ID* optional, in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "USER32.dll"
#cfunc global QueryDisplayConfig "QueryDisplayConfig" int, sptr, sptr, sptr, sptr, sptr
; res = QueryDisplayConfig(flags, varptr(numPathArrayElements), varptr(pathArray), varptr(numModeInfoArrayElements), varptr(modeInfoArray), varptr(currentTopologyId))
; flags : QUERY_DISPLAY_CONFIG_FLAGS -> "int"
; numPathArrayElements : DWORD* in/out -> "sptr"
; pathArray : DISPLAYCONFIG_PATH_INFO* out -> "sptr"
; numModeInfoArrayElements : DWORD* in/out -> "sptr"
; modeInfoArray : DISPLAYCONFIG_MODE_INFO* out -> "sptr"
; currentTopologyId : DISPLAYCONFIG_TOPOLOGY_ID* optional, in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。