Macros de Depuração e Reporte de Erros

Estas macros fornecem funcionalidades úteis de depuração e rastreamento.

_ATL_DEBUG_INTERFACES

Defina esta macro antes de incluir quaisquer ficheiros de cabeçalho ATL para rastrear todas AddRefRelease as chamadas e chamadas das interfaces dos seus componentes até à janela de saída.

#define _ATL_DEBUG_INTERFACES

Observações

A saída do traço aparecerá conforme mostrado abaixo:

ATL: QIThunk - 2008 AddRef : Object = 0x00d81ba0 Refcount = 1 CBug - IBug

A primeira parte de cada traço será ATL: QIThunksempre . De seguida, há um valor que identifica o thunk particular da interface que está a ser utilizado. Um thunk de interface é um objeto usado para manter uma contagem de referências e fornecer a capacidade de traço aqui utilizada. Um novo thunk de interface é criado em cada chamada to QueryInterface , exceto para pedidos para a IUnknown interface (neste caso, o mesmo thunk é devolvido todas as vezes para cumprir as regras de identidade do COM).

A seguir, verá ou Release indicará AddRef qual método foi chamado. Depois disso, verá um valor que identifica o objeto cujo número de referências de interface foi alterado. O valor traçado é o this ponteiro do objeto.

A contagem de referências que é rastreada é a contagem de referências nesse thunk após AddRef ou Release foi chamado. Note-se que esta contagem de referências pode não corresponder à contagem de referências do objeto. Cada thunk mantém a sua própria contagem de referências para o ajudar a cumprir totalmente as regras de contagem de referências da COM.

A última informação rastreada é o nome do objeto e a interface afetada pela AddRef chamada ou.Release

Quaisquer fugas de interface que sejam detetadas quando o servidor desliga e _Module.Term é chamado serão registadas desta forma:

ATL: QIThunk - 2005 LEAK : Object = 0x00d81ca0 Refcount = 1 MaxRefCount = 1 CBug - IBug

A informação aqui fornecida corresponde diretamente à informação fornecida nas instruções de traço anteriores, pelo que pode examinar as contagens de referências ao longo de toda a vida útil de um thunk de interface. Além disso, obtém uma indicação do número máximo de referências nesse thunk da interface.

_ATL_DEBUG_QI

Escreve todas as chamadas para QueryInterface na janela de saída.

#define _ATL_DEBUG_QI

Observações

Se uma chamada falhar QueryInterface , a janela de saída irá mostrar:

Nome da interface - failed

ATLASSERT

A macro ATLASSERT executa a mesma funcionalidade que a macro _ASSERTE encontrada na biblioteca de tempo de execução C.

ATLASSERT(booleanExpression);

Parâmetros

booleanExpression
Expressão (incluindo ponteiros) que avalia como diferente de zero ou 0.

Observações

Em compilações de depuração, o ATLASSERT avalia booleanExpression e gera um relatório de depuração quando o resultado é falso.

Requerimentos

Cabeçalho: atldef.h

ATLENSURE

Esta macro é usada para validar parâmetros passados a uma função.

ATLENSURE(booleanExpression);
ATLENSURE_THROW(booleanExpression, hr);

Parâmetros

booleanExpression
Especifica uma expressão booleana a ser testada.

horas
Especifica um código de erro a devolver.

Observações

Estas macros fornecem um mecanismo para detetar e notificar o utilizador sobre o uso incorreto dos parâmetros.

A macro chama ATLASSERT e, se a condição falhar, chama AtlThrow.

No caso da ATLCENSOR, AtlThrow é chamado com E_FAIL.

No ATLENSURE_THROW caso, AtlThrow é chamado com o HRESULT especificado.

A diferença entre ATLENSURE e ATLASSERT é que ATLENSURE lança uma exceção tanto em versões de Release como em compilações de Debug.

Example

void MyImportantFunction(char* psz)
{
   ATLENSURE(NULL != psz);

   char mysz[64];
   strcpy_s(mysz, sizeof(mysz), psz);
}

Requerimentos

Cabeçalho: afx.h

ATLTRACENOTIMPL

Em compilações de depuração do ATL, envia a string " funcname is not implemented" para o dispositivo de dump e retorna E_NOTIMPL.

ATLTRACENOTIMPL(funcname);

Parâmetros

funcname
[dentro] Uma cadeia contendo o nome da função que não está implementada.

Observações

Nas versões de lançamento, simplesmente devolve E_NOTIMPL.

Example

ATLTRACENOTIMPL(_T("IOleControl::GetControlInfo"));   

Requerimentos

Cabeçalho: atltrace.h

ATLTRACE

Reporta avisos a um dispositivo de saída, como a janela do depurador, de acordo com as bandeiras e níveis indicados. Incluído para compatibilidade retroativa.

ATLTRACE(exp);

ATLTRACE(
    DWORD category,
    UINT  level,
    LPCSTR lpszFormat, ...);

Parâmetros

exp
[dentro] A string e as variáveis a enviar para a janela de saída ou para qualquer aplicação que prenda estas mensagens.

categoria
[dentro] Tipo de evento ou método para reportar. Consulte as Observações para uma lista de categorias.

nível
[dentro] O nível de rastreamento a reportar. Consulte as Observações para mais detalhes.

lpszFormat
[dentro] A string formatada para enviar ao dispositivo de dump.

Observações

Veja ATLTRACE2 para uma descrição do ATLTRACE. ATLTRACE e ATLTRACE2 têm o mesmo comportamento, ATLTRACE está incluído para compatibilidade retroativa.

ATLTRACE2

Reporta avisos a um dispositivo de saída, como a janela do depurador, de acordo com as bandeiras e níveis indicados.

ATLTRACE2(exp);

ATLTRACE2(
    DWORD category,
    UINT level,
    LPCSTR lpszFormat,  ...);

Parâmetros

exp
[dentro] A cadeia a enviar para a janela de saída ou qualquer aplicação que prenda estas mensagens.

categoria
[dentro] Tipo de evento ou método para reportar. Consulte as Observações para uma lista de categorias.

nível
[dentro] O nível de rastreamento a reportar. Consulte as Observações para mais detalhes.

lpszFormat
[dentro] A printfcadeia de formato -style a usar para criar uma string para enviar ao dispositivo de dump.

Observações

A forma curta de ATLTRACE2 escreve uma string na janela de saída do depurador. A segunda forma de ATLTRACE2 também escreve a saída na janela de saída do depurador, mas está sujeita às definições da Ferramenta ATL/MFC Trace (ver Exemplo ATLTraceTool). Por exemplo, se definir o nível para 4 e a ferramenta ATL/MFC Trace para o nível 0, não verá a mensagem. O nível pode ser 0, 1, 2, 3 ou 4. O padrão, 0, reporta apenas os problemas mais graves.

O parâmetro de categoria lista as bandeiras de traço a definir. Estes flags correspondem aos tipos de métodos pelos quais pretende reportar. As tabelas abaixo listam as bandeiras de traço válidas que pode usar para o parâmetro da categoria .

ATL Trace Flags

MFC Trace Flags

Para declarar uma categoria de traço personalizada, declare uma instância global da CTraceCategory classe da seguinte forma:

CTraceCategory MY_CATEGORY(_T("MyCategoryName"), 1);

O nome da categoria, MY_CATEGORY neste exemplo, é o nome que especifica para o parâmetro da categoria . O primeiro parâmetro é o nome da categoria que aparecerá na Ferramenta ATL/MFC Trace. O segundo parâmetro é o nível padrão do traço. Este parâmetro é opcional, e o nível padrão do traço é 0.

Para usar uma categoria definida pelo utilizador:

ATLTRACE2(MY_CATEGORY, 2, _T("a message in a custom category"));

Para especificar que queres filtrar as mensagens de rastreamento, insere definições para essas macros no Stdafx.h antes da #include <atlbase.h> instrução.

Alternativamente, pode definir o filtro nas diretivas do pré-processador na caixa de diálogo Páginas de Propriedades . Clique no separador Pré-processador e depois insira o global na caixa de edição de Definições do Pré-processador .

Atlbase.h contém definições padrão dos macros ATLTRACE2 e essas definições serão usadas se não definir estes símbolos antes de o atlbase.h ser processado.

Nas versões de release, ATLTRACE2 compila para (void) 0.

ATLTRACE2 limita o conteúdo da string a ser enviado para o dispositivo de dump a no máximo 1023 caracteres, após formatação.

ATLTRACE e ATLTRACE2 têm o mesmo comportamento, ATLTRACE está incluído para compatibilidade retroativa.

Example

int i = 1;
ATLTRACE2(atlTraceGeneral, 4, "Integer = %d\n", i);
// Output: 'Integer = 1'

Consulte também

Macros
Depuração e Funções Globais de Relatórios de Erros