_CrtDbgReport, _CrtDbgReportW
Gera um relatório com uma mensagem de depuração e envia o relatório para três destinos possíveis (somente versões de depuração).
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 relatório: _CRT_WARN, _CRT_ERROR e _CRT_ASSERT.filename
Ponteiro para o nome do arquivo de origem em que a asserção/relatório ocorreu ou que é NULL.linenumber
Número da linha no arquivo de origem em que a asserção/relatório ocorreu ou que é NULL.moduleName
Ponteiro para o nome do módulo (.exe ou .dll) em que a asserção/relatório ocorreu.format
Ponteiro para a cadeia de caracteres formato-controle usada para criar a mensagem do usuário.argument
Argumentos de substituição opcionais usados por format.
Valor de retorno
Para todos os destinos do relatório, _CrtDbgReport e _CrtDbgReportW retornam -1 em caso de erro e 0 caso nenhum erro seja encontrado. No entanto, quando o destino do relatório é uma janela de mensagem de depuração e o usuário clica no botão Tentar novamente, essas funções retornam o valor 1. Se o usuário clicar no botão Abortar na janela da mensagem de depuração, essas funções serão abortadas imediatamente e não retornarão um valor.
As macros de depuração _RPT, _RPTF chamam _CrtDbgReport para gerar seus relatórios de depuração. As versões de caracteres largos dessas macros, bem como _ASSERT[E], _RPTWn e _RPTFWn, usam _CrtDbgReportW para gerar seus relatórios de depuração. Quando _CrtDbgReport ou _CrtDbgReportW retorna o valor 1, essas macros iniciam o depurador se a depuração JIT (just-in-time) estiver habilitada.
Comentários
_CrtDbgReport e _CrtDbgReportW podem enviar o relatório de depuração para três destinos diferentes: um arquivo de relatório de depuração, um monitor de depuração (o depurador Visual Studio) ou uma janela de mensagem de depuração. Duas funções de configuração _CrtSetReportMode e _CrtSetReportFile são usada para especificar o destino (ou destinos) de cada tipo de relatório. Essas funções permitem o controle independente do destino de cada tipo de relatório. Por exemplo, é possível especificar que um reportType de _CRT_WARN seja enviado somente ao monitor de depuração, enquanto um reportType de _CRT_ASSERT é enviado a uma janela de mensagem de depuração e a um arquivo de relatório definido pelo usuário.
_CrtDbgReportW é a versão de caracteres largos do _CrtDbgReport. Todos os parâmetros de saída e cadeia de caracteres estão em cadeias de caracteres largos. Caso contrário, não há diferença da versão de caractere de byte único.
_CrtDbgReport e _CrtDbgReportW criam a mensagem do usuário para o relatório de depuração ao substituir os argumentos argument[n] na cadeia de caracteres format usando as mesmas regras definidas pelas funções printf ou wprintf. Essas funções geram o relatório de depuração e determinam o destino (ou destinos) com base nos modos do relatório atual e no arquivo definido para reportType. Quando o relatório é enviado para uma janela de mensagem de depuração, filename, lineNumber e moduleName são incluídos nas informações exibidas na janela.
O tabela a seguir lista as opções disponíveis para o modo (ou modos), o arquivo do relatório e o comportamento resultante de _CrtDbgReport e _CrtDbgReportW. Essas opções são definidas como sinalizadores de bits em <crtdbg.h>.
Modo do relatório |
Arquivo do relatório |
Comportamento _CrtDbgReport, _CrtDbgReportW |
|---|---|---|
_CRTDBG_MODE_DEBUG |
Não aplicável |
Grava mensagens usando a API OutputDebugString do Windows. |
_CRTDBG_MODE_WNDW |
Não aplicável |
Chama a API MessageBox do Windows para criar uma caixa de mensagem e exibir a mensagem com os botões Abortar, Tentar novamente e Ignorar. Se o usuário clicar em Abortar, _CrtDbgReport ou _CrtDbgReport é abortado imediatamente. Se o usuário clicar em Tentar novamente, o valor 1 é retornado. Se o usuário clicar em Ignorar, a execução continua e _CrtDbgReport e _CrtDbgReportW retornam 0. Observe que clicar em Ignorar quando há uma condição de erro geralmente resulta em "comportamento inesperado". |
_CRTDBG_MODE_FILE |
__HFILE |
Grava mensagens no HANDLE fornecido ao usuário, usando a API WriteFile do Windows e não verifica a validade do identificador de arquivo: o aplicativo é responsável por abrir o relatório e apresentar um indicador de arquivo válido. |
_CRTDBG_MODE_FILE |
_CRTDBG_FILE_STDERR |
Grava a mensagem no stderr. |
_CRTDBG_MODE_FILE |
_CRTDBG_FILE_STDOUT |
Grava a mensagem no stdout. |
O relatório pode ser enviado para um, dois ou três destinos ou nenhum destino. Para obter mais informações sobre como especificar o modo (ou modos) do relatório e o arquivo do relatório, consulte as funções _CrtSetReportMode e _CrtSetReportFile. Para obter mais informações como usar as macros de depuração e as funções de relatórios, consulte Macros para relatórios.
Se seu aplicativo precisa de mais flexibilidade que _CrtDbgReport e _CrtDbgReportW fornecem, você pode gravar sua própria função de relatório e conectá-la ao mecanismo de relatório da biblioteca de tempo de execução C usando a função _CrtSetReportHook.
Requisitos
Rotina |
Cabeçalho necessário |
|---|---|
_CrtDbgReport |
<crtdbg.h> |
_CrtDbgReportW |
<crtdbg.h> |
_CrtDbgReport e _CrtDbgReportW são extensões da Microsoft. Para obter mais informações, consulte Compatibilidade.
Libraries
Somente versões de depuração de bibliotecas de tempo de execução C.
Exemplo
// crt_crtdbgreport.c
#include <crtdbg.h>
int main(int argc, char *argv[]) {
#ifdef _DEBUG
_CrtDbgReport(_CRT_ASSERT, __FILE__, __LINE__, argv[0], NULL);
#endif
}
Consulte crt_dbg2 para ver um exemplo de como alterar a função do relatório.