Implementing Attach

When the session debug manager (SDM) attaches to a program, it performs a sequence of tasks.

1. The SDM first obtains the IDebugProgramNodeAttach2 interface from the IDebugProgramNode2 object and calls the IDebugProgramNodeAttach2::OnAttach method.

2. If the IDebugProgramNodeAttach2 interface cannot be obtained or the IDebugProgramNodeAttach2::OnAttach method returns S_OK, the SDM then tries to obtain the IDebugProgramEx2 interface from the IDebugProgram2 object.

3. If the IDebugProgramEx2 interface can be obtained, the SDM calls the IDebugProgramEx2::Attach method.

4. If the IDebugProgramEx2::Attach method returns S_FALSE or the IDebugProgramEx2 interface cannot be obtained, the SDM instantiates the debug engine (DE) and calls the IDebugEngine2::Attach method.

The TextInterpreter tutorial does not implement either the IDebugProgramNodeAttach2 or IDebugProgramEx2 interface. The IDebugProgramNodeAttach2 interface provides an opportunity to cancel the attach operation while the IDebugProgramEx2 interface is for remote debugging. Instead, this tutorial implements the IDebugEngine2::Attach method which calls a custom method in the CProgram class, CProgram::EngineAttach.

The SDM passes to the IDebugEngine2::Attach method an IDebugEventCallback2 object, which the program later uses to generate debugging events. The SDM also provides an array of IDebugProgram2 objects that the program uses to obtain its unique program identifier. This identifier distinguishes it from all other programs being debugged. Since an array of IDebugProgram2 objects is passed to the IDebugEngine2::Attach method and the IDebugEngine2::Attach method needs to call the custom CProgram::EngineAttach method, it is necessary to identify the tutorial's version of the IDebugProgram2 objects. This is accomplished by associating a unique GUID with the CProgram class as a COM interface entry. IDebugEngine2::Attach then looks for that special interface on the IDebugProgram2 objects in the array.

To implement Attach

1. In Class View, right-click the CProgram class, click Add Variable, and add a variable with the Variable name, m_guidProgId, the Variable type GUID, and an Access type of Protected.

2. Open the Program.h file and add the following line just above the CProgram declaration. This defines the GUID for the interface that is to be used to identify the tutorial's CProgram class.

    
   extern const GUID __declspec(selectany) 
   IID_IAmBatchProgram = { 0x42bb7a04, 0x51a4, 0x49f1, { 0xb4, 0x91, 0xd5, 0x9c, 0x8c, 0x7c, 0x1, 0xe3 } }; 
   
   /////////////////////////////////////////////////////////////////////////////
   // CProgram
   class ATL_NO_VTABLE CProgram :
   

3. Also in the Program.h file, find the COM mapping and add the following bold line to the end of the list of entries:

       COM_INTERFACE_ENTRY(IDebugThread2)
       COM_INTERFACE_ENTRY_IID(IID_IAmBatchProgram, CProgram) 
   END_COM_MAP()
   

4. Open the Program.cpp file, find the CProgram::EngineAttach method, and replace the line //TODO: GET PROGRAM GUID with the following:

       pMDMProgram->GetProgramId(&m_guidProgId); 
   

5. Open the Engine.cpp file and add the following #include statement at the top of the file after the last #include statement:

   #include "Program.h"
   

6. Also in the Engine.cpp file, find the CEngine::Attach method and replace the line // TODO: IMPLEMENT ATTACH as well as the return statement with the following:

       for (DWORD cProgram = 0; cProgram < celtPrograms; cProgram++) 
       { 
           CProgram* pProgram = NULL; 
           if (rgpProgramNodes[cProgram] != NULL && 
               rgpProgramNodes[cProgram]->QueryInterface(IID_IAmBatchProgram, (void**)&pProgram) == S_OK) 
           { 
               pProgram->EngineAttach(rgpPrograms[cProgram], pCallback, dwReason); 
   
               pProgram->Release(); 
           } 
       } 
   
       return S_OK; 
   

7. Build the project to make sure there are no errors.

See Also

Concepts

Attaching the Program to the SDM