Fungsi InitiateShutdownA (winreg.h)
Memulai pematian dan menghidupkan ulang komputer yang ditentukan, dan memulai ulang aplikasi apa pun yang telah didaftarkan untuk memulai ulang.
Sintaks
DWORD InitiateShutdownA(
[in, optional] LPSTR lpMachineName,
[in, optional] LPSTR lpMessage,
[in] DWORD dwGracePeriod,
[in] DWORD dwShutdownFlags,
[in] DWORD dwReason
);
Parameter
[in, optional] lpMachineName
Nama komputer yang akan dimatikan. Jika nilai parameter ini ADALAH NULL, komputer lokal akan dimatikan.
[in, optional] lpMessage
Pesan yang akan ditampilkan dalam kotak dialog matikan interaktif.
[in] dwGracePeriod
Jumlah detik untuk menunggu sebelum mematikan komputer. Jika nilai parameter ini nol, komputer segera dimatikan. Nilai ini terbatas pada MAX_SHUTDOWN_TIMEOUT.
Jika nilai parameter ini lebih besar dari nol, dan parameter dwShutdownFlags menentukan bendera SHUTDOWN_GRACE_OVERRIDE, fungsi gagal dan mengembalikan kode kesalahan ERROR_BAD_ARGUMENTS.
[in] dwShutdownFlags
Satu atau beberapa bendera bit yang menentukan opsi untuk matikan. Nilai berikut ditentukan.
| Nilai | Makna |
|---|---|
|
Semua sesi dicatat secara paksa. Jika bendera ini tidak diatur dan pengguna selain pengguna saat ini masuk ke komputer yang ditentukan oleh parameter lpMachineName , fungsi ini gagal dengan nilai pengembalian ERROR_SHUTDOWN_USERS_LOGGED_ON. |
|
Menentukan bahwa sesi asal dicatat secara paksa. Jika bendera ini tidak diatur, sesi asal dimatikan secara interaktif, sehingga pematian tidak dijamin meskipun fungsi berhasil dikembalikan. |
|
Mengambil alih masa tenggang sehingga komputer segera dimatikan. |
|
Dimulai dengan InitiateShutdown berjalan pada Windows 8, Anda harus menyertakan bendera SHUTDOWN_HYBRID dengan satu atau beberapa bendera dalam tabel ini untuk menentukan opsi penonaktifan.
Dimulai dengan Windows 8, InitiateShutdown selalu memulai pematian sistem penuh jika bendera SHUTDOWN_HYBRID tidak ada. |
|
Komputer menginstal pembaruan apa pun sebelum memulai pematian. |
|
Komputer dimatikan tetapi tidak dimatikan atau di-boot ulang. |
|
Komputer dimatikan dan dimatikan. |
|
Komputer dimatikan dan di-boot ulang. |
|
Sistem di-boot ulang menggunakan fungsi ExitWindowsEx dengan bendera EWX_RESTARTAPPS. Ini memulai ulang aplikasi apa pun yang telah didaftarkan untuk memulai ulang menggunakan fungsi RegisterApplicationRestart . |
[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.
Nilai kembali
Jika fungsi berhasil, fungsi akan mengembalikan ERROR_SUCCESS.
Jika fungsi gagal, fungsi mengembalikan salah satu kode kesalahan berikut.
| Menampilkan kode | Deskripsi |
|---|---|
|
Pemanggil tidak memiliki hak istimewa yang diperlukan (SE_SHUTDOWN_PRIVILEGE atau SE_REMOTE_SHUTDOWN_PRIVILEGE) untuk melakukan operasi ini. |
|
Komputer yang ditentukan tidak ada atau tidak dapat diakses. |
|
Nama komputer yang ditentukan bukan nama komputer yang valid. |
|
Komputer yang ditentukan tidak mendukung antarmuka matikan. |
|
Sekumpulan parameter yang tidak valid diteruskan. Ini termasuk kombinasi berikut.
|
|
Pematian telah dimulai pada komputer yang ditentukan. |
|
Matikan untuk komputer yang ditentukan telah dijadwalkan tetapi tidak dimulai. Agar fungsi ini berhasil, bendera SHUTDOWN_GRACE_OVERRIDE harus diatur. |
|
Satu atau beberapa pengguna selain pengguna saat ini dicatat pada komputer yang ditentukan, dan bendera SHUTDOWN_FORCE_OTHERS tidak diatur. |
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.
Catatan
Header winreg.h mendefinisikan InitiateShutdown sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosedur 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 Vista [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2008 [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | winreg.h (termasuk Windows.h) |
| Pustaka | Advapi32.lib |
| DLL | Advapi32.dll |