模拟服务器

开发平台：

C/C++

DbgEng.h：源码内容

THIS_
IN OUT PWINDBG_EXTENSION_APIS64 Api
) PURE;
// The engine provides a simple mechanism
// to filter common events. Arbitrarily complicated
// filtering can be done by registering event callbacks
// but simple event filtering only requires
// setting the options of one of the predefined
// event filters.
// Simple event filters are either for specific
// events and therefore have an enumerant or
// they are for an exception and are based on
// the exceptions code. Exception filters
// are further divided into exceptions specially
// handled by the engine, which is a fixed set,
// and arbitrary exceptions.
// All three groups of filters are indexed together
// with the specific filters first, then the specific
// exception filters and finally the arbitrary
// exception filters.
// The first specific exception is the default
// exception. If an exception event occurs for
// an exception without settings the default
// exception settings are used.
STDMETHOD(GetNumberEventFilters)(
THIS_
OUT PULONG SpecificEvents,
OUT PULONG SpecificExceptions,
OUT PULONG ArbitraryExceptions
) PURE;
// Some filters have descriptive text associated with them.
STDMETHOD(GetEventFilterText)(
THIS_
IN ULONG Index,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG TextSize
) PURE;
// All filters support executing a command when the
// event occurs.
STDMETHOD(GetEventFilterCommand)(
THIS_
IN ULONG Index,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG CommandSize
) PURE;
STDMETHOD(SetEventFilterCommand)(
THIS_
IN ULONG Index,
IN PCSTR Command
) PURE;
STDMETHOD(GetSpecificFilterParameters)(
THIS_
IN ULONG Start,
IN ULONG Count,
OUT /* size_is(Count) */ PDEBUG_SPECIFIC_FILTER_PARAMETERS Params
) PURE;
STDMETHOD(SetSpecificFilterParameters)(
THIS_
IN ULONG Start,
IN ULONG Count,
IN /* size_is(Count) */ PDEBUG_SPECIFIC_FILTER_PARAMETERS Params
) PURE;
// Some specific filters have arguments to further
// qualify their operation.
STDMETHOD(GetSpecificFilterArgument)(
THIS_
IN ULONG Index,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG ArgumentSize
) PURE;
STDMETHOD(SetSpecificFilterArgument)(
THIS_
IN ULONG Index,
IN PCSTR Argument
) PURE;
// If Codes is non-NULL Start is ignored.
STDMETHOD(GetExceptionFilterParameters)(
THIS_
IN ULONG Count,
IN OPTIONAL /* size_is(Count) */ PULONG Codes,
IN ULONG Start,
OUT /* size_is(Count) */ PDEBUG_EXCEPTION_FILTER_PARAMETERS Params
) PURE;
// The codes in the parameter data control the application
// of the parameter data. If a code is not already in
// the set of filters it is added. If the ExecutionOption
// for a code is REMOVE then the filter is removed.
// Specific exception filters cannot be removed.
STDMETHOD(SetExceptionFilterParameters)(
THIS_
IN ULONG Count,
IN /* size_is(Count) */ PDEBUG_EXCEPTION_FILTER_PARAMETERS Params
) PURE;
// Exception filters support an additional command for
// second-chance events.
STDMETHOD(GetExceptionFilterSecondCommand)(
THIS_
IN ULONG Index,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG CommandSize
) PURE;
STDMETHOD(SetExceptionFilterSecondCommand)(
THIS_
IN ULONG Index,
IN PCSTR Command
) PURE;
// Yields processing to the engine until
// an event occurs. This method may
// only be called by the thread that started
// the debug session.
// When an event occurs the engine carries
// out all event processing such as calling
// callbacks.
// If the callbacks indicate that execution should
// break the wait will return, otherwise it
// goes back to waiting for a new event.
// If the timeout expires, S_FALSE is returned.
// The timeout is not currently supported for
// kernel debugging.
STDMETHOD(WaitForEvent)(
THIS_
IN ULONG Flags,
IN ULONG Timeout
) PURE;
// Retrieves information about the last event that occurred.
// EventType is one of the event callback mask bits.
// ExtraInformation contains additional event-specific
// information. Not all events have additional information.
STDMETHOD(GetLastEventInformation)(
THIS_
OUT PULONG Type,
OUT PULONG ProcessId,
OUT PULONG ThreadId,
OUT OPTIONAL PVOID ExtraInformation,
IN ULONG ExtraInformationSize,
OUT OPTIONAL PULONG ExtraInformationUsed,
OUT OPTIONAL PSTR Description,
IN ULONG DescriptionSize,
OUT OPTIONAL PULONG DescriptionUsed
) PURE;
// IDebugControl2.
STDMETHOD(GetCurrentTimeDate)(
THIS_
OUT PULONG TimeDate
) PURE;
// Retrieves the number of seconds since the
// machine started running.
STDMETHOD(GetCurrentSystemUpTime)(
THIS_
OUT PULONG UpTime
) PURE;
// If the current session is a dump session,
// retrieves any extended format information.
STDMETHOD(GetDumpFormatFlags)(
THIS_
OUT PULONG FormatFlags
) PURE;
// The debugger has been enhanced to allow
// arbitrary text replacements in addition
// to the simple $u0-$u9 text macros.
// Text replacement takes a given source
// text in commands and converts it to the
// given destination text. Replacements
// are named by their source text so that
// only one replacement for a source text
// string can exist.
STDMETHOD(GetNumberTextReplacements)(
THIS_
OUT PULONG NumRepl
) PURE;
// If SrcText is non-NULL the replacement
// is looked up by source text, otherwise
// Index is used to get the Nth replacement.
STDMETHOD(GetTextReplacement)(
THIS_
IN OPTIONAL PCSTR SrcText,
IN ULONG Index,
OUT OPTIONAL PSTR SrcBuffer,
IN ULONG SrcBufferSize,
OUT OPTIONAL PULONG SrcSize,
OUT OPTIONAL PSTR DstBuffer,
IN ULONG DstBufferSize,
OUT OPTIONAL PULONG DstSize
) PURE;
// Setting the destination text to
// NULL removes the alias.
STDMETHOD(SetTextReplacement)(
THIS_
IN PCSTR SrcText,
IN OPTIONAL PCSTR DstText
) PURE;
STDMETHOD(RemoveTextReplacements)(
THIS
) PURE;
// Outputs the complete list of current
// replacements.
STDMETHOD(OutputTextReplacements)(
THIS_
IN ULONG OutputControl,
IN ULONG Flags
) PURE;
};
//----------------------------------------------------------------------------
//
// IDebugDataSpaces.
//
//----------------------------------------------------------------------------
// Data space indices for callbacks and other methods.
#define DEBUG_DATA_SPACE_VIRTUAL 0
#define DEBUG_DATA_SPACE_PHYSICAL 1
#define DEBUG_DATA_SPACE_CONTROL 2
#define DEBUG_DATA_SPACE_IO 3
#define DEBUG_DATA_SPACE_MSR 4
#define DEBUG_DATA_SPACE_BUS_DATA 5
#define DEBUG_DATA_SPACE_DEBUGGER_DATA 6
// Count of data spaces.
#define DEBUG_DATA_SPACE_COUNT 7
// Indices for ReadDebuggerData interface
#define DEBUG_DATA_KernBase 24
#define DEBUG_DATA_BreakpointWithStatusAddr 32
#define DEBUG_DATA_SavedContextAddr 40
#define DEBUG_DATA_KiCallUserModeAddr 56
#define DEBUG_DATA_KeUserCallbackDispatcherAddr 64
#define DEBUG_DATA_PsLoadedModuleListAddr 72
#define DEBUG_DATA_PsActiveProcessHeadAddr 80
#define DEBUG_DATA_PspCidTableAddr 88
#define DEBUG_DATA_ExpSystemResourcesListAddr 96
#define DEBUG_DATA_ExpPagedPoolDescriptorAddr 104
#define DEBUG_DATA_ExpNumberOfPagedPoolsAddr 112
#define DEBUG_DATA_KeTimeIncrementAddr 120
#define DEBUG_DATA_KeBugCheckCallbackListHeadAddr 128
#define DEBUG_DATA_KiBugcheckDataAddr 136
#define DEBUG_DATA_IopErrorLogListHeadAddr 144
#define DEBUG_DATA_ObpRootDirectoryObjectAddr 152
#define DEBUG_DATA_ObpTypeObjectTypeAddr 160
#define DEBUG_DATA_MmSystemCacheStartAddr 168
#define DEBUG_DATA_MmSystemCacheEndAddr 176
#define DEBUG_DATA_MmSystemCacheWsAddr 184
#define DEBUG_DATA_MmPfnDatabaseAddr 192
#define DEBUG_DATA_MmSystemPtesStartAddr 200
#define DEBUG_DATA_MmSystemPtesEndAddr 208
#define DEBUG_DATA_MmSubsectionBaseAddr 216
#define DEBUG_DATA_MmNumberOfPagingFilesAddr 224
#define DEBUG_DATA_MmLowestPhysicalPageAddr 232
#define DEBUG_DATA_MmHighestPhysicalPageAddr 240
#define DEBUG_DATA_MmNumberOfPhysicalPagesAddr 248
#define DEBUG_DATA_MmMaximumNonPagedPoolInBytesAddr 256
#define DEBUG_DATA_MmNonPagedSystemStartAddr 264
#define DEBUG_DATA_MmNonPagedPoolStartAddr 272
#define DEBUG_DATA_MmNonPagedPoolEndAddr 280
#define DEBUG_DATA_MmPagedPoolStartAddr 288
#define DEBUG_DATA_MmPagedPoolEndAddr 296
#define DEBUG_DATA_MmPagedPoolInformationAddr 304
#define DEBUG_DATA_MmPageSize 312
#define DEBUG_DATA_MmSizeOfPagedPoolInBytesAddr 320
#define DEBUG_DATA_MmTotalCommitLimitAddr 328
#define DEBUG_DATA_MmTotalCommittedPagesAddr 336
#define DEBUG_DATA_MmSharedCommitAddr 344
#define DEBUG_DATA_MmDriverCommitAddr 352
#define DEBUG_DATA_MmProcessCommitAddr 360
#define DEBUG_DATA_MmPagedPoolCommitAddr 368
#define DEBUG_DATA_MmExtendedCommitAddr 376
#define DEBUG_DATA_MmZeroedPageListHeadAddr 384
#define DEBUG_DATA_MmFreePageListHeadAddr 392
#define DEBUG_DATA_MmStandbyPageListHeadAddr 400
#define DEBUG_DATA_MmModifiedPageListHeadAddr 408
#define DEBUG_DATA_MmModifiedNoWritePageListHeadAddr 416
#define DEBUG_DATA_MmAvailablePagesAddr 424
#define DEBUG_DATA_MmResidentAvailablePagesAddr 432
#define DEBUG_DATA_PoolTrackTableAddr 440
#define DEBUG_DATA_NonPagedPoolDescriptorAddr 448
#define DEBUG_DATA_MmHighestUserAddressAddr 456
#define DEBUG_DATA_MmSystemRangeStartAddr 464
#define DEBUG_DATA_MmUserProbeAddressAddr 472
#define DEBUG_DATA_KdPrintCircularBufferAddr 480
#define DEBUG_DATA_KdPrintCircularBufferEndAddr 488
#define DEBUG_DATA_KdPrintWritePointerAddr 496
#define DEBUG_DATA_KdPrintRolloverCountAddr 504
#define DEBUG_DATA_MmLoadedUserImageListAddr 512
#define DEBUG_DATA_NtBuildLabAddr 520
#define DEBUG_DATA_KiNormalSystemCall 528
#define DEBUG_DATA_KiProcessorBlockAddr 536
#define DEBUG_DATA_MmUnloadedDriversAddr 544
#define DEBUG_DATA_MmLastUnloadedDriverAddr 552
#define DEBUG_DATA_MmTriageActionTakenAddr 560
#define DEBUG_DATA_MmSpecialPoolTagAddr 568
#define DEBUG_DATA_KernelVerifierAddr 576
#define DEBUG_DATA_MmVerifierDataAddr 584
#define DEBUG_DATA_MmAllocatedNonPagedPoolAddr 592
#define DEBUG_DATA_MmPeakCommitmentAddr 600
#define DEBUG_DATA_MmTotalCommitLimitMaximumAddr 608
#define DEBUG_DATA_CmNtCSDVersionAddr 616
#define DEBUG_DATA_MmPhysicalMemoryBlockAddr 624
#define DEBUG_DATA_PaeEnabled 100000
#define DEBUG_DATA_SharedUserData 100008
//
// Processor information structures.
//
typedef struct _DEBUG_PROCESSOR_IDENTIFICATION_ALPHA
{
ULONG Type;
ULONG Revision;
} DEBUG_PROCESSOR_IDENTIFICATION_ALPHA, *PDEBUG_PROCESSOR_IDENTIFICATION_ALPHA;
typedef struct _DEBUG_PROCESSOR_IDENTIFICATION_AMD64
{
ULONG Family;
ULONG Model;
ULONG Stepping;
CHAR VendorString[16];
} DEBUG_PROCESSOR_IDENTIFICATION_AMD64, *PDEBUG_PROCESSOR_IDENTIFICATION_AMD64;
typedef struct _DEBUG_PROCESSOR_IDENTIFICATION_IA64
{
ULONG Model;
ULONG Revision;
ULONG Family;
ULONG ArchRev;
CHAR VendorString[16];
} DEBUG_PROCESSOR_IDENTIFICATION_IA64, *PDEBUG_PROCESSOR_IDENTIFICATION_IA64;
typedef struct _DEBUG_PROCESSOR_IDENTIFICATION_X86
{
ULONG Family;
ULONG Model;
ULONG Stepping;
CHAR VendorString[16];
} DEBUG_PROCESSOR_IDENTIFICATION_X86, *PDEBUG_PROCESSOR_IDENTIFICATION_X86;
typedef union _DEBUG_PROCESSOR_IDENTIFICATION_ALL
{
DEBUG_PROCESSOR_IDENTIFICATION_ALPHA Alpha;
DEBUG_PROCESSOR_IDENTIFICATION_AMD64 Amd64;
DEBUG_PROCESSOR_IDENTIFICATION_IA64 Ia64;
DEBUG_PROCESSOR_IDENTIFICATION_X86 X86;
} DEBUG_PROCESSOR_IDENTIFICATION_ALL, *PDEBUG_PROCESSOR_IDENTIFICATION_ALL;
// Indices for ReadProcessorSystemData.
#define DEBUG_DATA_KPCR_OFFSET 0
#define DEBUG_DATA_KPRCB_OFFSET 1
#define DEBUG_DATA_KTHREAD_OFFSET 2
#define DEBUG_DATA_BASE_TRANSLATION_VIRTUAL_OFFSET 3
#define DEBUG_DATA_PROCESSOR_IDENTIFICATION 4
#undef INTERFACE
#define INTERFACE IDebugDataSpaces
DECLARE_INTERFACE_(IDebugDataSpaces, IUnknown)
{
// IUnknown.
STDMETHOD(QueryInterface)(
THIS_
IN REFIID InterfaceId,
OUT PVOID* Interface
) PURE;
STDMETHOD_(ULONG, AddRef)(
THIS
) PURE;
STDMETHOD_(ULONG, Release)(
THIS
) PURE;
// IDebugDataSpaces.
STDMETHOD(ReadVirtual)(
THIS_
IN ULONG64 Offset,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WriteVirtual)(
THIS_
IN ULONG64 Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
// SearchVirtual searches the given virtual
// address range for the given pattern. PatternSize
// gives the byte length of the pattern and PatternGranularity
// controls the granularity of comparisons during
// the search.
// For example, a DWORD-granular search would
// use a pattern granularity of four to search by DWORD
// increments.
STDMETHOD(SearchVirtual)(
THIS_
IN ULONG64 Offset,
IN ULONG64 Length,
IN PVOID Pattern,
IN ULONG PatternSize,
IN ULONG PatternGranularity,
OUT PULONG64 MatchOffset
) PURE;
// These methods are identical to Read/WriteVirtual
// except that they avoid the kernel virtual memory
// cache entirely and are therefore useful for reading
// virtual memory which is inherently volatile, such
// as memory-mapped device areas, without contaminating
// or invalidating the cache.
// In user-mode they are the same as Read/WriteVirtual.
STDMETHOD(ReadVirtualUncached)(
THIS_
IN ULONG64 Offset,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WriteVirtualUncached)(
THIS_
IN ULONG64 Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
// The following two methods are convenience
// methods for accessing pointer values.
// They automatically convert between native pointers
// and canonical 64-bit values as necessary.
// These routines stop at the first failure.
STDMETHOD(ReadPointersVirtual)(
THIS_
IN ULONG Count,
IN ULONG64 Offset,
OUT /* size_is(Count) */ PULONG64 Ptrs
) PURE;
STDMETHOD(WritePointersVirtual)(
THIS_
IN ULONG Count,
IN ULONG64 Offset,
IN /* size_is(Count) */ PULONG64 Ptrs
) PURE;
// All non-virtual data spaces are only
// available when kernel debugging.
STDMETHOD(ReadPhysical)(
THIS_
IN ULONG64 Offset,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WritePhysical)(
THIS_
IN ULONG64 Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
STDMETHOD(ReadControl)(
THIS_
IN ULONG Processor,
IN ULONG64 Offset,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WriteControl)(
THIS_
IN ULONG Processor,
IN ULONG64 Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
STDMETHOD(ReadIo)(
THIS_
IN ULONG InterfaceType,
IN ULONG BusNumber,
IN ULONG AddressSpace,
IN ULONG64 Offset,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WriteIo)(
THIS_
IN ULONG InterfaceType,
IN ULONG BusNumber,
IN ULONG AddressSpace,
IN ULONG64 Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
STDMETHOD(ReadMsr)(
THIS_
IN ULONG Msr,
OUT PULONG64 Value
) PURE;
STDMETHOD(WriteMsr)(
THIS_
IN ULONG Msr,
IN ULONG64 Value
) PURE;
STDMETHOD(ReadBusData)(
THIS_
IN ULONG BusDataType,
IN ULONG BusNumber,
IN ULONG SlotNumber,
IN ULONG Offset,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WriteBusData)(
THIS_
IN ULONG BusDataType,
IN ULONG BusNumber,
IN ULONG SlotNumber,
IN ULONG Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
STDMETHOD(CheckLowMemory)(
THIS
) PURE;
STDMETHOD(ReadDebuggerData)(
THIS_
IN ULONG Index,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG DataSize
) PURE;
STDMETHOD(ReadProcessorSystemData)(
THIS_
IN ULONG Processor,
IN ULONG Index,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG DataSize
) PURE;
};
//
// Handle data types and structures.
//
#define DEBUG_HANDLE_DATA_TYPE_BASIC 0
#define DEBUG_HANDLE_DATA_TYPE_TYPE_NAME 1
#define DEBUG_HANDLE_DATA_TYPE_OBJECT_NAME 2
#define DEBUG_HANDLE_DATA_TYPE_HANDLE_COUNT 3
typedef struct _DEBUG_HANDLE_DATA_BASIC
{
ULONG TypeNameSize;
ULONG ObjectNameSize;
ULONG Attributes;
ULONG GrantedAccess;
ULONG HandleCount;
ULONG PointerCount;
} DEBUG_HANDLE_DATA_BASIC, *PDEBUG_HANDLE_DATA_BASIC;
#undef INTERFACE
#define INTERFACE IDebugDataSpaces2
DECLARE_INTERFACE_(IDebugDataSpaces2, IUnknown)
{
// IUnknown.
STDMETHOD(QueryInterface)(
THIS_
IN REFIID InterfaceId,
OUT PVOID* Interface
) PURE;
STDMETHOD_(ULONG, AddRef)(
THIS
) PURE;
STDMETHOD_(ULONG, Release)(
THIS
) PURE;
// IDebugDataSpaces.
STDMETHOD(ReadVirtual)(
THIS_
IN ULONG64 Offset,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WriteVirtual)(
THIS_
IN ULONG64 Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
// SearchVirtual searches the given virtual
// address range for the given pattern. PatternSize
// gives the byte length of the pattern and PatternGranularity
// controls the granularity of comparisons during
// the search.
// For example, a DWORD-granular search would
// use a pattern granularity of four to search by DWORD
// increments.
STDMETHOD(SearchVirtual)(
THIS_
IN ULONG64 Offset,
IN ULONG64 Length,
IN PVOID Pattern,
IN ULONG PatternSize,
IN ULONG PatternGranularity,
OUT PULONG64 MatchOffset
) PURE;
// These methods are identical to Read/WriteVirtual
// except that they avoid the kernel virtual memory
// cache entirely and are therefore useful for reading
// virtual memory which is inherently volatile, such
// as memory-mapped device areas, without contaminating
// or invalidating the cache.
// In user-mode they are the same as Read/WriteVirtual.
STDMETHOD(ReadVirtualUncached)(
THIS_
IN ULONG64 Offset,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WriteVirtualUncached)(
THIS_
IN ULONG64 Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
// The following two methods are convenience
// methods for accessing pointer values.
// They automatically convert between native pointers
// and canonical 64-bit values as necessary.
// These routines stop at the first failure.
STDMETHOD(ReadPointersVirtual)(
THIS_
IN ULONG Count,
IN ULONG64 Offset,
OUT /* size_is(Count) */ PULONG64 Ptrs
) PURE;
STDMETHOD(WritePointersVirtual)(
THIS_
IN ULONG Count,
IN ULONG64 Offset,
IN /* size_is(Count) */ PULONG64 Ptrs
) PURE;
// All non-virtual data spaces are only
// available when kernel debugging.
STDMETHOD(ReadPhysical)(
THIS_
IN ULONG64 Offset,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WritePhysical)(
THIS_
IN ULONG64 Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
STDMETHOD(ReadControl)(
THIS_
IN ULONG Processor,
IN ULONG64 Offset,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WriteControl)(
THIS_
IN ULONG Processor,
IN ULONG64 Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
STDMETHOD(ReadIo)(
THIS_
IN ULONG InterfaceType,
IN ULONG BusNumber,
IN ULONG AddressSpace,
IN ULONG64 Offset,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WriteIo)(
THIS_
IN ULONG InterfaceType,
IN ULONG BusNumber,
IN ULONG AddressSpace,
IN ULONG64 Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
STDMETHOD(ReadMsr)(
THIS_
IN ULONG Msr,
OUT PULONG64 Value
) PURE;
STDMETHOD(WriteMsr)(
THIS_
IN ULONG Msr,
IN ULONG64 Value
) PURE;
STDMETHOD(ReadBusData)(
THIS_
IN ULONG BusDataType,
IN ULONG BusNumber,
IN ULONG SlotNumber,
IN ULONG Offset,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WriteBusData)(
THIS_
IN ULONG BusDataType,
IN ULONG BusNumber,
IN ULONG SlotNumber,
IN ULONG Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
STDMETHOD(CheckLowMemory)(
THIS
) PURE;
STDMETHOD(ReadDebuggerData)(
THIS_
IN ULONG Index,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG DataSize
) PURE;
STDMETHOD(ReadProcessorSystemData)(
THIS_
IN ULONG Processor,
IN ULONG Index,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG DataSize
) PURE;
// IDebugDataSpaces2.
STDMETHOD(VirtualToPhysical)(
THIS_
IN ULONG64 Virtual,
OUT PULONG64 Physical
) PURE;
// Returns the physical addresses for the
// N levels of the systems paging structures.
// Level zero is the starting base physical
// address for virtual translations.
// Levels one-(N-1) will point to the appropriate
// paging descriptor for the virtual address at
// the given level of the paging hierarchy. The
// exact number of levels depends on many factors.
// The last level will be the fully translated
// physical address, matching what VirtualToPhysical
// returns. If the address can only be partially
// translated S_FALSE is returned.
STDMETHOD(GetVirtualTranslationPhysicalOffsets)(
THIS_
IN ULONG64 Virtual,
OUT OPTIONAL /* size_is(OffsetsSize) */ PULONG64 Offsets,
IN ULONG OffsetsSize,
OUT OPTIONAL PULONG Levels
) PURE;
// System handle data is accessible in certain
// debug sessions. The particular data available
// varies from session to session and platform
// to platform.
STDMETHOD(ReadHandleData)(
THIS_
IN ULONG64 Handle,
IN ULONG DataType,
OUT OPTIONAL PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG DataSize
) PURE;
// Fills memory with the given pattern.
// The fill stops at the first non-writable byte.
STDMETHOD(FillVirtual)(
THIS_
IN ULONG64 Start,
IN ULONG Size,
IN PVOID Pattern,
IN ULONG PatternSize,
OUT OPTIONAL PULONG Filled
) PURE;
STDMETHOD(FillPhysical)(
THIS_
IN ULONG64 Start,
IN ULONG Size,
IN PVOID Pattern,
IN ULONG PatternSize,
OUT OPTIONAL PULONG Filled
) PURE;
// Queries virtual memory mapping information given
// an address similarly to the Win32 API VirtualQuery.
// MEMORY_BASIC_INFORMATION64 is defined in crash.h.
// This method currently only works for user-mode sessions.
STDMETHOD(QueryVirtual)(
THIS_
IN ULONG64 Offset,
OUT PMEMORY_BASIC_INFORMATION64 Info
) PURE;
};
//----------------------------------------------------------------------------
//
// IDebugEventCallbacks.
//
//----------------------------------------------------------------------------
// Interest mask bits.
#define DEBUG_EVENT_BREAKPOINT 0x00000001
#define DEBUG_EVENT_EXCEPTION 0x00000002
#define DEBUG_EVENT_CREATE_THREAD 0x00000004
#define DEBUG_EVENT_EXIT_THREAD 0x00000008
#define DEBUG_EVENT_CREATE_PROCESS 0x00000010
#define DEBUG_EVENT_EXIT_PROCESS 0x00000020
#define DEBUG_EVENT_LOAD_MODULE 0x00000040
#define DEBUG_EVENT_UNLOAD_MODULE 0x00000080
#define DEBUG_EVENT_SYSTEM_ERROR 0x00000100
#define DEBUG_EVENT_SESSION_STATUS 0x00000200
#define DEBUG_EVENT_CHANGE_DEBUGGEE_STATE 0x00000400
#define DEBUG_EVENT_CHANGE_ENGINE_STATE 0x00000800
#define DEBUG_EVENT_CHANGE_SYMBOL_STATE 0x00001000
// SessionStatus flags.
// A debuggee has been discovered for the session.
#define DEBUG_SESSION_ACTIVE 0x00000000
// The session has been ended by EndSession.
#define DEBUG_SESSION_END_SESSION_ACTIVE_TERMINATE 0x00000001
#define DEBUG_SESSION_END_SESSION_ACTIVE_DETACH 0x00000002
#define DEBUG_SESSION_END_SESSION_PASSIVE 0x00000003
// The debuggee has run to completion. User-mode only.
#define DEBUG_SESSION_END 0x00000004
// The target machine has rebooted. Kernel-mode only.
#define DEBUG_SESSION_REBOOT 0x00000005
// The target machine has hibernated. Kernel-mode only.
#define DEBUG_SESSION_HIBERNATE 0x00000006
// The engine was unable to continue the session.
#define DEBUG_SESSION_FAILURE 0x00000007
// ChangeDebuggeeState flags.
// The debuggees state has changed generally, such
// as when the debuggee has been executing.
// Argument is zero.
#define DEBUG_CDS_ALL 0xffffffff
// Registers have changed. If only a single register
// changed, argument is the index of the register.
// Otherwise it is DEBUG_ANY_ID.
#define DEBUG_CDS_REGISTERS 0x00000001
// Data spaces have changed. If only a single
// space was affected, argument is the data
// space. Otherwise it is DEBUG_ANY_ID.
#define DEBUG_CDS_DATA 0x00000002
// ChangeEngineState flags.
// The engine state has changed generally.
// Argument is zero.
#define DEBUG_CES_ALL 0xffffffff
// Current thread changed. This may imply a change
// of process also. Argument is the ID of the new
// current thread.
#define DEBUG_CES_CURRENT_THREAD 0x00000001
// Effective processor changed. Argument is the
// new processor type.
#define DEBUG_CES_EFFECTIVE_PROCESSOR 0x00000002
// Breakpoints changed. If only a single breakpoint
// changed, argument is the ID of the breakpoint.
// Otherwise it is DEBUG_ANY_ID.
#define DEBUG_CES_BREAKPOINTS 0x00000004
// Code interpretation level changed. Argument is
// the new level.
#define DEBUG_CES_CODE_LEVEL 0x00000008
// Execution status changed. Argument is the new
// execution status.
#define DEBUG_CES_EXECUTION_STATUS 0x00000010
// Engine options have changed. Argument is the new
// options value.
#define DEBUG_CES_ENGINE_OPTIONS 0x00000020
// Log file information has changed. Argument
// is TRUE if a log file was opened and FALSE if
// a log file was closed.
#define DEBUG_CES_LOG_FILE 0x00000040
// Default number radix has changed. Argument
// is the new radix.
#define DEBUG_CES_RADIX 0x00000080
// Event filters changed. If only a single filter
// changed the argument is the filter's index,
// otherwise it is DEBUG_ANY_ID.
#define DEBUG_CES_EVENT_FILTERS 0x00000100
// Process options have changed. Argument is the new
// options value.
#define DEBUG_CES_PROCESS_OPTIONS 0x00000200
// Extensions have been added or removed.
#define DEBUG_CES_EXTENSIONS 0x00000400
// ChangeSymbolState flags.
// Symbol state has changed generally, such
// as after reload operations. Argument is zero.
#define DEBUG_CSS_ALL 0xffffffff
// Modules have been loaded. If only a
// single module changed, argument is the
// base address of the module. Otherwise
// it is zero.
#define DEBUG_CSS_LOADS 0x00000001
// Modules have been unloaded. If only a
// single module changed, argument is the
// base address of the module. Otherwise
// it is zero.
#define DEBUG_CSS_UNLOADS 0x00000002
// Current symbol scope changed.
#define DEBUG_CSS_SCOPE 0x00000004
// Paths have changed.
#define DEBUG_CSS_PATHS 0x00000008
// Symbol options have changed. Argument is the new
// options value.
#define DEBUG_CSS_SYMBOL_OPTIONS 0x00000010
// Type options have changed. Argument is the new
// options value.
#define DEBUG_CSS_TYPE_OPTIONS 0x00000020
#undef INTERFACE
#define INTERFACE IDebugEventCallbacks
DECLARE_INTERFACE_(IDebugEventCallbacks, IUnknown)
{
// IUnknown.
STDMETHOD(QueryInterface)(
THIS_
IN REFIID InterfaceId,
OUT PVOID* Interface
) PURE;
STDMETHOD_(ULONG, AddRef)(
THIS
) PURE;
STDMETHOD_(ULONG, Release)(
THIS
) PURE;
// IDebugEventCallbacks.
// The engine calls GetInterestMask once when
// the event callbacks are set for a client.
STDMETHOD(GetInterestMask)(
THIS_
OUT PULONG Mask
) PURE;
// A breakpoint event is generated when
// a breakpoint exception is received and
// it can be mapped to an existing breakpoint.
// The callback method is given a reference
// to the breakpoint and should release it when
// it is done with it.
STDMETHOD(Breakpoint)(
THIS_
IN PDEBUG_BREAKPOINT Bp
) PURE;
// Exceptions include breaks which cannot
// be mapped to an existing breakpoint
// instance.
STDMETHOD(Exception)(
THIS_
IN PEXCEPTION_RECORD64 Exception,
IN ULONG FirstChance
) PURE;
// Any of these values can be zero if they
// cannot be provided by the engine.
// Currently the kernel does not return thread
// or process change events.
STDMETHOD(CreateThread)(
THIS_
IN ULONG64 Handle,
IN ULONG64 DataOffset,
IN ULONG64 StartOffset
) PURE;
STDMETHOD(ExitThread)(
THIS_
IN ULONG ExitCode
) PURE;
// Any of these values can be zero if they
// cannot be provided by the engine.
STDMETHOD(CreateProcess)(
THIS_
IN ULONG64 ImageFileHandle,
IN ULONG64 Handle,
IN ULONG64 BaseOffset,
IN ULONG ModuleSize,
IN PCSTR ModuleName,
IN PCSTR ImageName,
IN ULONG CheckSum,
IN ULONG TimeDateStamp,
IN ULONG64 InitialThreadHandle,
IN ULONG64 ThreadDataOffset,
IN ULONG64 StartOffset
) PURE;
STDMETHOD(ExitProcess)(
THIS_
IN ULONG ExitCode
) PURE;
// Any of these values may be zero.
STDMETHOD(LoadModule)(
THIS_
IN ULONG64 ImageFileHandle,
IN ULONG64 BaseOffset,
IN ULONG ModuleSize,
IN PCSTR ModuleName,
IN PCSTR ImageName,
IN ULONG CheckSum,
IN ULONG TimeDateStamp
) PURE;
STDMETHOD(UnloadModule)(
THIS_
IN PCSTR ImageBaseName,
IN ULONG64 BaseOffset
) PURE;
STDMETHOD(SystemError)(
THIS_
IN ULONG Error,
IN ULONG Level
) PURE;
// Session status is synchronous like the other
// wait callbacks but it is called as the state
// of the session is changing rather than at
// specific events so its return value does not
// influence waiting. Implementations should just
// return DEBUG_STATUS_NO_CHANGE.
// Also, because some of the status
// notifications are very early or very
// late in the session lifetime there may not be
// current processes or threads when the notification
// is generated.
STDMETHOD(SessionStatus)(
THIS_
IN ULONG Status
) PURE;
// The following callbacks are informational
// callbacks notifying the provider about
// changes in debug state. The return value
// of these callbacks is ignored. Implementations
// can not call back into the engine.
// Debuggee state, such as registers or data spaces,
// has changed.
STDMETHOD(ChangeDebuggeeState)(
THIS_
IN ULONG Flags,
IN ULONG64 Argument
) PURE;
// Engine state has changed.
STDMETHOD(ChangeEngineState)(
THIS_
IN ULONG Flags,
IN ULONG64 Argument
) PURE;
// Symbol state has changed.
STDMETHOD(ChangeSymbolState)(
THIS_
IN ULONG Flags,
IN ULONG64 Argument
) PURE;
};
//----------------------------------------------------------------------------
//
// IDebugInputCallbacks.
//
//----------------------------------------------------------------------------
#undef INTERFACE
#define INTERFACE IDebugInputCallbacks
DECLARE_INTERFACE_(IDebugInputCallbacks, IUnknown)
{
// IUnknown.
STDMETHOD(QueryInterface)(
THIS_
IN REFIID InterfaceId,
OUT PVOID* Interface
) PURE;
STDMETHOD_(ULONG, AddRef)(
THIS
) PURE;
STDMETHOD_(ULONG, Release)(
THIS
) PURE;
// IDebugInputCallbacks.
// A call to the StartInput method is a request for
// a line of input from any client. The returned input
// should always be zero-terminated. The buffer size
// provided is only a guideline. A client can return
// more if necessary and the engine will truncate it
// before returning from IDebugControl::Input.
// The return value is ignored.
STDMETHOD(StartInput)(
THIS_
IN ULONG BufferSize
) PURE;
// The return value is ignored.
STDMETHOD(EndInput)(
THIS
) PURE;
};
//----------------------------------------------------------------------------
//
// IDebugOutputCallbacks.
//
//----------------------------------------------------------------------------
#undef INTERFACE
#define INTERFACE IDebugOutputCallbacks
DECLARE_INTERFACE_(IDebugOutputCallbacks, IUnknown)
{
// IUnknown.
STDMETHOD(QueryInterface)(
THIS_
IN REFIID InterfaceId,
OUT PVOID* Interface
) PURE;
STDMETHOD_(ULONG, AddRef)(
THIS
) PURE;
STDMETHOD_(ULONG, Release)(
THIS
) PURE;
// IDebugOutputCallbacks.
// This method is only called if the supplied mask
// is allowed by the clients output control.
// The return value is ignored.
STDMETHOD(Output)(
THIS_
IN ULONG Mask,
IN PCSTR Text
) PURE;
};
//----------------------------------------------------------------------------
//
// IDebugRegisters.
//
//----------------------------------------------------------------------------
#define DEBUG_REGISTER_SUB_REGISTER 0x00000001
#define DEBUG_REGISTERS_DEFAULT 0x00000000
#define DEBUG_REGISTERS_INT32 0x00000001
#define DEBUG_REGISTERS_INT64 0x00000002
#define DEBUG_REGISTERS_FLOAT 0x00000004
#define DEBUG_REGISTERS_ALL 0x00000007
typedef struct _DEBUG_REGISTER_DESCRIPTION
{
// DEBUG_VALUE type.
ULONG Type;
ULONG Flags;
// If this is a subregister the full
// registers description index is
// given in SubregMaster. The length, mask
// and shift describe how the subregisters
// bits fit into the full register.
ULONG SubregMaster;
ULONG SubregLength;
ULONG64 SubregMask;
ULONG SubregShift;
ULONG Reserved0;
} DEBUG_REGISTER_DESCRIPTION, *PDEBUG_REGISTER_DESCRIPTION;
#undef INTERFACE
#define INTERFACE IDebugRegisters
DECLARE_INTERFACE_(IDebugRegisters, IUnknown)
{
// IUnknown.
STDMETHOD(QueryInterface)(
THIS_
IN REFIID InterfaceId,
OUT PVOID* Interface
) PURE;
STDMETHOD_(ULONG, AddRef)(
THIS
) PURE;
STDMETHOD_(ULONG, Release)(
THIS
) PURE;
// IDebugRegisters.
STDMETHOD(GetNumberRegisters)(
THIS_
OUT PULONG Number
) PURE;
STDMETHOD(GetDescription)(
THIS_
IN ULONG Register,
OUT OPTIONAL PSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize,
OUT OPTIONAL PDEBUG_REGISTER_DESCRIPTION Desc
) PURE;
STDMETHOD(GetIndexByName)(
THIS_
IN PCSTR Name,
OUT PULONG Index
) PURE;
STDMETHOD(GetValue)(
THIS_
IN ULONG Register,
OUT PDEBUG_VALUE Value
) PURE;
// SetValue makes a best effort at coercing
// the given value into the given registers
// value type. If the given value is larger
// than the register can hold the least
// significant bits will be dropped. Float
// to int and int to float will be done
// if necessary. Subregister bits will be
// inserted into the master register.
STDMETHOD(SetValue)(
THIS_
IN ULONG Register,
IN PDEBUG_VALUE Value
) PURE;
// Gets Count register values. If Indices is
// non-NULL it must contain Count register
// indices which control the registers affected.
// If Indices is NULL the registers from Start
// to Start + Count 1 are retrieved.
STDMETHOD(GetValues)(
THIS_
IN ULONG Count,
IN OPTIONAL /* size_is(Count) */ PULONG Indices,
IN ULONG Start,
OUT /* size_is(Count) */ PDEBUG_VALUE Values
) PURE;
STDMETHOD(SetValues)(
THIS_
IN ULONG Count,
IN OPTIONAL /* size_is(Count) */ PULONG Indices,
IN ULONG Start,
IN /* size_is(Count) */ PDEBUG_VALUE Values
) PURE;
// Outputs a group of registers in a well-formatted
// way thats specific to the platforms register set.
// Uses the line prefix.
STDMETHOD(OutputRegisters)(
THIS_
IN ULONG OutputControl,
IN ULONG Flags
) PURE;
// Abstracted pieces of processor information.
// The mapping of these values to architectural
// registers is architecture-specific and their
// interpretation and existence may vary. They
// are intended to be directly compatible with
// calls which take this information, such as
// stack walking.
STDMETHOD(GetInstructionOffset)(
THIS_
OUT PULONG64 Offset
) PURE;
STDMETHOD(GetStackOffset)(
THIS_
OUT PULONG64 Offset
) PURE;
STDMETHOD(GetFrameOffset)(
THIS_
OUT PULONG64 Offset
) PURE;
};
//----------------------------------------------------------------------------
//
// IDebugSymbolGroup
//
//----------------------------------------------------------------------------
// OutputSymbols flags.
// Default output contains <Name>**NAME**<Offset>**OFF**<Value>**VALUE**
// per symbol.
#define DEBUG_OUTPUT_SYMBOLS_DEFAULT 0x00000000
#define DEBUG_OUTPUT_SYMBOLS_NO_NAMES 0x00000001
#define DEBUG_OUTPUT_SYMBOLS_NO_OFFSETS 0x00000002
#define DEBUG_OUTPUT_SYMBOLS_NO_VALUES 0x00000004
#define DEBUG_OUTPUT_SYMBOLS_NO_TYPES 0x00000010
#define DEBUG_OUTPUT_NAME_END "**NAME**"
#define DEBUG_OUTPUT_OFFSET_END "**OFF**"
#define DEBUG_OUTPUT_VALUE_END "**VALUE**"
#define DEBUG_OUTPUT_TYPE_END "**TYPE**"
// DEBUG_SYMBOL_PARAMETERS flags.
// Cumulative expansion level, takes four bits.
#define DEBUG_SYMBOL_EXPANSION_LEVEL_MASK 0x0000000f
// Symbols subelements follow.
#define DEBUG_SYMBOL_EXPANDED 0x00000010
// Symbols value is read-only.
#define DEBUG_SYMBOL_READ_ONLY 0x00000020
// Symbol subelements are array elements.
#define DEBUG_SYMBOL_IS_ARRAY 0x00000040
// Symbol is a float value.
#define DEBUG_SYMBOL_IS_FLOAT 0x00000080
// Symbol is a scope argument.
#define DEBUG_SYMBOL_IS_ARGUMENT 0x00000100
// Symbol is a scope argument.
#define DEBUG_SYMBOL_IS_LOCAL 0x00000200
typedef struct _DEBUG_SYMBOL_PARAMETERS
{
ULONG64 Module;
ULONG TypeId;
// ParentSymbol may be DEBUG_ANY_ID when unknown.
ULONG ParentSymbol;
// A subelement of a symbol can be a field, such
// as in structs, unions or classes; or an array
// element count for arrays.
ULONG SubElements;
ULONG Flags;
ULONG64 Reserved;
} DEBUG_SYMBOL_PARAMETERS, *PDEBUG_SYMBOL_PARAMETERS;
#undef INTERFACE
#define INTERFACE IDebugSymbolGroup
DECLARE_INTERFACE_(IDebugSymbolGroup, IUnknown)
{
// IUnknown.
STDMETHOD(QueryInterface)(
THIS_
IN REFIID InterfaceId,
OUT PVOID* Interface
) PURE;
STDMETHOD_(ULONG, AddRef)(
THIS
) PURE;
STDMETHOD_(ULONG, Release)(
THIS
) PURE;
// IDebugSymbolGroup.
STDMETHOD(GetNumberSymbols)(
THIS_
OUT PULONG Number
) PURE;
STDMETHOD(AddSymbol)(
THIS_
IN PCSTR Name,
OUT PULONG Index
) PURE;
STDMETHOD(RemoveSymbolByName)(
THIS_
IN PCSTR Name
) PURE;
STDMETHOD(RemoveSymbolByIndex)(
THIS_
IN ULONG Index
) PURE;
STDMETHOD(GetSymbolName)(
THIS_
IN ULONG Index,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG NameSize
) PURE;
STDMETHOD(GetSymbolParameters)(
THIS_
IN ULONG Start,
IN ULONG Count,
OUT /* size_is(Count) */ PDEBUG_SYMBOL_PARAMETERS Params
) PURE;
STDMETHOD(ExpandSymbol)(
THIS_
IN ULONG Index,
IN BOOL Expand
) PURE;
// Uses the line prefix.
STDMETHOD(OutputSymbols)(
THIS_
IN ULONG OutputControl,
IN ULONG Flags,
IN ULONG Start,
IN ULONG Count
) PURE;
STDMETHOD(WriteSymbol)(
THIS_
IN ULONG Index,
IN PCSTR Value
) PURE;
STDMETHOD(OutputAsType)(
THIS_
IN ULONG Index,
IN PCSTR Type
) PURE;
};
//----------------------------------------------------------------------------
//
// IDebugSymbols.
//
//----------------------------------------------------------------------------
//
// Information about a module.
//
// Flags.
#define DEBUG_MODULE_LOADED 0x00000000
#define DEBUG_MODULE_UNLOADED 0x00000001
// Symbol types.
#define DEBUG_SYMTYPE_NONE 0
#define DEBUG_SYMTYPE_COFF 1
#define DEBUG_SYMTYPE_CODEVIEW 2
#define DEBUG_SYMTYPE_PDB 3
#define DEBUG_SYMTYPE_EXPORT 4
#define DEBUG_SYMTYPE_DEFERRED 5
#define DEBUG_SYMTYPE_SYM 6
#define DEBUG_SYMTYPE_DIA 7
typedef struct _DEBUG_MODULE_PARAMETERS
{
ULONG64 Base;
ULONG Size;
ULONG TimeDateStamp;
ULONG Checksum;
ULONG Flags;
ULONG SymbolType;
ULONG ImageNameSize;
ULONG ModuleNameSize;
ULONG LoadedImageNameSize;
ULONG SymbolFileNameSize;
ULONG MappedImageNameSize;
ULONG64 Reserved[2];
} DEBUG_MODULE_PARAMETERS, *PDEBUG_MODULE_PARAMETERS;
// Scope arguments are function arguments
// and thus only change when the scope
// crosses functions.
#define DEBUG_SCOPE_GROUP_ARGUMENTS 0x00000001
// Scope locals are locals declared in a particular
// scope and are only defined within that scope.
#define DEBUG_SCOPE_GROUP_LOCALS 0x00000002
// All symbols in the scope.
#define DEBUG_SCOPE_GROUP_ALL 0x00000003
// Typed data output control flags.
#define DEBUG_OUTTYPE_DEFAULT 0x00000000
#define DEBUG_OUTTYPE_NO_INDENT 0x00000001
#define DEBUG_OUTTYPE_NO_OFFSET 0x00000002
#define DEBUG_OUTTYPE_VERBOSE 0x00000004
#define DEBUG_OUTTYPE_COMPACT_OUTPUT 0x00000008
#define DEBUG_OUTTYPE_RECURSION_LEVEL(Max) (((Max) & 0xf) << 4)
#define DEBUG_OUTTYPE_ADDRESS_OF_FIELD 0x00010000
#define DEBUG_OUTTYPE_ADDRESS_AT_END 0x00020000
#define DEBUG_OUTTYPE_BLOCK_RECURSE 0x00200000
// FindSourceFile flags.
#define DEBUG_FIND_SOURCE_DEFAULT 0x00000000
// Returns fully-qualified paths only. If this
// is not set the path returned may be relative.
#define DEBUG_FIND_SOURCE_FULL_PATH 0x00000001
// Scans all the path elements for a match and
// returns the one that has the most similarity
// between the given file and the matching element.
#define DEBUG_FIND_SOURCE_BEST_MATCH 0x00000002
// A special value marking an offset that should not
// be treated as a valid offset. This is only used
// in special situations where it is unlikely that
// this value would be a valid offset.
#define DEBUG_INVALID_OFFSET ((ULONG64)-1)
#undef INTERFACE
#define INTERFACE IDebugSymbols
DECLARE_INTERFACE_(IDebugSymbols, IUnknown)
{
// IUnknown.
STDMETHOD(QueryInterface)(
THIS_
IN REFIID InterfaceId,
OUT PVOID* Interface
) PURE;
STDMETHOD_(ULONG, AddRef)(
THIS
) PURE;
STDMETHOD_(ULONG, Release)(
THIS
) PURE;
// IDebugSymbols.
// Controls the symbol options used during
// symbol operations.
// Uses the same flags as dbghelps SymSetOptions.
STDMETHOD(GetSymbolOptions)(
THIS_
OUT PULONG Options
) PURE;
STDMETHOD(AddSymbolOptions)(
THIS_
IN ULONG Options
) PURE;
STDMETHOD(RemoveSymbolOptions)(
THIS_
IN ULONG Options
) PURE;
STDMETHOD(SetSymbolOptions)(
THIS_
IN ULONG Options
) PURE;
STDMETHOD(GetNameByOffset)(
THIS_
IN ULONG64 Offset,
OUT OPTIONAL PSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize,
OUT OPTIONAL PULONG64 Displacement
) PURE;
// A symbol name may not be unique, particularly
// when overloaded functions exist which all
// have the same name. If GetOffsetByName
// finds multiple matches for the name it
// can return any one of them. In that
// case it will return S_FALSE to indicate
// that ambiguity was arbitrarily resolved.
// A caller can then use SearchSymbols to
// find all of the matches if it wishes to
// perform different disambiguation.
STDMETHOD(GetOffsetByName)(
THIS_
IN PCSTR Symbol,
OUT PULONG64 Offset
) PURE;
// GetNearNameByOffset returns symbols
// located near the symbol closest to
// to the offset, such as the previous
// or next symbol. If Delta is zero it
// operates identically to GetNameByOffset.
// If Delta is nonzero and such a symbol
// does not exist an error is returned.
// The next symbol, if one exists, will
// always have a higher offset than the
// input offset so the displacement is
// always negative. The situation is
// reversed for the previous symbol.
STDMETHOD(GetNearNameByOffset)(
THIS_
IN ULONG64 Offset,
IN LONG Delta,
OUT OPTIONAL PSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize,
OUT OPTIONAL PULONG64 Displacement
) PURE;
STDMETHOD(GetLineByOffset)(
THIS_
IN ULONG64 Offset,
OUT OPTIONAL PULONG Line,
OUT OPTIONAL PSTR FileBuffer,
IN ULONG FileBufferSize,
OUT OPTIONAL PULONG FileSize,
OUT OPTIONAL PULONG64 Displacement
) PURE;
STDMETHOD(GetOffsetByLine)(
THIS_
IN ULONG Line,
IN PCSTR File,
OUT PULONG64 Offset
) PURE;
// Enumerates the engines list of modules
// loaded for the current process. This may
// or may not match the system module list
// for the process. Reload can be used to
// synchronize the engines list with the system
// if necessary.
// Some sessions also track recently unloaded
// code modules for help in analyzing failures
// where an attempt is made to call unloaded code.
// These modules are indexed after the loaded
// modules.
STDMETHOD(GetNumberModules)(
THIS_
OUT PULONG Loaded,
OUT PULONG Unloaded
) PURE;
STDMETHOD(GetModuleByIndex)(
THIS_
IN ULONG Index,
OUT PULONG64 Base
) PURE;
// The module name may not be unique.
// This method returns the first match.
STDMETHOD(GetModuleByModuleName)(
THIS_
IN PCSTR Name,
IN ULONG StartIndex,
OUT OPTIONAL PULONG Index,
OUT OPTIONAL PULONG64 Base
) PURE;
// Offset can be any offset within
// the module extent. Extents may
// not be unique when including unloaded
// drivers. This method returns the
// first match.
STDMETHOD(GetModuleByOffset)(
THIS_
IN ULONG64 Offset,
IN ULONG StartIndex,
OUT OPTIONAL PULONG Index,
OUT OPTIONAL PULONG64 Base
) PURE;
// If Index is DEBUG_ANY_ID the base address
// is used to look up the module instead.
STDMETHOD(GetModuleNames)(
THIS_
IN ULONG Index,
IN ULONG64 Base,
OUT OPTIONAL PSTR ImageNameBuffer,
IN ULONG ImageNameBufferSize,
OUT OPTIONAL PULONG ImageNameSize,
OUT OPTIONAL PSTR ModuleNameBuffer,
IN ULONG ModuleNameBufferSize,
OUT OPTIONAL PULONG ModuleNameSize,
OUT OPTIONAL PSTR LoadedImageNameBuffer,
IN ULONG LoadedImageNameBufferSize,
OUT OPTIONAL PULONG LoadedImageNameSize
) PURE;
STDMETHOD(GetModuleParameters)(
THIS_
IN ULONG Count,
IN OPTIONAL /* size_is(Count) */ PULONG64 Bases,
IN ULONG Start,
OUT /* size_is(Count) */ PDEBUG_MODULE_PARAMETERS Params
) PURE;
// Looks up the module from a <Module>!<Symbol>
// string.
STDMETHOD(GetSymbolModule)(
THIS_
IN PCSTR Symbol,
OUT PULONG64 Base
) PURE;
// Returns the string name of a type.
STDMETHOD(GetTypeName)(
THIS_
IN ULONG64 Module,
IN ULONG TypeId,
OUT OPTIONAL PSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize
) PURE;
// Returns the ID for a type name.
STDMETHOD(GetTypeId)(
THIS_
IN ULONG64 Module,
IN PCSTR Name,
OUT PULONG TypeId
) PURE;
STDMETHOD(GetTypeSize)(
THIS_
IN ULONG64 Module,
IN ULONG TypeId,
OUT PULONG Size
) PURE;
// Given a type which can contain members
// this method returns the offset of a
// particular member within the type.
// TypeId should give the container type ID
// and Field gives the dot-separated path
// to the field of interest.
STDMETHOD(GetFieldOffset)(
THIS_
IN ULONG64 Module,
IN ULONG TypeId,
IN PCSTR Field,
OUT PULONG Offset
) PURE;
STDMETHOD(GetSymbolTypeId)(
THIS_
IN PCSTR Symbol,
OUT PULONG TypeId,
OUT OPTIONAL PULONG64 Module
) PURE;
// As with GetOffsetByName a symbol's
// name may be ambiguous. GetOffsetTypeId
// returns the type for the symbol closest
// to the given offset and can be used
// to avoid ambiguity.
STDMETHOD(GetOffsetTypeId)(
THIS_
IN ULONG64 Offset,
OUT PULONG TypeId,
OUT OPTIONAL PULONG64 Module
) PURE;
// Helpers for virtual and physical data
// which combine creation of a location with
// the actual operation.
STDMETHOD(ReadTypedDataVirtual)(
THIS_
IN ULONG64 Offset,
IN ULONG64 Module,
IN ULONG TypeId,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WriteTypedDataVirtual)(
THIS_
IN ULONG64 Offset,
IN ULONG64 Module,
IN ULONG TypeId,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
STDMETHOD(OutputTypedDataVirtual)(
THIS_
IN ULONG OutputControl,
IN ULONG64 Offset,
IN ULONG64 Module,
IN ULONG TypeId,
IN ULONG Flags
) PURE;
STDMETHOD(ReadTypedDataPhysical)(
THIS_
IN ULONG64 Offset,
IN ULONG64 Module,
IN ULONG TypeId,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WriteTypedDataPhysical)(
THIS_
IN ULONG64 Offset,
IN ULONG64 Module,
IN ULONG TypeId,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
STDMETHOD(OutputTypedDataPhysical)(
THIS_
IN ULONG OutputControl,
IN ULONG64 Offset,
IN ULONG64 Module,
IN ULONG TypeId,
IN ULONG Flags
) PURE;
// Function arguments and scope block symbols
// can be retrieved relative to currently
// executing code. A caller can provide just
// a code offset for scoping purposes and look
// up names or the caller can provide a full frame
// and look up actual values. The values for
// scoped symbols are best-guess and may or may not
// be accurate depending on program optimizations,
// the machine architecture, the current point
// in the programs execution and so on.
// A caller can also provide a complete register
// context for setting a scope to a previous
// machine state such as a context saved for
// an exception. Usually this isnt necessary
// and the current register context is used.
STDMETHOD(GetScope)(
THIS_
OUT OPTIONAL PULONG64 InstructionOffset,
OUT OPTIONAL PDEBUG_STACK_FRAME ScopeFrame,
OUT OPTIONAL PVOID ScopeContext,
IN ULONG ScopeContextSize
) PURE;
// If ScopeFrame or ScopeContext is non-NULL then
// InstructionOffset is ignored.
// If ScopeContext is NULL the current
// register context is used.
// If the scope identified by the given
// information is the same as before
// SetScope returns S_OK. If the scope
// information changes, such as when the
// scope moves between functions or scope
// blocks, SetScope returns S_FALSE.
STDMETHOD(SetScope)(
THIS_
IN ULONG64 InstructionOffset,
IN OPTIONAL PDEBUG_STACK_FRAME ScopeFrame,
IN OPTIONAL PVOID ScopeContext,
IN ULONG ScopeContextSize
) PURE;
// ResetScope clears the scope information
// for situations where scoped symbols
// mask global symbols or when resetting
// from explicit information to the current
// information.
STDMETHOD(ResetScope)(
THIS
) PURE;
// A scope symbol is tied to its particular
// scope and only is meaningful within the scope.
// The returned group can be updated by passing it back
// into the method for lower-cost
// incremental updates when stepping.
STDMETHOD(GetScopeSymbolGroup)(
THIS_
IN ULONG Flags,
IN OPTIONAL PDEBUG_SYMBOL_GROUP Update,
OUT PDEBUG_SYMBOL_GROUP* Symbols
) PURE;
// Create a new symbol group.
STDMETHOD(CreateSymbolGroup)(
THIS_
OUT PDEBUG_SYMBOL_GROUP* Group
) PURE;
// StartSymbolMatch matches symbol names
// against the given pattern using simple
// regular expressions. The search results
// are iterated through using GetNextSymbolMatch.
// When the caller is done examining results
// the match should be freed via EndSymbolMatch.
// If the match pattern contains a module name
// the search is restricted to a single module.
// Pattern matching is only done on symbol names,
// not module names.
// All active symbol match handles are invalidated
// when the set of loaded symbols changes.
STDMETHOD(StartSymbolMatch)(
THIS_
IN PCSTR Pattern,
OUT PULONG64 Handle
) PURE;
// If Buffer is NULL the match does not
// advance.
STDMETHOD(GetNextSymbolMatch)(
THIS_
IN ULONG64 Handle,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG MatchSize,
OUT OPTIONAL PULONG64 Offset
) PURE;
STDMETHOD(EndSymbolMatch)(
THIS_
IN ULONG64 Handle
) PURE;
STDMETHOD(Reload)(
THIS_
IN PCSTR Module
) PURE;
STDMETHOD(GetSymbolPath)(
THIS_
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG PathSize
) PURE;
STDMETHOD(SetSymbolPath)(
THIS_
IN PCSTR Path
) PURE;
STDMETHOD(AppendSymbolPath)(
THIS_
IN PCSTR Addition
) PURE;
// Manipulate the path for executable images.
// Some dump files need to load executable images
// in order to resolve dump information. This
// path controls where the engine looks for
// images.
STDMETHOD(GetImagePath)(
THIS_
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG PathSize
) PURE;
STDMETHOD(SetImagePath)(
THIS_
IN PCSTR Path
) PURE;
STDMETHOD(AppendImagePath)(
THIS_
IN PCSTR Addition
) PURE;
// Path routines for source file location
// methods.
STDMETHOD(GetSourcePath)(
THIS_
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG PathSize
) PURE;
// Gets the nth part of the source path.
STDMETHOD(GetSourcePathElement)(
THIS_
IN ULONG Index,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG ElementSize
) PURE;
STDMETHOD(SetSourcePath)(
THIS_
IN PCSTR Path
) PURE;
STDMETHOD(AppendSourcePath)(
THIS_
IN PCSTR Addition
) PURE;
// Uses the given file path and the source path
// information to try and locate an existing file.
// The given file path is merged with elements
// of the source path and checked for existence.
// If a match is found the element used is returned.
// A starting element can be specified to restrict
// the search to a subset of the path elements;
// this can be useful when checking for multiple
// matches along the source path.
// The returned element can be 1, indicating
// the file was found directly and not on the path.
STDMETHOD(FindSourceFile)(
THIS_
IN ULONG StartElement,
IN PCSTR File,
IN ULONG Flags,
OUT OPTIONAL PULONG FoundElement,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG FoundSize
) PURE;
// Retrieves all the line offset information
// for a particular source file. Buffer is
// first intialized to DEBUG_INVALID_OFFSET for
// every entry. Then for each piece of line
// symbol information Buffer[Line] set to
// Lines offset. This produces a per-line
// map of the offsets for the lines of the
// given file. Line numbers are decremented
// for the map so Buffer[0] contains the offset
// for line number 1.
// If there is no line information at all for
// the given file the method fails rather
// than returning a map of invalid offsets.
STDMETHOD(GetSourceFileLineOffsets)(
THIS_
IN PCSTR File,
OUT OPTIONAL /* size_is(BufferLines) */ PULONG64 Buffer,
IN ULONG BufferLines,
OUT OPTIONAL PULONG FileLines
) PURE;
};
//
// GetModuleNameString strings.
//
#define DEBUG_MODNAME_IMAGE 0x00000000
#define DEBUG_MODNAME_MODULE 0x00000001
#define DEBUG_MODNAME_LOADED_IMAGE 0x00000002
#define DEBUG_MODNAME_SYMBOL_FILE 0x00000003
#define DEBUG_MODNAME_MAPPED_IMAGE 0x00000004
//
// Type options, used with Get/SetTypeOptions.
//
// Display PUSHORT and USHORT arrays in UNICODE
#define DEBUG_TYPEOPTS_UNICODE_DISPLAY 0x00000001
#undef INTERFACE
#define INTERFACE IDebugSymbols2
DECLARE_INTERFACE_(IDebugSymbols2, IUnknown)
{
// IUnknown.
STDMETHOD(QueryInterface)(
THIS_
IN REFIID InterfaceId,
OUT PVOID* Interface
) PURE;
STDMETHOD_(ULONG, AddRef)(
THIS
) PURE;
STDMETHOD_(ULONG, Release)(
THIS
) PURE;
// IDebugSymbols.
// Controls the symbol options used during
// symbol operations.
// Uses the same flags as dbghelps SymSetOptions.
STDMETHOD(GetSymbolOptions)(
THIS_
OUT PULONG Options
) PURE;
STDMETHOD(AddSymbolOptions)(
THIS_
IN ULONG Options
) PURE;
STDMETHOD(RemoveSymbolOptions)(
THIS_
IN ULONG Options
) PURE;
STDMETHOD(SetSymbolOptions)(
THIS_
IN ULONG Options
) PURE;
STDMETHOD(GetNameByOffset)(
THIS_
IN ULONG64 Offset,
OUT OPTIONAL PSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize,
OUT OPTIONAL PULONG64 Displacement
) PURE;
// A symbol name may not be unique, particularly
// when overloaded functions exist which all
// have the same name. If GetOffsetByName
// finds multiple matches for the name it
// can return any one of them. In that
// case it will return S_FALSE to indicate
// that ambiguity was arbitrarily resolved.
// A caller can then use SearchSymbols to
// find all of the matches if it wishes to
// perform different disambiguation.
STDMETHOD(GetOffsetByName)(
THIS_
IN PCSTR Symbol,
OUT PULONG64 Offset
) PURE;
// GetNearNameByOffset returns symbols
// located near the symbol closest to
// to the offset, such as the previous
// or next symbol. If Delta is zero it
// operates identically to GetNameByOffset.
// If Delta is nonzero and such a symbol
// does not exist an error is returned.
// The next symbol, if one exists, will
// always have a higher offset than the
// input offset so the displacement is
// always negative. The situation is
// reversed for the previous symbol.
STDMETHOD(GetNearNameByOffset)(
THIS_
IN ULONG64 Offset,
IN LONG Delta,
OUT OPTIONAL PSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize,
OUT OPTIONAL PULONG64 Displacement
) PURE;
STDMETHOD(GetLineByOffset)(
THIS_
IN ULONG64 Offset,
OUT OPTIONAL PULONG Line,
OUT OPTIONAL PSTR FileBuffer,
IN ULONG FileBufferSize,
OUT OPTIONAL PULONG FileSize,
OUT OPTIONAL PULONG64 Displacement
) PURE;
STDMETHOD(GetOffsetByLine)(
THIS_
IN ULONG Line,
IN PCSTR File,
OUT PULONG64 Offset
) PURE;
// Enumerates the engines list of modules
// loaded for the current process. This may
// or may not match the system module list
// for the process. Reload can be used to
// synchronize the engines list with the system
// if necessary.
// Some sessions also track recently unloaded
// code modules for help in analyzing failures
// where an attempt is made to call unloaded code.
// These modules are indexed after the loaded
// modules.
STDMETHOD(GetNumberModules)(
THIS_
OUT PULONG Loaded,
OUT PULONG Unloaded
) PURE;
STDMETHOD(GetModuleByIndex)(
THIS_
IN ULONG Index,
OUT PULONG64 Base
) PURE;
// The module name may not be unique.
// This method returns the first match.
STDMETHOD(GetModuleByModuleName)(
THIS_
IN PCSTR Name,
IN ULONG StartIndex,
OUT OPTIONAL PULONG Index,
OUT OPTIONAL PULONG64 Base
) PURE;
// Offset can be any offset within
// the module extent. Extents may
// not be unique when including unloaded
// drivers. This method returns the
// first match.
STDMETHOD(GetModuleByOffset)(
THIS_
IN ULONG64 Offset,
IN ULONG StartIndex,
OUT OPTIONAL PULONG Index,
OUT OPTIONAL PULONG64 Base
) PURE;
// If Index is DEBUG_ANY_ID the base address
// is used to look up the module instead.
STDMETHOD(GetModuleNames)(
THIS_
IN ULONG Index,
IN ULONG64 Base,
OUT OPTIONAL PSTR ImageNameBuffer,
IN ULONG ImageNameBufferSize,
OUT OPTIONAL PULONG ImageNameSize,
OUT OPTIONAL PSTR ModuleNameBuffer,
IN ULONG ModuleNameBufferSize,
OUT OPTIONAL PULONG ModuleNameSize,
OUT OPTIONAL PSTR LoadedImageNameBuffer,
IN ULONG LoadedImageNameBufferSize,
OUT OPTIONAL PULONG LoadedImageNameSize
) PURE;
STDMETHOD(GetModuleParameters)(
THIS_
IN ULONG Count,
IN OPTIONAL /* size_is(Count) */ PULONG64 Bases,
IN ULONG Start,
OUT /* size_is(Count) */ PDEBUG_MODULE_PARAMETERS Params
) PURE;
// Looks up the module from a <Module>!<Symbol>
// string.
STDMETHOD(GetSymbolModule)(
THIS_
IN PCSTR Symbol,
OUT PULONG64 Base
) PURE;
// Returns the string name of a type.
STDMETHOD(GetTypeName)(
THIS_
IN ULONG64 Module,
IN ULONG TypeId,
OUT OPTIONAL PSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize
) PURE;
// Returns the ID for a type name.
STDMETHOD(GetTypeId)(
THIS_
IN ULONG64 Module,
IN PCSTR Name,
OUT PULONG TypeId
) PURE;
STDMETHOD(GetTypeSize)(
THIS_
IN ULONG64 Module,
IN ULONG TypeId,
OUT PULONG Size
) PURE;
// Given a type which can contain members
// this method returns the offset of a
// particular member within the type.
// TypeId should give the container type ID
// and Field gives the dot-separated path
// to the field of interest.
STDMETHOD(GetFieldOffset)(
THIS_
IN ULONG64 Module,
IN ULONG TypeId,
IN PCSTR Field,
OUT PULONG Offset
) PURE;
STDMETHOD(GetSymbolTypeId)(
THIS_
IN PCSTR Symbol,
OUT PULONG TypeId,
OUT OPTIONAL PULONG64 Module
) PURE;
// As with GetOffsetByName a symbol's
// name may be ambiguous. GetOffsetTypeId
// returns the type for the symbol closest
// to the given offset and can be used
// to avoid ambiguity.
STDMETHOD(GetOffsetTypeId)(
THIS_
IN ULONG64 Offset,
OUT PULONG TypeId,
OUT OPTIONAL PULONG64 Module
) PURE;
// Helpers for virtual and physical data
// which combine creation of a location with
// the actual operation.
STDMETHOD(ReadTypedDataVirtual)(
THIS_
IN ULONG64 Offset,
IN ULONG64 Module,
IN ULONG TypeId,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WriteTypedDataVirtual)(
THIS_
IN ULONG64 Offset,
IN ULONG64 Module,
IN ULONG TypeId,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
STDMETHOD(OutputTypedDataVirtual)(
THIS_
IN ULONG OutputControl,
IN ULONG64 Offset,
IN ULONG64 Module,
IN ULONG TypeId,
IN ULONG Flags
) PURE;
STDMETHOD(ReadTypedDataPhysical)(
THIS_
IN ULONG64 Offset,
IN ULONG64 Module,
IN ULONG TypeId,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
) PURE;
STDMETHOD(WriteTypedDataPhysical)(
THIS_
IN ULONG64 Offset,
IN ULONG64 Module,
IN ULONG TypeId,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
) PURE;
STDMETHOD(OutputTypedDataPhysical)(
THIS_
IN ULONG OutputControl,
IN ULONG64 Offset,
IN ULONG64 Module,
IN ULONG TypeId,
IN ULONG Flags
) PURE;
// Function arguments and scope block symbols
// can be retrieved relative to currently
// executing code. A caller can provide just
// a code offset for scoping purposes and look
// up names or the caller can provide a full frame
// and look up actual values. The values for
// scoped symbols are best-guess and may or may not
// be accurate depending on program optimizations,
// the machine architecture, the current point
// in the programs execution and so on.
// A caller can also provide a complete register
// context for setting a scope to a previous
// machine state such as a context saved for
// an exception. Usually this isnt necessary
// and the current register context is used.
STDMETHOD(GetScope)(
THIS_
OUT OPTIONAL PULONG64 InstructionOffset,
OUT OPTIONAL PDEBUG_STACK_FRAME ScopeFrame,
OUT OPTIONAL PVOID ScopeContext,
IN ULONG ScopeContextSize
) PURE;
// If ScopeFrame or ScopeContext is non-NULL then
// InstructionOffset is ignored.
// If ScopeContext is NULL the current
// register context is used.
// If the scope identified by the given
// information is the same as before
// SetScope returns S_OK. If the scope
// information changes, such as when the
// scope moves between functions or scope
// blocks, SetScope returns S_FALSE.
STDMETHOD(SetScope)(
THIS_
IN ULONG64 InstructionOffset,
IN OPTIONAL PDEBUG_STACK_FRAME ScopeFrame,
IN OPTIONAL PVOID ScopeContext,
IN ULONG ScopeContextSize
) PURE;
// ResetScope clears the scope information
// for situations where scoped symbols
// mask global symbols or when resetting
// from explicit information to the current
// information.
STDMETHOD(ResetScope)(
THIS
) PURE;
// A scope symbol is tied to its particular
// scope and only is meaningful within the scope.
// The returned group can be updated by passing it back
// into the method for lower-cost
// incremental updates when stepping.
STDMETHOD(GetScopeSymbolGroup)(
THIS_
IN ULONG Flags,
IN OPTIONAL PDEBUG_SYMBOL_GROUP Update,
OUT PDEBUG_SYMBOL_GROUP* Symbols
) PURE;
// Create a new symbol group.
STDMETHOD(CreateSymbolGroup)(
THIS_
OUT PDEBUG_SYMBOL_GROUP* Group
) PURE;
// StartSymbolMatch matches symbol names
// against the given pattern using simple
// regular expressions. The search results
// are iterated through using GetNextSymbolMatch.
// When the caller is done examining results
// the match should be freed via EndSymbolMatch.
// If the match pattern contains a module name
// the search is restricted to a single module.
// Pattern matching is only done on symbol names,
// not module names.
// All active symbol match handles are invalidated
// when the set of loaded symbols changes.
STDMETHOD(StartSymbolMatch)(
THIS_
IN PCSTR Pattern,
OUT PULONG64 Handle
) PURE;
// If Buffer is NULL the match does not
// advance.
STDMETHOD(GetNextSymbolMatch)(
THIS_
IN ULONG64 Handle,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG MatchSize,
OUT OPTIONAL PULONG64 Offset
) PURE;
STDMETHOD(EndSymbolMatch)(
THIS_
IN ULONG64 Handle
) PURE;
STDMETHOD(Reload)(
THIS_
IN PCSTR Module
) PURE;
STDMETHOD(GetSymbolPath)(
THIS_
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG PathSize
) PURE;
STDMETHOD(SetSymbolPath)(
THIS_
IN PCSTR Path
) PURE;
STDMETHOD(AppendSymbolPath)(
THIS_
IN PCSTR Addition
) PURE;
// Manipulate the path for executable images.
// Some dump files need to load executable images
// in order to resolve dump information. This
// path controls where the engine looks for
// images.
STDMETHOD(GetImagePath)(
THIS_
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG PathSize
) PURE;
STDMETHOD(SetImagePath)(
THIS_
IN PCSTR Path
) PURE;
STDMETHOD(AppendImagePath)(
THIS_
IN PCSTR Addition
) PURE;
// Path routines for source file location
// methods.
STDMETHOD(GetSourcePath)(
THIS_
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG PathSize
) PURE;
// Gets the nth part of the source path.
STDMETHOD(GetSourcePathElement)(
THIS_
IN ULONG Index,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG ElementSize
) PURE;
STDMETHOD(SetSourcePath)(
THIS_
IN PCSTR Path
) PURE;
STDMETHOD(AppendSourcePath)(
THIS_
IN PCSTR Addition
) PURE;
// Uses the given file path and the source path
// information to try and locate an existing file.
// The given file path is merged with elements
// of the source path and checked for existence.
// If a match is found the element used is returned.
// A starting element can be specified to restrict
// the search to a subset of the path elements;
// this can be useful when checking for multiple
// matches along the source path.
// The returned element can be 1, indicating
// the file was found directly and not on the path.
STDMETHOD(FindSourceFile)(
THIS_
IN ULONG StartElement,
IN PCSTR File,
IN ULONG Flags,
OUT OPTIONAL PULONG FoundElement,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG FoundSize
) PURE;
// Retrieves all the line offset information
// for a particular source file. Buffer is
// first intialized to DEBUG_INVALID_OFFSET for
// every entry. Then for each piece of line
// symbol information Buffer[Line] set to
// Lines offset. This produces a per-line
// map of the offsets for the lines of the
// given file. Line numbers are decremented
// for the map so Buffer[0] contains the offset
// for line number 1.
// If there is no line information at all for
// the given file the method fails rather
// than returning a map of invalid offsets.
STDMETHOD(GetSourceFileLineOffsets)(
THIS_
IN PCSTR File,
OUT OPTIONAL /* size_is(BufferLines) */ PULONG64 Buffer,
IN ULONG BufferLines,
OUT OPTIONAL PULONG FileLines
) PURE;
// IDebugSymbols2.
// If Index is DEBUG_ANY_ID the base address
// is used to look up the module instead.
// Item is specified as in VerQueryValue.
// Module version information is only
// available for loaded modules and may
// not be available in all debug sessions.
STDMETHOD(GetModuleVersionInformation)(
THIS_
IN ULONG Index,
IN ULONG64 Base,
IN PCSTR Item,
OUT OPTIONAL PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG VerInfoSize
) PURE;
// Retrieves any available module name string
// such as module name or symbol file name.
// If Index is DEBUG_ANY_ID the base address
// is used to look up the module instead.
// If symbols are deferred an error will
// be returned.
// E_NOINTERFACE may be returned, indicating
// no information exists.
STDMETHOD(GetModuleNameString)(
THIS_
IN ULONG Which,
IN ULONG Index,
IN ULONG64 Base,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG NameSize
) PURE;
// Returns the string name of a constant type.
STDMETHOD(GetConstantName)(
THIS_
IN ULONG64 Module,
IN ULONG TypeId,
IN ULONG64 Value,
OUT OPTIONAL PSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize
) PURE;
// Gets name of a field in a struct
// FieldNumber is 0 based index of field in a struct
// Method fails with E_INVALIDARG if FieldNumber is
// too high for the struct fields
STDMETHOD(GetFieldName)(
THIS_
IN ULONG64 Module,
IN ULONG TypeId,
IN ULONG FieldIndex,
OUT OPTIONAL PSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize
) PURE;
// Control options for typed values.
STDMETHOD(GetTypeOptions)(
THIS_
OUT PULONG Options
) PURE;
STDMETHOD(AddTypeOptions)(
THIS_
IN ULONG Options
) PURE;
STDMETHOD(RemoveTypeOptions)(
THIS_
IN ULONG Options
) PURE;
STDMETHOD(SetTypeOptions)(
THIS_
IN ULONG Options
) PURE;
};
//----------------------------------------------------------------------------
//
// IDebugSystemObjects
//
//----------------------------------------------------------------------------
#undef INTERFACE
#define INTERFACE IDebugSystemObjects
DECLARE_INTERFACE_(IDebugSystemObjects, IUnknown)
{
// IUnknown.
STDMETHOD(QueryInterface)(
THIS_
IN REFIID InterfaceId,
OUT PVOID* Interface
) PURE;
STDMETHOD_(ULONG, AddRef)(
THIS
) PURE;
STDMETHOD_(ULONG, Release)(
THIS
) PURE;
// IDebugSystemObjects.
// In user mode debugging the debugger
// tracks all threads and processes and
// enumerates them through the following
// methods. When enumerating threads
// the threads are enumerated for the current
// process.
// Kernel mode debugging currently is
// limited to enumerating only the threads
// assigned to processors, not all of
// the threads in the system. Process
// enumeration is limited to a single
// virtual process representing kernel space.
// Returns the ID of the thread on which
// the last event occurred.
STDMETHOD(GetEventThread)(
THIS_
OUT PULONG Id
) PURE;
STDMETHOD(GetEventProcess)(
THIS_
OUT PULONG Id
) PURE;
// Controls implicit thread used by the
// debug engine. The debuggers current
// thread is just a piece of data held
// by the debugger for calls which use
// thread-specific information. In those
// calls the debuggers current thread is used.
// The debuggers current thread is not related
// to any system thread attribute.
// IDs for threads are small integer IDs
// maintained by the engine. They are not
// related to system thread IDs.
STDMETHOD(GetCurrentThreadId)(
THIS_
OUT PULONG Id
) PURE;
STDMETHOD(SetCurrentThreadId)(
THIS_
IN ULONG Id
) PURE;
// The current process is the process
// that owns the current thread.
STDMETHOD(GetCurrentProcessId)(
THIS_
OUT PULONG Id
) PURE;
// Setting the current process automatically
// sets the current thread to the thread that
// was last current in that process.
STDMETHOD(SetCurrentProcessId)(
THIS_
IN ULONG Id
) PURE;
// Gets the number of threads in the current process.
STDMETHOD(GetNumberThreads)(
THIS_
OUT PULONG Number
) PURE;
// Gets thread count information for all processes
// and the largest number of threads in a single process.
STDMETHOD(GetTotalNumberThreads)(
THIS_
OUT PULONG Total,
OUT PULONG LargestProcess
) PURE;
STDMETHOD(GetThreadIdsByIndex)(
THIS_
IN ULONG Start,
IN ULONG Count,
OUT OPTIONAL /* size_is(Count) */ PULONG Ids,
OUT OPTIONAL /* size_is(Count) */ PULONG SysIds
) PURE;
// Gets the debugger ID for the thread
// currently running on the given
// processor. Only works in kernel
// debugging.
STDMETHOD(GetThreadIdByProcessor)(
THIS_
IN ULONG Processor,
OUT PULONG Id
) PURE;
// Returns the offset of the current threads
// system data structure. When kernel debugging
// this is the offset of the KTHREAD.
// When user debugging it is the offset
// of the current TEB.
STDMETHOD(GetCurrentThreadDataOffset)(
THIS_
OUT PULONG64 Offset
) PURE;
// Looks up a debugger thread ID for the given
// system thread data structure.
// Currently when kernel debugging this will fail
// if the thread is not executing on a processor.
STDMETHOD(GetThreadIdByDataOffset)(
THIS_
IN ULONG64 Offset,
OUT PULONG Id
) PURE;
// Returns the offset of the current threads
// TEB. In user mode this is equivalent to
// the threads data offset.
STDMETHOD(GetCurrentThreadTeb)(
THIS_
OUT PULONG64 Offset
) PURE;
// Looks up a debugger thread ID for the given TEB.
// Currently when kernel debugging this will fail
// if the thread is not executing on a processor.
STDMETHOD(GetThreadIdByTeb)(
THIS_
IN ULONG64 Offset,
OUT PULONG Id
) PURE;
// Returns the system unique ID for the current thread.
// Not currently supported when kernel debugging.
STDMETHOD(GetCurrentThreadSystemId)(
THIS_
OUT PULONG SysId
) PURE;
// Looks up a debugger thread ID for the given
// system thread ID.
// Currently when kernel debugging this will fail
// if the thread is not executing on a processor.
STDMETHOD(GetThreadIdBySystemId)(
THIS_
IN ULONG SysId,
OUT PULONG Id
) PURE;
// Returns the handle of the current thread.
// In kernel mode the value returned is the
// index of the processor the thread is
// executing on plus one.
STDMETHOD(GetCurrentThreadHandle)(
THIS_
OUT PULONG64 Handle
) PURE;
// Looks up a debugger thread ID for the given handle.
// Currently when kernel debugging this will fail
// if the thread is not executing on a processor.
STDMETHOD(GetThreadIdByHandle)(
THIS_
IN ULONG64 Handle,
OUT PULONG Id
) PURE;
// Currently kernel mode sessions will only have
// a single process representing kernel space.
STDMETHOD(GetNumberProcesses)(
THIS_
OUT PULONG Number
) PURE;
STDMETHOD(GetProcessIdsByIndex)(
THIS_
IN ULONG Start,
IN ULONG Count,
OUT OPTIONAL /* size_is(Count) */ PULONG Ids,
OUT OPTIONAL /* size_is(Count) */ PULONG SysIds
) PURE;
// Returns the offset of the current processs
// system data structure. When kernel debugging
// this is the offset of the KPROCESS of
// the process that owns the current thread.
// When user debugging it is the offset
// of the current PEB.
STDMETHOD(GetCurrentProcessDataOffset)(
THIS_
OUT PULONG64 Offset
) PURE;
// Looks up a debugger process ID for the given
// system process data structure.
// Not currently supported when kernel debugging.
STDMETHOD(GetProcessIdByDataOffset)(
THIS_
IN ULONG64 Offset,
OUT PULONG Id
) PURE;
// Returns the offset of the current processs
// PEB. In user mode this is equivalent to
// the processs data offset.
STDMETHOD(GetCurrentProcessPeb)(
THIS_
OUT PULONG64 Offset
) PURE;
// Looks up a debugger process ID for the given PEB.
// Not currently supported when kernel debugging.
STDMETHOD(GetProcessIdByPeb)(
THIS_
IN ULONG64 Offset,
OUT PULONG Id
) PURE;
// Returns the system unique ID for the current process.
// Not currently supported when kernel debugging.
STDMETHOD(GetCurrentProcessSystemId)(
THIS_
OUT PULONG SysId
) PURE;
// Looks up a debugger process ID for the given
// system process ID.
// Not currently supported when kernel debugging.
STDMETHOD(GetProcessIdBySystemId)(
THIS_
IN ULONG SysId,
OUT PULONG Id
) PURE;
// Returns the handle of the current process.
// In kernel mode this is the kernel processs
// artificial handle used for symbol operations
// and so can only be used with dbghelp APIs.
STDMETHOD(GetCurrentProcessHandle)(
THIS_
OUT PULONG64 Handle
) PURE;
// Looks up a debugger process ID for the given handle.
STDMETHOD(GetProcessIdByHandle)(
THIS_
IN ULONG64 Handle,
OUT PULONG Id
) PURE;
// Retrieve the name of the executable loaded
// in the process. This may fail if no executable
// was identified.
STDMETHOD(GetCurrentProcessExecutableName)(
THIS_
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG ExeSize
) PURE;
};
#undef INTERFACE
#define INTERFACE IDebugSystemObjects2
DECLARE_INTERFACE_(IDebugSystemObjects2, IUnknown)
{
// IUnknown.
STDMETHOD(QueryInterface)(
THIS_
IN REFIID InterfaceId,
OUT PVOID* Interface
) PURE;
STDMETHOD_(ULONG, AddRef)(
THIS
) PURE;
STDMETHOD_(ULONG, Release)(
THIS
) PURE;
// IDebugSystemObjects.
// In user mode debugging the debugger
// tracks all threads and processes and
// enumerates them through the following
// methods. When enumerating threads
// the threads are enumerated for the current
// process.
// Kernel mode debugging currently is
// limited to enumerating only the threads
// assigned to processors, not all of
// the threads in the system. Process
// enumeration is limited to a single
// virtual process representing kernel space.
// Returns the ID of the thread on which
// the last event occurred.
STDMETHOD(GetEventThread)(
THIS_
OUT PULONG Id
) PURE;
STDMETHOD(GetEventProcess)(
THIS_
OUT PULONG Id
) PURE;
// Controls implicit thread used by the
// debug engine. The debuggers current
// thread is just a piece of data held
// by the debugger for calls which use
// thread-specific information. In those
// calls the debuggers current thread is used.
// The debuggers current thread is not related
// to any system thread attribute.
// IDs for threads are small integer IDs
// maintained by the engine. They are not
// related to system thread IDs.
STDMETHOD(GetCurrentThreadId)(
THIS_
OUT PULONG Id
) PURE;
STDMETHOD(SetCurrentThreadId)(
THIS_
IN ULONG Id
) PURE;
// The current process is the process
// that owns the current thread.
STDMETHOD(GetCurrentProcessId)(
THIS_
OUT PULONG Id
) PURE;
// Setting the current process automatically
// sets the current thread to the thread that
// was last current in that process.
STDMETHOD(SetCurrentProcessId)(
THIS_
IN ULONG Id
) PURE;
// Gets the number of threads in the current process.
STDMETHOD(GetNumberThreads)(
THIS_
OUT PULONG Number
) PURE;
// Gets thread count information for all processes
// and the largest number of threads in a single process.
STDMETHOD(GetTotalNumberThreads)(
THIS_
OUT PULONG Total,
OUT PULONG LargestProcess
) PURE;
STDMETHOD(GetThreadIdsByIndex)(
THIS_
IN ULONG Start,
IN ULONG Count,
OUT OPTIONAL /* size_is(Count) */ PULONG Ids,
OUT OPTIONAL /* size_is(Count) */ PULONG SysIds
) PURE;
// Gets the debugger ID for the thread
// currently running on the given
// processor. Only works in kernel
// debugging.
STDMETHOD(GetThreadIdByProcessor)(
THIS_
IN ULONG Processor,
OUT PULONG Id
) PURE;
// Returns the offset of the current threads
// system data structure. When kernel debugging
// this is the offset of the KTHREAD.
// When user debugging it is the offset
// of the current TEB.
STDMETHOD(GetCurrentThreadDataOffset)(
THIS_
OUT PULONG64 Offset
) PURE;
// Looks up a debugger thread ID for the given
// system thread data structure.
// Currently when kernel debugging this will fail
// if the thread is not executing on a processor.
STDMETHOD(GetThreadIdByDataOffset)(
THIS_
IN ULONG64 Offset,
OUT PULONG Id
) PURE;
// Returns the offset of the current threads
// TEB. In user mode this is equivalent to
// the threads data offset.
STDMETHOD(GetCurrentThreadTeb)(
THIS_
OUT PULONG64 Offset
) PURE;
// Looks up a debugger thread ID for the given TEB.
// Currently when kernel debugging this will fail
// if the thread is not executing on a processor.
STDMETHOD(GetThreadIdByTeb)(
THIS_
IN ULONG64 Offset,
OUT PULONG Id
) PURE;
// Returns the system unique ID for the current thread.
// Not currently supported when kernel debugging.
STDMETHOD(GetCurrentThreadSystemId)(
THIS_
OUT PULONG SysId
) PURE;
// Looks up a debugger thread ID for the given
// system thread ID.
// Currently when kernel debugging this will fail
// if the thread is not executing on a processor.
STDMETHOD(GetThreadIdBySystemId)(
THIS_
IN ULONG SysId,
OUT PULONG Id
) PURE;
// Returns the handle of the current thread.
// In kernel mode the value returned is the
// index of the processor the thread is
// executing on plus one.
STDMETHOD(GetCurrentThreadHandle)(
THIS_
OUT PULONG64 Handle
) PURE;
// Looks up a debugger thread ID for the given handle.
// Currently when kernel debugging this will fail
// if the thread is not executing on a processor.
STDMETHOD(GetThreadIdByHandle)(
THIS_
IN ULONG64 Handle,
OUT PULONG Id
) PURE;
// Currently kernel mode sessions will only have
// a single process representing kernel space.
STDMETHOD(GetNumberProcesses)(
THIS_
OUT PULONG Number
) PURE;
STDMETHOD(GetProcessIdsByIndex)(
THIS_
IN ULONG Start,
IN ULONG Count,
OUT OPTIONAL /* size_is(Count) */ PULONG Ids,
OUT OPTIONAL /* size_is(Count) */ PULONG SysIds
) PURE;
// Returns the offset of the current processs
// system data structure. When kernel debugging
// this is the offset of the KPROCESS of
// the process that owns the current thread.
// When user debugging it is the offset
// of the current PEB.
STDMETHOD(GetCurrentProcessDataOffset)(
THIS_
OUT PULONG64 Offset
) PURE;
// Looks up a debugger process ID for the given
// system process data structure.
// Not currently supported when kernel debugging.
STDMETHOD(GetProcessIdByDataOffset)(
THIS_
IN ULONG64 Offset,
OUT PULONG Id
) PURE;
// Returns the offset of the current processs
// PEB. In user mode this is equivalent to
// the processs data offset.
STDMETHOD(GetCurrentProcessPeb)(
THIS_
OUT PULONG64 Offset
) PURE;
// Looks up a debugger process ID for the given PEB.
// Not currently supported when kernel debugging.
STDMETHOD(GetProcessIdByPeb)(
THIS_
IN ULONG64 Offset,
OUT PULONG Id
) PURE;
// Returns the system unique ID for the current process.
// Not currently supported when kernel debugging.
STDMETHOD(GetCurrentProcessSystemId)(
THIS_
OUT PULONG SysId
) PURE;
// Looks up a debugger process ID for the given
// system process ID.
// Not currently supported when kernel debugging.
STDMETHOD(GetProcessIdBySystemId)(
THIS_
IN ULONG SysId,
OUT PULONG Id
) PURE;
// Returns the handle of the current process.
// In kernel mode this is the kernel processs
// artificial handle used for symbol operations
// and so can only be used with dbghelp APIs.
STDMETHOD(GetCurrentProcessHandle)(
THIS_
OUT PULONG64 Handle
) PURE;
// Looks up a debugger process ID for the given handle.
STDMETHOD(GetProcessIdByHandle)(
THIS_
IN ULONG64 Handle,
OUT PULONG Id
) PURE;
// Retrieve the name of the executable loaded
// in the process. This may fail if no executable
// was identified.
STDMETHOD(GetCurrentProcessExecutableName)(
THIS_
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG ExeSize
) PURE;
// IDebugSystemObjects2.
// Return the number of seconds that the current
// process has been running.
STDMETHOD(GetCurrentProcessUpTime)(
THIS_
OUT PULONG UpTime
) PURE;
// During kernel sessions the debugger retrieves
// some information from the system thread and process
// running on the current processor. For example,
// the debugger will retrieve virtual memory translation
// information for when the debugger needs to
// carry out its own virtual to physical translations.
// Occasionally it can be interesting to perform
// similar operations but on a process which isnt
// currently running. The follow methods allow a caller
// to override the data offsets used by the debugger
// so that other system threads and processes can
// be used instead. These values are defaulted to
// the thread and process running on the current
// processor each time the debuggee executes or
// the current processor changes.
// The thread and process settings are independent so
// it is possible to refer to a thread in a process
// other than the current process and vice versa.
// Setting an offset of zero will reload the
// default value.
STDMETHOD(GetImplicitThreadDataOffset)(
THIS_
OUT PULONG64 Offset
) PURE;
STDMETHOD(SetImplicitThreadDataOffset)(
THIS_
IN ULONG64 Offset
) PURE;
STDMETHOD(GetImplicitProcessDataOffset)(
THIS_
OUT PULONG64 Offset
) PURE;
STDMETHOD(SetImplicitProcessDataOffset)(
THIS_
IN ULONG64 Offset
) PURE;
};
//----------------------------------------------------------------------------
//
// Extension callbacks.
//
//----------------------------------------------------------------------------
// Returns a version with the major version in
// the high word and the minor version in the low word.
#define DEBUG_EXTENSION_VERSION(Major, Minor)
((((Major) & 0xffff) << 16) | ((Minor) & 0xffff))
// Initialization routine. Called once when the extension DLL
// is loaded. Returns a version and returns flags detailing
// overall qualities of the extension DLL.
// A session may or may not be active at the time the DLL
// is loaded so initialization routines should not expect
// to be able to query session information.
typedef HRESULT (CALLBACK* PDEBUG_EXTENSION_INITIALIZE)
(OUT PULONG Version, OUT PULONG Flags);
// Exit routine. Called once just before the extension DLL is
// unloaded. As with initialization, a session may or
// may not be active at the time of the call.
typedef void (CALLBACK* PDEBUG_EXTENSION_UNINITIALIZE)
(void);
// A debuggee has been discovered for the session. It
// is not necessarily halted.
#define DEBUG_NOTIFY_SESSION_ACTIVE 0x00000000
// The session no longer has a debuggee.
#define DEBUG_NOTIFY_SESSION_INACTIVE 0x00000001
// The debuggee is halted and accessible.
#define DEBUG_NOTIFY_SESSION_ACCESSIBLE 0x00000002
// The debuggee is running or inaccessible.
#define DEBUG_NOTIFY_SESSION_INACCESSIBLE 0x00000003
typedef void (CALLBACK* PDEBUG_EXTENSION_NOTIFY)
(IN ULONG Notify, IN ULONG64 Argument);
// A PDEBUG_EXTENSION_CALL function can return this code
// to indicate that it was unable to handle the request
// and that the search for an extension function should
// continue down the extension DLL chain.
// Taken from STATUS_VALIDATE_CONTINUE
#define DEBUG_EXTENSION_CONTINUE_SEARCH
HRESULT_FROM_NT(0xC0000271L)
// Every routine in an extension DLL has the following prototype.
// The extension may be called from multiple clients so it
// should not cache the client value between calls.
typedef HRESULT (CALLBACK* PDEBUG_EXTENSION_CALL)
(IN PDEBUG_CLIENT Client, IN OPTIONAL PCSTR Args);
//----------------------------------------------------------------------------
//
// Extension functions.
//
// Extension functions differ from extension callbacks in that
// they are arbitrary functions exported from an extension DLL
// for other code callers instead of for human invocation from
// debugger commands. Extension function pointers are retrieved
// for an extension DLL with IDebugControl::GetExtensionFunction.
//
// Extension function names must begin with _EFN_. Other than that
// they can have any name and prototype. Extension functions
// must be public exports of their extension DLL. They should
// have a typedef for their function pointer prototype in an
// extension header so that callers have a header file to include
// with a type that allows a correctly-formed invocation of the
// extension function.
//
// The engine does not perform any validation of calls to
// extension functions. Once the extension function pointer
// is retrieved with GetExtensionFunction all calls go
// directly between the caller and the extension function and
// are not mediated by the engine.
//
//----------------------------------------------------------------------------
#ifdef __cplusplus
};
//----------------------------------------------------------------------------
//
// C++ implementation helper classes.
//
//----------------------------------------------------------------------------
#ifndef DEBUG_NO_IMPLEMENTATION
//
// DebugBaseEventCallbacks provides a do-nothing base implementation
// of IDebugEventCallbacks. A program can derive their own
// event callbacks class from DebugBaseEventCallbacks and implement
// only the methods they are interested in. Programs must be
// careful to implement GetInterestMask appropriately.
//
class DebugBaseEventCallbacks : public IDebugEventCallbacks
{
public:
// IUnknown.
STDMETHOD(QueryInterface)(
THIS_
IN REFIID InterfaceId,
OUT PVOID* Interface
)
{
*Interface = NULL;
#if _MSC_VER >= 1100
if (IsEqualIID(InterfaceId, __uuidof(IUnknown)) ||
IsEqualIID(InterfaceId, __uuidof(IDebugEventCallbacks)))
#else
if (IsEqualIID(InterfaceId, IID_IUnknown) ||
IsEqualIID(InterfaceId, IID_IDebugEventCallbacks))
#endif
{
*Interface = (IDebugEventCallbacks *)this;
AddRef();
return S_OK;
}
else
{
return E_NOINTERFACE;
}
}
// IDebugEventCallbacks.
STDMETHOD(Breakpoint)(
THIS_
IN PDEBUG_BREAKPOINT Bp
)
{
UNREFERENCED_PARAMETER(Bp);
return DEBUG_STATUS_NO_CHANGE;
}
STDMETHOD(Exception)(
THIS_
IN PEXCEPTION_RECORD64 Exception,
IN ULONG FirstChance
)
{
UNREFERENCED_PARAMETER(Exception);
UNREFERENCED_PARAMETER(FirstChance);
return DEBUG_STATUS_NO_CHANGE;
}
STDMETHOD(CreateThread)(
THIS_
IN ULONG64 Handle,
IN ULONG64 DataOffset,
IN ULONG64 StartOffset
)
{
UNREFERENCED_PARAMETER(Handle);
UNREFERENCED_PARAMETER(DataOffset);
UNREFERENCED_PARAMETER(StartOffset);
return DEBUG_STATUS_NO_CHANGE;
}
STDMETHOD(ExitThread)(
THIS_
IN ULONG ExitCode
)
{
UNREFERENCED_PARAMETER(ExitCode);
return DEBUG_STATUS_NO_CHANGE;
}
STDMETHOD(CreateProcess)(
THIS_
IN ULONG64 ImageFileHandle,
IN ULONG64 Handle,
IN ULONG64 BaseOffset,
IN ULONG ModuleSize,
IN PCSTR ModuleName,
IN PCSTR ImageName,
IN ULONG CheckSum,
IN ULONG TimeDateStamp,
IN ULONG64 InitialThreadHandle,
IN ULONG64 ThreadDataOffset,
IN ULONG64 StartOffset
)
{
UNREFERENCED_PARAMETER(ImageFileHandle);
UNREFERENCED_PARAMETER(Handle);
UNREFERENCED_PARAMETER(BaseOffset);
UNREFERENCED_PARAMETER(ModuleSize);
UNREFERENCED_PARAMETER(ModuleName);
UNREFERENCED_PARAMETER(ImageName);
UNREFERENCED_PARAMETER(CheckSum);
UNREFERENCED_PARAMETER(TimeDateStamp);
UNREFERENCED_PARAMETER(InitialThreadHandle);
UNREFERENCED_PARAMETER(ThreadDataOffset);
UNREFERENCED_PARAMETER(StartOffset);
return DEBUG_STATUS_NO_CHANGE;
}
STDMETHOD(ExitProcess)(
THIS_
IN ULONG ExitCode
)
{
UNREFERENCED_PARAMETER(ExitCode);
return DEBUG_STATUS_NO_CHANGE;
}
STDMETHOD(LoadModule)(
THIS_
IN ULONG64 ImageFileHandle,
IN ULONG64 BaseOffset,
IN ULONG ModuleSize,
IN PCSTR ModuleName,
IN PCSTR ImageName,
IN ULONG CheckSum,
IN ULONG TimeDateStamp
)
{
UNREFERENCED_PARAMETER(ImageFileHandle);
UNREFERENCED_PARAMETER(BaseOffset);
UNREFERENCED_PARAMETER(ModuleSize);
UNREFERENCED_PARAMETER(ModuleName);
UNREFERENCED_PARAMETER(ImageName);
UNREFERENCED_PARAMETER(CheckSum);
UNREFERENCED_PARAMETER(TimeDateStamp);
return DEBUG_STATUS_NO_CHANGE;
}
STDMETHOD(UnloadModule)(
THIS_
IN PCSTR ImageBaseName,
IN ULONG64 BaseOffset
)
{
UNREFERENCED_PARAMETER(ImageBaseName);
UNREFERENCED_PARAMETER(BaseOffset);
return DEBUG_STATUS_NO_CHANGE;
}
STDMETHOD(SystemError)(
THIS_
IN ULONG Error,
IN ULONG Level
)
{
UNREFERENCED_PARAMETER(Error);
UNREFERENCED_PARAMETER(Level);
return DEBUG_STATUS_NO_CHANGE;
}
STDMETHOD(SessionStatus)(
THIS_
IN ULONG Status
)
{
UNREFERENCED_PARAMETER(Status);
return DEBUG_STATUS_NO_CHANGE;
}
STDMETHOD(ChangeDebuggeeState)(
THIS_
IN ULONG Flags,
IN ULONG64 Argument
)
{
UNREFERENCED_PARAMETER(Flags);
UNREFERENCED_PARAMETER(Argument);
return S_OK;
}
STDMETHOD(ChangeEngineState)(
THIS_
IN ULONG Flags,
IN ULONG64 Argument
)
{
UNREFERENCED_PARAMETER(Flags);
UNREFERENCED_PARAMETER(Argument);
return S_OK;
}
STDMETHOD(ChangeSymbolState)(
THIS_
IN ULONG Flags,
IN ULONG64 Argument
)
{
UNREFERENCED_PARAMETER(Flags);
UNREFERENCED_PARAMETER(Argument);
return S_OK;
}
};
#endif // #ifndef DEBUG_NO_IMPLEMENTATION
#endif // #ifdef __cplusplus
#endif // #ifndef __DBGENG_H__