Freigeben über


QueryDisplayConfig-Funktion (winuser.h)

Die QueryDisplayConfig-Funktion ruft Informationen zu allen möglichen Anzeigepfaden für alle Anzeigegeräte oder Ansichten in der aktuellen Einstellung ab.

Syntax

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

Parameter

[in] flags

Der Typ der abzurufenden Informationen. Der Wert für den Flags-Parameter muss einen der folgenden Werte verwenden.

Wert Bedeutung
QDC_ALL_PATHS
0x00000001
Gibt alle möglichen Pfadkombinationen von Quellen an Ziele zurück.

Hinweis

Bei temporären Modi bedeutet die Einstellung QDC_ALL_PATHS, dass die zurückgegebenen Modusdaten möglicherweise nicht mit denen übereinstimmen, die in der Persistenzdatenbank gespeichert sind.

Hinweis

Dieses Flag kann sehr teuer zu berechnen sein. Es wird nicht empfohlen, dieses Flag zu verwenden, es sei denn, der Aufrufer versucht, den Satz gültiger Verbindungen zwischen Quellen und Zielen zu bestimmen.

QDC_ONLY_ACTIVE_PATHS
0x00000002
Gibt derzeit nur aktive Pfade zurück.

Hinweis

Bei temporären Modi bedeutet die einstellung QDC_ONLY_ACTIVE_PATHS, dass die zurückgegebenen Modusdaten möglicherweise nicht mit denen übereinstimmen, die in der Persistenzdatenbank gespeichert sind.

QDC_DATABASE_CURRENT
0x00000004
Gibt aktive Pfade zurück, die in der CCD-Datenbank für die aktuell verbundenen Anzeigen definiert sind.

Der Flags-Parameter kann auch bitweise OR'ed mit 0 oder mehr der folgenden Werte sein.

Wert Bedeutung
QDC_VIRTUAL_MODE_AWARE
0x00000010
Dieses Flag sollte bitweise oder mit anderen Flags versehen sein, um anzugeben, dass der Aufrufer die Unterstützung des virtuellen Modus kennt.

Wird ab Windows 10 unterstützt.

QDC_INCLUDE_HMD
0x00000020
Dieses Flag sollte bitweise OR'ed mit QDC_ONLY_ACTIVE_PATHS sein, um anzugeben, dass der Aufrufer head-mounted Displays (HMDs) in die Liste der aktiven Pfade aufnehmen möchte. Weitere Informationen finden Sie unter Hinweise.

Wird ab Windows 10 1703 Creators Update unterstützt.

QDC_VIRTUAL_REFRESH_RATE_AWARE
0x00000040
Dieses Flag sollte bitweise oder mit anderen Flags versehen sein, um anzugeben, dass der Aufrufer die Unterstützung der virtuellen Aktualisierungsrate kennt.

Wird ab Windows 11 unterstützt.

[in, out] numPathArrayElements

Zeiger auf eine Variable, die die Anzahl der Elemente in pPathInfoArray enthält. Dieser Parameter darf nicht NULL sein. Wenn QueryDisplayConfig ERROR_SUCCESS zurückgibt, wird pNumPathInfoElements mit der Anzahl der gültigen Einträge in pPathInfoArray aktualisiert.

[out] pathArray

Zeiger auf eine Variable, die ein Array von DISPLAYCONFIG_PATH_INFO Elementen enthält. Jedes Element in pPathInfoArray beschreibt einen einzelnen Pfad von einer Quelle zu einem Ziel. Die Quell- und Zielmodusinformationsindizes sind nur in Kombination mit den pmodeInfoArray-Tabellen gültig, die gleichzeitig für die API zurückgegeben werden. Dieser Parameter darf nicht NULL sein. Das pPathInfoArray wird immer in der Pfadprioritätsreihenfolge zurückgegeben. Weitere Informationen zur Reihenfolge der Pfadpriorität finden Sie unter Pfadprioritätsreihenfolge.

[in, out] numModeInfoArrayElements

Zeiger auf eine Variable, die die Anzahl im Element der Modusinformationstabelle angibt. Dieser Parameter darf nicht NULL sein. Wenn QueryDisplayConfig ERROR_SUCCESS zurückgibt, wird pNumModeInfoArrayElements mit der Anzahl der gültigen Einträge in pModeInfoArray aktualisiert.

[out] modeInfoArray

Zeiger auf eine Variable, die ein Array von DISPLAYCONFIG_MODE_INFO Elementen enthält. Dieser Parameter darf nicht NULL sein.

[out, optional] currentTopologyId

Zeiger auf eine Variable, die den Bezeichner der derzeit aktiven Topologie in der CCD-Datenbank empfängt. Eine Liste der möglichen Werte finden Sie im DISPLAYCONFIG_TOPOLOGY_ID aufgezählten Typs.

Der pCurrentTopologyId-Parameter wird nur festgelegt, wenn der Flags-Parameterwert QDC_DATABASE_CURRENT ist.

Wenn der Flags-Parameterwert auf QDC_DATABASE_CURRENT festgelegt ist, darf der pCurrentTopologyId-Parameter nicht NULL sein. Wenn der Flags-Parameterwert nicht auf QDC_DATABASE_CURRENT festgelegt ist, muss der pCurrentTopologyId-ParameterwertNULL sein.

Rückgabewert

Die Funktion gibt einen der folgenden Rückgabecodes zurück.

Rückgabecode Beschreibung
ERROR_SUCCESS
Die Funktion wurde erfolgreich ausgeführt.
ERROR_INVALID_PARAMETER
Die angegebene Kombination von Parametern und Flags ist ungültig.
ERROR_NOT_SUPPORTED
Das System führt keinen Grafiktreiber aus, der gemäß dem Windows Display Driver Model (WDDM) geschrieben wurde. Die Funktion wird nur auf einem System unterstützt, auf dem ein WDDM-Treiber ausgeführt wird.
ERROR_ACCESS_DENIED
Der Aufrufer hat keinen Zugriff auf die Konsolensitzung. Dieser Fehler tritt auf, wenn der aufrufende Prozess keinen Zugriff auf den aktuellen Desktop hat oder in einer Remotesitzung ausgeführt wird.
ERROR_GEN_FAILURE
Es ist ein unbekannter Fehler aufgetreten.
ERROR_INSUFFICIENT_BUFFER
Der angegebene Pfad- und Moduspuffer ist zu klein.

Hinweise

Da die GetDisplayConfigBufferSizes-Funktion nur die erforderliche Arraygröße zu einem bestimmten Zeitpunkt bestimmen kann, ist es möglich, dass zwischen Aufrufen von GetDisplayConfigBufferSizes und QueryDisplayConfig die Systemkonfiguration geändert wird und die bereitgestellten Arraygrößen nicht mehr ausreichen, um die neuen Pfaddaten zu speichern. In dieser Situation schlägt QueryDisplayConfig mit ERROR_INSUFFICIENT_BUFFER fehl, und der Aufrufer sollte GetDisplayConfigBufferSizes erneut aufrufen, um die neuen Arraygrößen abzurufen. Der Aufrufer sollte dann die richtige Menge an Arbeitsspeicher zuordnen.

QueryDisplayConfig gibt Pfade im Pfadarray zurück, das der pPathInfoArray-Parameter angibt, sowie die Quell- und Zielmodi in dem Modusarray, das der pModeInfoArray-Parameter angibt. QueryDisplayConfig gibt Pfade immer in der Pfadprioritätsreihenfolge zurück. Wenn QDC_ALL_PATHS im Flags-Parameter festgelegt ist, gibt QueryDisplayConfig alle inaktiven Pfade nach den aktiven Pfaden zurück.

Vollständige Pfad-, Quellmodus- und Zielmodusinformationen sind für alle aktiven Pfade verfügbar. Die ModeInfoIdx-Member in den DISPLAYCONFIG_PATH_SOURCE_INFO - und DISPLAYCONFIG_PATH_TARGET_INFO-Strukturen für die Quelle und das Ziel werden für diese aktiven Pfade eingerichtet. Für inaktive Pfade sind die zurückgegebenen Quell- und Zielmodusinformationen nicht verfügbar. Daher sind die Zielinformationen in der Pfadstruktur auf Standardwerte festgelegt, und die Quell- und Zielmodusindizes werden als ungültig markiert. Wenn bei Datenbankabfragen die aktuellen Verbindungsmonitore über einen Eintrag verfügen, gibt QueryDisplayConfig vollständige Pfad-, Quellmodus- und Zielmodusinformationen zurück (identisch mit aktiven Pfaden). Wenn die Datenbank jedoch keinen Eintrag hat, gibt QueryDisplayConfig nur die Pfadinformationen mit den Standardzieldetails zurück (identisch mit inaktiven Pfaden).

Ein Beispiel für die Beziehung zwischen Quell- und Zielmodusinformationen zu Pfadinformationen finden Sie unter Beziehung zwischen Modusinformationen und Pfadinformationen.

Der Aufrufer kann DisplayConfigGetDeviceInfo verwenden, um zusätzliche Informationen zum Quell- oder Zielgerät abzurufen, z. B. die Monitornamen, den bevorzugten Monitormodus und den Namen des Quellgeräts.

Wenn ein Ziel derzeit projiziert wird, hat das statusFlags-Element der DISPLAYCONFIG_PATH_TARGET_INFO-Struktur eines der DISPLAYCONFIG_TARGET_FORCED_XXX-Flags festgelegt.

Wenn das QDC_DATABASE_CURRENT-Flag im Flags-Parameter festgelegt ist, gibt QueryDisplayConfig den Topologiebezeichner der aktiven Datenbanktopologie in der Variablen zurück, auf die der pCurrentTopologyId-Parameter verweist. Wenn das QDC_ALL_PATHS- oder QDC_ONLY_ACTIVE_PATHS-Flag im Flags-Parameter festgelegt ist, muss der pCurrentTopologyId-Parameter auf NULL festgelegt werden. Andernfalls gibt QueryDisplayConfig ERROR_INVALID_PARAMETER zurück.

Wenn ein Aufrufer QueryDisplayConfig mit dem im Flags-Parameter festgelegten QDC_DATABASE_CURRENT-Flag aufruft, initialisiert QueryDisplayConfig die DISPLAYCONFIG_2DREGION Struktur, die im totalSize-Member der DISPLAYCONFIG_VIDEO_SIGNAL_INFO-Struktur angegeben ist, auf Nullen und schließt DISPLAYCONFIG_2DREGION nicht ab.

Die DEVMODE-Struktur, die von der Win32-Funktion EnumDisplaySettings zurückgegeben wird (in der Windows SDK-Dokumentation beschrieben), enthält Informationen, die sich sowohl auf den Quell- als auch auf den Zielmodus beziehen. Die CCD-APIs trennen jedoch explizit die Quell- und Zielmoduskomponenten.

Monitore mit Kopfmontage und speziellen Monitoren

QueryDisplayConfig und viele andere Win32-Anzeige-APIs haben nur begrenztes Bewusstsein für head-mounted und spezialisierte Monitore, da diese Anzeigen nicht an der Windows-Desktopumgebung teilnehmen. Es gibt jedoch Szenarien, in denen es erforderlich ist, die Konnektivität dieser Displays zu verstehen (z. B. Inhaltsschutzszenarien). Für diese eingeschränkten Szenarien kann verwendet werden, (QDC_INCLUDE_HMD | QDC_ONLY_ACTIVE_PATHS) um die Konnektivität von Head-Mounted-Displays zu ermitteln. Diese Pfade werden mit dem DISPLAYCONFIG_TARGET_IS_HMD-Flag im Feld DISPLAYCONFIG_PATH_TARGET_INFO.statusFlags markiert. Diese Unterstützung wurde im Windows 10 Creators Update 1703 hinzugefügt.

DPI-Virtualisierung

Diese API ist nicht an der DPI-Virtualisierung beteiligt. Alle Größen in der DEVMODE-Struktur beziehen sich auf physische Pixel und beziehen sich nicht auf den aufrufenden Kontext.

Beispiele

Im folgenden Beispiel werden aktive Anzeigepfade mit QueryDisplayConfig und GetDisplayConfigBufferSizes aufgelistet und Daten für jeden Pfad mithilfe von DisplayConfigGetDeviceInfo ausgegeben.

#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";
    }
}

Anforderungen

   
Unterstützte Mindestversion (Client) Verfügbar in Windows 7 und höheren Versionen der Windows-Betriebssysteme.
Zielplattform Universell
Header winuser.h (windows.h einschließen)
Bibliothek User32.lib; OneCoreUAP.lib auf Windows 10
DLL User32.dll
APIs ext-ms-win-ntuser-sysparams-ext-l1-1-1 (eingeführt in Windows 10, Version 10.0.14393)

Weitere Informationen

DISPLAYCONFIG_MODE_INFO

DISPLAYCONFIG_PATH_INFO

DISPLAYCONFIG_PATH_SOURCE_INFO

DISPLAYCONFIG_PATH_TARGET_INFO

DISPLAYCONFIG_TOPOLOGY_ID

DisplayConfigGetDeviceInfo

SetDisplayConfig