_CrtDbgReport, _CrtDbgReportW
Genera un informe con un mensaje de depuración y lo envía a tres destinos posibles (solo versión de depuración).
int _CrtDbgReport( int reportType, const char *filename, int linenumber, const char *moduleName, const char *format [, argument] ... ); int _CrtDbgReportW( int reportType, const wchar_t *filename, int linenumber, const wchar_t *moduleName, const wchar_t *format [, argument] ... );
Parámetros
reportType
Tipo de informe: _CRT_WARN, _CRT_ERROR y _CRT_ASSERT.filename
Puntero al nombre del archivo de código fuente donde se produjo la aserción o el informe, o NULL.linenumber
Número de la línea del archivo de código fuente donde se produjo la aserción o el informe, o NULL.moduleName
Puntero al nombre del módulo (.exe o .dll) donde se produjo la aserción o el informe.format
Puntero a la cadena de control de formato utilizada para crear el mensaje de usuario.argument
Argumentos de sustitución opcionales utilizados por format.
Valor devuelto
Para todos los destinos de informe, _CrtDbgReport y _CrtDbgReportW devuelven –1 si se produce un error, y 0 si no se producen errores. Sin embargo, cuando el destino del informe es una ventana de mensajes de depuración y el usuario hace clic en el botón Reintentar, estas funciones devuelven 1. Si el usuario hace clic en el botón Anular de la ventana de mensajes de depuración, estas funciones se anulan inmediatamente y no devuelven ningún valor.
Las macros de depuración _RPT, _RPTF llaman a _CrtDbgReport para generar los informes de depuración. Las versiones de caracteres anchos de estas macros, así como _ASSERT [E], _RPTWn y _RPTFWn, usan _CrtDbgReportW para generar los informes de depuración. Si _CrtDbgReport o _CrtDbgReportW devuelven 1, estas macros inician el depurador, siempre que esté habilitada la depuración Just-in-time (JIT).
Comentarios
_CrtDbgReport y _CrtDbgReportW pueden enviar el informe de depuración a tres destinos distintos: un archivo de informe de depuración, un monitor de depuración (el depurador Visual Studio) o una ventana de mensajes de depuración. Se usan dos funciones de configuración, _CrtSetReportMode y _CrtSetReportFile, para especificar los destinos de cada tipo de informe. Estas funciones permiten controlar por separado los destinos de los informes de cada tipo de informe. Por ejemplo, se puede especificar que un parámetro reportType de _CRT_WARN se envíe solo al monitor de depuración, y que el parámetro reportType de _CRT_ASSERT se envíe a una ventana de mensajes de depuración y a un archivo de informe definido por el usuario.
_CrtDbgReportW es la versión con caracteres anchos de _CrtDbgReport. Todos sus parámetros de salida y de cadena son cadenas de caracteres anchos; por lo demás, es idéntica a la versión de caracteres de un solo byte.
_CrtDbgReport y _CrtDbgReportW crean el mensaje de usuario para el informe de depuración sustituyendo los argumentos de argument[n] de la cadena format, con las mismas reglas definidas por las funciones printf o wprintf. A continuación, estas funciones generan el informe de depuración y determinan los destinos en función de los modos de informe actuales y el archivo definidos para reportType. Cuando el informe se envía a una ventana de mensajes de depuración, los parámetros filename, lineNumber y moduleName se incluyen en la información que se muestra en la ventana.
En la tabla siguiente se enumeran las opciones de los modos y el archivo de informe, y el comportamiento que producen _CrtDbgReport y _CrtDbgReportW. Estas opciones se definen como marcas de bits en <crtdbg.h>.
Modo de informe |
Archivo de informe |
Comportamiento de _CrtDbgReport y _CrtDbgReportW |
|---|---|---|
_CRTDBG_MODE_DEBUG |
No es aplicable |
Escribe un mensaje mediante la API OutputDebugString de Windows. |
_CRTDBG_MODE_WNDW |
No es aplicable |
Llama a la API MessageBox de Windows para crear el cuadro de mensaje en el que se mostrará el mensaje junto con los botones Anular, Reintentar y Omitir. Si un usuario hace clic en Anular, _CrtDbgReport o _CrtDbgReport se anulan inmediatamente. Si un usuario hace clic en Reintentar, devuelve 1. Si un usuario hace clic en Omitir, la ejecución continúa y _CrtDbgReport y _CrtDbgReportW devuelven 0. Observe que si se hace clic en Omitir cuando existe una condición de error, se suele producir un "comportamiento indefinido". |
_CRTDBG_MODE_FILE |
__HFILE |
Escribe el mensaje en el HANDLE proporcionado por el usuario, usando la API WriteFile de Windows, y no comprueba la validez del identificador de archivo. La aplicación se ocupa de abrir el archivo de informe y pasar un identificador de archivo válido. |
_CRTDBG_MODE_FILE |
_CRTDBG_FILE_STDERR |
Escribe el mensaje en stderr. |
_CRTDBG_MODE_FILE |
_CRTDBG_FILE_STDOUT |
Escribe el mensaje en stdout. |
El informe se puede enviar a uno, dos o tres destinos, o a ninguno. Para obtener más información sobre cómo especificar los modos de informe y el archivo de informe, vea las funciones _CrtSetReportMode y _CrtSetReportFile. Para más información sobre el uso de las macros de depuración y las funciones de creación de informes, vea Macros para los informes.
Si la aplicación necesita más flexibilidad que la proporcionada por _CrtDbgReport y _CrtDbgReportW, puede escribir su propia función de creación de informes y unirla al mecanismo de creación de informes de la biblioteca en tiempo de ejecución de C mediante la función _CrtSetReportHook.
Requisitos
Rutina |
Encabezado necesario |
|---|---|
_CrtDbgReport |
<crtdbg.h> |
_CrtDbgReportW |
<crtdbg.h> |
_CrtDbgReport y _CrtDbgReportW son extensiones de Microsoft. Para obtener más información, vea Compatibilidad.
Bibliotecas
Solo las versiones de depuración de las bibliotecas en tiempo de ejecución de C.
Ejemplo
// crt_crtdbgreport.c
#include <crtdbg.h>
int main(int argc, char *argv[]) {
#ifdef _DEBUG
_CrtDbgReport(_CRT_ASSERT, __FILE__, __LINE__, argv[0], NULL);
#endif
}
Vea crt_dbg2 para obtener un ejemplo de cómo cambiar la función de informes.