Funciones globales de depuración e informe de errores
Estas funciones proporcionan facilidades útiles de depuración y seguimiento.
| Nombre | Descripción |
|---|---|
| AtlHresultFromLastError | Devuelve a GetLastError el código de error en formato HRESULT. |
| AtlHresultFromWin32 | Convierte un código de error Win32 en un valor HRESULT. |
| AtlReportError | Configura IErrorInfo para proporcionar detalles de errores a un cliente. |
| AtlThrow | Genera una CAtlException. |
| AtlThrowLastWin32 | Llame a esta función para notificar un error en función del resultado de la función de Windows GetLastError. |
AtlHresultFromLastError
Devuelve el último valor de código de error del subproceso que realiza la llamada con el formato HRESULT.
HRESULT AtlHresultFromLastError();
Comentarios
AtlHresultFromLastError llama a GetLastError para obtener el último error y lo devuelve después de convertirlo en HRESULT mediante la macro HRESULT_FROM_WIN32.
Requisitos
Encabezado: atlcomcli.h
AtlHresultFromWin32
Convierte un código de error Win32 en un valor HRESULT.
AtlHresultFromWin32(DWORD error);
Parámetros
error
El valor de error que se va a convertir.
Comentarios
Convierte un código de error Win32 en un HRESULT, al usar la macro HRESULT_FROM_WIN32.
Nota:
En lugar de usar HRESULT_FROM_WIN32(GetLastError()), use la función AtlHresultFromLastError.
Requisitos
Encabezado: atlcomcli.h
AtlReportError
Configura la interfaz IErrorInfo para proporcionar información de error a los clientes del objeto.
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());
Parámetros
clsid
[in] El CLSID del objeto que notifica el error.
lpszDesc
[in] La cadena que describe el error. Las versiones Unicode especifican que lpszDesc es de tipo LPCOLESTR; la versión ANSI que especifica un tipo de LPCSTR.
iid
[in] El IID de la interfaz que define el error o GUID_NULL si el sistema operativo define el error.
hRes
[in] El parámetro HRESULT que quiere devolver al autor de llamada.
Nid
[in] El identificador de recurso donde se almacena la cadena de descripción del error. Este valor debe estar entre 0x0200 y 0xFFFF, ambos inclusive. En las compilaciones de depuración, un valor ASSERT será el resultado si nID no indexa una cadena válida. En las compilaciones de lanzamiento, la cadena de descripción del error se definirá como "Error desconocido".
dwHelpID
[in] El identificador de contexto de ayuda para el error.
lpszHelpFile
[in] La ruta de acceso y el nombre del archivo de ayuda que describe el error.
hInst
[in] El identificador del recurso. De forma predeterminada, este parámetro es __AtlBaseModuleModule::GetResourceInstance, en el que __AtlBaseModuleModule es la instancia global de CAtlBaseModule o una clase derivada del mismo.
Valor devuelto
Si el parámetro hRes no es cero, devuelve el valor de hRes. Si hRes es cero, las cuatro primeras versiones de AtlReportError devuelven DISP_E_EXCEPTION. Las dos últimas versiones devuelven el resultado de la macro MAKE_HRESULT( 1, FACILITY_ITF, nID ).
Comentarios
La cadena lpszDesc se usa como descripción de texto del error. Cuando el cliente recibe hRes devuelto desde AtlReportError, el cliente puede acceder a la estructura IErrorInfo para obtener más información sobre el error.
Ejemplo
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");
}
Precaución
No use AtlReportError en los controladores catch de C++. Algunas invalidaciones de estas funciones usan internamente las macros de conversión de cadenas ATL, que a su vez usan la función_alloca internamente. El uso de AtlReportError en un controlador catch de C++ puede provocar excepciones en dichos controladores.
Requisitos
Encabezado: atlcom.h
AtlThrow
Llame a esta función para notificar un error basado en un código de estado HRESULT.
__declspec(noreturn) inline void AtlThrow(HRESULT hr);
Parámetros
Hr
Valor HRESULT estándar.
Comentarios
El código ATL y MFC usan esta función cuando se da una condición de error. También se puede llamar desde el mismo código. La implementación predeterminada de esta función depende de la definición del símbolo _ATL_NO_EXCEPTIONS y del tipo de proyecto, de MFC o de ATL.
En todos los casos, esta función realiza un seguimiento del HRESULT al depurador.
En la actualización 3 de Visual Studio 2015 y versiones posteriores, esta función se atribuye a __declspec(noreturn) para evitar advertencias falsas de SAL.
Si _ATL_NO_EXCEPTIONS no está definido en un proyecto de MFC, esta función inicia una CMemoryException o una COleException basada en el valor de HRESULT.
Si _ATL_NO_EXCEPTIONS no está definido en un proyecto ATL, la función inicia una CAtlException.
Si se define _ATL_NO_EXCEPTIONS, la función produce un error de aserción en lugar de iniciar una excepción.
Para los proyectos de ATL, es posible proporcionar la propia implementación de esta función para que la use ATL en caso de error. Para ello, defina su propia función con la misma firma que AtlThrow y #define AtlThrow para que sea el nombre de la función. Esto debe hacerse antes de incluir atlexcept.h (lo que significa que debe hacerse antes de incluir los encabezados de ATL, ya que atlbase.h incluye atlexcept.h). Atribuye la función __declspec(noreturn) para evitar advertencias falsas de SAL.
Ejemplo
// 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 ..
};
Requisitos
Encabezado: atldef.h
AtlThrowLastWin32
Llame a esta función para notificar un error en función del resultado de la función de Windows GetLastError.
inline void AtlThrowLastWin32();
Comentarios
Esta función hace un seguimiento del resultado de GetLastError en el depurador.
Si _ATL_NO_EXCEPTIONS no está definido en un proyecto de MFC, esta función inicia una CMemoryException o COleException basada en el valor devuelto por GetLastError.
Si _ATL_NO_EXCEPTIONS no está definido en un proyecto ATL, la función inicia una CAtlException.
Si se define _ATL_NO_EXCEPTIONS, la función produce un error de aserción en lugar de iniciar una excepción.
Requisitos
Encabezado: atldef.h