Funciones de salida de depuración

  • Artículo

[La característica asociada a esta página, DirectShow, es una característica heredada. Se ha reemplazado por MediaPlayer, IMFMediaEngine y Captura de audio/vídeo en Media Foundation. Esas características se han optimizado para Windows 10 y Windows 11. Microsoft recomienda encarecidamente que el nuevo código use MediaPlayer, IMFMediaEngine y Audio/Video Capture en Media Foundation en lugar de DirectShow, siempre que sea posible. Microsoft sugiere que el código existente que usa las API heredadas se reescriba para usar las nuevas API si es posible.

Las clases base DirectShow proporcionan varias macros para mostrar información de depuración.

Función Descripción
DbgCheckModuleLevel Comprueba si el registro está habilitado para los tipos de mensajes y el nivel especificados.
DbgDumpObjectRegister Muestra información sobre los objetos activos.
DbgInitialise Inicializa la biblioteca de depuración.
DbgLog Envía una cadena a la ubicación de salida de depuración, si el registro está habilitado para el tipo y el nivel especificados.
DbgOutString Envía una cadena a la ubicación de salida de depuración.
DbgSetModuleLevel Establece el nivel de registro para uno o varios tipos de mensajes.
DbgTerminate Limpia la biblioteca de depuración.
Displaytype Envía información sobre un tipo de medio a la ubicación de salida de depuración.
DumpGraph Envía información sobre un gráfico de filtro a la ubicación de salida de depuración.
GuidNames Matriz global que contiene cadenas que representan los GUID definidos en Uuids.h.
NOMBRE Genera una cadena de solo depuración.
NOTA Envía una cadena a la ubicación de salida de depuración.
RECORDAR Genera un aviso en tiempo de compilación.

 

Claves del Registro

La función de salida de depuración de DirectShow usa un conjunto de claves del Registro. La ubicación de estas claves del Registro depende de la versión de Windows.

Antes de Windows Vista, las claves de depuración se encuentran en la siguiente ruta de acceso:

HKEY_LOCAL_MACHINE\SOFTWARE\Depuración

En Windows Vista o posterior, se encuentran en la siguiente ruta de acceso:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Directshow\Depuración

En el caso de los filtros de terceros, la ubicación depende de la versión de las clases base de DirectShow usadas para compilar el filtro. La versión incluida en Windows SDK para Windows Vista usa la ruta de acceso más reciente. Las versiones anteriores usaban la ruta de acceso anterior.

En los comentarios siguientes, la etiqueta <DebugRoot> se usa para indicar estas dos rutas de acceso. Sustituya la ruta de acceso correcta, según la versión de Windows o la versión de las clases base.

Registro de depuración

DirectShow define varios tipos de mensajes, que se muestran en la tabla siguiente.

Valor Descripción
LOG_ERROR Notificación de error.
LOG_LOCKING Bloqueo y desbloqueo de secciones críticas.
LOG_MEMORY Asignación de memoria, creación y destrucción de objetos.
LOG_TIMING Mediciones de tiempo y rendimiento.
LOG_TRACE Seguimiento general de llamadas.
CUSTOM1 a CUSTOM5 Disponible para mensajes de depuración personalizados

 

Cada una de las funciones de registro de depuración de DirectShow especifica un tipo de mensaje y un nivel de registro. El mensaje de depuración solo se muestra cuando el nivel de depuración actual para ese tipo de mensaje es igual o mayor que el nivel especificado en la función de registro. De lo contrario, se omite el mensaje.

Por ejemplo, el código siguiente genera la cadena "This is a debug message" (Este es un mensaje de depuración) si el nivel de LOG_TRACE es 3 o superior:

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

Cada módulo puede establecer su propio nivel de depuración para cada tipo de mensaje. (Un módulo es un archivo DLL o ejecutable que se puede cargar mediante la función LoadLibrary ). Los niveles de depuración de un módulo aparecen en el Registro con la siguiente clave:

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

donde <Tipo> de mensaje es el tipo de mensaje menos el "LOG_" inicial; por ejemplo, LOCKING para LOG_LOCKING mensajes. Cuando se carga un módulo, la biblioteca de depuración busca los niveles de registro del módulo en el registro. Si las claves del Registro no existen, la biblioteca de depuración las crea.

Un módulo también puede establecer sus propios niveles en tiempo de ejecución mediante la función DbgSetModuleLevel . Para enviar un mensaje a la salida de depuración, llame a la macro DbgLog . En el ejemplo siguiente se crea un mensaje de nivel 3 de tipo LOG_TRACE:

También puede especificar niveles de registro globales, con la siguiente clave del Registro:

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

La biblioteca de depuración usa el nivel que sea mayor, el nivel global o el nivel de módulo.

Ubicación de salida de depuración

La ubicación de salida de depuración viene determinada por otra clave del Registro:

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

Si el valor de esta clave es Console, la salida va a la ventana de la consola. Si el valor es Deb, Debug, Debuggero una cadena vacía, la salida va a la ventana del depurador. De lo contrario, la salida se escribe en un archivo especificado por la clave del Registro.

Antes de que un archivo ejecutable use la biblioteca de depuración de DirectShow, debe llamar a la función DbgInitialise . Después, debe llamar a la función DbgTerminate . Los archivos DLL no necesitan llamar a estas funciones, ya que el punto de entrada dll (definido en la biblioteca de clases base) los llama automáticamente.

Utilidades de depuración