Funções globais de relatório de erros e depuração
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