Fungsi InitiateSystemShutdownExW (winreg.h)
Memulai pematian dan mulai ulang opsional komputer yang ditentukan, dan secara opsional merekam alasan pematian.
Sintaks
BOOL InitiateSystemShutdownExW(
[in, optional] LPWSTR lpMachineName,
[in, optional] LPWSTR lpMessage,
[in] DWORD dwTimeout,
[in] BOOL bForceAppsClosed,
[in] BOOL bRebootAfterShutdown,
[in] DWORD dwReason
);
Parameter
[in, optional] lpMachineName
Nama jaringan komputer yang akan dimatikan. Jika lpMachineName adalah NULL atau string kosong, fungsi akan mematikan komputer lokal.
[in, optional] lpMessage
Pesan yang akan ditampilkan dalam kotak dialog matikan. Parameter ini bisa NULL jika tidak ada pesan yang diperlukan.
Windows Server 2003 dan Windows XP: String ini juga disimpan sebagai komentar dalam entri log peristiwa.
Windows Server 2003 dan Windows XP dengan SP1: String dibatasi hingga 3072 TCHAR.
[in] dwTimeout
Durasi waktu kotak dialog matikan harus ditampilkan, dalam hitungan detik. Saat kotak dialog ini ditampilkan, matikan dapat dihentikan oleh fungsi AbortSystemShutdown .
Jika dwTimeout bukan nol, InitiateSystemShutdownEx menampilkan kotak dialog pada komputer yang ditentukan. Kotak dialog menampilkan nama pengguna yang memanggil fungsi, menampilkan pesan yang ditentukan oleh parameter lpMessage , dan meminta pengguna untuk keluar. Kotak dialog berbubuh ketika dibuat dan tetap berada di atas jendela lain dalam sistem. Kotak dialog dapat dipindahkan tetapi tidak ditutup. Timer menghitung mundur waktu yang tersisa sebelum dimatikan.
Jika dwTimeout adalah nol, komputer dimatikan tanpa menampilkan kotak dialog, dan matikan tidak dapat dihentikan oleh AbortSystemShutdown.
Windows Server 2003 dan Windows XP dengan SP1: Nilai waktu habis terbatas pada MAX_SHUTDOWN_TIMEOUT detik.
Windows Server 2003 dan Windows XP dengan SP1: Jika komputer yang akan dimatikan adalah server Layanan Terminal, sistem menampilkan kotak dialog untuk semua pengguna lokal dan jarak jauh yang memperingatkan mereka bahwa pematian telah dimulai. Kotak dialog mencakup siapa yang meminta matikan, pesan tampilan (lihat lpMessage), dan berapa banyak waktu yang ada sampai server dimatikan.
[in] bForceAppsClosed
Jika parameter ini TRUE, aplikasi dengan perubahan yang belum disimpan akan ditutup secara paksa. Jika parameter ini FALSE, sistem menampilkan kotak dialog yang menginstruksikan pengguna untuk menutup aplikasi.
[in] bRebootAfterShutdown
Jika parameter ini TRUE, komputer akan segera dimulai ulang setelah dimatikan. Jika parameter ini FALSE, sistem membersihkan semua cache ke disk dan mematikan sistem dengan aman.
[in] dwReason
Alasan untuk memulai pematian. Parameter ini harus menjadi salah satu kode alasan pematian sistem.
Jika parameter ini nol, defaultnya adalah pematian yang tidak terdefinisi yang dicatat sebagai "Tidak ada judul karena alasan ini yang dapat ditemukan". Secara default, ini juga merupakan pematian yang tidak dienkripsi. Bergantung pada bagaimana sistem dikonfigurasi, pematian yang tidak terencana memicu pembuatan file yang berisi informasi status sistem, yang dapat menunda pematian. Oleh karena itu, jangan gunakan nol untuk parameter ini.
Windows XP: Informasi status sistem tidak disimpan selama pematian sistem yang tidak diencana. Teks sebelumnya tidak berlaku.
Nilai kembali
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
Untuk mematikan komputer lokal, utas panggilan harus memiliki hak istimewa SE_SHUTDOWN_NAME. Untuk mematikan komputer jarak jauh, utas panggilan harus memiliki hak istimewa SE_REMOTE_SHUTDOWN_NAME pada komputer jarak jauh. Secara default, pengguna dapat mengaktifkan hak istimewa SE_SHUTDOWN_NAME pada komputer tempat mereka masuk, dan administrator dapat mengaktifkan hak istimewa SE_REMOTE_SHUTDOWN_NAME pada komputer jarak jauh. Untuk informasi selengkapnya, lihat Menjalankan dengan Hak Istimewa Khusus.
Alasan umum kegagalan termasuk nama komputer yang tidak valid atau tidak dapat diakses atau hak istimewa yang tidak mencukupi. Kesalahan ERROR_SHUTDOWN_IN_PROGRESS dikembalikan jika pematian sudah berlangsung pada komputer yang ditentukan. Kesalahan ERROR_NOT_READY dapat dikembalikan jika pengalihan pengguna cepat diaktifkan tetapi tidak ada pengguna yang masuk.
Nilai pengembalian bukan nol tidak berarti logoff berhasil atau akan berhasil. Pematian adalah proses asinkron, dan dapat terjadi lama setelah panggilan API kembali, atau tidak sama sekali. Bahkan jika nilai batas waktu adalah nol, pematian masih dapat dibatalkan oleh aplikasi, layanan, atau bahkan sistem. Nilai pengembalian bukan nol menunjukkan bahwa validasi hak dan parameter berhasil dan sistem menerima permintaan matikan.
Ketika fungsi ini dipanggil, pemanggil harus menentukan apakah aplikasi dengan perubahan yang belum disimpan harus ditutup secara paksa atau tidak. Jika pemanggil memilih untuk tidak memaksa aplikasi ini untuk menutup dan aplikasi dengan perubahan yang tidak disimpan berjalan pada sesi konsol, pematian akan tetap berlangsung sampai pengguna masuk ke sesi konsol membatalkan pematian, menyimpan perubahan, menutup aplikasi, atau memaksa aplikasi untuk menutup. Selama periode ini, penonaktifan mungkin tidak dibatalkan kecuali oleh pengguna konsol, dan penonaktifan lain mungkin tidak dimulai.
Perhatikan bahwa memanggil fungsi ini dengan nilai parameter bForceAppsClosed yang diatur ke TRUE menghindari situasi ini. Ingatlah bahwa melakukan ini dapat mengakibatkan hilangnya data.
Windows Server 2003 dan Windows XP: Jika komputer dikunci dan parameter bForceAppsClosedFALSE, kode kesalahan terakhir adalah ERROR_MACHINE_LOCKED. Jika sistem belum siap untuk menangani permintaan, kode kesalahan terakhir adalah ERROR_NOT_READY. Aplikasi harus menunggu beberapa saat dan mencoba kembali panggilan. Misalnya, sistem dapat belum dibaca untuk memulai pematian, dan mengembalikan ERROR_NOT_READY, jika permintaan matikan datang pada saat yang sama pengguna mencoba masuk ke sistem. Dalam hal ini, aplikasi harus menunggu beberapa saat dan mencoba kembali panggilan.
Catatan
Header winreg.h mendefinisikan InitiateSystemShutdownEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows XP [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2003 [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | winreg.h (termasuk Windows.h) |
| Pustaka | Advapi32.lib |
| DLL | Advapi32.dll |
Lihat 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