InitiateShutdownA-Funktion (winreg.h)
Initiiert das Herunterfahren und Neustarten des angegebenen Computers und startet alle Anwendungen neu, 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 herunterzufahrenden Computers. Wenn der Wert dieses Parameters NULL ist, wird der lokale Computer heruntergefahren.
[in, optional] lpMessage
Die Meldung, die im Dialogfeld "Interaktives Herunterfahren" angezeigt werden soll.
[in] dwGracePeriod
Die Anzahl der Sekunden, die gewartet werden soll, bevor der Computer heruntergefahren wird. Wenn der Wert dieses Parameters null ist, wird der Computer sofort heruntergefahren. Dieser Wert ist auf MAX_SHUTDOWN_TIMEOUT beschränkt.
Wenn der Wert dieses Parameters größer als 0 (null) ist und der dwShutdownFlags-Parameter das Flag SHUTDOWN_GRACE_OVERRIDE angibt, schlägt die Funktion fehl und gibt den Fehlercode ERROR_BAD_ARGUMENTS zurück.
[in] dwShutdownFlags
Mindestens ein Bitflags, das Optionen für das Herunterfahren angibt. Die folgenden Werte werden definiert.
| Wert | Bedeutung |
|---|---|
|
Alle Sitzungen werden erzwungen abgemeldet. Wenn dieses Flag nicht festgelegt ist und andere Benutzer als der aktuelle Benutzer bei dem durch den lpMachineName-Parameter angegebenen Computer angemeldet sind, schlägt diese Funktion mit dem Rückgabewert ERROR_SHUTDOWN_USERS_LOGGED_ON fehl. |
|
Gibt an, dass die ursprüngliche Sitzung erzwungen abgemeldet wird. Wenn dieses Flag 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. |
|
Überschreibt die Karenzzeit, sodass der Computer sofort heruntergefahren wird. |
|
Ab InitiateShutdown auf Windows 8 müssen Sie das SHUTDOWN_HYBRID-Flag mit mindestens einem der Flags in dieser Tabelle einschließen, um Optionen für das Herunterfahren anzugeben.
Ab Windows 8 initiiert InitiateShutdown immer ein vollständiges Herunterfahren des Systems, wenn das flag SHUTDOWN_HYBRID fehlt. |
|
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 mithilfe der ExitWindowsEx-Funktion mit dem flag EWX_RESTARTAPPS neu gestartet. Dadurch werden alle Anwendungen neu gestartet, die mit der Funktion RegisterApplicationRestart für den Neustart registriert wurden. |
[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.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird ERROR_SUCCESS zurückgegeben.
Wenn die Funktion fehlschlägt, gibt sie einen der folgenden Fehlercodes zurück.
| 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 zugegriffen werden. |
|
Der angegebene Computername ist kein gültiger Computername. |
|
Der angegebene Computer unterstützt keine Herunterfahrschnittstelle. |
|
Ein ungültiger Satz von Parametern wurde übergeben. Dies umfasst 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 ist, muss das flag SHUTDOWN_GRACE_OVERRIDE festgelegt werden. |
|
Mindestens ein anderer Benutzer als der aktuelle Benutzer ist auf dem angegebenen Computer angemeldet, und das flag SHUTDOWN_FORCE_OTHERS wurde nicht festgelegt. |
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.
Hinweis
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 |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winreg.h (einschließlich Windows.h) |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.dll |