Fonction InitiateSystemShutdownExW (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 InitiateSystemShutdownExW(
[in, optional] LPWSTR lpMachineName,
[in, optional] LPWSTR 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 est 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 à 3072 TCHAR.
[in] dwTimeout
Durée pendant laquelle la boîte de dialogue d’arrêt doit s’afficher, en secondes. Bien que cette boîte de dialogue s’affiche, l’arrêt peut être arrêté par la fonction AbortSystemShutdown.
Si dwTimeout n’est pas 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 bips lorsqu’elle est créée et reste sur d’autres fenêtres du système. La boîte de dialogue peut être déplacée, mais pas fermée. Un minuteur compte la durée restante 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 de 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 leur indiquant que l’arrêt a été lancé. La boîte de dialogue inclut les personnes qui ont 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 est TRUE, les applications avec des modifications non enregistrées doivent être fermées de force. Si ce paramètre est FALSE, le système affiche une boîte de dialogue indiquant à l’utilisateur de fermer les applications.
[in] bRebootAfterShutdown
Si ce paramètre est TRUE, l’ordinateur doit redémarrer immédiatement après l’arrêt. Si ce paramètre est FALSE, le système vide tous les caches sur le disque et alimente le système en toute sécurité.
[in] dwReason
Motif de l’arrêt. Ce paramètre doit être l’un des codes de raison 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 enregistré sous la forme « Aucun titre pour cette raison est introuvable ». Par défaut, il s’agit également d’un arrêt non planifié. Selon la configuration du système, 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 : informations d’état système ne sont pas enregistrées lors d’un arrêt du système non planifié. Le texte précédent ne s’applique pas.
Valeur de retour
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’erreur étendues, 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 sur lequel 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 un privilège insuffisant. 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 de l’utilisateur est activé, mais qu’aucun utilisateur n’est connecté.
Une valeur de retour non nulle ne signifie pas que la déconnexion a été ou sera réussie. L’arrêt est un processus asynchrone et peut se produire longtemps après que l’appel d’API a retourné, ou pas du tout. Même si la valeur de 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 non 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 ou non. Si l’appelant choisit de ne pas forcer ces applications à 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 se connecte à la session de console abandonne l’arrêt, enregistre les modifications, ferme l’application ou force l’application à fermer. Pendant cette période, l’arrêt peut ne 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
Windows Server 2003 et Windows XP : Si l’ordinateur est verrouillé et que le paramètre bForceAppsClosed est FALSE, le dernier code d’erreur est ERROR_MACHINE_LOCKED. Si le système n’est pas prêt à gérer la requête, le dernier code d’erreur est ERROR_NOT_READY. L’application doit attendre un court moment et réessayer l’appel. Par exemple, le système peut être non 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 moment et réessayer l’appel.
Note
L’en-tête winreg.h définit InitiateSystemShutdownEx comme 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. Le mélange 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’en-tête | winreg.h (inclure Windows.h) |
| bibliothèque | Advapi32.lib |
| DLL | Advapi32.dll |