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.
Der Flags-Parameter kann auch bitweise OR'ed mit 0 oder mehr der folgenden Werte sein.
[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 |
|---|---|
|
Die Funktion wurde erfolgreich ausgeführt. |
|
Die angegebene Kombination von Parametern und Flags ist ungültig. |
|
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. |
|
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. |
|
Es ist ein unbekannter Fehler aufgetreten. |
|
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_PATH_SOURCE_INFO