Función GetStdHandle
Recupera un identificador del dispositivo estándar especificado (entrada estándar, salida estándar o error estándar).
Sintaxis
HANDLE WINAPI GetStdHandle(
_In_ DWORD nStdHandle
);
Parámetros
nStdHandle [in]
El dispositivo estándar. Este parámetro puede ser uno de los valores siguientes.
| Valor | Significado |
|---|---|
STD_INPUT_HANDLE ((DWORD)-10) |
El dispositivo de entrada estándar. Inicialmente, es el búfer de entrada de la consola, CONIN$. |
STD_OUTPUT_HANDLE ((DWORD)-11) |
El dispositivo de salida estándar. Inicialmente, es el búfer de pantalla activo de la consola, CONOUT$. |
STD_ERROR_HANDLE ((DWORD)-12) |
El dispositivo de error estándar. Inicialmente, es el búfer de pantalla activo de la consola, CONOUT$. |
Nota:
Los valores de estas constantes son números sin signo, pero se definen en los archivos de encabezado como una conversión a partir de un número con signo, y aprovechan que el compilador de C los sustituye por algo inferior al valor máximo de 32 bits. Al interactuar con estos identificadores en un lenguaje que no analiza los encabezados y vuelve a definir las constantes, tenga en cuenta esta restricción. Por ejemplo, ((DWORD)-10) en realidad es el número sin signo 4294967286.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es un identificador del dispositivo especificado o un identificador redirigido establecido por una llamada anterior en SetStdHandle. El identificador tiene los derechos de acceso GENERIC_READ y GENERIC_WRITE, a menos que la aplicación haya usado SetStdHandle para establecer un identificador estándar con un acceso inferior.
Sugerencia
No es necesario desechar este identificador con CloseHandle cuando haya terminado. Consulte Comentarios para más información.
Si se produce un error en la función, el valor devuelto es INVALID_HANDLE_VALUE. Para obtener información de error extendida, llame a GetLastError.
Si una aplicación no tiene identificadores estándar asociados, como un servicio que se ejecuta en un escritorio interactivo y no los ha redirigido, el valor devuelto es NULL.
Comentarios
Las aplicaciones que necesitan leer o escribir en la consola pueden usar los identificadores devueltos por GetStdHandle. Cuando se crea una consola, el identificador de entrada estándar es un identificador del búfer de entrada de la consola, y los identificadores de salida estándar y de error estándar son identificadores del búfer de pantalla activo de la consola. Las funciones ReadFile y WriteFile, o cualquiera de las funciones de la consola que tienen acceso al búfer de entrada de la consola o un búfer de pantalla (por ejemplo, las funciones ReadConsoleInput, WriteConsole o GetConsoleScreenBufferInfo) pueden usar estos identificadores.
Los identificadores estándar de un proceso se pueden redirigir mediante una llamada a SetStdHandle, en cuyo caso GetStdHandle devuelve el identificador redirigido. Si se han redirigido los identificadores estándar, puede especificar el valor CONIN$ en una llamada a la función CreateFile para obtener un identificador del búfer de entrada de la consola. De forma similar, puede especificar el valor CONOUT$ para obtener un identificador para el búfer de pantalla activo de la consola.
Los identificadores estándar de un proceso en la entrada del método principal están dictaminados por la configuración de la marca /SUBSYSTEM que se pasa al enlazador cuando se compiló la aplicación. Al especificar /SUBSYSTEM:CONSOLE, se solicita que el sistema operativo rellene los identificadores con una sesión de consola en el inicio, si el elemento primario aún no ha rellenado la tabla de identificadores estándar por herencia. Por el contrario, /SUBSYSTEM:WINDOWS implica que la aplicación no necesita una consola y que probablemente no usará los identificadores estándar. Puede encontrar más información sobre la herencia de identificadores en la documentación de STARTF_USESTDHANDLES.
Algunas aplicaciones funcionan fuera de los límites de su subsistema declarado; por ejemplo, una aplicación /SUBSYSTEM:WINDOWS puede comprobar o usar identificadores estándar para el registro o la depuración, pero funciona normalmente con una interfaz gráfica de usuario. Estas aplicaciones deberán sondear cuidadosamente el estado de los identificadores estándar en el inicio y usar AttachConsole, AllocConsole y FreeConsole para agregar o quitar una consola si se desea.
Algunas aplicaciones también pueden variar su comportamiento sobre el tipo de identificador heredado. La eliminación de la ambigüedad del tipo entre la consola, la canalización, el archivo y otros se pueden realizar con GetFileType.
Eliminación de identificadores
No es necesario aplicar CloseHandle cuando haya terminado con el identificador recuperado de GetStdHandle. El valor devuelto es simplemente una copia del valor almacenado en la tabla de procesos. Por lo general, el propio proceso se considera el propietario de estos identificadores y de su vigencia. Cada identificador se coloca en la tabla en el momento de la creación, en función de los detalles de herencia e inicio de la llamada CreateProcess y se liberará cuando se destruya el proceso.
La manipulación manual de la vigencia de estos identificadores puede ser conveniente para una aplicación que intente reemplazarlos intencionadamente o impedir que otras partes del proceso los utilicen. Como HANDLE se puede almacenar en caché mediante la ejecución de código, ese código no recogerá necesariamente los cambios realizados a través de SetStdHandle. Al cerrar el identificador de manera explícita a través de CloseHandle, se cerrará todo el proceso, y el siguiente uso de cualquier referencia almacenada en caché producirá un error.
La guía para reemplazar un identificador estándar en la tabla de procesos sería obtener el HANDLE existente de la tabla con GetStdHandle, usar SetStdHandle para colocar un nuevo HANDLE que se abre con CreateFile (o una función similar) y, a continuación, cerrar el identificador recuperado.
Las funciones GetStdHandle o SetStdHandle no validan los valores almacenados como identificadores en la tabla de procesos. La validación se realiza en el momento de la operación real de lectura y escritura, como ReadFile o WriteFile.
Comportamiento de la asociación o desasociación
Al asociarse a una nueva consola, los identificadores estándar siempre se reemplazan por identificadores de consola, a menos que se especifique STARTF_USESTDHANDLES durante la creación del proceso.
Si el valor existente del identificador estándar es NULL, o el valor existente del identificador estándar es similar a un pseudoidentificador de consola, el identificador se reemplaza por un identificador de consola.
Cuando un elemento primario usa tanto CREATE_NEW_CONSOLE como STARTF_USESTDHANDLES para crear un proceso de consola, no se reemplazarán los identificadores estándar a menos que el valor existente del identificador estándar sea NULL o un pseudoidentificador de consola.
Nota:
Los procesos de consola deben empezar con los identificadores estándar rellenados o se rellenarán automáticamente con los identificadores adecuados para una nueva consola. Las aplicaciones de la interfaz gráfica de usuario (GUI) se pueden iniciar sin los identificadores estándar y no se rellenarán automáticamente.
Ejemplos
Para un ejemplo, vea Lectura de eventos de búfer de entrada.
Requisitos
| Cliente mínimo compatible | Windows 2000 Professional [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows 2000 Server [solo aplicaciones de escritorio] |
| Encabezado | ProcessEnv.h (via Winbase.h, include Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |