Meldingen ontvangen

De volgende code laat zien hoe u uitgebreide statusinformatie ophaalt en rapporteert van de symboolhandler over het zoeken naar en laden van modules en de bijbehorende symboolbestanden.

Velen die bekend zijn met de WinDbg-debugger herinneren zich misschien een opdracht genaamd "!sym noisy". Deze opdracht wordt door de gebruiker gebruikt om te bepalen waarom WinDbg symboolbestanden wel of niet kan laden. Er wordt een uitgebreide lijst weergegeven van alles wat de symboolhandler probeert.

Dezelfde vermelding is ook beschikbaar voor iedereen die een client ontwikkelt voor de Symbol Handler van DbgHelp.

Roep eerst SymSetOptions- aan met SYMOPT_DEBUG. Dit zorgt ervoor dat DbgHelp foutopsporingsmeldingen inschakelt.

Nadat u SymInitializehebt aangeroepen, gebruikt u SymRegisterCallback64- om een callback-functie te registreren die DbgHelp zal aanroepen wanneer er een interessante gebeurtenis plaatsvindt. In dit voorbeeld wordt de callback-functie SymRegisterCallbackProc64genoemd. Symbol callback-functies ontvangen een verzameling actiecodes die ze kunnen verwerken volgens type. In dit voorbeeld verwerken we alleen de CBA_EVENT actiecode. Deze functie geeft een tekenreeks door die uitgebreide informatie bevat over een gebeurtenis die is opgetreden tijdens het laden van een symbool. Deze gebeurtenis kan alles zijn, van een poging om de gegevens in een uitvoerbare afbeelding te lezen tot de geslaagde locatie van een symboolbestand. SymRegisterCallbackProc64 geeft die tekenreeks weer en retourneert TRUE-.

Belangrijk

Zorg ervoor dat u ONWAAR retourneert naar elke actiecode die u niet verwerkt, anders kunt u niet-gedefinieerd gedrag ervaren. Raadpleeg SymRegisterCallbackProc64- voor een lijst met alle actiecodes en de gevolgen ervan.

 

Nu de callback is geregistreerd, is het tijd om de module die is opgegeven op de opdrachtregel te laden door SymLoadModuleExaan te roepen.

Roep tot slot SymCleanup- aan voordat u afsluit.

#include <windows.h>
#include <stdio.h>
#include <tchar.h>

#ifdef UNICODE
 #define DBGHELP_TRANSLATE_TCHAR
#endif
#include <dbghelp.h>

// Here is an implementation of a Symbol Callback function.

BOOL 
CALLBACK 
SymRegisterCallbackProc64(
    __in HANDLE hProcess,
    __in ULONG ActionCode,
    __in_opt ULONG64 CallbackData,
    __in_opt ULONG64 UserContext
    )
{
    UNREFERENCED_PARAMETER(hProcess);
    UNREFERENCED_PARAMETER(UserContext);
    
    PIMAGEHLP_CBA_EVENT evt;

    // If SYMOPT_DEBUG is set, then the symbol handler will pass
    // verbose information on its attempt to load symbols.
    // This information be delivered as text strings.
    
    switch (ActionCode)
    {
    case CBA_EVENT:
        evt = (PIMAGEHLP_CBA_EVENT)CallbackData;
        _tprintf(_T("%s"), (PTSTR)evt->desc);
        break;

    // CBA_DEBUG_INFO is the old ActionCode for symbol spew.
    // It still works, but we use CBA_EVENT in this example.
#if 0
    case CBA_DEBUG_INFO:
        _tprintf(_T("%s"), (PTSTR)CallbackData);
        break;
#endif

    default:
        // Return false to any ActionCode we don't handle
        // or we could generate some undesirable behavior.
        return FALSE;
    }

    return TRUE;
}

// Main code.

int __cdecl
#ifdef UNICODE
_tmain(
#else
main(
#endif
    __in int argc,
    __in_ecount(argc) PCTSTR argv[]
    )
{
    BOOL status;
    int rc = -1;
    HANDLE hProcess;
    DWORD64 module;
    
    if (argc < 2)
    {
        _tprintf(_T("You must specify an executable image to load.\n"));
        return rc;
    }

    // If we want to se debug spew, we need to set this option.
        
    SymSetOptions(SYMOPT_DEBUG);
    
    // We are not debugging an actual process, so lets use a placeholder
    // value of 1 for hProcess just to ID these calls from any other
    // series we may want to load.  For this simple case, anything will do.
    
    hProcess = (HANDLE)1;
    
    // Initialize the symbol handler.  No symbol path.  
    // Just let dbghelp use _NT_SYMBOL_PATH
    
    status = SymInitialize(hProcess, NULL, false);
    if (!status)
    {
        _tprintf(_T("Error 0x%x calling SymInitialize.\n"), GetLastError());
        return rc;
    }
     
    // Now register our callback.
    
    status = SymRegisterCallback64(hProcess, SymRegisterCallbackProc64, NULL);
    if (!status)
    {
        _tprintf(_T("Error 0x%x calling SymRegisterCallback64.\n"), GetLastError());
        goto cleanup;
    }
    
    // Go ahead and load a module for testing.
    
    module = SymLoadModuleEx(hProcess,  // our unique id
                             NULL,      // no open file handle to image
                             argv[1],   // name of image to load
                             NULL,      // no module name - dbghelp will get it
                             0,         // no base address - dbghelp will get it
                             0,         // no module size - dbghelp will get it
                             NULL,      // no special MODLOAD_DATA structure
                             0);        // flags
    if (!module)
    {
        _tprintf(_T("Error 0x%x calling SymLoadModuleEx.\n"), GetLastError());
        goto cleanup;
    }
    rc = 0;
    
cleanup:
    SymCleanup(hProcess);
    
    return rc;    
}

Als u NULL- opgeeft als de tweede parameter van SymInitialize geeft aan dat de symboolhandler het standaardzoekpad moet gebruiken om symboolbestanden te zoeken. Zie Symboolpadenvoor gedetailleerde informatie over hoe de symboolhandler symboolbestanden zoekt of hoe een toepassing een zoekpad voor symbolen kan opgeven.

Als u dit programma uitvoert, ziet u hoe het pad naar het symbool wordt verwerkt. Terwijl DbgHelp door het pad naar het symbool zoekt om het symboolbestand te vinden, roept het herhaaldelijk SymRegisterCallbackProc64 aan, dat op zijn beurt de volgende tekenreeksen toont die door DbgHelp worden doorgegeven.

d:\load.exe c:\home\dbghelp.dll
DBGHELP: No header for c:\home\dbghelp.dll.  Searching for image on disk
DBGHELP: c:\home\dbghelp.dll - OK
DBGHELP: .\dbghelp.pdb - file not found
DBGHELP: .\dll\dbghelp.pdb - file not found
DBGHELP: .\symbols\dll\dbghelp.pdb - file not found
DBGHELP: .\symbols\dll\dbghelp.pdb - file not found
DBGHELP: cache*c:\symbols\dbghelp.pdb - file not found
DBGHELP: cache*c:\symbols\dll\dbghelp.pdb - file not found
DBGHELP: cache*c:\symbols\symbols\dll\dbghelp.pdb - file not found
DBGHELP: d:\nt.binaries.amd64chk\symbols.pri\dbg\dbghelp.pdb - file not found
DBGHELP: dbghelp - private symbols & lines
         dbghelp.pdb