Fonction CreateConsoleScreenBuffer

Article
12/22/2023

Important

Ce document décrit les fonctionnalités de la plateforme de la console qui ne font plus partie de la feuille de route de notre écosystème. Nous vous déconseillons d’utiliser ce contenu dans de nouveaux produits, mais nous continuerons à prendre en charge des utilisations existantes pour l’avenir indéterminé. Notre solution moderne préférée se concentre sur les séquences de terminaux virtuels pour une compatibilité maximale dans les scénarios multiplateformes. Vous trouverez plus d’informations sur cette décision de conception dans notre document sur les consoles classiques et les terminaux virtuels.

Crée une mémoire tampon de l’écran de la console.

Syntaxe

HANDLE WINAPI CreateConsoleScreenBuffer(
  _In_             DWORD               dwDesiredAccess,
  _In_             DWORD               dwShareMode,
  _In_opt_   const SECURITY_ATTRIBUTES *lpSecurityAttributes,
  _In_             DWORD               dwFlags,
  _Reserved_       LPVOID              lpScreenBufferData
);

Paramètres

dwDesiredAccess [entrée]
L’accès à la mémoire tampon de l’écran de la console. Pour obtenir la liste des droits d’accès, consultez la section Sécurité des mémoires tampons de console et droits d’accès.

dwShareMode [entrée]
La valeur de ce paramètre peut être égale à zéro, ce qui indique que la mémoire tampon ne peut pas être partagée, ou elle peut correspondre à une ou plusieurs des valeurs suivantes.

Valeur	Signification
FILE_SHARE_READ 0x00000001	D'autres opérations d'ouverture peuvent être effectuées sur la mémoire tampon de l'écran de la console pour un accès en lecture.
FILE_SHARE_WRITE 0x00000002	D'autres opérations d'ouverture peuvent être effectuées sur la mémoire tampon de l'écran de la console pour un accès en écriture.

lpSecurityAttributes [entrée, facultatif]
Un pointeur vers une structure SECURITY_ATTRIBUTES qui détermine si le descripteur renvoyé peut être hérité par des processus enfants. Si la valeur de lpSecurityAttributes est NUL, le descripteur ne peut pas être hérité. Le membre lpSecurityDescriptor de la structure spécifie un descripteur de sécurité pour la nouvelle mémoire tampon de l’écran de la console. Si la valeur de lpSecurityAttributes est NUL, la mémoire tampon de l’écran de la console obtient un descripteur de sécurité par défaut. Les ACL du descripteur de sécurité par défaut d'une mémoire tampon de l'écran de la console proviennent du jeton primaire ou du jeton d'emprunt d'identité du créateur.

dwFlags [in]
Le type de mémoire tampon de l’écran de la console à créer. Le seul type de mémoire tampon d’écran pris en charge est CONSOLE_TEXTMODE_BUFFER.

lpScreenBufferData
Réservé ; doit être NUL.

Valeur renvoyée

Si la fonction aboutit, la valeur renvoyée est un descripteur vers la nouvelle mémoire tampon de l’écran de la console.

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

Notes

Une console peut avoir plusieurs mémoires tampons d’écran, mais une seule mémoire tampon d’écran active. Les mémoires tampons d’écran inactives sont accessibles pour la lecture et l’écriture, mais seules les mémoires tampons d’écran actives sont affichées. Pour rendre la nouvelle mémoire tampon d’écran active, utilisez la fonction SetConsoleActiveScreenBuffer.

La mémoire tampon d’écran nouvellement créée copie certaines propriétés de la mémoire tampon d’écran active au moment où cette fonction est appelée. Le comportement est le suivant :

Font – copié à partir de la mémoire tampon d’écran active
Display Window Size – copié à partir de la mémoire tampon d’écran active
Buffer Size – mis en correspondance avec Display Window Size (NON copié)
Default Attributes (couleurs) – copié à partir de la mémoire tampon d’écran active
Default Popup Attributes (couleurs) – copié à partir de la mémoire tampon d’écran active

Le processus appelant peut utiliser le descripteur renvoyé dans n’importe quelle fonction qui nécessite un descripteur vers une mémoire tampon de l’écran de la console, sous réserve des limitations d’accès spécifiées par le paramètre dwDesiredAccess.

Le processus peut utiliser la fonction DuplicateHandle pour créer un descripteur de mémoire tampon d’écran dupliqué avec un accès ou un héritage différents de ceux du descripteur d’origine. Toutefois, DuplicateHandle ne peut pas être utilisé pour créer un duplicata valide pour un autre processus (à l’exception de l’héritage).

Pour fermer le descripteur de mémoire tampon de l’écran de la console, utilisez la fonction CloseHandle.

Conseil

Cette API n’est pas recommandée, mais elle a un équivalent approximatif de terminal virtuel dans la séquence de mémoires tampons d’écran alternatif. La définition de la mémoire tampon de l'écran alternative peut fournir à une application un espace séparé et isolé pour dessiner au cours du runtime de la session, tout en préservant le contenu affiché par l'invocateur de l'application. Les informations relatives au dessin sont ainsi conservées pour permettre une restauration simple lors de la sortie du processus.

Exemples

Pour obtenir un exemple, consultez la section Lecture et écriture de blocs de caractères et d’attributs.

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	ConsoleApi2.h (via WinCon.h, include Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll