Fonctions globales de signalement d’erreurs et de débogage

Article
10/12/2023

Ces fonctions fournissent des installations de débogage et de trace utiles.

Nom	Description
AtlHresultFromLastError	Retourne un `GetLastError` code d’erreur sous la forme d’un HRESULT.
AtlHresultFromWin32	Convertit un code d'erreur Win32 en valeur HRESULT.
AtlReportError	Configure pour `IErrorInfo` fournir des détails d’erreur à un client.
AtlThrow	Lève un `CAtlException`.
AtlThrowLastWin32	Appelez cette fonction pour signaler une erreur en fonction du résultat de la fonction Windows `GetLastError`.

AtlHresultFromLastError

Retourne la dernière valeur du code d'erreur du thread appelant sous la forme d'une valeur HRESULT.

HRESULT AtlHresultFromLastError();

Notes

AtlHresultFromLastError appelle GetLastError pour obtenir la dernière erreur et retourne l’erreur après la conversion en HRESULT à l’aide de la macro HRESULT_FROM_WIN32.

Spécifications

En-tête : atlcomcli.h

AtlHresultFromWin32

Convertit un code d'erreur Win32 en valeur HRESULT.

AtlHresultFromWin32(DWORD error);

Paramètres

error
Valeur d’erreur à convertir.

Notes

Convertit un code d’erreur Win32 en HRESULT à l’aide de la macro HRESULT_FROM_WIN32.

Remarque

Au lieu d’utiliser HRESULT_FROM_WIN32(GetLastError()), utilisez la fonction AtlHresultFromLastError.

Spécifications

En-tête : atlcomcli.h

AtlReportError

Configure l’interface IErrorInfo pour fournir des informations d’erreur aux clients de l’objet.

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());

Paramètres

clsid
[in] CLSID de l’objet signalant l’erreur.

lpszDesc
[in] Chaîne décrivant l’erreur. Les versions Unicode spécifient que lpszDesc est de type LPCOLESTR ; la version ANSI spécifie un type de LPCSTR.

iid
[in] IID de l’interface définissant l’erreur ou GUID_NULL si l’erreur est définie par le système d’exploitation.

hRes
[in] HRESULT que vous souhaitez retourner à l’appelant.

nID
[in] Identificateur de ressource où la chaîne de description d’erreur est stockée. Cette valeur doit être comprise entre 0x0200 et 0xFFFF, de manière inclusive. Dans les builds de débogage, une assertion se produit si nID n’indexe pas de chaîne valide. Dans les builds de mise en production, la chaîne de description d’erreur est définie sur « Erreur inconnue ».

dwHelpID
[in] Identificateur de contexte d’aide pour l’erreur.

lpszHelpFile
[in] Chemin d’accès et nom du fichier d’aide décrivant l’erreur.

hInst
[in] Handle de la ressource. Par défaut, ce paramètre est __AtlBaseModuleModule::GetResourceInstance, où __AtlBaseModuleModule est l’instance globale de CAtlBaseModule ou une classe dérivée de celle-ci.

Valeur de retour

Si le paramètre hRes n’est pas différent de zéro, retourne la valeur de hRes. Si hRes est égal à zéro, les quatre premières versions de AtlReportError retour DISP_E_EXCEPTION. Les deux dernières versions retournent le résultat de la macro MAKE_HRESULT( 1, FACILITY_ITF, nID ).

Notes

La chaîne lpszDesc est utilisée comme description textuelle de l’erreur. Lorsque le client reçoit le hRes à partir duquel AtlReportErrorvous revenez, le client peut accéder à la IErrorInfo structure pour plus d’informations sur l’erreur.

Exemple

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");
}

Attention

N’utilisez AtlReportError pas les gestionnaires catch C++. Certaines substitutions de ces fonctions utilisent les macros de conversion de chaîne ATL en interne, qui utilisent à leur tour la _alloca fonction en interne. L’utilisation AtlReportError d’un gestionnaire catch C++ peut entraîner des exceptions dans les gestionnaires catch C++.

Spécifications

En-tête : atlcom.h

AtlThrow

Appelez cette fonction pour signaler une erreur basée sur un code d’état HRESULT.

__declspec(noreturn) inline void AtlThrow(HRESULT hr);

Paramètres

rh
Valeur HRESULT standard.

Notes

Cette fonction est utilisée par le code ATL et MFC en cas de condition d’erreur. Il peut également être appelé à partir de votre propre code. L’implémentation par défaut de cette fonction dépend de la définition du symbole _ATL_NO_EXCEPTIONS et du type de projet, MFC ou ATL.

Dans tous les cas, cette fonction trace hrESULT vers le débogueur.

Dans Visual Studio 2015 Update 3 et versions ultérieures, cette fonction est attribuée __declspec(noreturn) afin d’éviter les avertissements sal impulsants.

Si _ATL_NO_EXCEPTIONS n’est pas défini dans un projet MFC, cette fonction lève une exception CMemoryException ou COleException basée sur la valeur de HRESULT.

Si _ATL_NO_EXCEPTIONS n’est pas défini dans un projet ATL, la fonction lève une exception CAtlException.

Si _ATL_NO_EXCEPTIONS est défini, la fonction provoque un échec d’assertion au lieu de lever une exception.

Pour les projets ATL, il est possible de fournir votre propre implémentation de cette fonction à utiliser par ATL en cas de défaillance. Pour ce faire, définissez votre propre fonction avec la même signature que AtlThrow et #define AtlThrow être le nom de votre fonction. Cette opération doit être effectuée avant d’inclure atlexcept.h (ce qui signifie qu’elle doit être effectuée avant d’inclure tous les en-têtes ATL, car atlbase.h inclut atlexcept.h). Attribuez votre fonction __declspec(noreturn) pour éviter les avertissements sal impétatoires.

Exemple

// 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 ..
};

Spécifications

En-tête : atldef.h

AtlThrowLastWin32

Appelez cette fonction pour signaler une erreur en fonction du résultat de la fonction Windows GetLastError.

inline void AtlThrowLastWin32();

Notes

Cette fonction trace le résultat du GetLastError débogueur.

Si _ATL_NO_EXCEPTIONS n’est pas défini dans un projet MFC, cette fonction lève une exception CMemoryException ou COleException en fonction de la valeur retournée par GetLastError.

Si _ATL_NO_EXCEPTIONS n’est pas défini dans un projet ATL, la fonction lève une exception CAtlException.

Si _ATL_NO_EXCEPTIONS est défini, la fonction provoque un échec d’assertion au lieu de lever une exception.

Spécifications

En-tête : atldef.h

Voir aussi

Fonctions
Macros de signalement d’erreurs et de débogage

Partager via

Fonctions globales de signalement d’erreurs et de débogage

AtlHresultFromLastError

Notes

Spécifications

AtlHresultFromWin32

Paramètres

Notes

Spécifications

AtlReportError

Paramètres

Valeur de retour

Notes

Exemple

Spécifications

AtlThrow

Paramètres

Notes

Exemple

Spécifications

AtlThrowLastWin32

Notes

Spécifications

Voir aussi

Commentaires

Ressources supplémentaires