Funzione ReadConsole
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) |