Funzione ReadConsole

Articolo
07/12/2023

Legge l'input dei caratteri dal buffer di input della console e lo rimuove dal buffer.

Sintassi

BOOL WINAPI ReadConsole(
  _In_     HANDLE  hConsoleInput,
  _Out_    LPVOID  lpBuffer,
  _In_     DWORD   nNumberOfCharsToRead,
  _Out_    LPDWORD lpNumberOfCharsRead,
  _In_opt_ LPVOID  pInputControl
);

Parametri

hConsoleInput [in]
Handle per il buffer di input 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 che riceve i dati letti dal buffer di input della console.

nNumberOfCharsToRead [in]
Numero di caratteri da leggere. Le dimensioni del buffer a cui punta il parametro lpBuffer devono essere almeno nNumberOfCharsToRead * sizeof(TCHAR) byte.

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

pInputControl [in, facoltativo]
Puntatore a una struttura CONSOLE_READCONSOLE_CONTROL che specifica un carattere di controllo per segnalare la fine dell'operazione di lettura. Questo parametro può essere NULL.

Questo parametro richiede l'input Unicode per impostazione predefinita. Per la modalità ANSI, impostare questo parametro su NULL.

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:

ReadConsole legge l'input della tastiera dal buffer di input di una console. Si comporta come la funzione ReadFile , ad eccezione del fatto che può essere letta in modalità Unicode (carattere wide) o ANSI. Per avere applicazioni che mantengono un singolo set di origini compatibili con entrambe le modalità, usare ReadConsole anziché ReadFile. Anche se ReadConsole può essere usato solo con un handle di buffer di input della console, ReadFile può essere usato con altri handle ( ad esempio file o pipe). ReadConsole ha esito negativo se usato con un handle standard che è stato reindirizzato in modo che sia diverso da un handle della console.

Tutte le modalità di input che influiscono sul comportamento di ReadFile hanno lo stesso effetto su ReadConsole. Per recuperare e impostare le modalità di input di un buffer di input della console, usare le funzioni GetConsoleMode e SetConsoleMode.

Se il buffer di input contiene eventi di input diversi dagli eventi della tastiera (ad esempio eventi del mouse o eventi di ridimensionamento della finestra), vengono eliminati. Tali eventi possono essere letti solo tramite la funzione ReadConsoleInput.

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.

Il parametro pInputControl può essere usato per abilitare le riattivazioni intermedie dalla lettura in risposta a un carattere di controllo di completamento file specificato in una struttura CONSOLE_READCONSOLE_CONTROL . Questa funzionalità richiede l'abilitazione delle estensioni dei comandi, l'handle di output standard come handle di output della console e l'input per essere Unicode.

Windows Server 2003 e Windows XP/2000: la funzionalità di lettura intermedia non è supportata.

La modalità cooked è quando ENABLE_LINE_INPUT è impostato con SetConsoleMode nell'handle di input della console. In modalità cooked, l'host della console fornirà una riga di modifica per conto dell'applicazione della riga di comando e le chiamate a ReadFile o ReadConsole non restituiranno finché non viene premuto il tasto INVIO.

La lettura intermedia è un aumento di tale comportamento nella chiamata ReadConsole in modalità di lettura preparata. L'impostazione di un flag in dwCtrlWakeupMask sulla struttura CONSOLE_READCONSOLE_CONTROL e passarla a pinputControl mentre chiama ReadConsole, comporterà che la lettura non attenderà necessariamente una nuova riga, ma restituendo anche su un carattere specificato.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Intestazione	ConsoleApi.h (tramite WinCon.h, con Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll
Nomi Unicode e ANSI	ReadConsoleW (Unicode) e ReadConsoleA (ANSI)