Fungsi InitiateSystemShutdownA (winreg.h)
Memulai pematian dan hidupkan ulang opsional komputer yang ditentukan.
Untuk merekam alasan penonaktifan di log peristiwa, panggil fungsi InitiateSystemShutdownEx .
Sintaks
BOOL InitiateSystemShutdownA(
[in, optional] LPSTR lpMachineName,
[in, optional] LPSTR lpMessage,
[in] DWORD dwTimeout,
[in] BOOL bForceAppsClosed,
[in] BOOL bRebootAfterShutdown
);
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
Lamanya waktu kotak dialog matikan harus ditampilkan, dalam hitungan detik. Saat kotak dialog ini ditampilkan, pematian dapat dihentikan oleh fungsi AbortSystemShutdown .
Jika dwTimeout bukan nol, InitiateSystemShutdown 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 berbusa ketika dibuat dan tetap berada di atas jendela lain dalam sistem. Kotak dialog dapat dipindahkan tetapi tidak ditutup. Timer menghitung waktu yang tersisa sebelum pematian paksa.
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 batas waktu 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 menyertakan 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. Perhatikan bahwa ini dapat mengakibatkan kehilangan data.
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 menghapus semua cache ke disk dan mematikan sistem dengan aman.
Mengembalikan nilai
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.
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 adalah 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 penelepon memilih untuk tidak memaksa aplikasi ini ditutup, 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 sebentar 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 sebentar dan mencoba kembali panggilan.
Contoh
Misalnya, lihat Menampilkan Kotak Dialog Matikan.
Catatan
Header winreg.h mendefinisikan InitiateSystemShutdown 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
| 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