Fungsi QueryDisplayConfig (winuser.h)
Fungsi QueryDisplayConfig mengambil informasi tentang semua jalur tampilan yang mungkin untuk semua perangkat tampilan, atau tampilan, dalam pengaturan saat ini.
Sintaks
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
);
Parameter
[in] flags
Jenis informasi yang akan diambil. Nilai untuk parameter Bendera harus menggunakan salah satu nilai berikut.
Parameter Bendera mungkin juga bitwise OR'ed dengan nol atau lebih dari nilai berikut.
[in, out] numPathArrayElements
Penunjuk ke variabel yang berisi jumlah elemen dalam pPathInfoArray. Parameter ini tidak boleh NULL. Jika QueryDisplayConfig mengembalikan ERROR_SUCCESS, pNumPathInfoElements diperbarui dengan jumlah entri yang valid di pPathInfoArray.
[out] pathArray
Penunjuk ke variabel yang berisi array elemen DISPLAYCONFIG_PATH_INFO . Setiap elemen dalam pPathInfoArray menjelaskan satu jalur dari sumber ke target. Indeks informasi mode sumber dan target hanya valid dalam kombinasi dengan tabel pmodeInfoArray yang dikembalikan untuk API secara bersamaan. Parameter ini tidak boleh NULL. pPathInfoArray selalu dikembalikan dalam urutan prioritas jalur. Untuk informasi selengkapnya tentang urutan prioritas jalur, lihat Urutan Prioritas Jalur.
[in, out] numModeInfoArrayElements
Penunjuk ke variabel yang menentukan angka dalam elemen tabel informasi mode. Parameter ini tidak boleh NULL. Jika QueryDisplayConfig mengembalikan ERROR_SUCCESS, pNumModeInfoArrayElements diperbarui dengan jumlah entri yang valid di pModeInfoArray.
[out] modeInfoArray
Penunjuk ke variabel yang berisi array elemen DISPLAYCONFIG_MODE_INFO . Parameter ini tidak boleh NULL.
[out, optional] currentTopologyId
Penunjuk ke variabel yang menerima pengidentifikasi topologi aktif saat ini dalam database CCD. Untuk daftar nilai yang mungkin, lihat jenis DISPLAYCONFIG_TOPOLOGY_ID yang dijumlahkan.
Parameter pCurrentTopologyId hanya diatur saat nilai parameter Bendera QDC_DATABASE_CURRENT.
Jika nilai parameter Bendera diatur ke QDC_DATABASE_CURRENT, parameter pCurrentTopologyId tidak boleh NULL. Jika nilai parameter Bendera tidak diatur ke QDC_DATABASE_CURRENT, nilai parameter pCurrentTopologyId harus NULL.
Mengembalikan nilai
Fungsi mengembalikan salah satu kode pengembalian berikut.
| Menampilkan kode | Deskripsi |
|---|---|
|
Fungsi berhasil. |
|
Kombinasi parameter dan bendera yang ditentukan tidak valid. |
|
Sistem tidak menjalankan pengandar grafis yang ditulis sesuai dengan Windows Display Driver Model (WDDM). Fungsi ini hanya didukung pada sistem dengan driver WDDM yang berjalan. |
|
Pemanggil tidak memiliki akses ke sesi konsol. Kesalahan ini terjadi jika proses panggilan tidak memiliki akses ke desktop saat ini atau sedang berjalan pada sesi jarak jauh. |
|
Terjadi kesalahan yang tidak ditentukan. |
|
Jalur yang disediakan dan buffer mode terlalu kecil. |
Keterangan
Karena fungsi GetDisplayConfigBufferSizes hanya dapat menentukan ukuran array yang diperlukan pada saat tertentu, ada kemungkinan bahwa antara panggilan ke GetDisplayConfigBufferSizes dan QueryDisplayConfig konfigurasi sistem akan berubah dan ukuran array yang disediakan tidak akan cukup lagi untuk menyimpan data jalur baru. Dalam situasi ini, QueryDisplayConfig gagal dengan ERROR_INSUFFICIENT_BUFFER, dan pemanggil harus memanggil GetDisplayConfigBufferSizes lagi untuk mendapatkan ukuran array baru. Pemanggil kemudian harus mengalokasikan jumlah memori yang benar.
QueryDisplayConfig mengembalikan jalur dalam array jalur yang ditentukan parameter pPathInfoArray dan mode sumber dan target dalam array mode yang ditentukan parameter pModeInfoArray . QueryDisplayConfig selalu mengembalikan jalur dalam urutan prioritas jalur. Jika QDC_ALL_PATHS diatur dalam parameter Bendera , QueryDisplayConfig mengembalikan semua jalur yang tidak aktif setelah jalur aktif.
Jalur lengkap, mode sumber, dan informasi mode target tersedia untuk semua jalur aktif. Anggota ModeInfoIdx dalam struktur DISPLAYCONFIG_PATH_SOURCE_INFO dan DISPLAYCONFIG_PATH_TARGET_INFO untuk sumber dan target disiapkan untuk jalur aktif ini. Untuk jalur yang tidak aktif, informasi mode sumber dan target yang dikembalikan tidak tersedia; oleh karena itu, informasi target dalam struktur jalur diatur ke nilai default, dan indeks mode sumber dan target ditandai sebagai tidak valid. Untuk kueri database, jika monitor koneksi saat ini memiliki entri, QueryDisplayConfig mengembalikan jalur lengkap, mode sumber, dan informasi mode target (sama seperti untuk jalur aktif). Namun, jika database tidak memiliki entri, QueryDisplayConfig hanya mengembalikan informasi jalur dengan detail target default (sama seperti untuk jalur yang tidak aktif).
Untuk contoh bagaimana informasi mode sumber dan target terkait dengan informasi jalur, lihat Hubungan Informasi Mode ke Informasi Jalur.
Pemanggil dapat menggunakan DisplayConfigGetDeviceInfo untuk mendapatkan informasi tambahan tentang perangkat sumber atau target, misalnya, nama monitor dan memantau mode pilihan dan nama perangkat sumber.
Jika target saat ini sedang diproyeksikan paksa, anggota statusFlags dari struktur DISPLAYCONFIG_PATH_TARGET_INFO memiliki salah satu bendera DISPLAYCONFIG_TARGET_FORCED_XXX yang ditetapkan.
Jika bendera QDC_DATABASE_CURRENT diatur dalam parameter Bendera , QueryDisplayConfig mengembalikan pengidentifikasi topologi topologi database aktif dalam variabel yang ditunjukkan parameter pCurrentTopologyId . Jika bendera QDC_ALL_PATHS atau QDC_ONLY_ACTIVE_PATHS diatur dalam parameter Bendera , parameter pCurrentTopologyId harus diatur ke NULL; jika tidak, QueryDisplayConfig mengembalikan ERROR_INVALID_PARAMETER.
Jika penelepon memanggil QueryDisplayConfig dengan bendera QDC_DATABASE_CURRENT yang diatur dalam parameter Bendera , QueryDisplayConfig menginisialisasi struktur DISPLAYCONFIG_2DREGION yang ditentukan dalam anggota totalSize dari struktur DISPLAYCONFIG_VIDEO_SIGNAL_INFO ke nol dan tidak menyelesaikan DISPLAYCONFIG_2DREGION.
Struktur DEVMODE yang dikembalikan oleh fungsi EnumDisplaySettings Win32 (dijelaskan dalam dokumentasi Windows SDK) berisi informasi yang berkaitan dengan mode sumber dan target. Namun, API CCD secara eksplisit memisahkan komponen mode sumber dan target.
Monitor yang dipasang di kepala dan khusus
QueryDisplayConfig dan banyak API tampilan Win32 lainnya memiliki kesadaran terbatas tentang monitor yang dipasang di kepala dan khusus, karena tampilan tersebut tidak berpartisipasi dalam lingkungan desktop Windows. Namun, ada skenario di mana perlu untuk memahami konektivitas tampilan ini (misalnya skenario perlindungan konten). Untuk skenario terbatas ini, (QDC_INCLUDE_HMD | QDC_ONLY_ACTIVE_PATHS) dapat digunakan untuk menemukan konektivitas tampilan yang dipasang di kepala. Jalur ini akan ditandai dengan bendera DISPLAYCONFIG_TARGET_IS_HMD di bidang DISPLAYCONFIG_PATH_TARGET_INFO.statusFlags . Dukungan ini ditambahkan dalam Windows 10 1703 Creators Update.
Virtualisasi DPI
API ini tidak berpartisipasi dalam virtualisasi DPI. Semua ukuran dalam struktur DEVMODE berada dalam hal piksel fisik, dan tidak terkait dengan konteks panggilan.
Contoh
Contoh berikut menghitung jalur tampilan aktif dengan QueryDisplayConfig dan GetDisplayConfigBufferSizes dan mencetak data untuk setiap jalur menggunakan 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";
}
}
Persyaratan
| Klien minimum yang didukung | Tersedia di Windows 7 dan versi yang lebih baru dari sistem operasi Windows. |
| Target Platform | Universal |
| Header | winuser.h (termasuk Windows.h) |
| Pustaka | User32.lib; OneCoreUAP.lib di Windows 10 |
| DLL | User32.dll |
| Set API | ext-ms-win-ntuser-sysparams-ext-l1-1-1 (diperkenalkan dalam Windows 10, versi 10.0.14393) |
Lihat juga
DISPLAYCONFIG_PATH_SOURCE_INFO