Fungsi ReadConsoleOutput

Artikel
10/23/2023

Penting

Dokumen ini menjelaskan fungsionalitas platform konsol yang tidak lagi menjadi bagian dari peta jalan ekosistem kami. Kami tidak menyarankan penggunaan konten ini dalam produk baru, tetapi kami akan terus mendukung penggunaan yang ada untuk masa depan yang tidak terbatas. Solusi modern pilihan kami berfokus pada urutan terminal virtual untuk kompatibilitas maksimum dalam skenario lintas platform. Anda dapat menemukan informasi selengkapnya tentang keputusan desain ini di konsol klasik vs. dokumen terminal virtual kami.

Membaca data atribut karakter dan warna dari blok persegi panjang sel karakter dalam buffer layar konsol, dan fungsi menulis data ke blok persegi panjang di lokasi tertentu di buffer tujuan.

Sintaks

BOOL WINAPI ReadConsoleOutput(
  _In_    HANDLE      hConsoleOutput,
  _Out_   PCHAR_INFO  lpBuffer,
  _In_    COORD       dwBufferSize,
  _In_    COORD       dwBufferCoord,
  _Inout_ PSMALL_RECT lpReadRegion
);

Parameter

hConsoleOutput [in]
Handel ke buffer layar konsol. Handel harus memiliki akses GENERIC_READ yang tepat. Untuk informasi selengkapnya, lihat Keamanan dan Hak Akses Buffer Konsol.

lpBuffer [keluar]
Penunjuk ke buffer tujuan yang menerima data yang dibaca dari buffer layar konsol. Pointer ini diperlakukan sebagai asal array dua dimensi struktur CHAR_INFO yang ukurannya ditentukan oleh parameter dwBufferSize .

dwBufferSize [in]
Ukuran parameter lpBuffer , dalam sel karakter. Anggota X dari struktur COORD adalah jumlah kolom; anggota Y adalah jumlah baris.

dwBufferCoord [in]
Koordinat sel kiri atas dalam parameter lpBuffer yang menerima data yang dibaca dari buffer layar konsol. Anggota X dari struktur COORD adalah kolom , dan anggota Y adalah baris .

lpReadRegion [masuk, keluar]
Penunjuk ke struktur SMALL_RECT. Pada input, anggota struktur menentukan koordinat kiri atas dan kanan bawah persegi panjang buffer layar konsol tempat fungsi akan dibaca. Pada output, anggota struktur menentukan persegi panjang aktual yang digunakan.

Nilai hasil

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

ReadConsoleOutput memperlakukan buffer layar konsol dan buffer tujuan sebagai array dua dimensi (kolom dan baris sel karakter). Persegi panjang yang diarahkan oleh parameter lpReadRegion menentukan ukuran dan lokasi blok yang akan dibaca dari buffer layar konsol. Persegi panjang tujuan dengan ukuran yang sama terletak dengan sel kiri atasnya pada koordinat parameter dwBufferCoord dalam array lpBuffer . Data yang dibaca dari sel di persegi panjang sumber buffer layar konsol disalin ke sel yang sesuai di buffer tujuan. Jika sel yang sesuai berada di luar batas persegi panjang buffer tujuan (yang dimensinya ditentukan oleh parameter dwBufferSize ), data tidak disalin.

Sel di buffer tujuan yang sesuai dengan koordinat yang tidak berada dalam batas buffer layar konsol dibiarkan tidak berubah. Dengan kata lain, ini adalah sel yang data buffer layarnya tidak tersedia untuk dibaca.

Sebelum ReadConsoleOutput kembali, readConsoleOutput mengatur anggota struktur yang diarahkan oleh parameter lpReadRegion ke persegi panjang buffer layar aktual yang selnya disalin ke buffer tujuan. Persegi panjang ini mencerminkan sel dalam persegi panjang sumber yang ada sel yang sesuai di buffer tujuan, karena ReadConsoleOutput mengklip dimensi persegi panjang sumber agar pas dengan batas buffer layar konsol.

Jika persegi panjang yang ditentukan oleh lpReadRegion sepenuhnya berada di luar batas buffer layar konsol, atau jika persegi panjang yang sesuai diposisikan sepenuhnya di luar batas buffer tujuan, tidak ada data yang disalin. Dalam hal ini, fungsi kembali dengan anggota struktur yang ditujukkan oleh parameter lpReadRegion yang diatur sed sehingga anggota Kanan kurang dari Kiri, atau anggota Bawah kurang dari Atas. Untuk menentukan ukuran buffer layar konsol, gunakan fungsi GetConsoleScreenBufferInfo.

Fungsi ReadConsoleOutput tidak berpengaruh pada posisi kursor buffer layar konsol. Konten buffer layar konsol tidak diubah oleh fungsi .

Fungsi ini menggunakan karakter Unicode atau karakter 8-bit dari halaman kode konsol saat ini. Halaman kode konsol default awalnya ke halaman kode OEM sistem. Untuk mengubah halaman kode konsol, gunakan fungsi SetConsoleCP atau SetConsoleOutputCP. Konsumen warisan juga dapat menggunakan perintah chcp atau mode con cp select= , tetapi tidak disarankan untuk pengembangan baru.

Tip

API ini tidak disarankan dan tidak memiliki terminal virtual yang setara. Keputusan ini sengaja menyelaraskan platform Windows dengan sistem operasi lain di mana aplikasi klien individu diharapkan untuk mengingat status yang ditarik sendiri untuk manipulasi lebih lanjut. Aplikasi jarak jauh melalui utilitas lintas platform dan transportasi seperti SSH mungkin tidak berfungsi seperti yang diharapkan jika menggunakan API ini.

Contoh

Misalnya, lihat Membaca dan Menulis Blok Karakter dan Atribut.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Header	ConsoleApi2.h (melalui WinCon.h, termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll
Nama Unicode dan ANSI	ReadConsoleOutputW (Unicode) dan ReadConsoleOutputA (ANSI)

Bagikan melalui