Microsoft Windows Embedded CE 6.0 Exam Preparation Kit

Table 4-2.

Table 4-2 DBGPARAM elements

Field	Description	Example
lpszName	Defines the name of the module with a maximum length of 32 characters.	TEXT('ModuleName')
rglpszZones	Defines an array of 16 names for the debug zones. Each name can be up to 32 characters long. Platform Builder displays this information to the user when selecting the active zones in the module.	{ TEXT('Init'), TEXT('Deinit'), TEXT('On'), TEXT('Undefined'), TEXT ('Undefined'), TEXT('Undefined'), TEXT('Undefined'), TEXT('Undefined'), TEXT('Undefined'), TEXT ('Undefined'), TEXT('Undefined'), TEXT('Undefined'), TEXT('Undefined'), TEXT('Failure'), TEXT('Warning'), TEXT('Error') }
ulZoneMask	The current zone mask used in the DEBUGZONE macro to determine the currently selected debug zone.	MASK_INIT | MASK_ON | MASK_ERROR

NOTE

Debug zones

Windows Embedded CE supports a total of 16 named debug zones, yet not all have to be defined if the module doesn’t require them. Each module uses a separate set of zone names that should clearly reflect the purpose of each implemented zone.

The Dbgapi.h header file defines the DBGPARAM structure and debugging macros. Because these macros use a predefined DBGPARAM variable named dpCurSettings, it is important that you use the same name in your source code as well, as illustrated in the following code snippet.

#include <DBGAPI.H>
// A macro to increase the readability of zone mask definitions
#define DEBUGMASK(n) (0x00000001<<n)
// Definition of zone masks supported in this module
#define MASK_INIT    DEBUGMASK(0)
#define MASK_DEINIT  DEBUGMASK(1)
#define MASK_ON      DEBUGMASK(2)
#define MASK_FAILURE DEBUGMASK(13)
#define MASK_WARNING DEBUGMASK(14)
#define MASK_ERROR   DEBUGMASK(15)
// Definition dpCurSettings variable with the initial debug zone state
// set to Failure, Warning, and Error.
DBGPARAM dpCurSettings = {
 TEXT('ModuleName'), // Specify the actual module name for clarity!
 {
  TEXT('Init'), TEXT('Deinit'), TEXT('On'), TEXT('Undefined'),
  TEXT('Undefined'), TEXT('Undefined'), TEXT('Undefined'),
  TEXT('Undefined'), TEXT('Undefined'), TEXT('Undefined'),
  TEXT('Undefined'), TEXT('Undefined'), TEXT('Undefined'),
  TEXT('Failure'), TEXT('Warning'), TEXT('Error')
 },
 MASK_INIT | MASK_ON | MASK_ERROR
};
// Main entry point into DLL
BOOL APIENTRY DllMain( HANDLE hModule,
 DWORD ul_reason_for_call, LPVOID lpReserved) {
 if (ul_reason_for_call == DLL_PROCESS_ATTACH) {
  // Register with the Debug Message service each time
  // the DLL is loaded into the address space of a process.
  DEBUGREGISTER((HMODULE)hModule);
 }
 return TRUE;
}

Zone Definitions

The sample code above registers six debug zones for the module that you can now use in conjunction with conditional statements in debugging macros. The following line of code shows one possible way to do this:

DEBUGMSG(dpCurSettings.ulZoneMask & (0x00000001<<(15)),
 (TEXT('Error Information
')));

If the debug zone is currently set to MASK_ERROR, the conditional expression evaluates to TRUE and DEBUGMSG sends the information to the debug output stream. However, to improve the readability of your code, you should use the DEBUGZONE macro defined in Dbgapi.h, as illustrated in the following code snippet, to define flags for your zones. Among other things, this approach simplifies the combination of debug zones through logical AND and OR operations.

#include <DBGAPI.H>
// Definition of zone flags: TRUE or FALSE according to selected debug zone.
#define ZONE_INIT    DEBUGZONE(0)
#define ZONE_DEINIT  DEBUGZONE(1)
#define ZONE_ON      DEBUGZONE(2)
#define ZONE_FAILURE DEBUGZONE(13)