Implementing the Functions Required for a Debugger Extension DLL (Windows Embedded CE 6.0)

1/5/2010

This topic describes how to implement the functions that are required for a custom debugger extension DLL. These functions are required by Platform Builder to load and unload the DLL as a debugger extension.

Before you begin to implement these functions, you must complete the steps in Creating a Debugger Extension DLL Project.

To implement the functions required for a debugger extension DLL

1. In Visual Studio 2005, in Solution Explorer, expand Source Files, and then double-click hello_ext.cpp.

2. Add an implementation of WinDbgExtensionDllInit that matches the following function signature from wdbgexts_ce.h:

   typedef VOID
   (WDBGAPI*PWINDBG_EXTENSION_DLL_INIT)(
       PWINDBG_EXTENSION_APIS lpExtensionApis,
       USHORT                 MajorVersion,
       USHORT                 MinorVersion
   );
   

   Platform Builder calls this function when it loads the debugger extension. The PWINDBG_EXTENSION_APIS structure contains callback functions for the APIs. Notice that this structure may change for each version, so check its nSize member.

3. Next, add an implementation of WinDbgExtensionDllShutdown that matches the following function signature:

   void WDBGAPI WinDbgExtensionDllShutdown( void );
   

   Platform Builder calls this function before it unloads the debugger extension. In the function implementation, add code that should be called before this debugger extension is unloaded, such as terminating threads that you started, or closing open handles.

4. Next, add an implementation of ExtensionApiVersion that matches the following function signature:

   typedef LPEXT_API_VERSION
   (WDBGAPI*PWINDBG_EXTENSION_API_VERSION)(
       VOID
   );
   

   This function returns a pointer to an EXT_API_VERSION structure, which is defined in wdbgexts_ce.h as follows:

   typedef struct EXT_API_VERSION {
       USHORT  MajorVersion;
       USHORT  MinorVersion;
       USHORT  Revision;
       USHORT  Reserved;
   } EXT_API_VERSION, *LPEXT_API_VERSION;
   

To add the Hello command to the debugger extension DLL

1. In hello_ext.cpp, use the DECLARE_API macro to add a command called Hello.

   Note

   The name of this command must be identical to the name that you want to use for the debugger command.

2. (Optional) Customize the implementation by adding additional functionality. For more information on the functionality that you can add, see Debugger Extension Functions.

After you have completed these steps, you are ready to create a .def file to export the functions that you implemented in this topic.

Example

The following code shows you a starting point for implementing the required functions for a debugger extension DLL:

// hello_ext.cpp : Defines the entry point for the DLL application.

#include "stdafx.h"

#ifdef _MANAGED
  #pragma managed(push, off)
#endif

BOOL APIENTRY DllMain( HMODULE hModule,
                       DWORD  ul_reason_for_call,
                       LPVOID lpReserved
            )
{
    return TRUE;
}

#ifdef _MANAGED
  #pragma managed(pop)
#endif

USHORT                 SavedMajorVersion;
USHORT                 SavedMinorVersion;
EXT_API_VERSION ApiVersion = { 3, 5, EXT_API_VERSION_NUMBER, 0 };

void WDBGAPI WinDbgExtensionDllInit(
        PWINDBG_EXTENSION_APIS lpExtensionApis,
        USHORT MajorVersion,
        USHORT MinorVersion)
{
    // Copy lpExtensionApis to ExtensionAPis so that extension
    // functions can 
    // access the Platform Builder Debugger Extension API.
    
ExtensionApis = *lpExtensionApis;

    SavedMajorVersion = MajorVersion;
    SavedMinorVersion = MinorVersion;

    // Add code that should run after the Extension DLL is loaded 
    // into Platform Builder.
}

LPEXT_API_VERSION ExtensionApiVersion()
{
    return &ApiVersion;
}

DECLARE_API(Hello)
{
     dprintf("HELLO_EXT: Hello!\n");
     // Implement debugger functionality by calling the  
     // Debugger Extension Functions
}

See Also

Concepts

How to Create and Debug a Debugger Extension
Debugger Extension Functions