QueryDisplayConfig 函数 （winuser.h）

QueryDisplayConfig 函数检索当前设置中所有显示设备或视图的所有可能显示路径的相关信息。

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

参数

[in] flags

要检索的信息的类型。 flags 参数的值必须使用下列值之一。

标志参数也可能是按位 OR，其中包含以下值中的零个或多个。

[in, out] numPathArrayElements

指向包含 pathArray 中元素数的变量的指针。 此参数不能 NULL。 如果 QueryDisplayConfig 返回ERROR_SUCCESS，则 numPathArrayElements 使用 pathArray 中的有效条目数进行更新。

[out] pathArray

指向包含 DISPLAYCONFIG_PATH_INFO 元素数组的变量的指针。 pathArray 中的每个元素描述从源到目标的单个路径。 源和目标模式信息索引仅与同时为 API 返回的 modeInfoArray 表结合使用。 此参数不能 NULL。 pathArray 始终按路径优先级顺序返回。 有关路径优先级顺序的详细信息，请参阅 路径优先级顺序。

[in, out] numModeInfoArrayElements

指向指定模式信息表中元素中的数字的变量的指针。 此参数不能 NULL。 如果 QueryDisplayConfig 返回ERROR_SUCCESS， 则 numModeInfoArrayElements 将更新 modeInfoArray 中的有效条目数。

[out] modeInfoArray

指向包含 DISPLAYCONFIG_MODE_INFO 元素数组的变量的指针。 此参数不能 NULL。

[out, optional] currentTopologyId

指向接收 CCD 数据库中当前活动拓扑标识符的变量的指针。 有关可能值的列表，请参阅 DISPLAYCONFIG_TOPOLOGY_ID 枚举类型。

仅当标志参数值QDC_DATABASE_CURRENT时，才会设置 currentTopologyId 参数。

如果 标志 参数值设置为QDC_DATABASE_CURRENT， 则 currentTopologyId 参数不得为 NULL。 如果未将 标志 参数值设置为QDC_DATABASE_CURRENT， 则 currentTopologyId 参数值必须为 NULL。

返回值

该函数返回以下返回代码之一。

注解

由于 GetDisplayConfigBufferSizes 函数只能确定特定时间所需的数组大小，因此在调用 GetDisplayConfigBufferSizes 和 QueryDisplayConfig 之间，系统配置将更改，提供的数组大小将不再足以存储新的路径数据。 在这种情况下， QueryDisplayConfig 失败并出现ERROR_INSUFFICIENT_BUFFER，调用方应再次调用 GetDisplayConfigBufferSizes 以获取新的数组大小。 然后，调用方应分配正确的内存量。

QueryDisplayConfig 返回 pathArray 参数指定的路径数组中的路径，以及 modeInfoArray 参数所指定的模式数组中的源和目标模式。 QueryDisplayConfig 始终按路径优先级顺序返回路径。 如果在 标志 参数中设置了 QDC_ALL_PATHS，QueryDisplayConfig 将返回活动路径之后的所有非活动路径。

所有活动路径都提供完整路径、源模式和目标模式信息。 将为这些活动路径设置源和目标DISPLAYCONFIG_PATH_SOURCE_INFO和DISPLAYCONFIG_PATH_TARGET_INFO结构中的 ModeInfoIdx 成员。 对于非活动路径，返回的源和目标模式信息不可用;因此，路径结构中的目标信息设置为默认值，源和目标模式索引标记为无效。 对于数据库查询，如果当前连接监视器具有条目， QueryDisplayConfig 将返回完整路径、源模式和目标模式信息（与活动路径相同）。 但是，如果数据库没有条目， QueryDisplayConfig 仅返回具有默认目标详细信息的路径信息（与非活动路径相同）。

有关源模式和目标模式信息与路径信息的关系的示例，请参阅 模式信息与路径信息的关系。

调用方可以使用 DisplayConfigGetDeviceInfo 获取有关源或目标设备的其他信息，例如监视器名称和监视首选模式和源设备名称。

如果当前正在强制投影目标，则DISPLAYCONFIG_PATH_TARGET_INFO结构的 statusFlags 成员设置了DISPLAYCONFIG_TARGET_FORCED_XXX标志之一。

如果在 Flags 参数中设置了QDC_DATABASE_CURRENT标志， QueryDisplayConfig 会在 currentTopologyId 参数指向的变量中返回活动数据库拓扑的拓扑标识符。 如果在 Flags 参数中设置了 QDC_ALL_PATHS 或 QDC_ONLY_ACTIVE_PATHS 标志，则 currentTopologyId 参数必须设置为 NULL;否则， QueryDisplayConfig 返回ERROR_INVALID_PARAMETER。

如果调用方使用标志参数中设置的 QDC_DATABASE_CURRENT 标志调用 QueryDisplayConfig，QueryDisplayConfig 将初始化在 DISPLAYCONFIG_VIDEO_SIGNAL_INFO 结构的 totalSize 成员中指定的DISPLAYCONFIG_2DREGION结构，并且未完成DISPLAYCONFIG_2DREGION。

由 EnumDisplaySettings Win32 函数（Windows SDK 文档中所述）返回的 DEVMODE 结构包含与源模式和目标模式相关的信息。 但是， CCD API 显式分隔源和目标模式组件。

头部装载和专用监视器

QueryDisplayConfig 和其他许多 Win32 显示 API 对头装载和专用监视器的感知有限，因为这些显示器不参与Windows桌面环境。 但是，在某些情况下，有必要了解这些显示器的连接性（例如内容保护方案）。 对于这些有限的方案， (QDC_INCLUDE_HMD | QDC_ONLY_ACTIVE_PATHS) 可用于发现已装载的显示器的连接。 这些路径将使用 DISPLAYCONFIG_PATH_TARGET_INFO.statusFlags 字段中的 DISPLAYCONFIG_TARGET_IS_HMD 标志进行标记。 Windows 10 1703 创意者更新中添加了此支持。

DPI 虚拟化

此 API 不参与 DPI 虚拟化。 DEVMODE 结构中的所有大小都以物理像素为单位，与调用上下文无关。

示例

以下示例使用 QueryDisplayConfig 和 GetDisplayConfigBufferSize 枚举活动显示路径，并使用 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";
    }
}

要求

另请参阅

DISPLAYCONFIG_MODE_INFO

DISPLAYCONFIG_PATH_INFO

DISPLAYCONFIG_PATH_SOURCE_INFO

DISPLAYCONFIG_PATH_TARGET_INFO

DISPLAYCONFIG_TOPOLOGY_ID

DisplayConfigGetDeviceInfo

SetDisplayConfig