InitiateShutdownA-Funktion (winreg.h)
Initiiert ein Herunterfahren und Neustart des angegebenen Computers und startet alle Anwendungen, die für den Neustart registriert wurden.
Syntax
DWORD InitiateShutdownA(
[in, optional] LPSTR lpMachineName,
[in, optional] LPSTR lpMessage,
[in] DWORD dwGracePeriod,
[in] DWORD dwShutdownFlags,
[in] DWORD dwReason
);
Parameter
[in, optional] lpMachineName
Der Name des Computers, der heruntergefahren werden soll. Wenn der Wert dieses Parameters NULL-ist, wird der lokale Computer heruntergefahren.
[in, optional] lpMessage
Die Meldung, die im Dialogfeld zum interaktiven Herunterfahren angezeigt werden soll.
[in] dwGracePeriod
Die Anzahl der Sekunden, die gewartet werden sollen, bevor der Computer heruntergefahren wird. Wenn der Wert dieses Parameters null ist, wird der Computer sofort heruntergefahren. Dieser Wert ist auf MAX_SHUTDOWN_TIMEOUTbeschränkt.
Wenn der Wert dieses Parameters größer als Null ist und der dwShutdownFlags Parameter das Flag SHUTDOWN_GRACE_OVERRIDEangibt, schlägt die Funktion fehl und gibt den Fehlercode ERROR_BAD_ARGUMENTSzurück.
[in] dwShutdownFlags
Mindestens ein Bit-Flag, das Optionen für das Herunterfahren angibt. Die folgenden Werte sind definiert.
| Wert | Bedeutung |
|---|---|
|
Alle Sitzungen werden erzwungen abgemeldet. Wenn diese Kennzeichnung nicht festgelegt ist und andere Benutzer als der aktuelle Benutzer auf dem Computer angemeldet sind, der durch den parameter lpMachineName angegeben wird, schlägt diese Funktion mit einem Rückgabewert von ERROR_SHUTDOWN_USERS_LOGGED_ONfehl. |
|
Gibt an, dass die ursprüngliche Sitzung erzwungen abgemeldet wird. Wenn dieses Kennzeichen nicht festgelegt ist, wird die ursprüngliche Sitzung interaktiv heruntergefahren, sodass ein Herunterfahren auch dann nicht garantiert wird, wenn die Funktion erfolgreich zurückgegeben wird. |
|
Setzt die Nachfrist außer Kraft, sodass der Computer sofort heruntergefahren wird. |
|
Ab "InitiateShutdown" unter Windows 8 ausgeführt wird, müssen Sie das SHUTDOWN_HYBRID-Flag mit einer oder mehreren Flags in dieser Tabelle einschließen, um Optionen für das Herunterfahren anzugeben.
Ab Windows 8 "InitiateShutdown" immer ein vollständiges System herunterfahren, wenn das SHUTDOWN_HYBRID Flag nicht vorhanden ist. |
|
Der Computer installiert alle Updates, bevor das Herunterfahren gestartet wird. |
|
Der Computer wird heruntergefahren, aber nicht heruntergefahren oder neu gestartet. |
|
Der Computer wird heruntergefahren und heruntergefahren. |
|
Der Computer wird heruntergefahren und neu gestartet. |
|
Das System wird mit der ExitWindowsEx--Funktion mit der EWX_RESTARTAPPS-Kennzeichnung neu gestartet. Dadurch werden alle Anwendungen neu gestartet, die mit der RegisterApplicationRestart-Funktion für den Neustart registriert wurden. |
[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.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird ERROR_SUCCESSzurückgegeben.
Wenn die Funktion fehlschlägt, wird eine der folgenden Fehlercodes zurückgegeben.
| Rückgabecode | Beschreibung |
|---|---|
|
Der Aufrufer verfügt nicht über die erforderlichen Berechtigungen (SE_SHUTDOWN_PRIVILEGE oder SE_REMOTE_SHUTDOWN_PRIVILEGE), um diesen Vorgang auszuführen. |
|
Der angegebene Computer ist nicht vorhanden oder kann nicht zugänglich sein. |
|
Der angegebene Computername ist kein gültiger Computername. |
|
Der angegebene Computer unterstützt keine Herunterfahren-Schnittstelle. |
|
Es wurde ein ungültiger Satz von Parametern übergeben. Dazu gehören die folgenden Kombinationen.
|
|
Auf dem angegebenen Computer wurde bereits ein Herunterfahren gestartet. |
|
Ein Herunterfahren für den angegebenen Computer wurde geplant, aber nicht gestartet. Damit diese Funktion erfolgreich ausgeführt werden kann, muss das SHUTDOWN_GRACE_OVERRIDE Flag festgelegt werden. |
|
Mindestens ein anderer Benutzer als der aktuelle Benutzer ist auf dem angegebenen Computer angemeldet, und das SHUTDOWN_FORCE_OTHERS Flag wurde nicht festgelegt. |
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.
Anmerkung
Der winreg.h-Header definiert "InitiateShutdown" 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 Vista [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2008 [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | winreg.h (enthalten Windows.h) |
| Library | Advapi32.lib |
| DLL- | Advapi32.dll |