Funzione ReadConsoleOutputCharacter

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.

Copia un numero di caratteri da celle consecutive di un buffer dello schermo della console, a partire da una posizione specificata.

Sintassi

BOOL WINAPI ReadConsoleOutputCharacter(
  _In_  HANDLE  hConsoleOutput,
  _Out_ LPTSTR  lpCharacter,
  _In_  DWORD   nLength,
  _In_  COORD   dwReadCoord,
  _Out_ LPDWORD lpNumberOfCharsRead
);

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.

lpCharacter [out]
Puntatore a un buffer che riceve i caratteri letti dal buffer dello schermo della console.

nLength [in]
Numero di celle di caratteri del buffer dello schermo da cui leggere. Le dimensioni del buffer a cui punta il parametro lpCharacter devono essere nLength * sizeof(TCHAR).

dwReadCoord [in]
Coordinate della prima cella nel buffer dello schermo della console da cui leggere, in caratteri. Il membro X della struttura COORD è la colonna e il membro Y è la riga.

lpNumberOfCharsRead [out]
Puntatore a una variabile che riceve il numero di caratteri effettivamente letti.

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:

Se il numero di caratteri da leggere si estende oltre la fine della riga del buffer dello schermo specificata, i caratteri vengono letti dalla riga successiva. Se il numero di caratteri da leggere si estende oltre la fine del buffer dello schermo della console, i caratteri fino alla fine del buffer dello schermo della console vengono letti.

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.

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	ReadConsoleOutputCharacterW (Unicode) e ReadConsoleOutputCharacterA (ANSI)