SetDisplayConfig, fonction (winuser.h)
La fonction SetDisplayConfig modifie la topologie d’affichage, les modes source et cible en activant exclusivement les chemins d’accès spécifiés dans la session active.
Syntaxe
LONG SetDisplayConfig(
[in] UINT32 numPathArrayElements,
[in, optional] DISPLAYCONFIG_PATH_INFO *pathArray,
[in] UINT32 numModeInfoArrayElements,
[in, optional] DISPLAYCONFIG_MODE_INFO *modeInfoArray,
[in] UINT32 flags
);
Paramètres
[in] numPathArrayElements
Nombre d’éléments dans pathArray.
[in, optional] pathArray
Tableau de tous les chemins d’affichage à définir. Seuls les chemins d’accès de ce tableau dont l’indicateur DISPLAYCONFIG_PATH_ACTIVE est défini dans le membre des indicateursde DISPLAYCONFIG_PATH_INFO sont définis. Ce paramètre peut être NULL. L’ordre dans lequel les chemins d’accès actifs apparaissent dans ce tableau détermine la priorité du chemin. Pour plus d’informations sur l’ordre de priorité des chemins d’accès, consultez Ordre de priorité du chemin.
[in] numModeInfoArrayElements
Nombre d’éléments en modeInfoArray.
[in, optional] modeInfoArray
Tableau d’informations sur les modes source et cible d’affichage (DISPLAYCONFIG_MODE_INFO) référencées par le membre modeInfoIdx de DISPLAYCONFIG_PATH_SOURCE_INFO et DISPLAYCONFIG_PATH_TARGET_INFO élément des informations de chemin d’accès de pathArray. Ce paramètre peut être NULL.
[in] flags
Or au niveau du bit des valeurs d’indicateur qui indique le comportement de cette fonction. Ce paramètre peut être l’une des valeurs suivantes ou une combinaison des valeurs suivantes : 0 n’est pas valide. Pour obtenir une description des combinaisons d’indicateurs valides, voir ci-dessous.
La liste suivante contient des combinaisons de valeurs valides pour le paramètre Flags :
- Vous devez définir SDC_APPLY ou SDC_VALIDATE, mais pas les deux.
- Vous devez définir des SDC_USE_SUPPLIED_DISPLAY_CONFIG ou des combinaisons de SDC_TOPOLOGY_XXX. SDC_USE_SUPPLIED_DISPLAY_CONFIG ne peut pas être défini avec un indicateur de SDC_TOPOLOGY_XXX.
- SDC_NO_OPTIMIZATION ne peut être défini qu’avec SDC_APPLY.
- SDC_ALLOW_CHANGES est autorisé avec toute autre combinaison valide.
- SDC_SAVE_TO_DATABASE ne peut être défini qu’avec SDC_USE_SUPPLIED_DISPLAY_CONFIG.
- SDC_PATH_PERSIST_IF_REQUIRED ne peut pas être utilisé avec SDC_USE_SUPPLIED_DISPLAY_CONFIG ou SDC_TOPOLOGY_SUPPLIED.
- SDC_FORCE_MODE_ENUMERATION est valide uniquement lorsque SDC_APPLY et SDC_USE_SUPPLIED_DISPLAY_CONFIG sont spécifiés.
- SDC_ALLOW_PATH_ORDER_CHANGES est autorisé uniquement lorsque SDC_TOPOLOGY_SUPPLIED est spécifié.
- SDC_TOPOLOGY_SUPPLIED ne peut pas être utilisé avec un autre indicateur de SDC_TOPOLOGY_XXX. En raison d’un problème de validation, si un appelant enfreint cette règle, SetDisplayConfig n’échoue pas. Toutefois, SetDisplayConfig ignore l’indicateur SDC_TOPOLOGY_SUPPLIED.
Valeur retournée
La fonction retourne l’un des codes de retour suivants.
| Code de retour | Description |
|---|---|
|
La fonction a réussi. |
|
La combinaison de paramètres et d’indicateurs spécifiée n’est pas valide. |
|
Le système n’exécute pas de pilote graphique qui a été écrit selon le modèle WDDM (Windows Display Driver Model). La fonction est uniquement prise en charge sur un système sur lequel un pilote WDDM est en cours d’exécution. |
|
L’appelant n’a pas accès à la session de console. Cette erreur se produit si le processus appelant n’a pas accès au bureau actuel ou s’exécute sur une session à distance. |
|
Une erreur non spécifiée s'est produite. |
|
La fonction n’a pas pu trouver de solution utilisable pour les modes source et cible que l’appelant n’a pas spécifiés. |
Remarques
La fonction SetDisplayConfig prend les chemins d’affichage actifs avec toutes les informations de mode source et cible spécifiées, et utilise la logique de mode optimale pour générer les informations manquantes en mode source et cible. Cette fonction définit ensuite le chemin d’affichage complet.
Les membres ModeInfoIdx dans les structures DISPLAYCONFIG_PATH_SOURCE_INFO et DISPLAYCONFIG_PATH_TARGET_INFO sont utilisés pour indiquer si le mode source et le mode cible sont fournis pour un chemin actif donné. Si la valeur d’index est DISPLAYCONFIG_PATH_MODE_IDX_INVALID pour l’une ou l’autre, cela indique que les informations de mode ne sont pas spécifiées. Il est valide pour le chemin d’accès plus le mode source ou le chemin plus les informations de mode source et cible à spécifier pour un chemin d’accès donné. Toutefois, il n’est pas valide que le chemin d’accès et le mode cible soient spécifiés sans le mode source.
Les modes source et cible pour chaque identificateur source et cible ne peuvent apparaître dans le tableau modeInfoArray qu’une seule fois. Par exemple, un mode source pour l’identificateur source S1 ne peut apparaître dans la table qu’une seule fois ; si plusieurs chemins font référence à la même source, ils doivent utiliser le même ModeInfoIdx.
La plupart des appelants utilisent QueryDisplayConfig pour obtenir la configuration actuelle ainsi que d’autres possibilités valides, puis utilisent SetDisplayConfig pour tester et définir la configuration.
L’ordre dans lequel les chemins actifs apparaissent dans le tableau PathArray détermine la priorité du chemin.
Par défaut, SetDisplayConfig ne modifie jamais les informations fournies sur le chemin d’accès, le mode source ou le mode cible. Si la logique du mode optimal ne peut pas trouver de solution sans modifier les informations de chemin d’affichage spécifiées, SetDisplayConfig échoue avec ERROR_BAD_CONFIGURATION. Dans ce cas, l’appelant doit spécifier l’indicateur SDC_ALLOW_CHANGES pour permettre à la fonction d’ajuster certains des détails de la source et du mode spécifiés pour permettre au changement de chemin d’affichage de réussir.
Si les modes source et cible spécifiés ou calculés ont les mêmes dimensions, SetDisplayConfig définit automatiquement la mise à l’échelle du chemin sur DISPLAYCONFIG_PPR_IDENTITY avant de définir le chemin d’affichage et de l’enregistrer dans la base de données. Pour plus d’informations sur la façon dont SetDisplayConfig gère la mise à l’échelle, consultez Mise à l’échelle de l’image de bureau.
Lorsque l’appelant spécifie l’indicateur SDC_USE_SUPPLIED_DISPLAY_CONFIG pour définir un chemin d’accès au clone et si des index en mode source ne sont pas valides dans le tableau de chemins, SetDisplayConfig détermine que tous les index du mode source de cette source ne sont pas valides. SetDisplayConfig utilise la logique de mode optimale pour déterminer les informations sur le mode source.
À l’exception de l’indicateur SDC_TOPOLOGY_SUPPLIED (pour plus d’informations sur SDC_TOPOLOGY_SUPPLIED, voir le paragraphe suivant), les indicateurs SDC_TOPOLOGY_XXX définissent les derniers paramètres de chemin d’affichage, y compris les informations de mode source et cible pour ce type de topologie. Pour plus d’informations sur les combinaisons d’indicateurs de SDC_TOPOLOGY_XXX valides, consultez la description du paramètre Indicateurs . Les paramètres pathArray et modeInfoArray doivent être NULL et leurs tailles associées doivent être égales à zéro. Par exemple, si SDC_TOPOLOGY_CLONE et SDC_TOPOLOGY_EXTEND sont définis, cette fonction utilise la configuration de clone ou d’extension de chemin d’affichage la plus récente. Si un type de topologie unique est demandé, la dernière configuration de ce type est utilisée. Si cette topologie n’avait jamais été définie auparavant, SetDisplayConfig utilise la meilleure logique de topologie pour trouver la meilleure topologie, puis la meilleure logique de mode pour trouver le meilleur mode source et cible à utiliser. Si une combinaison des indicateurs de topologie avait été définie et qu’aucun d’entre eux n’avait d’entrées de base de données, la priorité suivante est utilisée. Pour les ordinateurs portables : cloner, étendre, interne, puis externe ; pour les bureaux, la priorité est d’étendre, puis de cloner.
L’appelant peut spécifier l’indicateur de SDC_TOPOLOGY_SUPPLIED pour indiquer qu’il définit uniquement les informations de chemin d’accès (topologie) et demande que SetDisplayConfig obtient, puis utilise les informations de mode source et cible de la base de données de persistance. Si les chemins d’accès actifs que l’appelant fournit n’ont pas d’entrée dans la base de données de persistance, SetDisplayConfig échoue. Dans ce cas, si l’appelant appelle à nouveau SetDisplayConfig avec les mêmes données de chemin d’accès, mais avec l’indicateur SDC_USE_SUPPLIED_DISPLAY_CONFIG défini, SetDisplayConfig utilise la logique de mode optimale pour créer les informations de mode source et cible. Lorsque l’appelant spécifie SDC_TOPOLOGY_SUPPLIED, l’appelant doit définir le paramètre numModeInfoArrayElements sur zéro et le paramètre modeInfoArray sur NULL ; Toutefois, l’appelant doit définir les paramètres pathArray et numPathArrayElements pour les informations de chemin dont l’appelant a besoin. L’appelant doit marquer tous les index du mode source et cible comme non valides (DISPLAYCONFIG_PATH_MODE_IDX_INVALID) dans ces données de chemin d’accès.
Le tableau suivant fournit quelques scénarios courants où SetDisplayConfig est appelé avec les combinaisons d’indicateurs que l’appelant transmet au paramètre Flags pour réaliser les scénarios.
| Scénario | Combinaison d’indicateurs |
|---|---|
| Tester si une configuration d’affichage spécifiée est prise en charge sur l’ordinateur | SDC_VALIDATE | SDC_USE_SUPPLIED_DISPLAY_CONFIG |
| Définir une configuration d’affichage spécifiée et enregistrer dans la base de données | SDC_APPLY | SDC_USE_SUPPLIED_DISPLAY_CONFIG | SDC_SAVE_TO_DATABASE |
| Définir une configuration d’affichage temporaire (autrement dit, la configuration d’affichage ne sera pas enregistrée) | SDC_APPLY | SDC_USE_SUPPLIED_DISPLAY_CONFIG |
| Tester si le clonage est pris en charge sur l’ordinateur | SDC_VALIDATE | SDC_TOPOLOGY_CLONE |
| Définir la topologie de clonage | SDC_APPLY | SDC_TOPOLOGY_CLONE |
| Définir la topologie de clonage et autoriser l’activation de la persistance du chemin d’accès si nécessaire pour répondre à la demande | SDC_APPLY | SDC_TOPOLOGY_CLONE | SDC_PATH_PERSIST_IF_REQUIRED |
| Revenir d’un mode temporaire à la dernière configuration d’affichage enregistrée | SDC_APPLY| SDC_USE_DATABASE_CURRENT |
| Étant donné uniquement les informations de chemin d’accès, définissez la configuration d’affichage avec les informations source et cible de la base de données pour les chemins et ignorez l’ordre du chemin d’accès | SDC_APPLY | SDC_TOPOLOGY_SUPPLIED | SDC_ALLOW_PATH_ORDER_CHANGES |
Virtualisation PPP
Cette API ne participe pas à la virtualisation PPP. Toutes les tailles de la structure DEVMODE sont en termes de pixels physiques et ne sont pas liées au contexte appelant.Spécifications
| Client minimal pris en charge | Disponible dans Windows 7 et versions ultérieures des systèmes d’exploitation Windows. |
| Plateforme cible | Universal |
| En-tête | winuser.h (inclure Windows.h) |
| Bibliothèque | User32.lib |
| DLL | User32.dll |
| Ensemble d’API | ext-ms-win-ntuser-sysparams-ext-l1-1-1 (introduit dans Windows 10, version 10.0.14393) |
Voir aussi
DISPLAYCONFIG_PATH_SOURCE_INFO