GetStdHandle (funzione)

Articolo
10/20/2023

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 sull'ereditarietà dell'handle sono disponibili nella documentazione relativa a STARTF_Uedizione Standard STDHANDLES.

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 collega a una nuova console, gli handle standard vengono sempre sostituiti con handle della console, a meno che non venga specificato STARTF_Uedizione Standard STDHANDLES 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_Uedizione Standard STDHANDLES 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)
Libreria	Kernel32.lib
DLL	Kernel32.dll