setDisplayConfig 函式 (winuser.h)
SetDisplayConfig函式會藉由在目前會話中獨佔啟用指定的路徑，來修改顯示拓撲、來源和目標模式。
語法
LONG SetDisplayConfig(
[in] UINT32 numPathArrayElements,
[in, optional] DISPLAYCONFIG_PATH_INFO *pathArray,
[in] UINT32 numModeInfoArrayElements,
[in, optional] DISPLAYCONFIG_MODE_INFO *modeInfoArray,
[in] UINT32 flags
);
參數
[in] numPathArrayElements
pathArray中的專案數目。
[in, optional] pathArray
要設定之所有顯示路徑的陣列。 只會設定在此陣列中設定DISPLAYCONFIG_PATH_ACTIVE旗標成員DISPLAYCONFIG_PATH_INFO的路徑。 此參數可以是 Null。 此陣列中作用中路徑出現的順序會決定路徑優先順序。 如需路徑優先順序的詳細資訊，請參閱 路徑優先順序順序。
[in] numModeInfoArrayElements
modeInfoArray中的專案數目。
[in, optional] modeInfoArray
顯示來源和目標模式資訊的陣列 (DISPLAYCONFIG_MODE_INFO) ，DISPLAYCONFIG_PATH_SOURCE_INFO的 modeInfoIdx 成員所參考，以及 pathArray路徑資訊DISPLAYCONFIG_PATH_TARGET_INFO元素所參考。 此參數可以是 Null。
[in] flags
旗標值的位 OR，表示這個函式的行為。 此參數可以是下列其中一個值，或下列值的組合;0 無效。 如需有效旗標組合的描述，請參閱下方。
下列清單包含 Flags 參數的有效值組合：
- 必須設定SDC_APPLY或SDC_VALIDATE，但不能同時設定兩者。
- 必須設定SDC_USE_SUPPLIED_DISPLAY_CONFIG或任何SDC_TOPOLOGY_XXX組合。 SDC_USE_SUPPLIED_DISPLAY_CONFIG無法使用任何SDC_TOPOLOGY_XXX旗標來設定。
- SDC_NO_OPTIMIZATION只能設定SDC_APPLY。
- 允許使用任何其他有效組合SDC_ALLOW_CHANGES。
- SDC_SAVE_TO_DATABASE只能設定SDC_USE_SUPPLIED_DISPLAY_CONFIG。
- SDC_PATH_PERSIST_IF_REQUIRED無法與SDC_USE_SUPPLIED_DISPLAY_CONFIG或SDC_TOPOLOGY_SUPPLIED搭配使用。
- 只有在指定SDC_APPLY和SDC_USE_SUPPLIED_DISPLAY_CONFIG時，SDC_FORCE_MODE_ENUMERATION才有效。
- 只有在指定SDC_TOPOLOGY_SUPPLIED時，才允許SDC_ALLOW_PATH_ORDER_CHANGES。
- SDC_TOPOLOGY_SUPPLIED不能與任何其他SDC_TOPOLOGY_XXX旗標搭配使用。 由於驗證問題，如果呼叫端違反此規則， SetDisplayConfig 就不會失敗。 不過， SetDisplayConfig 會忽略SDC_TOPOLOGY_SUPPLIED旗標。
傳回值
函式會傳回下列其中一個傳回碼。
| 傳回碼 | 描述 |
|---|---|
|
此函數已成功。 |
|
指定的參數和旗標組合無效。 |
|
系統未執行根據 Windows 顯示驅動程式模型所撰寫的圖形驅動程式 ， (WDDM) 。 只有在執行 WDDM 驅動程式的系統上才支援函式。 |
|
呼叫端無法存取主控台會話。 如果呼叫進程無法存取目前的桌面或在遠端會話上執行，就會發生此錯誤。 |
|
發生未指定的錯誤。 |
|
函式找不到呼叫端未指定之來源和目標模式的可運作解決方案。 |
備註
SetDisplayConfig函式會採用具有任何指定來源和目標模式資訊的作用中顯示路徑，並使用最佳模式邏輯來產生任何遺漏的來源和目標模式資訊。 此函式接著會設定完整的顯示路徑。
DISPLAYCONFIG_PATH_SOURCE_INFO和DISPLAYCONFIG_PATH_TARGET_INFO結構中的ModeInfoIdx成員是用來指出是否為指定的使用中路徑提供來源和目標模式。 如果其中一個索引值DISPLAYCONFIG_PATH_MODE_IDX_INVALID，這表示未指定模式資訊。 它適用于路徑加上來源模式，或路徑加上指定路徑的來源和目標模式資訊。 不過，如果路徑加上目標模式沒有來源模式，則無效。
每個來源和目標識別碼的來源和目標模式只能出現在 modeInfoArray 陣列中一次。 例如，來源識別碼 S1 的來源模式只能出現在資料表中一次;如果多個路徑參考相同的來源，則必須使用相同的 ModeInfoIdx。
預期大部分的呼叫端都使用 QueryDisplayConfig 來取得目前的設定以及其他有效的可能性，然後使用 SetDisplayConfig 來測試和設定設定。
使用中路徑出現在 PathArray 陣列中的順序會決定路徑優先順序。
根據預設， SetDisplayConfig 永遠不會變更任何提供的路徑、來源模式或目標模式資訊。 如果最佳模式邏輯在未變更指定的顯示路徑資訊的情況下找不到解決方案， SetDisplayConfig 會因為ERROR_BAD_CONFIGURATION而失敗。 在此情況下，呼叫端應該指定SDC_ALLOW_CHANGES旗標，讓函式調整一些指定的來源和模式詳細資料，以允許顯示路徑變更成功。
如果指定的或計算來源和目標模式具有相同的維度， SetDisplayConfig 會在設定顯示路徑並將它儲存在資料庫中之前，自動將路徑調整設定為DISPLAYCONFIG_PPR_IDENTITY。 如需 SetDisplayConfig 如何處理縮放的資訊，請參閱 調整桌面映射。
當呼叫端指定SDC_USE_SUPPLIED_DISPLAY_CONFIG旗標來設定複製路徑時，如果路徑陣列中有任何來源模式索引無效， SetDisplayConfig 會判斷該來源的所有來源模式索引都無效。 SetDisplayConfig 會使用最佳模式邏輯來判斷來源模式資訊。
除了SDC_TOPOLOGY_SUPPLIED旗標 (，如需SDC_TOPOLOGY_SUPPLIED的詳細資訊，請參閱下列段落) 、SDC_TOPOLOGY_XXX旗標會設定上次顯示路徑設定，包括該拓撲類型的來源和目標模式資訊。 如需有效SDC_TOPOLOGY_XXX旗標組合的詳細資訊，請參閱 Flags 參數描述。 pathArray和modeInfoArray參數必須是Null，且其相關聯的大小必須為零。 例如，如果已設定SDC_TOPOLOGY_CLONE和SDC_TOPOLOGY_EXTEND，此函式會使用最新的複製或擴充顯示路徑組態。 如果要求單一拓撲類型，則會使用該類型的最後一個組態。 如果之前從未設定過該拓撲， SetDisplayConfig 會使用最佳拓撲邏輯來尋找最佳拓撲，然後最佳模式邏輯來尋找要使用的最佳來源和目標模式。 如果已設定拓撲旗標的組合，且其中沒有任何拓撲旗標具有資料庫專案，則會使用下列優先順序。 針對膝上型電腦：複製、擴充、內部和外部;對於桌面而言，優先順序為 extend，然後複製。
呼叫端可以指定SDC_TOPOLOGY_SUPPLIED旗標，指出它只會設定拓撲 (路徑資訊) ，並要求 SetDisplayConfig 取得，然後使用持續性資料庫中的來源和目標模式資訊。 如果呼叫端提供的作用中路徑在持續性資料庫中沒有專案， SetDisplayConfig 就會失敗。 在此情況下，如果呼叫端再次使用相同的路徑資料呼叫 SetDisplayConfig ，但已設定SDC_USE_SUPPLIED_DISPLAY_CONFIG旗標， SetDisplayConfig 會 使用最佳模式邏輯來建立來源和目標模式資訊。 當呼叫端指定SDC_TOPOLOGY_SUPPLIED時，呼叫端必須將 numModeInfoArrayElements 參數設定為零，並將 modeInfoArray 參數設定為 Null;不過，呼叫端必須針對呼叫端所需的路徑資訊設定 pathArray 和 numPathArrayElements 參數。 呼叫端必須將此路徑資料中的所有來源和目標模式索引標示為無效 (DISPLAYCONFIG_PATH_MODE_IDX_INVALID) 。
下表提供一些常見的案例，其中 會呼叫 SetDisplayConfig 以及呼叫端傳遞至 Flags 參數以達成案例的旗標組合。
| 案例 | 旗標組合 |
|---|---|
| 測試電腦上是否支援指定的顯示組態 | SDC_VALIDATE |SDC_USE_SUPPLIED_DISPLAY_CONFIG |
| 設定指定的顯示組態並儲存至資料庫 | SDC_APPLY |SDC_USE_SUPPLIED_DISPLAY_CONFIG |SDC_SAVE_TO_DATABASE |
| 設定暫存顯示組態 (，即不會儲存顯示組態) | SDC_APPLY |SDC_USE_SUPPLIED_DISPLAY_CONFIG |
| 測試電腦上是否支援複製 | SDC_VALIDATE |SDC_TOPOLOGY_CLONE |
| 設定複寫拓撲 | SDC_APPLY |SDC_TOPOLOGY_CLONE |
| 設定複寫拓撲，並在需要滿足要求時允許啟用路徑持續性 | SDC_APPLY |SDC_TOPOLOGY_CLONE |SDC_PATH_PERSIST_IF_REQUIRED |
| 從暫存模式返回上次儲存的顯示組態 | SDC_APPLY|SDC_USE_DATABASE_CURRENT |
| 只指定路徑資訊，請使用來自資料庫的路徑來源和目標資訊來設定顯示組態，並忽略路徑順序 | SDC_APPLY |SDC_TOPOLOGY_SUPPLIED |SDC_ALLOW_PATH_ORDER_CHANGES |
DPI 虛擬化
此 API 不會參與 DPI 虛擬化。 DEVMODE 結構中的所有大小都是以實體圖元為根據，而且與呼叫內容無關。規格需求
| 最低支援的用戶端 | 適用于 Windows 7 和更新版本的 Windows 作業系統。 |
| 目標平台 | Universal |
| 標頭 | winuser.h (包含 Windows.h) |
| 程式庫 | User32.lib |
| Dll | User32.dll |
| API 集合 | ext-ms-win-ntuser-sysparams-ext-l1-1-1 (于 Windows 10 10.0.14393 版) |
另請參閱
DISPLAYCONFIG_PATH_SOURCE_INFO