QueryDisplayConfig 函數 （winuser.h）

QueryDisplayConfig 函式會取得目前設定中所有顯示裝置或視圖的所有可能顯示路徑資訊。

語法

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

要取得的資訊類型。 旗標參數的值必須使用以下其中一個值。

旗標參數也可以以以下零個或多個值進行位元或運算。

[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 列舉型別。

currentTopologyId 參數僅在旗標參數值為 QDC_DATABASE_CURRENT 時設定。

若旗標參數值設為 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 在 flags 參數中設定， QueryDisplayConfig 會回傳所有在啟用路徑之後的非活躍路徑。

所有活動路徑的完整路徑、來源模式及目標模式資訊皆可取得。 DISPLAYCONFIG_PATH_SOURCE_INFO 中 ModeInfoIdx 成員，以及來源與目標的 DISPLAYCONFIG_PATH_TARGET_INFO 結構，皆為這些活躍路徑設置。 對於非活躍路徑，回傳的來源與目標模式資訊無法取得;因此，路徑結構中的目標資訊被設定為預設值，且來源與目標模式索引被標記為無效。 對於資料庫查詢，如果目前的連接監控器有條目， QueryDisplayConfig 會回傳完整的路徑、來源模式和目標模式資訊（與主動路徑相同）。 然而，如果資料庫沒有條目， QueryDisplayConfig 只會回傳帶有預設目標細節的路徑資訊（與非活躍路徑相同）。

關於來源模式與目標模式資訊與路徑資訊的關聯範例，請參見 模式資訊與路徑資訊的關係。

呼叫者可使用 DisplayConfigGetDeviceInfo 取得關於來源或目標裝置的額外資訊，例如監視器名稱、監視器偏好模式及來源裝置名稱。

如果目標目前正在被強制投影，DISPLAYCONFIG_PATH_TARGET_INFO結構中的 statusFlags 成員會設定其中一個DISPLAYCONFIG_TARGET_FORCED_XXX旗標。

如果 QDC_DATABASE_CURRENT 旗標設在 Flags 參數中， QueryDisplayConfig 會回傳 currentTopologyId 參數指向的變數中活動資料庫拓撲的拓撲識別碼。 若 QDC_ALL_PATHS 或 QDC_ONLY_ACTIVE_PATHS 旗標設於 Flags 參數中，則 currentTopologyId 參數必須設為 NULL;否則， QueryDisplayConfig 會回傳 ERROR_INVALID_PARAMETER。

如果呼叫者呼叫 QueryDisplayConfig 時，旗標參數中設定了 QDC_DATABASE_CURRENT 標誌，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 和 GetDisplayConfigBufferSizes 的活動顯示路徑，並使用 DisplayConfigGetDeviceInformation 列印出每條路徑的資料。

#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

設定顯示配置