Fonction InitiateSystemShutdownExA (winreg.h)
Lance un arrêt et un redémarrage facultatif de l’ordinateur spécifié, et enregistre éventuellement la raison de l’arrêt.
Syntaxe
BOOL InitiateSystemShutdownExA(
[in, optional] LPSTR lpMachineName,
[in, optional] LPSTR lpMessage,
[in] DWORD dwTimeout,
[in] BOOL bForceAppsClosed,
[in] BOOL bRebootAfterShutdown,
[in] DWORD dwReason
);
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, InitiateSystemShutdownEx 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 l’arrêt.
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. 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é.
[in] dwReason
Motif du lancement de l’arrêt. Ce paramètre doit être l’un des codes de motif d’arrêt du système.
Si ce paramètre est égal à zéro, la valeur par défaut est un arrêt non défini qui est consigné comme « Aucun titre n’a pu être trouvé pour cette raison ». Par défaut, il s’agit également d’un arrêt non planifié. Selon la façon dont le système est configuré, un arrêt non planifié déclenche la création d’un fichier qui contient les informations d’état du système, ce qui peut retarder l’arrêt. Par conséquent, n’utilisez pas zéro pour ce paramètre.
Windows XP : Les informations d’état du système ne sont pas enregistrées lors d’un arrêt non planifié du système. Le texte précédent ne s’applique pas.
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 disposer du 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 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 ces applications à se fermer et qu’une application avec des modifications non enregistrées s’exécute 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.
Notes
L’en-tête winreg.h définit InitiateSystemShutdownEx 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
| Condition requise | Valeur |
|---|---|
| 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 |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour