DirectShow Animated Header -- Debug Logging by Module Level DirectShow Animated Header -- Debug Logging by Module Level* Microsoft DirectShow SDK
*Index  *Topic Contents
*Previous Topic: Miscellaneous Macros
*Next Topic: Object Register Debugging

Debug Logging by Module Level


Some of the more conventional debug logging techniques provided by Microsoft® DirectShow™ (like DbgOutString) are monolithic. That is, they are either all on (in a debug build) or all off (in other builds). DirectShow provides other debug logging techniques that give much finer control in turning logging on and off. These pinpoint techniques make it easy to isolate and debug individual modules without seeing other people's extraneous debug output, or suffering the possible performance hit when too much information is logged. You can control the pinpoint DirectShow debug routines by module, by type, and by level, as defined in the following list.

You can set the initial debug levels for a given test run. For each module you want to control, you can store a debugging level for each of the types in the registry. For a list of the registry names to use, see Registry Setting of Debug Levels by Type.

You call the DbgLog macro to attempt to log some piece of data, which might or might not actually be logged, depending on the current debug levels. When you call DbgLog, you supply one or more type flags (possibly combined by bitwise-OR), the debug level, and the data to be logged in the form of a printf-style format string, which can refer to optional parameters. (By definition, C/C++ macros allow only a fixed number of parameters. In your call to DbgLog, you enclose all parameters in an extra set of parentheses. This is a common C/C++ idiom.)

Following are some examples of calling DbgLog. The first example is a simple call with one type and no optional parameters; the second call gives two types and no optional parameters; the third call has two types and includes an optional parameter.


DbgLog((LOG_TRACE, 1, TEXT("CVidCap created")));
DbgLog((LOG_ERROR|LOG_TRACE, 1, TEXT("Driver failed to connect") ) );
DbgLog(( LOG_ERROR|LOG_TRACE, 2
       , TEXT("Driver disconnect: %x"), bDriverDisconnected) );

Each module has its own current debug level for each type. These current levels are initialized from the registry by DbgInitialise. For dynamic-link libraries (DLLs) linking to strmbase.lib, the DbgInitialise function is called automatically when the DLL is loaded. Executables must call DbgInitialise explicitly, with the module instance handle given to them through the WinMain entry point. An executable must also call DbgTerminate when finished to clean up the resources the debug library uses. This cleanup is also done automatically for DLLs.

For more information about how the debug output location is chosen, see Debug Output Location.

Types of Logging Information

A DWORD value is used to indicate types of information to be logged, as indicated by the following bitmasks. Some operations can be performed on multiple types simultaneously, by using bitwise-OR to combine the bitmasks; for example, (LOG_TRACE | LOG_ERROR).
LOG_TIMING Timing and performance measurements.
LOG_TRACE General step and call tracing.
LOG_MEMORY Memory and object allocation/destruction.
LOG_LOCKING Locking/unlocking of critical sections.
LOG_ERROR Debug error notification.

Registry Setting of Debug Levels by Type

For every module and executable, Microsoft DirectShow will load a debugging level key for each of the five types. The level keys are stored in the registry under the HKEY_LOCAL_MACHINE\SOFTWARE\Debug\<Module Name>\<KeyName> key values. The allowable values for <KeyName> in the registry are: "TIMING", "TRACE", "MEMORY", "LOCKING", and "ERROR". Note that the values read from the registry are all read during initialization; DirectShow does not look for update notifications while it runs. If the values change, you must restart the application to pick them up.
Name Description
DbgCheckModuleLevel Checks if given types and level are being logged.
DbgInitialise Initializes the debug library with the module handle and sets the current logging levels accordingly.
DbgLog Logs a message for given types and level. (Ignored except in debug builds.)
DbgLogInfo Logs a message for given types and level. (Provided only in debug builds.)
DbgSetModuleLevel Changes the logging level for given types.
DbgTerminate Cleans up the debug library.
DisplayType Displays the given media type.


DbgCheckModuleLevel

Debug Logging by Module Level

Checks whether logging is enabled for the given message types and level. If logging is enabled for any of the given types at the level given, DbgCheckModuleLevel indicates that the message should be logged.

BOOL WINAPI DbgCheckModuleLevel(
  DWORD Types,
  DWORD Level
  );

Parameters
Types
One or more types of message, such as LOG_TIMING, masked together.
Level
Logging level for this message, where zero means always log.
Return Values

Returns TRUE if these module types and level are to be logged; otherwise, returns FALSE.

Remarks

DbgCheckModuleLevel is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included.


DbgInitialise

Debug Logging by Module Level

Initializes the debug library. Among other things, it sets the current logging levels to correspond to the levels that are appropriate for the indicated module.

void WINAPI DbgInitialise(
  HINSTANCE hInst
  );

Parameters
hInst
Module instance handle.
Remarks

DbgInitialise is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included. DbgInitialise also opens the debug output location, as described in Debug Output Location.


DbgLog

Debug Logging by Module Level

Invokes the DbgLogInfo function.

void WINAPI DbgLog(
  DWORD Types,
  DWORD Level,
  const TCHAR *pFormat,
  ...
  );

Parameters
Types
One or more types of message, such as LOG_TIMING, masked together.
Level
Logging level for this message, where zero means always log.
pFormat
A printf-style format string, which must be in quotation marks.
Remarks

DbgLog is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included.


DbgLogInfo

Debug Logging by Module Level

Formats and sends a message to the debugger, if debug logging is enabled for the given message type and level.

void WINAPI DbgLogInfo(
  DWORD Types,
  DWORD Level,
  const TCHAR *pFormat,
  ...
  );

Parameters
Types
One or more types of message, such as LOG_TIMING, masked together.
Level
Logging level for this message, where zero means always log.
pFormat
A printf-style format string, which must be in quotation marks.
Remarks

DbgLogInfo exists only in debug builds.


DbgSetModuleLevel

Debug Logging by Module Level

Changes the current logging level for message types whose bits are set in the Types parameter to Level. Other logging levels are unchanged.

void WINAPI DbgSetModuleLevel(
  DWORD Types,
  DWORD Level
  );

Parameters
Types
One or more types of message, such as LOG_TIMING, masked together.
Level
Logging level that will be set for future messages. That is, future messages must have a level less than or equal to this value in order for the debug routines to log them.
Remarks

The DirectShow debug routines ignore DbgSetModuleLevel unless DEBUG is defined when the Microsoft DirectShow headers are included.


DbgTerminate

Debug Logging by Module Level

Cleans the debug library.

void WINAPI DbgTerminate( );

Remarks

This is called to clean up the resources the debug library uses. If you called DbgInitialise, then you should call DbgTerminate. For example, DbgTerminate deletes the object register list. (For more information about using that aspect of debugging, see Object Register Debugging.) DbgTerminate also closes the debug output location, as described in Debug Output Location. DbgTerminate is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included.


DisplayType

Debug Logging by Module Level

Displays the media type details on the debug log.

void WINAPI DisplayType(
  LPSTR label,
  const AM_MEDIA_TYPE *pmtIn
  );

Parameters
label
Short message to be logged with the media type.
pmtIn
Pointer to the media type to be displayed.
Remarks

The major types and subtypes are converted into strings for display. DisplayType also asks the base classes for a string description of the subtype, so MEDIASUBTYPE_RGB565 becomes RGB 565 16-bit. In addition, it displays the fields in the BITMAPINFOHEADER structure; this should succeed because input types are not accepted unless the format is big enough.

DisplayType is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

*Top of Page