Registering Debug Zones (Windows Embedded CE 6.0)

1/5/2010

Debug zone registration involves setting initial debug zones in the registry and registering zones with registration macros.

For more information about setting debug zones, see Setting Initial Debug Zones.

Registering Zones With Registration Macros

After declaring the Setting Debug Zone Parameters structure, call the appropriate registration macro to register the structure with the debugging subsystem.

DEBUGREGISTER registers debug zones in Debug configurations, and RETAILREGISTERZONES registers debug zones in Release configurations.

The syntax for the registration macros is

DEBUGREGISTER(hMod | NULL). 
RETAILREGISTERZONES(hMod | NULL). 

If you are debugging a .dll file, call the registration macro with the module name.

If you are debugging an .exe file, call the registration macro with NULL.

For more information, see Controlling Debug Message Output With Macros.

Example

In the following code example, the application's header file includes an ifdef-else-endif conditional block to define for both Release and Debug configurations. This block associates the previously defined debug zones with their corresponding macro names to be used with the DEBUGMSG conditional macro in the source code.

#ifdef DEBUG
// These macros are used as the first arg to DEBUGMSG.
  #define ZONE_INIT       DEBUGZONE(ZONEID_INIT)
  #define ZONE_SECOND     DEBUGZONE(ZONEID_SECOND)
  #define ZONE_EXCEPT     DEBUGZONE(ZONEID_EXCEPT)
  .
  #define ZONE_ERROR      DEBUGZONE(ZONEID_ERROR)
#else
  // For release configurations, these conditionals are always 0.
  #define ZONE_INIT       0
  #define ZONE_SECOND     0
  #define ZONE_EXCEPT     0
  .
  #define ZONE_ERROR      0

#endif
//
// The following code example shows how to register the DBGPARAM structure 
// and define the DEBUGMSG and RETAILMSG macros:
//
// First, register with the debug subsystem.  For a process, the 
// parameter is NULL.  For a DLL, the parameter is hModule.
DEBUGREGISTER(NULL);

// This message shows up in debug configurations only, if ZONE_INIT is turned on.
DEBUGMSG (ZONE_INIT, (TEXT("DBGSAMP1 starting 1\n")));

// This message shows up in both debug and release configurations.
RETAILMSG(1, (TEXT("DBGSAMP1 starting 2\n")));

The following code example shows another example of using debug zones.

// Declare a DBGPARAM structure and give names to all used zones.
DBGPARAM dpCurSettings = { L"foodll", {
  L"Info",      L"Validate",    L"bar",      L"random",
  L"Undefined",  L"Undefined",  L"Undefined",  L"Undefined",
  L"Undefined",  L"Undefined",  L"Undefined",  L"Undefined",
  L"Undefined",  L"Undefined",  L"Undefined",  L"Undefined" },
  0x00000000 };

// Associate bits with a zone. These should correlate 
// to the order of the text strings (zone names) above.
#define ZONE_INFO    DEBUGZONE(0)
#define ZONE_VALIDATE  DEBUGZONE(1)
#define ZONE_BAR      DEBUGZONE(2)
#define ZONE_RANDOM    DEBUGZONE(3)

// Register : Assume that this is a DLL.
// A process would do the same in its libmain.
BOOL DllEntry (HANDLE hinstDLL, DWORD fdwReason, LPVOID lpv) {
  if ( fdwReason == DLL_PROCESS_ATTACH ) {
    DEBUGREGISTER(hinstDLL);
  }
...
}

// Use the defined zone in debug messages.
DEBUGMSG (ZONE_INFO, (TEXT("This is a sample message.")));

// or use a zone as a Boolean operator to turn execution of some code on and off.
if (ZONE_VALIDATE) {
  // validate data ...

See Also

Concepts

Application Debugging with the Kernel Debugger

Other Resources

Debug Zones