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 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.

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.

Esempi

Un esempio è disponibile in Lettura di eventi del buffer di input.

Requisiti

Vedi anche

Funzioni della console

Handle della console

CreateFile

GetConsoleScreenBufferInfo

ReadConsoleInput

ReadFile

SetStdHandle

WriteConsole

WriteFile