SetDisplayConfig-Funktion (winuser.h)
Die SetDisplayConfig-Funktion ändert den Anzeigetopologie-, Quell- und Zielmodus, indem die angegebenen Pfade in der aktuellen Sitzung ausschließlich aktiviert werden.
Syntax
LONG SetDisplayConfig(
[in] UINT32 numPathArrayElements,
[in, optional] DISPLAYCONFIG_PATH_INFO *pathArray,
[in] UINT32 numModeInfoArrayElements,
[in, optional] DISPLAYCONFIG_MODE_INFO *modeInfoArray,
[in] UINT32 flags
);
Parameter
[in] numPathArrayElements
Anzahl der Elemente in pathArray.
[in, optional] pathArray
Array aller anzeigepfade, die festgelegt werden sollen. Es werden nur die Pfade innerhalb dieses Arrays festgelegt, für die das DISPLAYCONFIG_PATH_ACTIVE-Flag im Flags-Elementvon DISPLAYCONFIG_PATH_INFO festgelegt ist. Dieser Parameter kann NULL sein. Die Reihenfolge, in der aktive Pfade in diesem Array angezeigt werden, bestimmt die Pfadpriorität. Weitere Informationen zur Reihenfolge der Pfadpriorität finden Sie unter Pfadprioritätsreihenfolge.
[in] numModeInfoArrayElements
Anzahl der Elemente in modeInfoArray.
[in, optional] modeInfoArray
Array von Anzeigequellen- und Zielmodusinformationen (DISPLAYCONFIG_MODE_INFO), auf das vom modeInfoIdx-Member von DISPLAYCONFIG_PATH_SOURCE_INFO und DISPLAYCONFIG_PATH_TARGET_INFO Element der Pfadinformationen aus pathArray verwiesen wird. Dieser Parameter kann NULL sein.
[in] flags
Ein bitweiser OR mit Flagwerten, der das Verhalten dieser Funktion angibt. Dieser Parameter kann einer der folgenden Werte oder eine Kombination der folgenden Werte sein: 0 ist ungültig. Eine Beschreibung der gültigen Flagkombinationen finden Sie unten.
Die folgende Liste enthält gültige Kombinationen von Werten für den Flags-Parameter :
- Es muss entweder SDC_APPLY oder SDC_VALIDATE festgelegt werden, aber nicht beides.
- Es müssen entweder SDC_USE_SUPPLIED_DISPLAY_CONFIG oder beliebige Kombinationen von SDC_TOPOLOGY_XXX festgelegt werden. SDC_USE_SUPPLIED_DISPLAY_CONFIG kann nicht mit einem SDC_TOPOLOGY_XXX-Flag festgelegt werden.
- SDC_NO_OPTIMIZATION kann nur mit SDC_APPLY festgelegt werden.
- SDC_ALLOW_CHANGES ist mit jeder anderen gültigen Kombination zulässig.
- SDC_SAVE_TO_DATABASE kann nur mit SDC_USE_SUPPLIED_DISPLAY_CONFIG festgelegt werden.
- SDC_PATH_PERSIST_IF_REQUIRED können nicht mit SDC_USE_SUPPLIED_DISPLAY_CONFIG oder SDC_TOPOLOGY_SUPPLIED verwendet werden.
- SDC_FORCE_MODE_ENUMERATION ist nur gültig, wenn SDC_APPLY und SDC_USE_SUPPLIED_DISPLAY_CONFIG angegeben werden.
- SDC_ALLOW_PATH_ORDER_CHANGES ist nur zulässig, wenn SDC_TOPOLOGY_SUPPLIED angegeben ist.
- SDC_TOPOLOGY_SUPPLIED können nicht mit anderen SDC_TOPOLOGY_XXX-Flags verwendet werden. Aufgrund eines Validierungsproblems schlägt SetDisplayConfig nicht fehl, wenn ein Aufrufer gegen diese Regel verstößt. SetDisplayConfig ignoriert jedoch das SDC_TOPOLOGY_SUPPLIED-Flag.
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. |
|
Die Funktion konnte keine funktionsfähige Lösung für die Quell- und Zielmodi finden, die der Aufrufer nicht angegeben hat. |
Hinweise
Die SetDisplayConfig-Funktion übernimmt die aktiven Anzeigepfade mit allen angegebenen Quell- und Zielmodusinformationen und verwendet die Logik des besten Modus, um fehlende Quell- und Zielmodusinformationen zu generieren. Diese Funktion legt dann den vollständigen Anzeigepfad fest.
Die ModeInfoIdx-Member in den DISPLAYCONFIG_PATH_SOURCE_INFO - und DISPLAYCONFIG_PATH_TARGET_INFO-Strukturen werden verwendet, um anzugeben, ob der Quell- und Zielmodus für einen bestimmten aktiven Pfad angegeben wird. Wenn der Indexwert für beide DISPLAYCONFIG_PATH_MODE_IDX_INVALID ist, gibt dies an, dass die Modusinformationen nicht angegeben werden. Sie ist gültig für den Pfad plus Quellmodus oder den Pfad plus Quell- und Zielmodusinformationen, die für einen bestimmten Pfad angegeben werden sollen. Es ist jedoch nicht gültig, dass der Pfad- und Zielmodus ohne den Quellmodus angegeben wird.
Die Quell- und Zielmodi für die einzelnen Quell- und Zielbezeichner können nur einmal im array modeInfoArray angezeigt werden. Beispielsweise kann ein Quellmodus für den Quellbezeichner S1 nur einmal in der Tabelle angezeigt werden. wenn mehrere Pfade auf dieselbe Quelle verweisen, müssen sie dieselbe ModeInfoIdx verwenden.
Es wird erwartet, dass die meisten Aufrufer QueryDisplayConfig verwenden, um die aktuelle Konfiguration zusammen mit anderen gültigen Möglichkeiten abzurufen und dann SetDisplayConfig zum Testen und Festlegen der Konfiguration zu verwenden.
Die Reihenfolge, in der die aktiven Pfade im PathArray-Array angezeigt werden, bestimmt die Pfadpriorität.
Standardmäßig ändert SetDisplayConfig niemals informationen zu Pfad, Quellmodus oder Zielmodus. Wenn die Beste Moduslogik keine Lösung finden kann, ohne die angegebenen Anzeigepfadinformationen zu ändern, schlägt SetDisplayConfig mit ERROR_BAD_CONFIGURATION fehl. In diesem Fall sollte der Aufrufer das SDC_ALLOW_CHANGES Flag angeben, damit die Funktion einige der angegebenen Quell- und Modusdetails optimieren kann, damit die Änderung des Anzeigepfads erfolgreich ist.
Wenn die angegebenen oder berechneten Quell- und Zielmodi dieselben Dimensionen aufweisen, legt SetDisplayConfig die Pfadskalierung automatisch auf DISPLAYCONFIG_PPR_IDENTITY fest, bevor der Anzeigepfad festgelegt und in der Datenbank gespeichert wird. Informationen zur Verarbeitung der Skalierung durch SetDisplayConfig finden Sie unter Skalieren des Desktopimages.
Wenn der Aufrufer das SDC_USE_SUPPLIED_DISPLAY_CONFIG-Flag angibt, um einen Klonpfad festzulegen, und wenn Quellmodusindizes im Pfadarray ungültig sind, bestimmt SetDisplayConfig , dass alle Quellmodusindizes aus dieser Quelle ungültig sind. SetDisplayConfig verwendet die beste Moduslogik, um die Quellmodusinformationen zu bestimmen.
Mit Ausnahme des flags SDC_TOPOLOGY_SUPPLIED (weitere Informationen zu SDC_TOPOLOGY_SUPPLIED finden Sie im folgenden Absatz), legen die SDC_TOPOLOGY_XXX-Flags letzte Anzeigepfadeinstellungen fest, einschließlich der Quell- und Zielmodusinformationen für diesen Topologietyp. Informationen zu gültigen SDC_TOPOLOGY_XXX Flagkombinationen finden Sie in der Beschreibung des Flags-Parameters . Die Parameter pathArray und modeInfoArray müssen NULL sein, und die zugeordneten Größen müssen 0 sein. Wenn beispielsweise SDC_TOPOLOGY_CLONE und SDC_TOPOLOGY_EXTEND festgelegt sind, verwendet diese Funktion die neueste Konfiguration des Anzeigepfads klonen oder erweitern. Wenn ein einzelner Topologietyp angefordert wird, wird die letzte Konfiguration dieses Typs verwendet. Wenn diese Topologie noch nie festgelegt wurde, verwendet SetDisplayConfig die beste Topologielogik, um die beste Topologie zu finden, und dann die logik des besten Modus, um den besten Quell- und Zielmodus zu finden. Wenn eine Kombination der Topologieflags festgelegt wurde und keines von ihnen Datenbankeinträge aufweist, wird die folgende Priorität verwendet. Für Laptops: klonen, erweitern, intern und dann extern; für Desktops ist die Priorität erweitern und dann klonen.
Der Aufrufer kann das SDC_TOPOLOGY_SUPPLIED-Flag angeben, um anzugeben, dass er nur die Pfadinformationen (Topologie) und Anforderungen festlegt, die SetDisplayConfig abruft und dann die Quell- und Zielmodusinformationen aus der Persistenzdatenbank verwendet. Wenn die aktiven Pfade, die der Aufrufer bereitstellt, keinen Eintrag in der Persistenzdatenbank enthalten, schlägt SetDisplayConfig fehl. Wenn der Aufrufer in diesem Fall SetDisplayConfig erneut mit denselben Pfaddaten, aber mit dem SDC_USE_SUPPLIED_DISPLAY_CONFIG Flags aufruft, verwendet SetDisplayConfig die Logik des besten Modus, um die Quell- und Zielmodusinformationen zu erstellen. Wenn der Aufrufer SDC_TOPOLOGY_SUPPLIED angibt, muss der Aufrufer den numModeInfoArrayElements-Parameter auf Null und den modeInfoArray-Parameter auf NULL festlegen. Der Aufrufer muss jedoch die Parameter pathArray und numPathArrayElements für die Pfadinformationen festlegen, die der Aufrufer benötigt. Der Aufrufer muss alle Quell- und Zielmodusindizes in diesen Pfaddaten als ungültig (DISPLAYCONFIG_PATH_MODE_IDX_INVALID) markieren.
Die folgende Tabelle enthält einige gängige Szenarien, in denen SetDisplayConfig zusammen mit den Flagkombinationen aufgerufen wird, die der Aufrufer an den Flags-Parameter übergibt, um die Szenarien zu erreichen.
| Szenario | Flag-Kombination |
|---|---|
| Testen, ob eine angegebene Anzeigekonfiguration auf dem Computer unterstützt wird | SDC_VALIDATE | SDC_USE_SUPPLIED_DISPLAY_CONFIG |
| Festlegen einer angegebenen Anzeigekonfiguration und Speichern in der Datenbank | SDC_APPLY | SDC_USE_SUPPLIED_DISPLAY_CONFIG | SDC_SAVE_TO_DATABASE |
| Festlegen einer temporären Anzeigekonfiguration (d. h. die Anzeigekonfiguration wird nicht gespeichert) | SDC_APPLY | SDC_USE_SUPPLIED_DISPLAY_CONFIG |
| Testen, ob klonen auf dem Computer unterstützt wird | SDC_VALIDATE | SDC_TOPOLOGY_CLONE |
| Festlegen der Klontopologie | SDC_APPLY | SDC_TOPOLOGY_CLONE |
| Legen Sie die Klontopologie fest, und lassen Sie die Pfadpersistenz zu, wenn dies erforderlich ist, um die Anforderung zu erfüllen. | SDC_APPLY | SDC_TOPOLOGY_CLONE | SDC_PATH_PERSIST_IF_REQUIRED |
| Zurück von einem temporären Modus zur zuletzt gespeicherten Anzeigekonfiguration | SDC_APPLY| SDC_USE_DATABASE_CURRENT |
| Legen Sie die Anzeigekonfiguration mit den Quell- und Zielinformationen aus der Datenbank für die Pfade fest, und ignorieren Sie die Pfadreihenfolge. | SDC_APPLY | SDC_TOPOLOGY_SUPPLIED | SDC_ALLOW_PATH_ORDER_CHANGES |
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.Anforderungen
| Unterstützte Mindestversion (Client) | Verfügbar in Windows 7 und höheren Versionen der Windows-Betriebssysteme. |
| Zielplattform | Universell |
| Header | winuser.h (einschließlich Windows.h) |
| Bibliothek | User32.lib |
| 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