Fonction InitiateSystemShutdownA (winreg.h)

Article
08/27/2023

Lance un arrêt et un redémarrage facultatif de l’ordinateur spécifié.

Pour enregistrer une raison de l’arrêt dans le journal des événements, appelez la fonction InitiateSystemShutdownEx .

Syntaxe

BOOL InitiateSystemShutdownA(
  [in, optional] LPSTR lpMachineName,
  [in, optional] LPSTR lpMessage,
  [in]           DWORD dwTimeout,
  [in]           BOOL  bForceAppsClosed,
  [in]           BOOL  bRebootAfterShutdown
);

Paramètres

[in, optional] lpMachineName

Nom réseau de l’ordinateur à arrêter. Si lpMachineName a la valeur NULL ou une chaîne vide, la fonction arrête l’ordinateur local.

[in, optional] lpMessage

Message à afficher dans la boîte de dialogue d’arrêt. Ce paramètre peut être NULL si aucun message n’est requis.

Windows Server 2003 et Windows XP : Cette chaîne est également stockée en tant que commentaire dans l’entrée du journal des événements.

Windows Server 2003 et Windows XP avec SP1 : La chaîne est limitée à 3 072 TCHAR.

[in] dwTimeout

Durée pendant laquelle la boîte de dialogue d’arrêt doit être affichée, en secondes. Lorsque cette boîte de dialogue s’affiche, l’arrêt peut être arrêté par la fonction AbortSystemShutdown .

Si dwTimeout n’est pas égal à zéro, InitiateSystemShutdown affiche une boîte de dialogue sur l’ordinateur spécifié. La boîte de dialogue affiche le nom de l’utilisateur qui a appelé la fonction, affiche le message spécifié par le paramètre lpMessage et invite l’utilisateur à se déconnecter. La boîte de dialogue bipse lorsqu’elle est créée et reste au-dessus des autres fenêtres du système. La boîte de dialogue peut être déplacée, mais pas fermée. Un minuteur compte le temps restant avant un arrêt forcé.

Si dwTimeout est égal à zéro, l’ordinateur s’arrête sans afficher la boîte de dialogue et l’arrêt ne peut pas être arrêté par AbortSystemShutdown.

Windows Server 2003 et Windows XP avec SP1 : La valeur du délai d’attente est limitée à MAX_SHUTDOWN_TIMEOUT secondes.

Windows Server 2003 et Windows XP avec SP1 : Si l’ordinateur à arrêter est un serveur Terminal Services, le système affiche une boîte de dialogue à tous les utilisateurs locaux et distants qui les avertit que l’arrêt a été lancé. La boîte de dialogue indique qui a demandé l’arrêt, le message d’affichage (voir lpMessage) et la durée d’arrêt du serveur.

[in] bForceAppsClosed

Si ce paramètre a la valeur TRUE, les applications avec des modifications non enregistrées doivent être fermées de force. Notez que cela peut entraîner une perte de données.

Si ce paramètre a la valeur FALSE, le système affiche une boîte de dialogue indiquant à l’utilisateur de fermer les applications.

[in] bRebootAfterShutdown

Si ce paramètre a la valeur TRUE, l’ordinateur doit redémarrer immédiatement après l’arrêt. Si ce paramètre a la valeur FALSE, le système vide tous les caches sur le disque et met le système hors tension en toute sécurité.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Pour arrêter l’ordinateur local, le thread appelant doit avoir le privilège SE_SHUTDOWN_NAME . Pour arrêter un ordinateur distant, le thread appelant doit disposer du privilège SE_REMOTE_SHUTDOWN_NAME sur l’ordinateur distant. Par défaut, les utilisateurs peuvent activer le privilège SE_SHUTDOWN_NAME sur l’ordinateur auquel ils sont connectés, et les administrateurs peuvent activer le privilège SE_REMOTE_SHUTDOWN_NAME sur les ordinateurs distants. Pour plus d’informations, consultez Exécution avec des privilèges spéciaux.

Les raisons courantes de l’échec incluent un nom d’ordinateur non valide ou inaccessible ou des privilèges insuffisants. L’erreur ERROR_SHUTDOWN_IN_PROGRESS est retournée si un arrêt est déjà en cours sur l’ordinateur spécifié. L’erreur ERROR_NOT_READY peut être retournée si le basculement rapide d’utilisateur est activé, mais qu’aucun utilisateur n’est connecté.

Une valeur de retour autre que zéro ne signifie pas que la déconnexion a été ou sera réussie. L’arrêt est un processus asynchrone, qui peut se produire longtemps après le retour de l’appel d’API, ou pas du tout. Même si la valeur du délai d’expiration est égale à zéro, l’arrêt peut toujours être abandonné par les applications, les services ou même le système. La valeur de retour autre que zéro indique que la validation des droits et des paramètres a réussi et que le système a accepté la demande d’arrêt.

Lorsque cette fonction est appelée, l’appelant doit spécifier si les applications avec des modifications non enregistrées doivent être fermées de force. Si l’appelant choisit de ne pas forcer la fermeture de ces applications et qu’une application avec des modifications non enregistrées est en cours d’exécution sur la session de console, l’arrêt reste en cours jusqu’à ce que l’utilisateur connecté à la session de console abandonne l’arrêt, enregistre les modifications, ferme l’application ou force l’application à se fermer. Pendant cette période, l’arrêt ne peut pas être abandonné, sauf par l’utilisateur de la console, et un autre arrêt peut ne pas être lancé.

Notez que l’appel de cette fonction avec la valeur du paramètre bForceAppsClosed définie sur TRUE évite cette situation. N’oubliez pas que cela peut entraîner une perte de données.

Windows Server 2003 et Windows XP : Si l’ordinateur est verrouillé et que le paramètre bForceAppsClosed a la valeur FALSE, le dernier code d’erreur est ERROR_MACHINE_LOCKED. Si le système n’est pas prêt à gérer la demande, le dernier code d’erreur est ERROR_NOT_READY. L’application doit attendre un court instant et réessayer l’appel. Par exemple, le système peut ne pas être lu pour lancer un arrêt et retourner ERROR_NOT_READY, si la demande d’arrêt arrive en même temps qu’un utilisateur tente de se connecter au système. Dans ce cas, l’application doit attendre un court instant et réessayer l’appel.

Exemples

Pour obtenir un exemple, consultez Affichage de la boîte de dialogue Arrêt.

Notes

L’en-tête winreg.h définit InitiateSystemShutdown en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise


Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	winreg.h (inclure Windows.h)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll