Funções de saída de depuração

[O recurso associado a esta página, DirectShow, é um recurso herdado. Ele foi substituído por MediaPlayer, IMFMediaEngine e Captura de Áudio/Vídeo na Media Foundation. Esses recursos foram otimizados para Windows 10 e Windows 11. A Microsoft recomenda fortemente que o novo código use MediaPlayer, IMFMediaEngine e Captura de Áudio/Vídeo no Media Foundation em vez de DirectShow, quando possível. A Microsoft sugere que o código existente que usa as APIs herdadas seja reescrito para usar as novas APIs, se possível.]

As Classes Base do DirectShow fornecem várias macros para exibir informações de depuração.

Função Descrição
DbgCheckModuleLevel Verifica se o registro em log está habilitado para os tipos e o nível de mensagem especificados.
DbgDumpObjectRegister Exibe informações sobre objetos ativos.
DbgInitialise Inicializa a biblioteca de depuração.
DbgLog Envia uma cadeia de caracteres para o local de saída de depuração, se o registro em log estiver habilitado para o tipo e o nível especificados.
DbgOutString Envia uma cadeia de caracteres para o local de saída de depuração.
DbgSetModuleLevel Define o nível de log para um ou mais tipos de mensagem.
DbgTerminate Limpa a biblioteca de depuração.
DisplayType Envia informações sobre um tipo de mídia para o local de saída de depuração.
DumpGraph Envia informações sobre um grafo de filtro para o local de saída de depuração.
GuidNames Matriz global que contém cadeias de caracteres que representam os GUIDs definidos em Uuids.h.
NOME Gera uma cadeia de caracteres somente de depuração.
NOTA Envia uma cadeia de caracteres para o local de saída de depuração.
LEMBRAR Gera um lembrete em tempo de compilação.

 

Chaves do Registro

A função de saída de depuração no DirectShow usa um conjunto de chaves do Registro. O local dessas chaves do Registro depende da versão do Windows.

Antes do Windows Vista, as chaves de depuração estão localizadas no seguinte caminho:

HKEY_LOCAL_MACHINE\SOFTWARE\Depurar

No Windows Vista ou posterior, eles estão localizados no seguinte caminho:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Directshow\Depurar

Para filtros de terceiros, o local depende de qual versão das Classes Base do DirectShow foi usada para criar o filtro. A versão incluída no SDK do Windows para Windows Vista usa o caminho mais recente. As versões anteriores usavam o caminho mais antigo.

Nas observações a seguir, o rótulo <DebugRoot> é usado para indicar esses dois caminhos. Substitua o caminho correto, dependendo da versão do Windows ou da versão das classes base.

Log de depuração

O DirectShow define vários tipos de mensagem, mostrados na tabela a seguir.

Valor Descrição
LOG_ERROR Notificação de erro.
LOG_LOCKING Bloqueio e desbloqueio de seções críticas.
LOG_MEMORY Alocação de memória e criação e destruição de objetos.
LOG_TIMING Medições de tempo e desempenho.
LOG_TRACE Rastreamento de chamadas gerais.
CUSTOM1 a CUSTOM5 Disponível para mensagens de depuração personalizadas

 

Cada uma das funções de log de depuração do DirectShow especifica um tipo de mensagem e um nível de log. A mensagem de depuração é exibida somente quando o nível de depuração atual desse tipo de mensagem é igual ou maior que o nível especificado na função de registro em log. Caso contrário, a mensagem será ignorada.

Por exemplo, o código a seguir gera a cadeia de caracteres "Esta é uma mensagem de depuração" se o nível de LOG_TRACE for 3 ou superior:

DbgLog((LOG_TRACE, 3, TEXT("This is a debug message")));

Cada módulo pode definir seu próprio nível de depuração para cada tipo de mensagem. (Um módulo é uma DLL ou executável que pode ser carregada usando a função LoadLibrary .) Os níveis de depuração de um módulo aparecem no registro sob a seguinte chave:

HKEY_LOCAL_MACHINE\<DebugRoot>\<ModuleName>\<MessageType>

em que <Tipo> de Mensagem é o tipo de mensagem menos o "LOG_" inicial; por exemplo, LOCKING para mensagens LOG_LOCKING. Quando um módulo é carregado, a biblioteca de depuração localiza os níveis de log do módulo no registro. Se as chaves do Registro não existirem, a biblioteca de depuração as criará.

Um módulo também pode definir seus próprios níveis em tempo de execução, usando a função DbgSetModuleLevel . Para enviar uma mensagem para a saída de depuração, chame a macro DbgLog . O exemplo a seguir cria uma mensagem de nível 3 do tipo LOG_TRACE:

Você também pode especificar níveis de log globais, com a seguinte chave do Registro:

\HKEY_LOCAL_MACHINE\<DebugRoot>\GLOBAL\<Message Type>

A biblioteca de depuração usa qualquer nível maior, o nível global ou o nível do módulo.

Local de saída de depuração

O local de saída de depuração é determinado por outra chave do Registro:

HKEY_LOCAL_MACHINE\<DebugRoot>\<Modile Name>\LogToFile

Se o valor dessa chave for Console, a saída irá para a janela do console. Se o valor for Deb, Debug, Debuggerou uma cadeia de caracteres vazia, a saída será para a janela do depurador. Caso contrário, a saída será gravada em um arquivo especificado pela chave do Registro.

Antes que um executável use a biblioteca de depuração do DirectShow, ele deve chamar a função DbgInitialise . Posteriormente, ele deve chamar a função DbgTerminate . As DLLs não precisam chamar essas funções, pois o ponto de entrada de DLL (definido na biblioteca de classes base) as chama automaticamente.

Utilitários de depuração