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 herunterzufahrenden Computers. Wenn lpMachineNameNULL oder eine leere Zeichenfolge ist, wird der lokale Computer von der Funktion heruntergefahren.
[in, optional] lpMessage
Die Meldung, die im Dialogfeld "Herunterfahren" angezeigt werden soll. Dieser Parameter kann NULL sein, wenn keine Meldung 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 TCHARs beschränkt.
[in] dwTimeout
Die Dauer, für die das Dialogfeld "Herunterfahren" in Sekunden angezeigt werden soll. Während dieses Dialogfelds angezeigt wird, kann das Herunterfahren durch die Funktion AbortSystemShutdown beendet werden.
Wenn dwTimeout nicht 0 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 lpMessage-Parameter angegebene Meldung angezeigt, und der Benutzer wird aufgefordert, sich abzumelden. Das Dialogfeld signalisiert, wenn es erstellt wird, und bleibt auf anderen Fenstern im System. Das Dialogfeld kann verschoben, aber nicht geschlossen werden. Ein Timer zählt die verbleibende Zeit vor dem Herunterfahren.
Wenn dwTimeout null ist, wird der Computer heruntergefahren, ohne das Dialogfeld anzuzeigen, und das Herunterfahren kann nicht von 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 es sich bei dem herunterzufahrenden Computer um einen Terminaldiensteserver handelt, zeigt das System allen lokalen und Remotebenutzern ein Dialogfeld an, das sie darüber warnt, dass das Herunterfahren initiiert wurde. Das Dialogfeld enthält, wer das Herunterfahren angefordert hat, die Anzeigemeldung (siehe lpMessage) und wie lange es bis zum Herunterfahren des Servers dauert.
[in] bForceAppsClosed
Wenn dieser Parameter TRUE ist, müssen Anwendungen mit nicht gespeicherten Änderungen erzwungen geschlossen werden. Wenn dieser Parameter FALSE ist, zeigt das System ein Dialogfeld an, in dem der Benutzer angewiesen wird, die Anwendungen zu schließen.
[in] bRebootAfterShutdown
Wenn dieser Parameter TRUE ist, wird der Computer unmittelbar nach dem Herunterfahren neu gestartet. Wenn dieser Parameter FALSE ist, leert das System alle Caches auf dem Datenträger und schaltet das System sicher ein.
[in] dwReason
Der Grund für die Einleitung des Herunterfahrens. Dieser Parameter muss einer der Gründe für das Herunterfahren des Systems sein.
Wenn dieser Parameter null ist, ist der Standardwert ein undefiniertes Herunterfahren, das mit "Kein Titel aus diesem Grund gefunden" protokolliert wird. Standardmäßig handelt es sich auch um 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 nicht null für diesen Parameter.
Windows XP: Systemstatusinformationen werden während eines ungeplanten Herunterfahrens des Systems nicht gespeichert. Der vorangehende Text gilt nicht.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.
Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Hinweise
Um den lokalen Computer herunterzufahren, muss der aufrufende Thread über die berechtigung SE_SHUTDOWN_NAME verfügen. Um einen Remotecomputer herunterzufahren, muss der aufrufende Thread über die berechtigung SE_REMOTE_SHUTDOWN_NAME auf dem Remotecomputer verfügen. Standardmäßig können Benutzer die berechtigung SE_SHUTDOWN_NAME auf dem Computer aktivieren, auf dem sie angemeldet sind, und Administratoren können die Berechtigung SE_REMOTE_SHUTDOWN_NAME auf Remotecomputern aktivieren. Weitere Informationen finden Sie unter Ausführen mit speziellen Berechtigungen.
Häufige Fehlerursachen sind ein ungültiger oder nicht zugänglicher Computername oder unzureichende Berechtigungen. Der Fehler ERROR_SHUTDOWN_IN_PROGRESS wird zurückgegeben, wenn auf dem angegebenen Computer bereits ein Herunterfahren 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 0 (null) bedeutet nicht, dass die Abmeldung erfolgreich war oder sein wird. Das Herunterfahren ist ein asynchroner Prozess, der lange nach der Rückgabe des API-Aufrufs oder gar nicht auftreten kann. Selbst wenn der Timeoutwert 0 (null) ist, kann das Herunterfahren von Anwendungen, Diensten oder sogar dem System abgebrochen werden. Der Rückgabewert ungleich 0 (null) gibt an, dass die Überprüfung der Rechte und Parameter erfolgreich war und das System die Anforderung zum Herunterfahren akzeptiert hat.
Wenn diese Funktion aufgerufen wird, muss der Aufrufer angeben, ob Anwendungen mit nicht gespeicherten Änderungen zwangsweise geschlossen werden sollen. Wenn der Aufrufer das Schließen dieser Anwendungen nicht erzwingt und eine Anwendung mit nicht gespeicherten Änderungen in der Konsolensitzung ausgeführt wird, wird das Herunterfahren fortgesetzt, bis der bei der Konsolensitzung angemeldete Benutzer das Herunterfahren abbricht, Änderungen speichert, die Anwendung schließt oder das Schließen der Anwendung erzwingt. Während dieses Zeitraums kann das Herunterfahren nicht abgebrochen werden, 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 , der auf TRUE festgelegt ist, diese Situation vermeidet. Denken Sie daran, dass dies zu Datenverlust führen kann.
Windows Server 2003 und Windows XP: Wenn der Computer gesperrt ist und der bForceAppsClosed-ParameterFALSE ist, 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 kurz warten und den Aufruf wiederholen. Das System kann z. B. ein Herunterfahren initiieren und ERROR_NOT_READY zurückgeben, wenn die Herunterfahrensanforderung gleichzeitig erfolgt, wenn ein Benutzer versucht, sich beim System anzumelden. In diesem Fall sollte die Anwendung kurz warten und den Aufruf wiederholen.
Hinweis
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 |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winreg.h (Windows.h einschließen) |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.dll |