Fonction GetStdHandle

Article
07/12/2023

Récupère un handle vers l’appareil standard spécifié (entrée standard, sortie standard ou erreur standard).

Syntaxe

HANDLE WINAPI GetStdHandle(
  _In_ DWORD nStdHandle
);

Paramètres

nStdHandle [entrée]
Périphérique standard. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
STD_INPUT_HANDLE`((DWORD)-10)`	Périphérique d’entrée standard. À la base, il s’agit de la mémoire tampon d’entrée de la console, `CONIN$`.
STD_OUTPUT_HANDLE`((DWORD)-11)`	Périphérique de sortie standard. À la base, il s’agit de la mémoire tampon d’écran de la console active, `CONOUT$`.
STD_ERROR_HANDLE`((DWORD)-12)`	Périphérique d’erreur standard. À la base, il s’agit de la mémoire tampon d’écran de la console active, `CONOUT$`.

Remarque

Bien que les valeurs de ces constantes soient des nombres non signés, elles sont définies dans les fichiers d’en-tête en tant que cast d’un nombre signé et tirent parti du compilateur C qui les fait passer juste en dessous de la valeur maximale de 32 bits. En cas d’interfaçage avec ces handles dans un langage qui n’analyse pas les en-têtes et qui redéfinit les constantes, tenez compte de cette contrainte. Par exemple, ((DWORD)-10) est en fait le nombre non signé 4294967286.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle vers le périphérique spécifié, ou un handle redirigé défini par un appel précédent à SetStdHandle. Le handle a les droits d’accès GENERIC_READ et GENERIC_WRITE, sauf si l’application a utilisé SetStdHandle pour définir un handle standard avec un accès plus restreint.

Conseil

Quand vous avez terminé, il n’est pas nécessaire de supprimer ce handle avec CloseHandle. Pour plus d’informations, consultez la section Remarques.

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

Si une application n’a pas de handles standard associés, comme un service s’exécutant sur un bureau interactif, et qu’elle ne les a pas redirigés, la valeur de retour est NULL.

Notes

Les handles retournés par GetStdHandle peuvent être utilisés par les applications qui doivent lire ou écrire dans la console. Quand une console est créée, le handle d’entrée standard est un handle vers la mémoire tampon d’entrée de la console, et les handles de sortie standard et d’erreur standard sont des handles vers la mémoire tampon d’écran active de la console. Ces handles peuvent être utilisés par les fonctions ReadFile et WriteFile, ou par une des fonctions de console qui accèdent à la mémoire tampon d’entrée de la console ou à une mémoire tampon d’écran (par exemple, les fonctions ReadConsoleInput, WriteConsole ou GetConsoleScreenBufferInfo).

Les handles standard d’un processus peuvent être redirigés par un appel à SetStdHandle, auquel cas GetStdHandle retourne le handle redirigé. Si les handles standard ont été redirigés, vous pouvez spécifier la valeur CONIN$ dans un appel à la fonction CreateFile pour obtenir un handle vers la mémoire tampon d’entrée d’une console. De même, vous pouvez spécifier la valeur CONOUT$ pour obtenir un handle vers la mémoire tampon d’écran active d’une console.

Les handles standard d’un processus sur l’entrée de la méthode main sont dictés par la configuration de l’indicateur /SUBSYSTEM passé à l’éditeur de liens lors de la génération de l’application. La spécification de /SUBSYSTEM : CONSOLE demande que le système d’exploitation remplisse les handles avec une session de console au démarrage si le parent n’a pas déjà rempli la table de handles standard par héritage. En revanche, /SUBSYSTEM:WINDOWS implique que l’application n’a pas besoin d’une console et qu’elle ne va probablement pas utiliser les handles standard. Vous trouverez plus d’informations sur l’héritage des handles dans la documentation pour STARTF_USESTDHANDLES.

Certaines applications fonctionnent en dehors des limites de leur sous-système déclaré. Par exemple, une application /SUBSYSTEM:WINDOWS peut vérifier/utiliser des handles standard à des fins de journalisation ou de débogage, mais elle fonctionne normalement avec une interface graphique utilisateur. Ces applications doivent soigneusement interroger l’état des handles standard au démarrage et utiliser AttachConsole, AllocConsole et FreeConsole pour ajouter/supprimer une console si nécessaire.

Certaines applications peuvent également modifier leur comportement selon le type de handle hérité. La levée des ambiguïtés de type entre console, canal, fichier et d’autres éléments peut être effectué avec GetFileType.

Suppression du handle

Il n’est pas nécessaire d’effectuer une opération CloseHandle quand vous n’avez plus besoin du handle récupéré dans GetStdHandle. La valeur retournée est simplement une copie de la valeur stockée dans la table de processus. Le processus lui-même est généralement considéré comme le propriétaire de ces handles et de leur durée de vie. Chaque handle est placé dans la table lors de la création en fonction des spécificités d’héritage et de lancement de l’appel CreateProcess et est libéré quand le processus est détruit.

La manipulation manuelle de la durée de vie de ces handles peut être souhaitable pour une application qui tente intentionnellement de les remplacer ou d’empêcher d’autres parties du processus de les utiliser. Étant donné qu’un HANDLE peut être mis en cache en exécutant du code, ce code n’intègre pas nécessairement les changements effectués avec SetStdHandle. La fermeture explicite du handle avec CloseHandle ferme l’ensemble du processus, et l’utilisation suivante de toute référence mise en cache rencontre une erreur.

Pour remplacer un handle standard dans la table de processus, il est conseillé d’obtenir le HANDLE existant de la table avec GetStdHandle, d’utiliser SetStdHandle pour placer un nouveau HANDLE dans celui ouvert avec CreateFile (ou une fonction similaire), puis de fermer le handle récupéré.

Les fonctions GetStdHandle et SetStdHandle n’effectuent aucune validation des valeurs stockées comme handles dans la table de processus. La validation est effectuée au moment de l’opération de lecture/écriture, par exemple ReadFile ou WriteFile.

Comportement d’attachement/détachement

Lors de l’attachement à une nouvelle console, les handles standard sont toujours remplacés par des handles de console, sauf si STARTF_USESTDHANDLES a été spécifié lors de la création du processus.

Si la valeur existante du handle standard est NULL ou si la valeur existante du handle standard ressemble à un pseudohandle de console, le handle est remplacé par un handle de console.

Quand un parent utilise à la fois CREATE_NEW_CONSOLE et STARTF_USESTDHANDLES pour créer un processus de console, les handles standard ne sont pas remplacés, sauf si la valeur existante du handle standard est NULL ou un pseudohandle de console.

Remarque

Les processus de console doivent démarrer avec les handles standard remplis ; sinon, ils seront renseignés automatiquement avec les handles appropriés pour une nouvelle console. Les applications avec interface graphique utilisateur peuvent être démarrées sans les handles standard ; ils ne seront pas renseignés automatiquement.

Exemples

Pour obtenir un exemple, consultez Lecture des événements de mémoire tampon d’entrée.

Spécifications


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
En-tête	ProcessEnv.h (via Winbase.h, inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll