Fungsi GetStdHandle
Mengambil handel ke perangkat standar yang ditentukan (input standar, output standar, atau kesalahan standar).
Sintaks
HANDLE WINAPI GetStdHandle(
_In_ DWORD nStdHandle
);
Parameter
nStdHandle [in]
Perangkat standar. Parameter ini bisa menjadi salah satu nilai berikut.
| Value | Makna |
|---|---|
STD_INPUT_HANDLE((DWORD)-10) |
Perangkat input standar. Awalnya, ini adalah buffer input konsol, CONIN$. |
STD_OUTPUT_HANDLE((DWORD)-11) |
Perangkat output standar. Awalnya, ini adalah buffer layar konsol aktif, CONOUT$. |
STD_ERROR_HANDLE((DWORD)-12) |
Perangkat kesalahan standar. Awalnya, ini adalah buffer layar konsol aktif, CONOUT$. |
Catatan
Nilai untuk konstanta ini adalah angka yang tidak ditandatangani, tetapi didefinisikan dalam file header sebagai cast dari nomor yang ditandatangani dan memanfaatkan kompiler C yang menggulirkannya ke tepat di bawah nilai maksimum 32-bit. Saat berinteraksi dengan handel ini dalam bahasa yang tidak mengurai header dan menentukan ulang konstanta, harap waspadai batasan ini. Sebagai contoh, ((DWORD)-10) sebenarnya adalah angka 4294967286yang tidak ditandatangani .
Nilai hasil
Jika fungsi berhasil, nilai pengembalian adalah handel ke perangkat yang ditentukan, atau handel yang dialihkan yang diatur oleh panggilan sebelumnya ke SetStdHandle. Handel ini memiliki hak akses GENERIC_READ dan GENERIC_WRITE , kecuali aplikasi telah menggunakan SetStdHandle untuk mengatur handel standar dengan akses yang lebih rendah.
Tip
Tidak diperlukan untuk membuang handel ini dengan CloseHandle setelah selesai. Lihat Keterangan untuk informasi selengkapnya.
Jika fungsi gagal, nilai yang dikembalikan adalah INVALID_HANDLE_VALUE. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.
Jika aplikasi tidak memiliki handel standar terkait, seperti layanan yang berjalan di desktop interaktif, dan belum mengalihkannya, nilai yang dikembalikan adalah NULL.
Keterangan
Handel yang dikembalikan oleh GetStdHandle dapat digunakan oleh aplikasi yang perlu membaca dari atau menulis ke konsol. Saat konsol dibuat, handel input standar adalah handel ke buffer input konsol, dan output standar dan handel kesalahan standar adalah handel dari buffer layar aktif konsol. Handel ini dapat digunakan oleh fungsi ReadFile dan WriteFile, atau oleh salah satu fungsi konsol yang mengakses buffer input konsol atau buffer layar (misalnya, fungsi ReadConsoleInput, WriteConsole, atau GetConsoleScreenBufferInfo).
Handel standar proses dapat dialihkan oleh panggilan ke SetStdHandle, dalam hal ini GetStdHandle mengembalikan handel yang dialihkan. Jika handel standar telah dialihkan, Anda dapat menentukan CONIN$ nilai dalam panggilan ke fungsi CreateFile untuk mendapatkan handel ke buffer input konsol. Demikian pula, Anda dapat menentukan CONOUT$ nilai untuk mendapatkan handel ke buffer layar aktif konsol.
Handel standar proses pada entri metode utama ditentukan oleh konfigurasi bendera /SUBSYSTEM yang diteruskan ke linker ketika aplikasi dibuat. Menentukan permintaan /SUBSYSTEM:CONSOLE bahwa sistem operasi mengisi handel dengan sesi konsol saat startup, jika induk belum mengisi tabel handle standar berdasarkan pewarisan. Sebaliknya, /SUBSYSTEM:WINDOWS menyiratkan bahwa aplikasi tidak memerlukan konsol dan kemungkinan tidak akan menggunakan handel standar. Informasi selengkapnya tentang pewarisan penanganan dapat ditemukan dalam dokumentasi untuk STARTF_USESTDHANDLES.
Beberapa aplikasi beroperasi di luar batas subsistem yang dinyatakan; misalnya, aplikasi /SUBSYSTEM:WINDOWS mungkin memeriksa/menggunakan handel standar untuk tujuan pengelogan atau penelusuran kesalahan tetapi beroperasi secara normal dengan antarmuka pengguna grafis. Aplikasi ini harus hati-hati memeriksa status handel standar pada startup dan menggunakan AttachConsole, AllocConsole, dan FreeConsole untuk menambahkan/menghapus konsol jika diinginkan.
Beberapa aplikasi juga dapat memvariasikan perilakunya pada jenis handel yang diwariskan. Membedakan jenis antara konsol, pipa, file, dan lainnya dapat dilakukan dengan GetFileType.
Menangani pembuangan
Tidak diperlukan untuk CloseHandle setelah selesai dengan handel yang diambil dari GetStdHandle. Nilai yang dikembalikan hanyalah salinan nilai yang disimpan dalam tabel proses. Proses itu sendiri umumnya dianggap sebagai pemilik handel ini dan masa pakainya. Setiap handel ditempatkan dalam tabel pada pembuatan tergantung pada warisan dan meluncurkan spesifik panggilan CreateProcess dan akan dibebaskan ketika proses dihancurkan.
Manipulasi manual masa pakai handel ini mungkin diinginkan untuk aplikasi yang sengaja mencoba menggantinya atau memblokir bagian lain dari proses menggunakannya. Sebagai dapat di-cache dengan menjalankan kode, kode tersebut tidak akan selalu mengambil perubahan yang HANDLE dilakukan melalui SetStdHandle. Menutup handel secara eksplisit melalui CloseHandle akan menutupnya di seluruh proses dan penggunaan referensi cache berikutnya akan mengalami kesalahan.
Panduan untuk mengganti handel standar dalam tabel proses adalah mendapatkan yang ada HANDLE dari tabel dengan GetStdHandle, gunakan SetStdHandle untuk menempatkan baru HANDLE di yang dibuka dengan CreateFile (atau fungsi serupa), lalu untuk menutup handel yang diambil.
Tidak ada validasi nilai yang disimpan sebagai handel dalam tabel proses dengan fungsi GetStdHandle atau SetStdHandle . Validasi dilakukan pada saat operasi baca/tulis aktual seperti ReadFile atau WriteFile.
Lampirkan/lepaskan perilaku
Saat melampirkan ke konsol baru, handel standar selalu diganti dengan handel konsol kecuali STARTF_USESTDHANDLES ditentukan selama pembuatan proses.
Jika nilai handel standar yang ada adalah NULL, atau nilai handel standar yang ada terlihat seperti pseudohandle konsol, handel diganti dengan handel konsol.
Ketika induk menggunakan CREATE_NEW_CONSOLE dan STARTF_USESTDHANDLES untuk membuat proses konsol, handel standar tidak akan diganti kecuali nilai handel standar yang ada adalah NULL atau pseudohandle konsol.
Catatan
Proses konsol harus dimulai dengan handel standar yang diisi atau akan diisi secara otomatis dengan handel yang sesuai ke konsol baru. Aplikasi antarmuka pengguna grafis (GUI) dapat dimulai tanpa handel standar dan tidak akan diisi secara otomatis.
Contoh
Misalnya, lihat Membaca Peristiwa Buffer Input.
Persyaratan
| Klien minimum yang didukung | Windows 2000 Professional [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows 2000 Server [hanya aplikasi desktop] |
| Header | ProcessEnv.h (melalui Winbase.h, sertakan Windows.h) |
| Pustaka | Kernel32.lib |
| DLL | Kernel32.dll |
Baca juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk