Funções globais de relatório de erros e depuração

  • Artigo

Essas funções fornecem instalações úteis de depuração e rastreamento.

Nome Descrição
AtlHresultFromLastError Retorna um código de erro GetLastError no formulário de um HRESULT.
AtlHresultFromWin32 Converte um código de erro do Win32 em HRESULT.
AtlReportError Configura-se IErrorInfo para fornecer detalhes de erro a um cliente.
AtlThrow Lança CAtlException.
AtlThrowLastWin32 Chame essa função para sinalizar um erro com base no resultado da função GetLastError do Windows.

AtlHresultFromLastError

Retorna o valor do código do último erro do thread de chamada na forma de HRESULT.

HRESULT AtlHresultFromLastError();

Comentários

AtlHresultFromLastError chama GetLastError para obter o último erro e retorna o erro depois de convertê-lo em um HRESULT usando a macro HRESULT_FROM_WIN32.

Requisitos

Cabeçalho: atlcomcli.h

AtlHresultFromWin32

Converte um código de erro do Win32 em HRESULT.

AtlHresultFromWin32(DWORD error);

Parâmetros

error
O valor do erro a ser convertido.

Comentários

Converte um código de erro Win32 em um HRESULT usando a macro HRESULT_FROM_WIN32.

Observação

Em vez de usar HRESULT_FROM_WIN32(GetLastError()), use a função AtlHresultFromLastError.

Requisitos

Cabeçalho: atlcomcli.h

AtlReportError

Configura a interface IErrorInfo para fornecer informações de erro para os clientes do 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] O CLSID do objeto que relata o erro.

lpszDesc
[in] A cadeia de caracteres que descreve o erro. As versões Unicode especificam que lpszDesc é do tipo LPCOLESTR. A versão ANSI especifica um tipo de LPCSTR.

iid
[in] O IID da interface que define o erro ou GUID_NULL se o erro for definido pelo sistema operacional.

hRes
[in] O HRESULT que você deseja retornar ao chamador.

Nid
[in] O identificador de recurso em que a cadeia de caracteres de descrição do erro é armazenada. Esse valor deve estar entre 0x0200 e 0xFFFF, inclusive. Em builds de depuração, um ASSERT resultará se nID não indexar uma cadeia de caracteres válida. Nos builds de versão, a cadeia de caracteres de descrição do erro será definida como "Erro Desconhecido".

dwHelpID
[in] O identificador de contexto de ajuda para o erro.

lpszHelpFile
[in] O caminho e o nome do arquivo de ajuda que descreve o erro.

hInst
[in] O identificador para o recurso. Por padrão, esse parâmetro é __AtlBaseModuleModule::GetResourceInstance, onde __AtlBaseModuleModule está a instância global de CAtlBaseModule ou uma classe derivada dele.

Valor de retorno

Se o parâmetro hRes for diferente de zero, retornará o valor de hRes. Se hRes for zero, as quatro primeiras versões de AtlReportError retornarão DISP_E_EXCEPTION. As duas últimas versões retornam o resultado da macro MAKE_HRESULT( 1, FACILITY_ITF, nID ).

Comentários

O lpszDesc de cadeia de caracteres é usado como a descrição do texto do erro. Quando o cliente recebe os hRes dos quais você retorna AtlReportError, o cliente pode acessar a estrutura IErrorInfo para obter detalhes sobre o erro.

Exemplo

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

Cuidado

Não use AtlReportError em manipuladores de captura C++. Algumas substituições dessas funções usam as macros de conversão de cadeia de caracteres ATL internamente, que, por sua vez, usam a função _alloca internamente. Usar AtlReportError em um manipulador de captura C++ pode causar exceções em manipuladores de captura C++.

Requisitos

Cabeçalho: atlcom.h

AtlThrow

Chame essa função para sinalizar um erro com base em um código de status HRESULT.

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

Parâmetros

RH
Valor HRESULT padrão.

Comentários

Essa função é usada pelo código ATL e MFC no caso de uma condição de erro. Ele também pode ser chamado do seu próprio código. A implementação padrão dessa função depende da definição do símbolo _ATL_NO_EXCEPTIONS e do tipo de projeto, MFC ou ATL.

Em todos os casos, essa função rastreia o HRESULT até o depurador.

No Visual Studio 2015 Atualização 3 e posteriores, essa função é atribuída __declspec(noreturn) para evitar avisos SAL espúrios.

Se _ATL_NO_EXCEPTIONS não estiver definido em um projeto MFC, essa função gerará um CMemoryException ou um COleException com base no valor do HRESULT.

Se _ATL_NO_EXCEPTIONS não estiver definido em um projeto ATL, a função gerará um CAtlException.

Se _ATL_NO_EXCEPTIONS for definido, a função causará uma falha de asserção em vez de gerar uma exceção.

Para projetos da ATL, é possível fornecer sua própria implementação dessa função a ser usada pela ATL em caso de falha. Para fazer isso, defina sua própria função com a mesma assinatura que AtlThrow e #define AtlThrow para ser o nome da sua função. Isso deve ser feito antes de incluir atlexcept.h (o que significa que deve ser feito antes de incluir quaisquer cabeçalhos ATL, já que atlbase.h inclui atlexcept.h). Atribua sua função __declspec(noreturn) para evitar avisos de SAL espúrios.

Exemplo

// 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

Cabeçalho: atldef.h

AtlThrowLastWin32

Chame essa função para sinalizar um erro com base no resultado da função GetLastError do Windows.

inline void AtlThrowLastWin32();

Comentários

Essa função rastreia o resultado de GetLastError para o depurador.

Se _ATL_NO_EXCEPTIONS não estiver definido em um projeto MFC, essa função gerará um CMemoryException ou um COleException com base no valor do GetLastError.

Se _ATL_NO_EXCEPTIONS não estiver definido em um projeto ATL, a função gerará um CAtlException.

Se _ATL_NO_EXCEPTIONS for definido, a função causará uma falha de asserção em vez de gerar uma exceção.

Requisitos

Cabeçalho: atldef.h

Confira também

Funções
Macros de relatórios de erros e depuração