GetStdHandle (funzione)
Recupera un handle per il dispositivo standard specificato (input standard, output standard o errore standard).
Sintassi
HANDLE WINAPI GetStdHandle(
_In_ DWORD nStdHandle
);
Parametri
nStdHandle [in]
Il dispositivo standard. Questo parametro può avere uno dei valori seguenti.
| Valore | Significato |
|---|---|
STD_INPUT_HANDLE ((DWORD)-10) |
Il dispositivo di input standard. Inizialmente si tratta del buffer di input della console, ovvero CONIN$. |
STD_OUTPUT_HANDLE ((DWORD)-11) |
Il dispositivo di output standard. Inizialmente si tratta del buffer dello schermo della console attivo, ovvero CONOUT$. |
STD_ERROR_HANDLE ((DWORD)-12) |
Il dispositivo di errore standard. Inizialmente si tratta del buffer dello schermo della console attivo, ovvero CONOUT$. |
Nota
I valori per queste costanti sono numeri senza segno, ma sono definiti nei file di intestazione come cast da un numero con segno e sfruttano il rollover del compilatore C fino al valore massimo a 32 bit. Quando si interagisce con questi handle in un linguaggio che non analizza le intestazioni e ridefinisce le costanti, tenere presente questo vincolo. Ad esempio, ((DWORD)-10) è in realtà il numero 4294967286senza segno .
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un handle per il dispositivo specificato o un handle reindirizzato impostato da una chiamata precedente su SetStdHandle. L'handle ha GENERIC_READ e GENERIC_WRITE diritti di accesso, a meno che l'applicazione non abbia usato SetStdHandle per impostare un handle standard con accesso minore.
Suggerimento
Non è necessario eliminare questo handle con CloseHandle al termine. Vedere osservazioni Per ulteriori informazioni.
Se la funzione ha esito negativo, il valore restituito è INVALID_HANDLE_VALUE. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Se a un'applicazione non sono associati handle standard, ad esempio un servizio in esecuzione su un desktop interattivo, e non sono stati reindirizzati, il valore restituito sarà NULL.
Osservazioni:
Gli handle restituiti da GetStdHandle possono essere usati dalle applicazioni che devono leggere o scrivere nella console. Al momento della creazione di una console, l'handle di input standard è un handle per il buffer di input della console e gli handle di output standard e di errore standard sono handle del buffer dello schermo attivo della console. Questi handle possono essere usati dalle funzioni ReadFile e WriteFile o da qualsiasi funzione della console che accede al buffer di input della console o a un buffer dello schermo, ad esempio ReadConsoleInput, WriteConsole o GetConsoleScreenBufferInfo.
Gli handle standard di un processo possono essere reindirizzati da una chiamata a SetStdHandle, nel qual caso GetStdHandle restituisce l'handle reindirizzato. Se gli handle standard sono stati reindirizzati, è possibile specificare il valore CONIN$ in una chiamata alla funzione CreateFile per ottenere un handle per il buffer di input di una console. Analogamente, è possibile specificare il valore CONOUT$ per ottenere un handle per il buffer dello schermo attivo di una console.
Gli handle standard di un processo all'immissione del metodo principale sono determinati dalla configurazione del flag /SUBSYSTEM passato al linker al momento della compilazione dell'applicazione. Se si specifica /SUBSYSTEM:CONSOLE, si richiede al sistema operativo di riempire gli handle con una sessione della console all'avvio, se il padre non ha già riempito la tabella di handle standard mediante ereditarietà. Viceversa, /SUBSYSTEM:WINDOWS implica che l'applicazione non necessita di una console e probabilmente non userà gli handle standard. Altre informazioni sulla gestione dell'ereditarietà sono disponibili nella documentazione per STARTF_USESTDHANDLES.
Alcune applicazioni operano all'esterno dei limiti del sottosistema dichiarato. Ad esempio, un'applicazione /SUBSYSTEM:WINDOWS potrebbe controllare/usare gli handle standard per la registrazione o il debug, ma funzionare normalmente con un'interfaccia utente grafica. Queste applicazioni dovranno verificare accuratamente lo stato degli handle standard all'avvio e usare AttachConsole, AllocConsole, and FreeConsole per aggiungere/rimuovere una console, se necessario.
Alcune applicazioni possono anche variare il comportamento in base al tipo di handle ereditato. La distinzione del tipo tra console, pipe, file e altri può essere eseguita con GetFileType.
Gestire l'eliminazione
Non è necessario chiudere CloseHandle quando l'handle viene recuperato da GetStdHandle.It is not required to CloseHandle when done with the handle retrieved from GetStdHandle. Il valore restituito è semplicemente una copia del valore archiviato nella tabella di processo. Il processo stesso è in genere considerato il proprietario di questi handle e la loro durata. Ogni handle viene inserito nella tabella alla creazione a seconda dell'ereditarietà e delle specifiche di avvio della chiamata CreateProcess e verrà liberato quando il processo viene eliminato definitivamente.
La manipolazione manuale della durata di questi handle può essere utile per un'applicazione che tenta intenzionalmente di sostituirle o bloccare l'uso di altre parti del processo. Poiché può HANDLE essere memorizzato nella cache eseguendo il codice, tale codice non rileverà necessariamente le modifiche apportate tramite SetStdHandle. La chiusura esplicita dell'handle tramite CloseHandle la chiuderà a livello di processo e l'utilizzo successivo di qualsiasi riferimento memorizzato nella cache riscontrerà un errore.
Le linee guida per la sostituzione di un handle standard nella tabella di processo consisterebbero nell'ottenere la esistente HANDLE dalla tabella con GetStdHandle, usare SetStdHandle per inserire un nuovo HANDLE oggetto in che viene aperto con CreateFile (o una funzione simile), quindi per chiudere l'handle recuperato.
Non esiste alcuna convalida dei valori archiviati come handle nella tabella di processo tramite le funzioni GetStdHandle o SetStdHandle . La convalida viene eseguita al momento dell'operazione di lettura/scrittura effettiva, ad esempio ReadFile o WriteFile.
Comportamento di collegamento/scollegamento
Quando si esegue il collegamento a una nuova console, gli handle standard vengono sempre sostituiti con handle della console, a meno che non sia stato specificato STARTF_USESTDHANDLES durante la creazione del processo.
Se il valore esistente dell'handle standard è NULL o se ha l'aspetto di uno pseudohandle della console, l'handle viene sostituito con un handle della console.
Quando un elemento padre usa sia CREATE_NEW_CONSOLE che STARTF_USESTDHANDLES per creare un processo della console, gli handle standard non verranno sostituiti a meno che il valore esistente dell'handle standard non sia NULL o uno pseudohandle della console.
Nota
I processi della console devono iniziare con gli handle standard riempiti, altrimenti verranno riempiti automaticamente con gli handle appropriati per una nuova console. Le applicazioni GUI (interfaccia utente grafica) possono essere avviate senza gli handle standard e non verranno riempite automaticamente.
Esempi
Un esempio è disponibile in Lettura di eventi del buffer di input.
Requisiti
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Intestazione | ProcessEnv.h (tramite Winbase.h, con Windows.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |