QueryDisplayConfig function (winuser.h)

The QueryDisplayConfig function retrieves information about all possible display paths for all display devices, or views, in the current setting.

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

Parameters

[in] flags

The type of information to retrieve. The value for the Flags parameter must use one of the following values.

The Flags parameter may also be bitwise OR'ed with zero or more of the following values.

[in, out] numPathArrayElements

Pointer to a variable that contains the number of elements in pPathInfoArray. This parameter cannot be NULL. If QueryDisplayConfig returns ERROR_SUCCESS, pNumPathInfoElements is updated with the number of valid entries in pPathInfoArray.

[out] pathArray

Pointer to a variable that contains an array of DISPLAYCONFIG_PATH_INFO elements. Each element in pPathInfoArray describes a single path from a source to a target. The source and target mode information indexes are only valid in combination with the pmodeInfoArray tables that are returned for the API at the same time. This parameter cannot be NULL. The pPathInfoArray is always returned in path priority order. For more information about path priority order, see Path Priority Order.

[in, out] numModeInfoArrayElements

Pointer to a variable that specifies the number in element of the mode information table. This parameter cannot be NULL. If QueryDisplayConfig returns ERROR_SUCCESS, pNumModeInfoArrayElements is updated with the number of valid entries in pModeInfoArray.

[out] modeInfoArray

Pointer to a variable that contains an array of DISPLAYCONFIG_MODE_INFO elements. This parameter cannot be NULL.

[out, optional] currentTopologyId

Pointer to a variable that receives the identifier of the currently active topology in the CCD database. For a list of possible values, see the DISPLAYCONFIG_TOPOLOGY_ID enumerated type.

The pCurrentTopologyId parameter is only set when the Flags parameter value is QDC_DATABASE_CURRENT.

If the Flags parameter value is set to QDC_DATABASE_CURRENT, the pCurrentTopologyId parameter must not be NULL. If the Flags parameter value is not set to QDC_DATABASE_CURRENT, the pCurrentTopologyId parameter value must be NULL.

Return value

The function returns one of the following return codes.

Remarks

As the GetDisplayConfigBufferSizes function can only determine the required array size at a particular moment in time, it is possible that between calls to GetDisplayConfigBufferSizes and QueryDisplayConfig the system configuration will change and the provided array sizes will no longer be sufficient to store the new path data. In this situation, QueryDisplayConfig fails with ERROR_INSUFFICIENT_BUFFER, and the caller should call GetDisplayConfigBufferSizes again to get the new array sizes. The caller should then allocate the correct amount of memory.

QueryDisplayConfig returns paths in the path array that the pPathInfoArray parameter specifies and the source and target modes in the mode array that the pModeInfoArray parameter specifies. QueryDisplayConfig always returns paths in path priority order. If QDC_ALL_PATHS is set in the Flags parameter, QueryDisplayConfig returns all the inactive paths after the active paths.

Full path, source mode, and target mode information is available for all active paths. The ModeInfoIdx members in the DISPLAYCONFIG_PATH_SOURCE_INFO and DISPLAYCONFIG_PATH_TARGET_INFO structures for the source and target are set up for these active paths. For inactive paths, returned source and target mode information is not available; therefore, the target information in the path structure is set to default values, and the source and target mode indexes are marked as invalid. For database queries, if the current connect monitors have an entry, QueryDisplayConfig returns full path, source mode, and target mode information (same as for active paths). However, if the database does not have a entry, QueryDisplayConfig returns just the path information with the default target details (same as for inactive paths).

For an example of how source and target mode information relates to path information, see Relationship of Mode Information to Path Information.

The caller can use DisplayConfigGetDeviceInfo to obtain additional information about the source or target device, for example, the monitor names and monitor preferred mode and source device name.

If a target is currently being force projected, the statusFlags member of the DISPLAYCONFIG_PATH_TARGET_INFO structure has one of the DISPLAYCONFIG_TARGET_FORCED_XXX flags set.

If the QDC_DATABASE_CURRENT flag is set in the Flags parameter, QueryDisplayConfig returns the topology identifier of the active database topology in the variable that the pCurrentTopologyId parameter points to. If the QDC_ALL_PATHS or QDC_ONLY_ACTIVE_PATHS flag is set in the Flags parameter, the pCurrentTopologyId parameter must be set to NULL; otherwise, QueryDisplayConfig returns ERROR_INVALID_PARAMETER.

If a caller calls QueryDisplayConfig with the QDC_DATABASE_CURRENT flag set in the Flags parameter, QueryDisplayConfig initializes the DISPLAYCONFIG_2DREGION structure that is specified in the totalSize member of the DISPLAYCONFIG_VIDEO_SIGNAL_INFO structure to zeros and does not complete DISPLAYCONFIG_2DREGION.

The DEVMODE structure that is returned by the EnumDisplaySettings Win32 function (described in the Windows SDK documentation) contains information that relates to both the source and target modes. However, the CCD APIs explicitly separate the source and target mode components.

Head-mounted and specialized monitors

QueryDisplayConfig and many other Win32 display APIs have limited awareness of head-mounted and specialized monitors, since those displays do not participate in the Windows desktop environment. However, there are scenarios where it's necessary to understand the connectivity of these displays (e.g. content protection scenarios). For these limited scenarios, (QDC_INCLUDE_HMD | QDC_ONLY_ACTIVE_PATHS) can be used to discover the connectivity of head-mounted displays. These paths will be marked with the the DISPLAYCONFIG_TARGET_IS_HMD flag in the DISPLAYCONFIG_PATH_TARGET_INFO.statusFlags field. This support was added in the Windows 10 1703 Creators Update.

DPI virtualization

This API does not participate in DPI virtualization. All sizes in the DEVMODE structure are in terms of physical pixels, and are not related to the calling context.

Examples

The following example enumerates active display paths with QueryDisplayConfig and GetDisplayConfigBufferSizes and prints out data for each path using 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";
    }
}

Requirements

See also

DISPLAYCONFIG_MODE_INFO

DISPLAYCONFIG_PATH_INFO

DISPLAYCONFIG_PATH_SOURCE_INFO

DISPLAYCONFIG_PATH_TARGET_INFO

DISPLAYCONFIG_TOPOLOGY_ID

DisplayConfigGetDeviceInfo

SetDisplayConfig