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
);
參數
[in] flags
要擷取的資訊類型。 Flags參數的值必須使用下列其中一個值。
Flags參數也可以以零或多個下列值位 OR。
[in, out] numPathArrayElements
變數的指標，其中包含 pPathInfoArray中的專案數目。 此參數不可為 Null。 如果 QueryDisplayConfig 傳回ERROR_SUCCESS， pNumPathInfoElements 會以 pPathInfoArray中的有效專案數目更新。
[out] pathArray
包含 DISPLAYCONFIG_PATH_INFO 元素陣列之變數的指標。 pPathInfoArray中的每個元素都會描述從來源到目標的單一路徑。 來源和目標模式資訊索引只能與同時針對 API 傳回的 pmodeInfoArray 資料表搭配使用。 此參數不可為 Null。 pPathInfoArray一律會以路徑優先順序傳回。 如需路徑優先順序的詳細資訊，請參閱 路徑優先順序順序。
[in, out] numModeInfoArrayElements
變數的指標，指定模式資訊資料表元素中的數位。 此參數不可為 Null。 如果 QueryDisplayConfig 傳回ERROR_SUCCESS， pNumModeInfoArrayElements 會以 pModeInfoArray中的有效專案數目更新。
[out] modeInfoArray
包含 DISPLAYCONFIG_MODE_INFO 專案陣列之變數的指標。 此參數不可為 Null。
[out, optional] currentTopologyId
接收 CCD 資料庫中目前使用中拓撲識別碼的變數指標。 如需可能值的清單，請參閱 DISPLAYCONFIG_TOPOLOGY_ID 列舉類型。
只有在Flags參數值QDC_DATABASE_CURRENT時，才會設定pCurrentTopologyId參數。
如果 Flags 參數值設定為 QDC_DATABASE_CURRENT， pCurrentTopologyId 參數不得為 Null。 如果 Flags 參數值未設定為 QDC_DATABASE_CURRENT， pCurrentTopologyId 參數值必須是 Null。
傳回值
函式會傳回下列其中一個傳回碼。
| 傳回碼 | 描述 |
|---|---|
|
此函數已成功。 |
|
指定之參數和旗標的組合無效。 |
|
系統未執行根據 Windows 顯示驅動程式模型所撰寫的圖形驅動程式 ， (WDDM) 。 只有在執行 WDDM 驅動程式的系統上才支援函式。 |
|
呼叫端無法存取主控台會話。 如果呼叫進程無法存取目前的桌面或在遠端會話上執行，就會發生此錯誤。 |
|
發生未指定的錯誤。 |
|
提供的路徑和模式緩衝區太小。 |
備註
由於 GetDisplayConfigBufferSizes 函 式只能判斷特定時間點所需的陣列大小，因此在 呼叫 GetDisplayConfigBufferSizes 和 QueryDisplayConfig 之間，系統組態將會變更，而且提供的陣列大小將不再足以儲存新的路徑資料。 在此情況下， QueryDisplayConfig 會因為ERROR_INSUFFICIENT_BUFFER而失敗，而呼叫端應該再次呼叫 GetDisplayConfigBufferSizes 以取得新的陣列大小。 接著，呼叫端應該配置正確的記憶體數量。
QueryDisplayConfig 會傳回 pPathInfoArray 參數所指定之路徑陣列中的路徑，以及 pModeInfoArray 參數所指定模式陣列中的來源和目標模式。 QueryDisplayConfig 一律會以路徑優先順序傳回路徑。 如果在 Flags 參數中設定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 會在 pCurrentTopologyId 參數指向的變數中傳回使用中資料庫拓撲的拓撲識別碼。 如果在 Flags 參數中設定QDC_ALL_PATHS或QDC_ONLY_ACTIVE_PATHS旗標， pCurrentTopologyId 參數必須設定為 Null;否則， QueryDisplayConfig 會傳回ERROR_INVALID_PARAMETER。
如果呼叫端使用Flags參數中設定的 QDC_DATABASE_CURRENT 旗標呼叫QueryDisplayConfig，則 QueryDisplayConfig會將DISPLAYCONFIG_VIDEO_SIGNAL_INFO結構totalSize成員中指定的DISPLAYCONFIG_2DREGION結構初始化為零，且未完成DISPLAYCONFIG_2DREGION。
EnumDisplaySettings Win32 函式所傳回的 DEVMODE 結構 (Windows SDK 檔) 包含與來源和目標模式相關的資訊。 不過， 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 Creators Update 中新增。
DPI 虛擬化
此 API 不會參與 DPI 虛擬化。 DEVMODE 結構中的所有大小都是以實體圖元為根據，而且與呼叫內容無關。
範例
下列範例會列舉 使用 QueryDisplayConfig 和 GetDisplayConfigBufferSizes 的作用中顯示路徑，並使用 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";
}
}
規格需求
| 最低支援的用戶端 | 適用于 Windows 7 和更新版本的 Windows 作業系統。 |
| 目標平台 | Universal |
| 標頭 | winuser.h (包含 Windows.h) |
| 程式庫 | User32.lib;Windows 10 上的 OneCoreUAP.lib |
| Dll | User32.dll |
| API 集合 | ext-ms-win-ntuser-sysparams-ext-l1-1-1 (于 Windows 10 10.0.14393 版) |
另請參閱
DISPLAYCONFIG_PATH_SOURCE_INFO