Funzione ReadConsoleOutput

Articolo
10/23/2023

Importante

Questo documento descrive le funzionalità della piattaforma della console che non fanno più parte della roadmap dell'ecosistema. Non è consigliabile usare questo contenuto nei nuovi prodotti, ma continueremo a supportare gli utilizzi esistenti per il futuro indefinito. La soluzione moderna preferita è incentrata sulle sequenze di terminale virtuale per garantire la massima compatibilità negli scenari multipiattaforma. Per altre informazioni su questa decisione di progettazione, vedere il documento relativo alla console classica e al terminale virtuale.

Legge i dati degli attributi carattere e colore da un blocco rettangolare di celle di caratteri in un buffer dello schermo della console e la funzione scrive i dati in un blocco rettangolare in una posizione specificata nel buffer di destinazione.

Sintassi

BOOL WINAPI ReadConsoleOutput(
  _In_    HANDLE      hConsoleOutput,
  _Out_   PCHAR_INFO  lpBuffer,
  _In_    COORD       dwBufferSize,
  _In_    COORD       dwBufferCoord,
  _Inout_ PSMALL_RECT lpReadRegion
);

Parametri

hConsoleOutput [in]
Handle per il buffer dello schermo della console. L'handle deve avere il diritto di accesso GENERIC_READ . Per altre informazioni, vedere Sicurezza dei buffer della console e diritti di accesso.

lpBuffer [out]
Puntatore a un buffer di destinazione che riceve i dati letti dal buffer dello schermo della console. Questo puntatore viene considerato come origine di una matrice bidimensionale di strutture CHAR_INFO le cui dimensioni sono specificate dal parametro dwBufferSize.

dwBufferSize [in]
Dimensione del parametro lpBuffer , nelle celle di caratteri. Il membro X della struttura COORD è il numero di colonne. Il membro Y è il numero di righe.

dwBufferCoord [in]
Coordinate della cella superiore sinistra nel parametro lpBuffer che riceve i dati letti dal buffer dello schermo della console. Il membro X della struttura COORD è la colonna e il membro Y è la riga.

lpReadRegion [in, out]
Puntatore a una struttura SMALL_RECT. All'input, i membri della struttura specificano le coordinate in alto a sinistra e in basso a destra del rettangolo del buffer dello schermo della console da cui leggere la funzione. Nell'output, i membri della struttura specificano il rettangolo effettivo utilizzato.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Osservazioni:

ReadConsoleOutput considera il buffer dello schermo della console e il buffer di destinazione come matrici bidimensionali (colonne e righe di celle di caratteri). Il rettangolo a cui punta il parametro lpReadRegion specifica le dimensioni e la posizione del blocco da leggere dal buffer dello schermo della console. Un rettangolo di destinazione della stessa dimensione si trova con la cella superiore sinistra alle coordinate del parametro dwBufferCoord nella matrice lpBuffer . I dati letti dalle celle nel rettangolo di origine del buffer dello schermo della console vengono copiati nelle celle corrispondenti nel buffer di destinazione. Se la cella corrispondente non rientra nei limiti del rettangolo del buffer di destinazione (le cui dimensioni sono specificate dal parametro dwBufferSize ), i dati non vengono copiati.

Le celle nel buffer di destinazione corrispondenti alle coordinate che non rientrano nei limiti del buffer dello schermo della console vengono lasciate invariate. In altre parole, si tratta delle celle per le quali non sono disponibili dati del buffer dello schermo da leggere.

Prima che ReadConsoleOutput restituisca, imposta i membri della struttura a cui punta il parametro lpReadRegion sul rettangolo del buffer dello schermo effettivo le cui celle sono state copiate nel buffer di destinazione. Questo rettangolo riflette le celle nel rettangolo di origine per cui esiste una cella corrispondente nel buffer di destinazione, perché ReadConsoleOutput ritaglia le dimensioni del rettangolo di origine per adattarsi ai limiti del buffer dello schermo della console.

Se il rettangolo specificato da lpReadRegion si trova completamente al di fuori dei limiti del buffer dello schermo della console o se il rettangolo corrispondente è posizionato completamente al di fuori dei limiti del buffer di destinazione, non vengono copiati dati. In questo caso, la funzione restituisce con i membri della struttura a cui punta il parametro lpReadRegion impostato in modo che il membro Right sia minore di Left o che il membro Bottom sia minore di Top. Per determinare le dimensioni del buffer dello schermo della console, usare la funzione GetConsoleScreenBufferInfo.

La funzione ReadConsoleOutput non ha alcun effetto sulla posizione del cursore del buffer dello schermo della console. Il contenuto del buffer dello schermo della console non viene modificato dalla funzione .

Questa funzione usa i caratteri Unicode o i caratteri a 8 bit dalla tabella codici corrente della console. Inizialmente il valore predefinito della tabella codici della console è la tabella codici OEM del sistema. Per modificare la tabella codici della console usare le funzioni SetConsoleCP o SetConsoleOutputCP. I consumer legacy possono anche usare i comandichcp o mode con cp select= ma non è consigliabile per il nuovo sviluppo.

Suggerimento

Questa API non è consigliata e non ha un terminale virtuale equivalente. Questa decisione allinea intenzionalmente la piattaforma Windows ad altri sistemi operativi in cui si prevede che l'applicazione client ricordi il proprio stato disegnato per ulteriori modifiche. Le applicazioni remote tramite utilità multipiattaforma e trasporti come SSH potrebbero non funzionare come previsto se si usa questa API.

Esempi

Per un esempio, vedere Lettura e scrittura di blocchi di caratteri e attributi.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Intestazione	ConsoleApi2.h (tramite WinCon.h, includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll
Nomi Unicode e ANSI	ReadConsoleOutputW (Unicode) e ReadConsoleOutputA (ANSI)