InitiateSystemShutdownW-Funktion (winreg.h)
Initiiert ein Herunterfahren und optionalen Neustart des angegebenen Computers.
Rufen Sie zum Aufzeichnen eines Grunds für das Herunterfahren im Ereignisprotokoll die InitiateSystemShutdownEx--Funktion auf.
Syntax
BOOL InitiateSystemShutdownW(
[in, optional] LPWSTR lpMachineName,
[in, optional] LPWSTR lpMessage,
[in] DWORD dwTimeout,
[in] BOOL bForceAppsClosed,
[in] BOOL bRebootAfterShutdown
);
Parameter
[in, optional] lpMachineName
Der Netzwerkname des Computers, der heruntergefahren werden soll. Wenn lpMachineName-NULL- oder eine leere Zeichenfolge ist, wird die Funktion den lokalen Computer heruntergefahren.
[in, optional] lpMessage
Die Meldung, die im Dialogfeld "Herunterfahren" angezeigt werden soll. Dieser Parameter kann NULL- werden, wenn keine Nachricht erforderlich ist.
Windows Server 2003 und Windows XP: Diese Zeichenfolge wird auch als Kommentar im Ereignisprotokolleintrag gespeichert.
Windows Server 2003 und Windows XP mit SP1: Die Zeichenfolge ist auf 3072 TCHARsbeschränkt.
[in] dwTimeout
Die Zeitspanne, die das Dialogfeld zum Herunterfahren in Sekunden angezeigt werden soll. Während dieses Dialogfelds angezeigt wird, kann das Herunterfahren durch die AbortSystemShutdown- funktion beendet werden.
Wenn dwTimeout- nicht null ist, zeigt "InitiateSystemShutdown" ein Dialogfeld auf dem angegebenen Computer an. Im Dialogfeld wird der Name des Benutzers angezeigt, der die Funktion aufgerufen hat, die durch den parameter lpMessage angegebene Meldung angezeigt, und der Benutzer wird aufgefordert, sich abzumelden. Das Dialogfeld zeigt beim Erstellen einen Signalton an und verbleibt über anderen Fenstern im System. Das Dialogfeld kann verschoben, aber nicht geschlossen werden. Ein Timer zählt die verbleibende Zeit nach unten, bevor ein erzwungenes Herunterfahren beendet wird.
Wenn dwTimeout- null ist, wird der Computer heruntergefahren, ohne das Dialogfeld anzuzeigen, und das Herunterfahren kann nicht durch "AbortSystemShutdown"beendet werden.
Windows Server 2003 und Windows XP mit SP1: Der Timeoutwert ist auf MAX_SHUTDOWN_TIMEOUT Sekunden beschränkt.
Windows Server 2003 und Windows XP mit SP1: Wenn der Computer heruntergefahren werden soll, zeigt das System ein Dialogfeld für alle lokalen und Remotebenutzer an, dass das Herunterfahren initiiert wurde. Das Dialogfeld enthält, wer das Herunterfahren angefordert hat, die Anzeigemeldung (siehe lpMessage), und wie viel Zeit es bis zum Herunterfahren des Servers gibt.
[in] bForceAppsClosed
Wenn dieser Parameter TRUEist, werden Anwendungen mit nicht gespeicherten Änderungen forcibly geschlossen. Beachten Sie, dass dies zu Datenverlust führen kann.
Wenn dieser Parameter FALSEist, zeigt das System ein Dialogfeld an, in dem der Benutzer die Anwendungen schließen kann.
[in] bRebootAfterShutdown
Wenn dieser Parameter TRUEist, wird der Computer unmittelbar nach dem Herunterfahren neu gestartet. Wenn dieser Parameter FALSEist, löscht das System alle Caches auf dem Datenträger und aktiviert das System sicher.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.
Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Bemerkungen
Um den lokalen Computer herunterzufahren, muss der aufrufende Thread über die SE_SHUTDOWN_NAME Berechtigung verfügen. Um einen Remotecomputer herunterzufahren, muss der aufrufende Thread über die SE_REMOTE_SHUTDOWN_NAME Berechtigungen auf dem Remotecomputer verfügen. Standardmäßig können Benutzer die SE_SHUTDOWN_NAME Berechtigungen auf dem Computer aktivieren, an dem sie angemeldet sind, und Administratoren können die SE_REMOTE_SHUTDOWN_NAME Berechtigungen auf Remotecomputern aktivieren. Weitere Informationen finden Sie unter Ausführen mit speziellen Rechten.
Häufige Fehlerursachen sind ungültige oder nicht zugängliche Computernamen oder unzureichende Berechtigungen. Der Fehler ERROR_SHUTDOWN_IN_PROGRESS wird zurückgegeben, wenn bereits ein Herunterfahren auf dem angegebenen Computer ausgeführt wird. Der Fehler ERROR_NOT_READY kann zurückgegeben werden, wenn der schnelle Benutzerwechsel aktiviert ist, aber kein Benutzer angemeldet ist.
Ein Rückgabewert ungleich Null bedeutet nicht, dass die Abmeldung erfolgreich war oder erfolgreich ist. Das Herunterfahren ist ein asynchroner Prozess, und er kann lange auftreten, nachdem der API-Aufruf zurückgegeben wurde oder gar nicht. Auch wenn der Timeoutwert null ist, kann das Herunterfahren weiterhin von Anwendungen, Diensten oder sogar vom System abgebrochen werden. Der Rückgabewert ungleich Null gibt an, dass die Überprüfung der Rechte und Parameter erfolgreich war und dass das System die Herunterfahren-Anforderung akzeptiert hat.
Wenn diese Funktion aufgerufen wird, muss der Aufrufer angeben, ob Anwendungen mit nicht gespeicherten Änderungen forcibly geschlossen werden sollen. Wenn der Aufrufer nicht erzwingt, dass diese Anwendungen geschlossen werden, und eine Anwendung mit nicht gespeicherten Änderungen in der Konsolensitzung ausgeführt wird, bleibt das Herunterfahren aktiv, bis der Benutzer bei der Konsolensitzung angemeldet ist, das Herunterfahren abbricht, Änderungen speichert, die Anwendung schließt oder erzwingt, dass die Anwendung geschlossen wird. Während dieses Zeitraums wird das Herunterfahren möglicherweise nicht abgebrochen, außer vom Konsolenbenutzer, und ein weiteres Herunterfahren wird möglicherweise nicht initiiert.
Beachten Sie, dass das Aufrufen dieser Funktion mit dem Wert des bForceAppsClosed--Parameters auf TRUE festgelegt ist, diese Situation vermeiden. Denken Sie daran, dass dies zu Datenverlust führen kann.
Windows Server 2003 und Windows XP: Wenn der Computer gesperrt ist und der bForceAppsClosed Parameter FALSEist, wird der letzte Fehlercode ERROR_MACHINE_LOCKED. Wenn das System nicht bereit ist, die Anforderung zu verarbeiten, ist der letzte Fehlercode ERROR_NOT_READY. Die Anwendung sollte eine kurze Weile warten und den Anruf wiederholen. Das System kann beispielsweise ungelesen sein, um ein Herunterfahren zu initiieren und ERROR_NOT_READYzurückzugeben, wenn die Anforderung zum Herunterfahren gleichzeitig von einem Benutzer versucht, sich beim System anzumelden. In diesem Fall sollte die Anwendung kurz warten und den Anruf wiederholen.
Beispiele
Ein Beispiel finden Sie unter Anzeigen des Dialogfelds "Herunterfahren".
Anmerkung
Der winreg.h-Header definiert "InitiateSystemShutdown" als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows XP [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | winreg.h (enthalten Windows.h) |
| Library | Advapi32.lib |
| DLL- | Advapi32.dll |