Funzione InitiateSystemShutdownExA (winreg.h)
Avvia un arresto e un riavvio facoltativo del computer specificato e, facoltativamente, registra il motivo dell'arresto.
Sintassi
BOOL InitiateSystemShutdownExA(
[in, optional] LPSTR lpMachineName,
[in, optional] LPSTR lpMessage,
[in] DWORD dwTimeout,
[in] BOOL bForceAppsClosed,
[in] BOOL bRebootAfterShutdown,
[in] DWORD dwReason
);
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 AbortSystemShutdown.
Se dwTimeout non è zero, InitiateSystemShutdownEx 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 dell'arresto.
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. 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.
[in] dwReason
Motivo dell'avvio dell'arresto. Questo parametro deve essere uno dei codici motivo di arresto del sistema .
Se questo parametro è zero, il valore predefinito è un arresto non definito registrato come "Non è stato possibile trovare alcun titolo per questo motivo". Per impostazione predefinita, è anche un arresto non pianificato. A seconda della configurazione del sistema, un arresto non pianificato attiva la creazione di un file contenente le informazioni sullo stato del sistema, che può ritardare l'arresto. Pertanto, non usare zero per questo parametro.
Windows XP: informazioni sullo stato del sistema non vengono salvate durante un arresto del sistema non pianificato. Il testo precedente non si applica.
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 l'opzione rapida dell'utente è abilitata, ma nessun utente è connesso.
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.
Nota
L'intestazione winreg.h definisce InitiateSystemShutdownEx 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 |