Funzione InitiateSystemShutdownA (winreg.h)
Avvia un arresto e un riavvio facoltativo del computer specificato.
Per registrare un motivo per l'arresto nel registro eventi, chiamare la funzione
Sintassi
BOOL InitiateSystemShutdownA(
[in, optional] LPSTR lpMachineName,
[in, optional] LPSTR lpMessage,
[in] DWORD dwTimeout,
[in] BOOL bForceAppsClosed,
[in] BOOL bRebootAfterShutdown
);
Parametri
[in, optional] lpMachineName
Nome di rete del computer da arrestare. Se lpMachineName è NULL o una stringa vuota, la funzione arresta il computer locale.
[in, optional] lpMessage
Messaggio da visualizzare nella finestra di dialogo di arresto. Questo parametro può essere null se non è necessario alcun messaggio.
Windows Server 2003 e Windows XP: Questa stringa viene archiviata anche come commento nella voce del registro eventi.
Windows Server 2003 e Windows XP con SP1: La stringa è limitata a 3072 TCHAR.
[in] dwTimeout
Intervallo di tempo durante il quale deve essere visualizzata la finestra di dialogo di arresto, in secondi. Mentre viene visualizzata questa finestra di dialogo, l'arresto può essere arrestato dalla funzione
Se dwTimeout non è zero, InitiateSystemShutdown visualizza una finestra di dialogo nel computer specificato. La finestra di dialogo visualizza il nome dell'utente che ha chiamato la funzione, visualizza il messaggio specificato dal parametro lpMessage e richiede all'utente di disconnettersi. La finestra di dialogo si attiva quando viene creata e rimane in cima ad altre finestre del sistema. La finestra di dialogo può essere spostata ma non chiusa. Un timer conta il tempo rimanente prima di un arresto forzato.
Se dwTimeout è zero, il computer si arresta senza visualizzare la finestra di dialogo e l'arresto non può essere arrestato da AbortSystemShutdown.
Windows Server 2003 e Windows XP con SP1: Il valore di timeout è limitato a MAX_SHUTDOWN_TIMEOUT secondi.
Windows Server 2003 e Windows XP con SP1: Se il computer da arrestare è un server Servizi terminal, il sistema visualizza una finestra di dialogo per tutti gli utenti locali e remoti che avvisano che l'arresto è stato avviato. La finestra di dialogo include chi ha richiesto l'arresto, il messaggio di visualizzazione (vedere lpMessage) e il tempo necessario fino all'arresto del server.
[in] bForceAppsClosed
Se questo parametro è TRUE, le applicazioni con modifiche non salvate devono essere chiuse forzatamente. Si noti che ciò può comportare la perdita di dati.
Se questo parametro è FALSE, il sistema visualizza una finestra di dialogo che indica all'utente di chiudere le applicazioni.
[in] bRebootAfterShutdown
Se questo parametro è TRUE, il computer deve essere riavviato immediatamente dopo l'arresto. Se questo parametro è FALSE, il sistema scarica tutte le cache su disco e alimenta in modo sicuro il sistema.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è diverso da zero.
Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni estese sull'errore, chiamare GetLastError.
Osservazioni
Per arrestare il computer locale, il thread chiamante deve avere il privilegio SE_SHUTDOWN_NAME. Per arrestare un computer remoto, il thread chiamante deve avere il privilegio SE_REMOTE_SHUTDOWN_NAME nel computer remoto. Per impostazione predefinita, gli utenti possono abilitare il privilegio SE_SHUTDOWN_NAME nel computer in cui sono connessi e gli amministratori possono abilitare il privilegio SE_REMOTE_SHUTDOWN_NAME nei computer remoti. Per altre informazioni, vedere esecuzione con privilegi speciali.
I motivi comuni dell'errore includono un nome computer non valido o inaccessibile o privilegi insufficienti. L'errore ERROR_SHUTDOWN_IN_PROGRESS viene restituito se un arresto è già in corso nel computer specificato. L'errore ERROR_NOT_READY può essere restituito se il cambio rapido utente è abilitato ma non è connesso alcun utente.
Un valore restituito diverso da zero non indica che la disconnessione è stata o avrà esito positivo. L'arresto è un processo asincrono e può verificarsi molto tempo dopo che la chiamata API è stata restituita o non affatto. Anche se il valore di timeout è zero, l'arresto può comunque essere interrotto da applicazioni, servizi o persino dal sistema. Il valore restituito diverso da zero indica che la convalida dei diritti e dei parametri ha avuto esito positivo e che il sistema ha accettato la richiesta di arresto.
Quando questa funzione viene chiamata, il chiamante deve specificare se le applicazioni con modifiche non salvate devono essere chiuse forzatamente. Se il chiamante sceglie di non forzare la chiusura di queste applicazioni e un'applicazione con modifiche non salvate viene eseguita nella sessione della console, l'arresto rimarrà in corso finché l'utente non ha eseguito l'accesso alla sessione della console interrompe l'arresto, salva le modifiche, chiude l'applicazione o forza la chiusura dell'applicazione. Durante questo periodo, l'arresto potrebbe non essere interrotto ad eccezione dell'utente della console e potrebbe non essere avviato un altro arresto.
Si noti che la chiamata a questa funzione con il valore del parametro bForceAppsClosed impostato su TRUE evita questa situazione. Tenere presente che questa operazione può comportare la perdita di dati.
Windows Server 2003 e Windows XP: Se il computer è bloccato e il parametro bForceAppsClosed è FALSE, l'ultimo codice di errore è ERROR_MACHINE_LOCKED. Se il sistema non è pronto per gestire la richiesta, l'ultimo codice di errore è ERROR_NOT_READY. L'applicazione dovrebbe attendere un breve periodo di tempo e ripetere la chiamata. Ad esempio, il sistema può essere letto per avviare un arresto e restituire ERROR_NOT_READY, se la richiesta di arresto arriva contemporaneamente a un utente tenta di accedere al sistema. In questo caso, l'applicazione deve attendere un breve periodo di tempo e ripetere la chiamata.
Esempi
Per un esempio, vedere Visualizzazione della finestra di dialogo Arresto.
Nota
L'intestazione winreg.h definisce InitiateSystemShutdown come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows XP [app desktop | App UWP] |
| server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| piattaforma di destinazione | Finestre |
| intestazione |
winreg.h (include Windows.h) |
| libreria |
Advapi32.lib |
| dll | Advapi32.dll |