Debuggen und globale Funktionen für die Fehlerberichterstattung
Diese Funktionen bieten nützliche Debug- und Ablaufverfolgungsfunktionen.
| Name | Beschreibung |
|---|---|
| AtlHresultFromLastError | Gibt einen GetLastError Fehlercode in Form eines HRESULT zurück. |
| AtlHresultFromWin32 | Konvertiert einen Win32-Fehlercode in ein HRESULT. |
| AtlReportError | Richtet die Einrichtung IErrorInfo ein, um Fehlerdetails für einen Client bereitzustellen. |
| AtlThrow | Löst eine CAtlException aus. |
| AtlThrowLastWin32 | Mit dieser Funktion können Sie auf der Grundlage des Ergebnisses der Windows-Funktion GetLastError einen Fehler signalisieren. |
AtlHresultFromLastError
Gibt den Codewert des letzten Fehlers des aufrufenden Threads in Form eines HRESULT zurück.
HRESULT AtlHresultFromLastError();
Hinweise
AtlHresultFromLastError Ruft GetLastError den letzten Fehler ab und gibt den Fehler nach der Konvertierung in ein HRESULT mithilfe des HRESULT_FROM_WIN32-Makros zurück.
Anforderungen
Kopfzeile: atlcomcli.h
AtlHresultFromWin32
Konvertiert einen Win32-Fehlercode in ein HRESULT.
AtlHresultFromWin32(DWORD error);
Parameter
error
Der zu konvertierende Fehlerwert.
Hinweise
Wandelt einen Win32-Fehlercode mithilfe des Makros HRESULT_FROM_WIN32 in ein HRESULT um.
Hinweis
Verwenden Sie anstelle der Verwendung HRESULT_FROM_WIN32(GetLastError())die Funktion AtlHresultFromLastError.
Anforderungen
Kopfzeile: atlcomcli.h
AtlReportError
Richtet die IErrorInfo Schnittstelle ein, um Fehlerinformationen für Clients des Objekts bereitzustellen.
HRESULT WINAPI AtlReportError(
const CLSID& clsid,
LPCOLESTR lpszDesc,
const IID& iid = GUID_NULL,
HRESULT hRes = 0);
HRESULT WINAPI AtlReportError(
const CLSID& clsid,
LPCOLESTR lpszDesc,
DWORD dwHelpID,
LPCOLESTR lpszHelpFile,
const IID& iid = GUID_NULL,
HRESULT hRes = 0);
HRESULT WINAPI AtlReportError(
const CLSID& clsid,
LPCSTR lpszDesc,
const IID& iid = GUID_NULL,
HRESULT hRes = 0);
HRESULT WINAPI AtlReportError(
const CLSID& clsid,
LPCSTR lpszDesc,
DWORD dwHelpID,
LPCSTR lpszHelpFile,
const IID& iid = GUID_NULL,
HRESULT hRes = 0);
HRESULT WINAPI AtlReportError(
const CLSID& clsid,
UINT nID,
const IID& iid = GUID_NULL,
HRESULT hRes = 0,
HINSTANCE hInst = _AtlBaseModule.GetResourceInstance());
HRESULT WINAPI AtlReportError(
const CLSID& clsid,
UINT nID,
DWORD dwHelpID,
LPCOLESTR lpszHelpFile,
const IID& iid = GUID_NULL,
HRESULT hRes = 0,
HINSTANCE hInst = _AtlBaseModule.GetResourceInstance());
Parameter
clsid
[in] Die CLSID des Objekts, das den Fehler meldet.
lpszDesc
[in] Die Zeichenfolge, die den Fehler beschreibt. Die Unicode-Versionen geben an, dass lpszDesc vom Typ LPCOLESTR ist; die ANSI-Version gibt einen Typ von LPCSTR an.
iid
[in] Die IID der Schnittstelle, die den Fehler definiert, oder GUID_NULL, wenn der Fehler vom Betriebssystem definiert wird.
hRes
[in] Das HRESULT, das an den Aufrufer zurückgegeben werden soll.
Nid
[in] Der Ressourcenbezeichner, in dem die Fehlerbeschreibungszeichenfolge gespeichert ist. Dieser Wert sollte zwischen 0x0200 und 0xFFFF einschließlich liegen. In Debugbuilds führt eine ASSERTION dazu, wenn nID keine gültige Zeichenfolge indiziert. In Releasebuilds wird die Fehlerbeschreibungszeichenfolge auf "Unbekannter Fehler" festgelegt.
dwHelpID
[in] Der Hilfekontextbezeichner für den Fehler.
lpszHelpFile
[in] Der Pfad und der Name der Hilfedatei, die den Fehler beschreibt.
hInst
[in] Das Handle für die Ressource. Dieser Parameter ist __AtlBaseModuleModule::GetResourceInstancestandardmäßig die __AtlBaseModuleModule globale Instanz von CAtlBaseModule oder eine von ihr abgeleitete Klasse.
Rückgabewert
Wenn der hRes-Parameter nicht null ist, wird der Wert von hRes zurückgegeben. Wenn hRes null ist, werden die ersten vier Versionen der AtlReportError Rückgabe DISP_E_EXCEPTION. Die letzten beiden Versionen geben das Ergebnis des Makros MAKE_HRESULT( 1, FACILITY_ITF, nID ) zurück.
Hinweise
Die Zeichenfolge lpszDesc wird als Textbeschreibung des Fehlers verwendet. Wenn der Client die von Ihnen zurückgegebenen AtlReportErrorhRes empfängt, kann der Client auf die IErrorInfo Struktur zugreifen, um Details zum Fehler zu erhalten.
Beispiel
STDMETHODIMP CMyControl::MyErrorProneMethod()
{
BOOL bSucceeded = ErrorProneFunc();
if (bSucceeded)
return S_OK;
else
// hRes is set to DISP_E_EXCEPTION
return AtlReportError(GetObjectCLSID(), L"My error message");
}
Achtung
Verwenden Sie AtlReportError nicht in C++-Catch-Handlern. Einige Außerkraftsetzungen dieser Funktionen verwenden die ATL-Zeichenfolgenkonvertierungsmakros intern, die wiederum die _alloca Funktion intern verwenden. Die Verwendung AtlReportError in einem C++-Catch-Handler kann Ausnahmen in C++-Catch-Handlern verursachen.
Anforderungen
Kopfzeile: atlcom.h
AtlThrow
Rufen Sie diese Funktion auf, um einen Fehler basierend auf einem HRESULT-Statuscode zu signalisieren.
__declspec(noreturn) inline void AtlThrow(HRESULT hr);
Parameter
Hr
HRESULT-Standardwert.
Hinweise
Diese Funktion wird von ATL- und MFC-Code im Falle einer Fehlerbedingung verwendet. Sie kann auch aus Ihrem eigenen Code aufgerufen werden. Die Standardimplementierung dieser Funktion hängt von der Definition des Symbols _ATL_NO_EXCEPTIONS und vom Typ des Projekts, MFC oder ATL ab.
In allen Fällen verfolgt diese Funktion das HRESULT auf den Debugger.
In Visual Studio 2015 Update 3 und höher wird diese Funktion __declspec(noreturn) attributiert, um verschmähte SAL-Warnungen zu vermeiden.
Wenn _ATL_NO_EXCEPTIONS nicht in einem MFC-Projekt definiert ist, löst diese Funktion eine CMemoryException oder eine COleException basierend auf dem Wert des HRESULT aus.
Wenn _ATL_NO_EXCEPTIONS nicht in einem ATL-Projekt definiert ist, löst die Funktion eine CAtlException aus.
Wenn _ATL_NO_EXCEPTIONS definiert ist, verursacht die Funktion einen Assertionsfehler, anstatt eine Ausnahme zu auslösen.
Bei ATL-Projekten ist es möglich, ihre eigene Implementierung dieser Funktion bereitzustellen, die von ATL im Falle eines Fehlers verwendet werden soll. Definieren Sie dazu Ihre eigene Funktion mit der gleichen Signatur wie AtlThrow und #define AtlThrow der Name Ihrer Funktion sein soll. Dies muss erfolgen, bevor atlexcept.h eingeschlossen wird (was bedeutet, dass sie vor dem Einschließen aller ATL-Header erfolgen muss, da atlbase.h atlexcept.h enthält). Ordnen Sie Ihre Funktion __declspec(noreturn) zu, um verschmähte SAL-Warnungen zu vermeiden.
Beispiel
// Constructors and operators cannot return error codes, and
// so they are the place where exceptions are generally used.
class CMyClass
{
private:
CComPtr<IBuddy> m_spBuddy;
public:
CMyClass()
{
HRESULT hr = m_spBuddy.CoCreateInstance(CLSID_Buddy);
if (FAILED(hr))
AtlThrow(hr);
}
// methods ..
};
Anforderungen
Kopfzeile: atldef.h
AtlThrowLastWin32
Mit dieser Funktion können Sie auf der Grundlage des Ergebnisses der Windows-Funktion GetLastError einen Fehler signalisieren.
inline void AtlThrowLastWin32();
Hinweise
Diese Funktion verfolgt das Ergebnis des GetLastError Debuggers nach.
Wenn _ATL_NO_EXCEPTIONS nicht in einem MFC-Projekt definiert ist, löst diese Funktion eine CMemoryException oder eine COleException basierend auf dem von GetLastError.
Wenn _ATL_NO_EXCEPTIONS nicht in einem ATL-Projekt definiert ist, löst die Funktion eine CAtlException aus.
Wenn _ATL_NO_EXCEPTIONS definiert ist, verursacht die Funktion einen Assertionsfehler, anstatt eine Ausnahme zu auslösen.
Anforderungen
Kopfzeile: atldef.h