_CrtDbgReport, _CrtDbgReportW
Genera un rapporto con un messaggio di debug e lo invia tre possibili destinazioni (solo versione di debug).
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] ... );
Parametri
reportType
Tipo di segnalazione: _CRT_WARN, _CRT_ERROR e _CRT_ASSERT.filename
Puntatore al nome del file di origine in cui si è verificata l'asserzione o il rapporto o NULL.linenumber
Numero di riga nel file di origine in cui si è verificata l'asserzione o il rapporto o NULL.moduleName
Puntatore al nome del modulo (.exe o .dll) in cui si è verificata l'asserzione o il rapporto.format
Puntatore alla stringa di controllo del formato usata per creare il messaggio utente.argument
Argomenti di sostituzione facoltativi usati da format.
Valore restituito
Per tutte le destinazioni del rapporto, _CrtDbgReport e _CrtDbgReportW restituiscono –1 se si verifica un errore e 0 se non si verificano errori. Tuttavia, quando la destinazione del rapporto è una finestra di messaggio di debug e l'utente fa clic sul pulsante Riprova, queste funzioni restituiscono 1. Se l'utente fa clic sul pulsante Interrompi nella finestra di messaggio di debug, queste funzioni vengono interrotte immediatamente e non restituiscono un valore.
Le macro di debug _RPT, _RPTF effettuano una chiamata a _CrtDbgReport per generare i relativi rapporti di debug. Le versioni a caratteri wide di queste macro, nonché _ASSERT[E], _RPTWn e _RPTFWn usano _CrtDbgReportW per generare i rapporti di debug. Quando _CrtDbgReport o _CrtDbgReportW restituiscono 1, queste macro avviano il debugger JIT (just-in-time), purché il debug sia abilitato.
Note
_CrtDbgReport e _CrtDbgReportW possono inviare il rapporto di debug a tre destinazioni diverse: un file di rapporto di debug, un monitor di debug (ovvero il debugger Visual Studio) o a una finestra di messaggio di debug. Vengono usate due funzioni di configurazione, _CrtSetReportMode ed _CrtSetReportFile, per specificare la destinazione o le destinazioni per ogni tipo di rapporto Queste funzioni consentono alle destinazioni per la creazione dei rapporti per ogni tipo di rapporto di essere controllate separatamente. È ad esempio possibile specificare che un reportType di _CRT_WARN possa essere inviato solo al monitor di debug, mentre un reportType di _CRT_ASSERT sia inviato a una finestra di messaggio di debug e a un file di rapporto definito dall'utente.
_CrtDbgReportW è la versione a caratteri wide di _CrtDbgReport. Tutti gli output e i parametri di stringa sono espressi in stringhe a caratteri wide, per il resto è identico alla versione a un byte.
_CrtDbgReport e _CrtDbgReportW creano il messaggio utente per il rapporto di debug tramite la sostituzione degli argomenti argument[n] nella stringa format, usando le stesse regole definite dalle funzioni printf o wprintf. Queste funzioni generano quindi il rapporto di debug e determinano la destinazione o le destinazioni in base alle modalità rapporto correnti e al file definito per reportType. Quando il rapporto viene inviato a una finestra di messaggio di debug, filename, lineNumber e moduleName sono inclusi nelle informazioni visualizzate nella finestra.
Nella tabella seguente sono illustrate le scelte disponibili per le modalità rapporto e il file e il comportamento risultante di _CrtDbgReport e _CrtDbgReportW. Queste opzioni sono definite come flag di bit in <crtdbg.h>.
Modalità rapporto |
File di rapporto |
Comportamento di _CrtDbgReport, _CrtDbgReportW |
|---|---|---|
_CRTDBG_MODE_DEBUG |
Non applicabile |
Scrive i messaggi usando l'API OutputDebugString di Windows. |
_CRTDBG_MODE_WNDW |
Non applicabile |
Effettua una chiamata all'API MessageBox di Windows per creare la finestra di messaggio in cui visualizzare il messaggio oltre ai pulsanti Interrompi, Riprova e Ignora. Se un utente fa clic su Interrompi, _CrtDbgReport o _CrtDbgReport viene immediatamente interrotto. Se un utente fa clic su Riprova, restituisce 1. Se un utente fa clic su Ignora, l'esecuzione continua e _CrtDbgReport e _CrtDbgReportW restituiscono 0. Si noti che quando si fa clic su Ignora in presenza di una condizione di errore, spesso si determina un "comportamento indefinito". |
_CRTDBG_MODE_FILE |
__HFILE |
Scrive un messaggio nell'HANDLE fornito dall'utente, usando l'API WriteFile di Windows e non verifica la validità dell'handle di file. L'applicazione è responsabile dell'apertura del file del rapporto e del passaggio di un file di handle valido. |
_CRTDBG_MODE_FILE |
_CRTDBG_FILE_STDERR |
Scrive il messaggio in stderr. |
_CRTDBG_MODE_FILE |
_CRTDBG_FILE_STDOUT |
Scrive il messaggio in stdout. |
Il rapporto può essere inviato a una, due o tre destinazioni o a nessuna destinazione. Per altre informazioni su come specificare la modalità rapporto e il file del rapporto, vedere le funzioni _CrtSetReportMode e _CrtSetReportFile. Per altre informazioni sull'uso delle macro di debug e delle funzioni di creazione dei rapporti, vedere Macro per la creazione di rapporti.
Se l'applicazione necessita di maggiore flessibilità di quella fornita da _CrtDbgReport e _CrtDbgReportW, è possibile scrivere una funzione di creazione dei rapporti personalizzata e agganciarla nel meccanismo di creazione dei rapporti della libreria di runtime C usando la funzione _CrtSetReportHook.
Requisiti
Routine |
Intestazione obbligatoria |
|---|---|
_CrtDbgReport |
<crtdbg.h> |
_CrtDbgReportW |
<crtdbg.h> |
_CrtDbgReport e _CrtDbgReportW sono estensioni Microsoft. Per altre informazioni, vedere Compatibilità.
Librerie
Solo versioni di debug delle librerie di runtime C.
Esempio
// crt_crtdbgreport.c
#include <crtdbg.h>
int main(int argc, char *argv[]) {
#ifdef _DEBUG
_CrtDbgReport(_CRT_ASSERT, __FILE__, __LINE__, argv[0], NULL);
#endif
}
Per un esempio su come modificare la funzione rapporto, vedere crt_dbg2.