Partager via


QueryDisplayConfig, fonction (winuser.h)

La fonction QueryDisplayConfig récupère des informations sur tous les chemins d’affichage possibles pour tous les périphériques d’affichage, ou vues, dans le paramètre actuel.

Syntaxe

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

Paramètres

[in] flags

Type d’informations à récupérer. La valeur du paramètre Flags doit utiliser l’une des valeurs suivantes.

Valeur Signification
QDC_ALL_PATHS
0x00000001
Retourne toutes les combinaisons de chemins d’accès possibles de sources aux cibles.

Notes

Dans le cas de tous les modes temporaires, le paramètre QDC_ALL_PATHS signifie que les données de mode retournées peuvent ne pas être identiques à celles stockées dans la base de données de persistance.

Notes

Ce indicateur peut être très coûteux à calculer. Il n’est pas recommandé d’utiliser cet indicateur, sauf si l’appelant tente de déterminer l’ensemble de connexions valides entre les sources et les cibles.

QDC_ONLY_ACTIVE_PATHS
0x00000002
Retourne uniquement les chemins d’accès actuellement actifs.

Notes

Dans le cas de tous les modes temporaires, le paramètre QDC_ONLY_ACTIVE_PATHS signifie que les données de mode retournées peuvent ne pas être identiques à celles stockées dans la base de données de persistance.

QDC_DATABASE_CURRENT
0x00000004
Retourne les chemins d’accès actifs tels que définis dans la base de données CCD pour les affichages actuellement connectés.

Le paramètre Flags peut également être or’ed au niveau du bit avec zéro ou plusieurs des valeurs suivantes.

Valeur Signification
QDC_VIRTUAL_MODE_AWARE
0x00000010
Cet indicateur doit être or’ed au niveau du bit avec d’autres indicateurs pour indiquer que l’appelant est conscient de la prise en charge du mode virtuel.

Pris en charge à partir de Windows 10.

QDC_INCLUDE_HMD
0x00000020
Cet indicateur doit être or’ed au niveau du bit avec QDC_ONLY_ACTIVE_PATHS pour indiquer que l’appelant souhaite inclure des affichages montés en tête (HMD) dans la liste des chemins actifs. Pour plus d'informations, consultez la section Notes.

Pris en charge à partir de Windows 10 1703 Creators Update.

QDC_VIRTUAL_REFRESH_RATE_AWARE
0x00000040
Cet indicateur doit être or’ed au niveau du bit avec d’autres indicateurs pour indiquer que l’appelant est conscient de la prise en charge de la fréquence d’actualisation virtuelle.

Prise en charge à partir de Windows 11.

[in, out] numPathArrayElements

Pointeur vers une variable qui contient le nombre d’éléments dans pPathInfoArray. Ce paramètre ne peut pas avoir la valeur NULL. Si QueryDisplayConfig retourne ERROR_SUCCESS, pNumPathInfoElements est mis à jour avec le nombre d’entrées valides dans pPathInfoArray.

[out] pathArray

Pointeur vers une variable qui contient un tableau d’éléments DISPLAYCONFIG_PATH_INFO . Chaque élément de pPathInfoArray décrit un chemin d’accès unique d’une source à une cible. Les index d’informations en mode source et cible ne sont valides qu’en combinaison avec les tables pmodeInfoArray retournées en même temps pour l’API. Ce paramètre ne peut pas avoir la valeur NULL. Le pPathInfoArray est toujours retourné dans l’ordre de priorité du chemin. Pour plus d’informations sur l’ordre de priorité des chemins d’accès, consultez Ordre de priorité du chemin d’accès.

[in, out] numModeInfoArrayElements

Pointeur vers une variable qui spécifie le nombre dans l’élément de la table d’informations de mode. Ce paramètre ne peut pas avoir la valeur NULL. Si QueryDisplayConfig retourne ERROR_SUCCESS, pNumModeInfoArrayElements est mis à jour avec le nombre d’entrées valides dans pModeInfoArray.

[out] modeInfoArray

Pointeur vers une variable qui contient un tableau d’éléments DISPLAYCONFIG_MODE_INFO . Ce paramètre ne peut pas avoir la valeur NULL.

[out, optional] currentTopologyId

Pointeur vers une variable qui reçoit l’identificateur de la topologie actuellement active dans la base de données CCD. Pour obtenir la liste des valeurs possibles, consultez le DISPLAYCONFIG_TOPOLOGY_ID type énuméré.

Le paramètre pCurrentTopologyId est défini uniquement lorsque la valeur du paramètre Flags est QDC_DATABASE_CURRENT.

Si la valeur du paramètre Flags est définie sur QDC_DATABASE_CURRENT, le paramètre pCurrentTopologyId ne doit pas avoir la valeur NULL. Si la valeur du paramètre Flags n’est pas définie sur QDC_DATABASE_CURRENT, la valeur du paramètre pCurrentTopologyId doit être NULL.

Valeur retournée

La fonction retourne l’un des codes de retour suivants.

Code de retour Description
ERROR_SUCCESS
La fonction a réussi.
ERROR_INVALID_PARAMETER
La combinaison de paramètres et d’indicateurs spécifiés n’est pas valide.
ERROR_NOT_SUPPORTED
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 avec un pilote WDDM en cours d’exécution.
ERROR_ACCESS_DENIED
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 distante.
ERROR_GEN_FAILURE
Une erreur non spécifiée s'est produite.
ERROR_INSUFFICIENT_BUFFER
Le chemin d’accès et la mémoire tampon de mode fournis sont trop petits.

Remarques

Étant donné que la fonction GetDisplayConfigBufferSizes ne peut déterminer la taille de tableau requise qu’à un moment donné, il est possible qu’entre les appels à GetDisplayConfigBufferSizes et QueryDisplayConfig , la configuration système change et les tailles de tableau fournies ne soient plus suffisantes pour stocker les nouvelles données de chemin d’accès. Dans ce cas, QueryDisplayConfig échoue avec ERROR_INSUFFICIENT_BUFFER, et l’appelant doit appeler à nouveau GetDisplayConfigBufferSizes pour obtenir les nouvelles tailles de tableau. L’appelant doit ensuite allouer la quantité de mémoire correcte.

QueryDisplayConfig retourne les chemins d’accès dans le tableau de chemins que le paramètre pPathInfoArray spécifie, ainsi que les modes source et cible dans le tableau de modes spécifié par le paramètre pModeInfoArray . QueryDisplayConfig retourne toujours les chemins dans l’ordre de priorité du chemin. Si QDC_ALL_PATHS est défini dans le paramètre Flags , QueryDisplayConfig retourne tous les chemins inactifs après les chemins d’accès actifs.

Les informations sur le chemin d’accès complet, le mode source et le mode cible sont disponibles pour tous les chemins d’accès actifs. Les membres ModeInfoIdx dans les structures DISPLAYCONFIG_PATH_SOURCE_INFO et DISPLAYCONFIG_PATH_TARGET_INFO pour la source et la cible sont configurés pour ces chemins actifs. Pour les chemins d’accès inactifs, les informations de mode source et cible retournées ne sont pas disponibles ; par conséquent, les informations cibles dans la structure de chemin d’accès sont définies sur des valeurs par défaut, et les index en mode source et cible sont marqués comme non valides. Pour les requêtes de base de données, si les moniteurs de connexion actuels ont une entrée, QueryDisplayConfig retourne des informations complètes sur le chemin d’accès, le mode source et le mode cible (identiques à celles des chemins d’accès actifs). Toutefois, si la base de données n’a pas d’entrée, QueryDisplayConfig retourne uniquement les informations de chemin avec les détails de la cible par défaut (comme pour les chemins inactifs).

Pour obtenir un exemple de relation entre les informations de mode source et cible et les informations sur le chemin d’accès, consultez Relation des informations de mode aux informations sur le chemin d’accès.

L’appelant peut utiliser DisplayConfigGetDeviceInfo pour obtenir des informations supplémentaires sur l’appareil source ou cible, par exemple, les noms des moniteurs et le mode de surveillance préféré et le nom de l’appareil source.

Si une cible est actuellement en cours de projection forcée, le membre statusFlags de la structure DISPLAYCONFIG_PATH_TARGET_INFO a l’un des indicateurs DISPLAYCONFIG_TARGET_FORCED_XXX définis.

Si l’indicateur QDC_DATABASE_CURRENT est défini dans le paramètre Flags , QueryDisplayConfig retourne l’identificateur de topologie de la topologie de base de données active dans la variable vers laquelle pointe le paramètre pCurrentTopologyId . Si l’indicateur QDC_ALL_PATHS ou QDC_ONLY_ACTIVE_PATHS est défini dans le paramètre Flags , le paramètre pCurrentTopologyId doit avoir la valeur NULL ; sinon, QueryDisplayConfig retourne ERROR_INVALID_PARAMETER.

Si un appelant appelle QueryDisplayConfig avec l’indicateur QDC_DATABASE_CURRENT défini dans le paramètre Flags , QueryDisplayConfig initialise la structure DISPLAYCONFIG_2DREGION spécifiée dans le membre totalSize de la structure DISPLAYCONFIG_VIDEO_SIGNAL_INFO sur zéros et ne termine pas DISPLAYCONFIG_2DREGION.

La structure DEVMODE retournée par la fonction Win32 EnumDisplaySettings (décrite dans la documentation du Kit de développement logiciel (SDK) Windows) contient des informations relatives aux modes source et cible. Toutefois, les API CCD séparent explicitement les composants en mode source et en mode cible.

Moniteurs spécialisés et montés en tête

QueryDisplayConfig et de nombreuses autres API d’affichage Win32 ont une connaissance limitée des moniteurs montés en tête et spécialisés, car ces affichages ne participent pas à l’environnement de bureau Windows. Toutefois, il existe des scénarios où il est nécessaire de comprendre la connectivité de ces affichages (par exemple, les scénarios de protection du contenu). Pour ces scénarios limités, (QDC_INCLUDE_HMD | QDC_ONLY_ACTIVE_PATHS) vous pouvez utiliser pour découvrir la connectivité des affichages montés en tête. Ces chemins d’accès seront marqués avec l’indicateur DISPLAYCONFIG_TARGET_IS_HMD dans le champ DISPLAYCONFIG_PATH_TARGET_INFO.statusFlags . Cette prise en charge a été ajoutée dans la Windows 10 1703 Creators Update.

Virtualisation DPI

Cette API ne participe pas à la virtualisation DPI. Toutes les tailles de la structure DEVMODE sont en pixels physiques et ne sont pas liées au contexte appelant.

Exemples

L’exemple suivant énumère les chemins d’affichage actifs avec QueryDisplayConfig et GetDisplayConfigBufferSizes , et imprime des données pour chaque chemin à l’aide de 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";
    }
}

Configuration requise

   
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 ; OneCoreUAP.lib sur Windows 10
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_MODE_INFO

DISPLAYCONFIG_PATH_INFO

DISPLAYCONFIG_PATH_SOURCE_INFO

DISPLAYCONFIG_PATH_TARGET_INFO

DISPLAYCONFIG_TOPOLOGY_ID

DisplayConfigGetDeviceInfo

SetDisplayConfig