InitiateSystemShutdownExA-Funktion (winreg.h)
Initiiert ein Herunterfahren und optionalen Neustart des angegebenen Computers und zeichnet optional den Grund für das Herunterfahren auf.
Syntax
BOOL InitiateSystemShutdownExA(
[in, optional] LPSTR lpMachineName,
[in, optional] LPSTR lpMessage,
[in] DWORD dwTimeout,
[in] BOOL bForceAppsClosed,
[in] BOOL bRebootAfterShutdown,
[in] DWORD dwReason
);
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 InitiateSystemShutdownEx 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 vor dem Herunterfahren nach unten.
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. 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.
[in] dwReason
Der Grund für das Initiieren des Herunterfahrens. Dieser Parameter muss einer der Systemschließungsgrundcodessein.
Wenn dieser Parameter null ist, ist die Standardeinstellung ein nicht definiertes Herunterfahren, das als "Kein Titel aus diesem Grund gefunden" protokolliert wird. Standardmäßig ist es auch ein ungeplantes Herunterfahren. Je nachdem, wie das System konfiguriert ist, löst ein ungeplantes Herunterfahren die Erstellung einer Datei aus, die die Systemstatusinformationen enthält, wodurch das Herunterfahren verzögert werden kann. Verwenden Sie daher für diesen Parameter keine Null.
Windows XP: Systemstatusinformationen werden während eines ungeplanten Systemabfahrens nicht gespeichert. Der vorangehende Text gilt nicht.
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, auf 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 diese Anwendungen nicht zum Schließen erzwingt und eine Anwendung mit nicht gespeicherten Änderungen in der Konsolensitzung ausgeführt wird, bleibt das Herunterfahren in Bearbeitung, 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, wird der letzte Fehlercode ERROR_NOT_READY. Die Anwendung sollte eine kurze Weile warten und den Anruf wiederholen. Beispielsweise kann das System ungelesen sein, um ein Herunterfahren zu initiieren und ERROR_NOT_READY zurückzugeben, wenn die Herunterfahren-Anforderung gleichzeitig von einem Benutzer versucht, sich beim System anzumelden. In diesem Fall sollte die Anwendung kurz warten und den Anruf wiederholen.
Anmerkung
Der winreg.h-Header definiert "InitiateSystemShutdownEx" 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 |