Função GetStdHandle
Recupera um identificador para o dispositivo padrão especificado (entrada padrão, saída padrão ou erro padrão).
Sintaxe
HANDLE WINAPI GetStdHandle(
_In_ DWORD nStdHandle
);
Parâmetros
nStdHandle [in]
O desvio padrão. Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
STD_INPUT_HANDLE ((DWORD)-10) |
O dispositivo de entrada padrão. Inicialmente, esse é o buffer de entrada do console, CONIN$. |
STD_OUTPUT_HANDLE ((DWORD)-11) |
O dispositivo de saída padrão. Inicialmente, esse é o buffer de tela do console ativo, CONOUT$. |
STD_ERROR_HANDLE ((DWORD)-12) |
O dispositivo de erro padrão. Inicialmente, esse é o buffer de tela do console ativo, CONOUT$. |
Observação
Os valores dessas constantes são números não assinados, mas são definidos nos arquivos de cabeçalho como uma conversão de um número assinado e aproveitam o compilador C, substituindo-os para ficarem abaixo do valor máximo de 32 bits. Ao fazer a interface com esses identificadores em uma linguagem que não analisa os cabeçalhos e está redefinindo as constantes, esteja ciente dessa restrição. Por exemplo, ((DWORD)-10) é, na verdade, o número não assinado 4294967286.
Valor retornado
Se a função for bem-sucedida, o valor retornado será um identificador para o dispositivo especificado ou um identificador redirecionado definido por uma chamada anterior para SetStdHandle. O identificador tem os direitos de acesso GENERIC_READ e GENERIC_WRITE, a menos que o aplicativo tenha usado SetStdHandle para definir um identificador padrão com menos acesso.
Dica
Não será necessário descartar esse identificador com CloseHandle quando terminar. Confira Comentários para obter mais informações.
Se houver falha na função, o valor retornado será INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError.
Se um aplicativo não tiver identificadores padrão associados, como um serviço em execução em uma área de trabalho interativa, e não as tiver redirecionado, o valor retornado será NULL.
Comentários
Os identificadores retornados por GetStdHandle podem ser usados por aplicativos que precisam fazer a leitura do console ou a gravação nele. Quando um console é criado, o identificador de entrada padrão é um identificador para o buffer de entrada do console, e os identificadores de saída padrão e de erro padrão são identificadores do buffer de tela ativo do console. Esses identificadores podem ser usados pelas funções ReadFile e WriteFile ou por qualquer uma das funções de console que acessam o buffer de entrada do console ou um buffer de saída (por exemplo, as funções ReadConsoleInput, WriteConsole ou GetConsoleScreenBufferInfo).
Os identificadores padrão de um processo podem ser redirecionados por uma chamada para SetStdHandle. Nesse caso, GetStdHandle retorna o identificador redirecionado. Se os identificadores padrão tiverem sido redirecionados, você poderá especificar o valor CONIN$ em uma chamada para a função CreateFile para obter um identificador para o buffer de entrada de um console. Da mesma forma, você pode especificar o valor CONOUT$ para obter um identificador para o buffer de tela ativo de um console.
Os identificadores padrão de um processo na entrada do método principal são ditados pela configuração do sinalizador /SUBSYSTEM passado para o vinculador quando o aplicativo foi criado. Especificar /SUBSYSTEM:CONSOLE solicita que o sistema operacional preencha os identificadores com uma sessão de console na inicialização, caso o pai ainda não tenha preenchido a tabela de identificador padrão por herança. Por outro lado, /SUBSYSTEM:WINDOWS implica que o aplicativo não precisa de um console e provavelmente não usará os identificadores padrão. Mais informações sobre a herança de identificadores podem ser encontradas na documentação de STARTF_USESTDHANDLES.
Alguns aplicativos operam fora dos limites do subsistema declarado deles; por exemplo, um aplicativo /SUBSYSTEM:WINDOWS pode verificar/usar identificadores padrão para fins de registro em log ou depuração, mas operar normalmente com uma interface gráfica do usuário. Esses aplicativos precisarão investigar cuidadosamente o estado dos identificadores padrão na inicialização e fazer uso de AttachConsole, AllocConsole e FreeConsole para adicionar/remover um console, se desejado.
Alguns aplicativos também podem variar o comportamento deles no tipo de identificador herdado. A desambiguação do tipo entre o console, o pipe, o arquivo e outros pode ser executada com GetFileType.
Descarte do identificador
Não será necessário CloseHandle quando concluir o identificador recuperado de GetStdHandle. O valor retornado é simplesmente uma cópia do valor armazenado na tabela de processo. O processo em si geralmente é considerado o proprietário desses identificadores e do tempo de vida deles. Cada identificador é colocado na tabela durante a criação, dependendo da herança e das especificidades de inicialização da chamada CreateProcess e será liberado quando o processo for destruído.
A manipulação manual do tempo de vida desses identificadores pode ser desejável para um aplicativo tentar substituí-los intencionalmente ou impedir que outras partes do processo os usem. Como um HANDLE pode ser armazenado em cache por meio da execução de código, esse código não coletará necessariamente as alterações feitas por meio de SetStdHandle. Fechar o identificador explicitamente por meio de CloseHandle o fechará em todo o processo e o próximo uso de qualquer referência armazenada em cache encontrará um erro.
As diretrizes para substituir um identificador padrão na tabela de processo seriam obter o HANDLE existente da tabela com GetStdHandle, usar SetStdHandle para colocar um novo HANDLE no que é aberto com CreateFile (ou uma função semelhante) e, em seguida, fechar o identificador recuperado.
Não há nenhuma validação dos valores armazenados como identificadores na tabela de processo pelas funções GetStdHandle ou SetStdHandle. A validação é realizada no momento da operação de leitura/gravação real, como ReadFile ou WriteFile.
Comportamento de anexação/desanexação
Quando são anexados a um novo console, os identificadores padrão sempre são substituídos por identificadores de console, a menos que STARTF_USESTDHANDLES tenha sido especificado durante a criação do processo.
Se o valor existente do identificador padrão for NULL ou o valor existente do identificador padrão for semelhante a um pseudoidentificador de console, o identificador será substituído por um identificador de console.
Quando um pai usa CREATE_NEW_CONSOLE e STARTF_USESTDHANDLES para criar um processo de console, os identificadores padrão não serão substituídos a menos que o valor existente do identificador padrão seja NULL ou um pseudoidentificador de console.
Observação
Os processos de console precisam começar com os identificadores padrão preenchidos ou serão preenchidos automaticamente com os identificadores apropriados para um novo console. Os aplicativos de GUI (interface gráfica do usuário) podem ser iniciados sem os identificadores padrão e não serão preenchidos automaticamente.
Exemplos
Para obter um exemplo, confira Como ler eventos de buffer de entrada.
Requisitos
| Cliente mínimo com suporte | Windows 2000 Professional [somente aplicativos para desktop] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| Cabeçalho | ProcessEnv.h (por meio de Winbase.h, incluir Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |