_CrtDbgReport, _CrtDbgReportW
Generiert einen Bericht mit einer Debugmeldung und sendet den Bericht zu drei möglichen Zielen (nur Debugversion).
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] ... );
Parameter
reportType
Berichtstyp: _CRT_WARN, _CRT_ERROR und _CRT_ASSERT.filename
Zeiger auf den Namen der Quelldatei, in der Assert/Bericht oder NULL aufgetreten sind.linenumber
Zeilennummer in der Quelldatei, in der Assert/Bericht oder NULL aufgetreten sind.moduleName
Zeiger auf den Namen des Moduls (.exe oder .dll), in dem die Assertion oder der Bericht aufgetreten ist.format
Zeiger auf die Formatsteuerelementzeichenfolge, mit der die Benutzermeldung erstellt wird.argument
Von format verwendete optionale Ersatzargumente.
Rückgabewert
Für alle Berichtsziele geben _CrtDbgReport und _CrtDbgReportW bei einem Fehler – 1 und bei keinem Fehler 0 zurück. Wenn das Berichtsziel jedoch das Fenster einer Debugmeldung ist und der Benutzer auf die Schaltfläche Wiederholen klickt, dann geben diese Funktionen 1 zurück. Wenn der Benutzer im Fenster der Debugmeldung auf die Schaltfläche Abbrechen klickt, brechen diese Funktionen sofort ab und geben keinen Wert zurück.
Die Debugmakros _RPT, _RPTF rufen _CrtDbgReport auf, um ihre Debugberichte zu generieren. Die Breitzeichenversionen dieser Makros sowie _ASSERT [e], _RPTWn und _RPTFWn verwenden _CrtDbgReportW, um ihre Debugberichte zu generieren. Wenn _CrtDbgReport oder _CrtDbgReportW den Wert 1 zurückgeben, starten diese Makros den Debugger, vorausgesetzt, dass Just-In-Time(JIT)-Debugging aktiviert ist.
Hinweise
_CrtDbgReport und _CrtDbgReportW können den Debugbericht an drei verschiedene Ziele senden: an eine Debugberichtsdatei, einen Debugmonitor (der Visual Studio-Debugger) oder an ein Debugmeldungsfenster. Mit den zwei Konfigurationsfeatures _CrtSetReportMode und _CrtSetReportFile werden die Ziele für die einzelnen Berichtstypen angegeben. Mithilfe dieser Funktionen können die Berichtsziele für die einzelnen Berichtstypen separat gesteuert werden. Es kann beispielsweise angegeben werden, dass ein reportType von _CRT_WARN nur zum Debugmonitor gesendet wird, wohingegen ein reportType von _CRT_ASSERT zu einem Debugmeldungsfenster und einer benutzerdefinierten Berichtsdatei gesendet wird.
_CrtDbgReportW ist die Breitzeichenversion von _CrtDbgReport. Alle seine Ausgabe- und Zeichenfolgenparameter sind in Zeichenfolgen mit Breitzeichen. Ansonsten sind sie mit der Einzelbytezeichenversion identisch.
_CrtDbgReport und _CrtDbgReportW erstellen die Benutzermeldung für den Debugbericht, indem sie die argument[n]-Argumente durch die format-Zeichenfolge ersetzen und dabei die gleichen Regeln verwenden, die auch für die Funktionen printf oder wprintf definiert sind. Diese Funktionen generieren dann den Debugbericht und bestimmen das Ziel bzw. die Ziele gemäß der der für reportType definierten aktuellen Berichtsmodi und Berichtsdatei. Wenn der Bericht an ein Debugmeldungsfenster gesendet wird, sind filename, lineNumber und moduleName in den im Fenster angezeigten Informationen enthalten.
In der folgenden Tabelle werden die verfügbaren Optionen für den Berichtsmodus (bzw. die Berichtsmodi) und die Berichtsdatei sowie das resultierende Verhalten von _CrtDbgReport und _CrtDbgReportW aufgeführt. Diese Optionen werden als Bitflags in <crtdbg.h> definiert.
Berichtsmodus |
Berichtsdatei |
Verhalten von _CrtDbgReport und _CrtDbgReportW |
|---|---|---|
_CRTDBG_MODE_DEBUG |
Nicht zutreffend |
Schreibt Nachrichten mithilfe der Windows-API OutputDebugString. |
_CRTDBG_MODE_WNDW |
Nicht zutreffend |
Ruft die Windows-API MessageBox zum Erstellen eines Meldungsfelds auf, um die Meldung zusammen mit den Schaltflächen Abbrechen, Wiederholen und Ignorieren anzuzeigen. Wenn ein Benutzer auf Abbrechen klickt, wird _CrtDbgReport oder _CrtDbgReport sofort abgebrochen. Wenn ein Benutzer auf Wiederholen klickt, wird 1 zurückgegeben. Wenn ein Benutzer auf Ignorieren klickt, wird die Ausführung fortgesetzt, und _CrtDbgReport und _CrtDbgReportW geben 0 zurück. Wenn ein Fehlerzustand vorliegt, führt das Klicken auf Ignorieren häufig zu einem "undefinierten Verhalten". |
_CRTDBG_MODE_FILE |
__HFILE |
Schreibt mithilfe der Windows-API WriteFile, eine Meldung an ein benutzerdefiniertes HANDLE, überprüft jedoch nicht die Gültigkeit des Dateihandles. Die Anwendung ist für das Öffnen der Berichtsdatei und das Übergeben eines gültigen Dateihandles verantwortlich. |
_CRTDBG_MODE_FILE |
_CRTDBG_FILE_STDERR |
Schreibt eine Meldung in stderr. |
_CRTDBG_MODE_FILE |
_CRTDBG_FILE_STDOUT |
Schreibt eine Meldung in stdout. |
Der Bericht entweder an ein Ziel, an zwei oder drei Ziele oder an kein Ziel gesendet werden. Weitere Informationen zum Angeben des Berichtsmodus bzw. der Berichtsmodi und der Berichtsdatei finden Sie unter den Funktionen _CrtSetReportMode und _CrtSetReportFile. Weitere Informationen zum Verwenden der Debugmakros und der Berichtsfunktionen finden Sie unter Makros für die Berichterstellung.
Wenn Ihre Anwendung mehr Flexibilität benötigt, als von _CrtDbgReport und _CrtDbgReportW bereitgestellt wird, können Sie Ihre eigene Berichtsfunktion schreiben und sie in die Berichtsmechanismen der C-Laufzeitbibliothek integrieren, indem Sie die _CrtSetReportHook-Funktion verwenden.
Anforderungen
Routine |
Erforderlicher Header |
|---|---|
_CrtDbgReport |
<crtdbg.h> |
_CrtDbgReportW |
<crtdbg.h> |
_CrtDbgReport und _CrtDbgReportW sind Microsoft-Erweiterungen. Weitere Informationen finden Sie unterKompatibilität.
Bibliotheken
Nur Debugversionen von C-Laufzeitbibliotheken.
Beispiel
// crt_crtdbgreport.c
#include <crtdbg.h>
int main(int argc, char *argv[]) {
#ifdef _DEBUG
_CrtDbgReport(_CRT_ASSERT, __FILE__, __LINE__, argv[0], NULL);
#endif
}
Unter crt_dbg2 finden Sie ein Beispiel, wie Sie die Berichtsfunktion ändern können.