序號(hào)

函數(shù)名稱

ImageHlp.DLL

DbgHelp.DLL

1

Bindlmage

N/A

2

BindlmageEx

N/A

3

CheckSumMappedFile

N/A

4

EnumerateLoadedModules

5

EnumerateLoadedModules64

6

ExtensionApiVersion

N/A

7

FindDebuglnfoFile

8

FindDebuglnfoFileEx

9

FindExecutablelmage

10

FindExecutablelmageEx

11

FindFilelnSearchPath

12

GetlmageConfiglnformation

N/A

13

GetlmageUnusedHeaderBytes

N/A

14

GetTimestampForLoadedLibrary

15

ImageAddCertificate

N/A

16

ImageDirectoryEntryToData

17

ImageDirectoryEntryToDataEx

18

ImageEnumerateCertificates

N/A

19

ImageGetCertificateData

N/A

20

ImageGetCertificateHeader

N/A

21

ImageGetDigestStream

N/A

22

ImagehlpApiVersion

23

ImagehlpApiVersionEx

24

ImageLoad

N/A

25

ImageNtHeader

26

ImageRemoveCertificate

N/A

27

ImageRvaToSection

28

ImageRvaToVa

29

ImageUnload

N/A

30

MakeSureDirectoryPathExists

31

MapAndLoad

N/A

32

MapDebuglnformation

33

MapFileAndCheckSumA

N/A

34

MapFileAndCheckSumW

N/A

35

ReBaselmage

N/A

36

ReBaseImage64

N/A

37

RemovePrivateCvSymbolic

N/A

38

RemovePrivateCvSymbolicEx

N/A

39

RemoveRelocations

N/A

40

SearchTreeForFile

41

SetlmageConfiglnformation

N/A

42

SplitSymbols

N/A

43

StackWalk

44

StackWalk64

45

Sym

N/A

46

SymCleanup

47

SymEnumerateModules

48

SymEnumerateModules64

49

SymEnumerateSymbols

50

SymEnumerateSymbols64

51

SymEnumerateSymbolsW

52

SymFunctionTableAccess

53

SymFunctionTa ble Access64

54

SymGetLineFromAddr

55

SymGetLineFromAddr64

56

SymGetLineFromName

57

SymGetLineFromName64

58

SymGetLineNext

59

SymGetLineNext64

60

SymGetLinePrev

61

SymGetLinePrev64

62

SymGetModuleBase

63

SymGetModuleBase64

64

SymGetModulelnfo

65

SymGetModuleInfo64

66

SymGetModulelnfo Ex

67

SymGetModulelnfo Ex64

68

SymGetModulelnfoW

69

SymGetModulelnfo W64

70

SymGetOptions

71

SymGetSearchPath

72

SymGetSymbolInfo

73

SymGetSymbolInfo64

74

SymGetSymFromAddr

75

SymGetSymFromAddr64

76

SymGetSymFromName

77

SymGetSymFromName64

78

SymGetSymNext

79

SymGetSymNext64

80

SymGetSymPrev

81

SymGetSymPrev64

82

Symlnitialize

83

SymLoadModule

84

SymLoadModule64

85

SymMatchFileName

86

SymEnumerateSymbolsW64

87

SymRegisterCallback

88

SymRegisterCallback64

89

SymRegisterFunctionEntryCallback

90

SymRegisterFunctionEntryCallback64

91

SymSetOptions

92

SymSetSearchPath

93

SymUnDName

94

SymUnDName64

95

SymUnloadModule

96

SymUnloadModule64

97

TouchFileTimes

N/A

98

UnDecorateSymbolName

99

UnMapAndLoad

N/A

100

UnmapDebuglnformation

101

UpdateDebuglnfoFile

N/A

102

UpdateDebuglnfoFileEx

N/A

103

WinDbgExtensionDllInit

N/A

在本節(jié)的示例代碼中，我會(huì)演示如何使用psapi.dll和imagehlp.dll完成如下任務(wù)：

l 枚舉所有內(nèi)核組件和驅(qū)動(dòng)程序

l 枚舉系統(tǒng)當(dāng)前管理的所有進(jìn)程

l 枚舉加載到進(jìn)程地址空間的所有模塊（modules）

l 枚舉一個(gè)給定組件的所有符號(hào)（如果其符號(hào)文件可用的話）

psapi.dll的接口并不像其設(shè)計(jì)的那樣好。它提供了最小的功能集，盡管它曾試圖增加一些便利性。雖然，它能從內(nèi)核獲取一些信息但卻扔掉了其中的大多數(shù)，只留下很少一部分。

由于psapi.dll和imagehlp.dll的函數(shù)并不是標(biāo)準(zhǔn)Win32 API的一部分，它們所需的頭文件和導(dǎo)入庫(kù)不會(huì)自動(dòng)包括在Visual C/C++工程中。因此，列表1-2中列出的四個(gè)指示符（directives）應(yīng)該在你的原文件中出現(xiàn)。第一部分是所需的頭文件，剩余部分用于和這兩個(gè)DLL中的導(dǎo)出函數(shù)建立動(dòng)態(tài)鏈接。

#include <imagehlp.h>

#include <psapi.h>

#pragma comment (linker,”/defaultlib:imagehlp.dll”)

#pragma comment (linker,”/defaultlib:psapi.dll”)

列表1-2增加psapi.dll和imagehlp.dll到Visual C/C++工程

譯注：

其實(shí)，也可以采用靜態(tài)鏈接，如下：

#pragma comment(lib,”psapi.lib”)

#pragma comment(lib,”imagehlp.lib”)

這樣，就不需要目標(biāo)平臺(tái)必須有這兩個(gè)DLL了。

光盤中的示列代碼

在本書(shū)的附帶光盤中，有兩個(gè)工程是構(gòu)建與psapi.dll和imagehlp.dll之上。其中一個(gè)示例工程是w2k_sym.exe----一個(gè)Windows 2000符號(hào)瀏覽器，它可以從任意符號(hào)文件中提取符號(hào)名稱（假如你已經(jīng)安裝了的話）。它輸出的符號(hào)表可以按照名稱、地址和大小來(lái)排序，同時(shí)接受一個(gè)采用通配符的過(guò)濾器。作為附送功能，w2k_sym.exe還可列出當(dāng)前活動(dòng)的系統(tǒng)模塊/驅(qū)動(dòng)程序的名稱，運(yùn)行的進(jìn)程和每個(gè)進(jìn)程加載的模塊。另一個(gè)示例工程是調(diào)試支持庫(kù)w2k_dbg.dll，這個(gè)庫(kù)包含幾個(gè)便于使用的針對(duì)psapi.dll和imagehlp.dll的外包函數(shù)。w2k_sym.exe完全依賴這個(gè)DLL。這些工程的源代碼分別位于光盤的srcw2k_dbg和srcw2k_sym目錄。

表1-2列出了w2k_dbg.dll用到的函數(shù)名稱。A./W列表示對(duì)ANSI和Unicode的支持情況。稍早提示過(guò)，psapi.dll同時(shí)支持ANSI和Unicode。不幸的是，imagehlp.dll和dbghelp.dll沒(méi)有這么聰明，其中幾個(gè)函數(shù)只能接受ANSI字符串。這有些煩人，因?yàn)閃indows 2000的調(diào)試程序通常不能運(yùn)行在Windows 9x上，所以不該限制使用Unicode。若將imagehlp.dll假如你的工程中，你就必須選擇是使用ANSI還是來(lái)回轉(zhuǎn)化Unicode字符串。因?yàn)槲液苡憛捲谝粋€(gè)可處理16位字符串的系統(tǒng)中使用8位的字符串，所以我選擇后一種方法。w2k_dbg.dll導(dǎo)出的所有函數(shù)中涉及的字符串默認(rèn)都是Unicode。所以，如果你在自己的Windows 2000工程中使用這個(gè)DLL不需要再關(guān)心字符大小問(wèn)題。

另一方面，imagehlp.dll和dbghelp.dll有一個(gè)psapi.dll沒(méi)有的特性：他們同樣適用于Win64----讓每個(gè)開(kāi)發(fā)人員恐懼的64位Windows，這是因?yàn)闆](méi)人知道將Win32程序移植到Win64有多困難。這些DLL導(dǎo)出了Win64 API函數(shù)，好吧----或許有一天我們會(huì)用到他們。

名稱

A/W

庫(kù)

EnumDeviceDrivers

psapi.dll

EnumProcesses

psapi.dll

EnumProcessModules

psapi.dll

GetDeviceDriverFileName

A/W

psapi.dll

GetModuleFileNameEx

A/W

psapi.dll

GetModulelnformation

psapi.dll

ImageLoad

A

imagehlp.dll

ImageUnload

imagehlp.dll

SymCleanup

imagehlp.dll

SymEnumerateSymbols

A/W

imagehlp.dll

Symlnitialize

A

imagehlp.dll

SymLoadModule

A

imagehlp.dll

SymUnloadModule

imagehlp.dll

表1-2; w2k_dbg.dll使用的調(diào)試函數(shù)

我沒(méi)有深入的探究psapi.dll和imagehlp.dll。本書(shū)的焦點(diǎn)在于未文檔化的接口，而且在SDK中與這兩個(gè)DLL的接口有關(guān)的文檔還算不錯(cuò)?？墒?，我并不打算完全繞過(guò)它們，因?yàn)樗鼈兒蚖indows 2000 Native API（將在第2章討論）緊密聯(lián)系在一起。而且，psapi.dll是證明為什么未文檔化的接口比文檔化的那個(gè)更好的最佳實(shí)例。該DLL的接口不僅僅只是看上去的簡(jiǎn)單和笨拙---在某些地方它竟然會(huì)返回明顯矛盾的數(shù)據(jù)。如果我不得不編寫(xiě)一個(gè)專業(yè)的調(diào)試工具來(lái)出售，我是不會(huì)指望這個(gè)DLL的。Windows 2000內(nèi)核提供了強(qiáng)大、通用和更加合適的調(diào)試API函數(shù)。然而，這些幾乎都沒(méi)有文檔化。幸運(yùn)的是，微軟提供的許多系統(tǒng)工具都廣泛的使用了這些API，so it has undergone only slight changes across Windows NT versions。是的，如果你使用了這些API，每當(dāng)發(fā)布了新版的NT，你就必須修訂和小心的測(cè)試你的軟件，但是它們帶來(lái)的好處遠(yuǎn)大于這些障礙。

本章隨后的大多數(shù)示例代碼都來(lái)自w2k_dbg.dll，你可以在光盤的srcw2k_dbgw2k_dbg.c中發(fā)現(xiàn)它們。這個(gè)DLL封裝了多個(gè)步驟，以返回更豐富的信息。數(shù)據(jù)會(huì)以合適的大小、鏈表（包括可選的索引值）返回，以便于對(duì)它們進(jìn)行排序等操作。表1-3列出了w2k_dbg.dll導(dǎo)出的所有API函數(shù)。這些函數(shù)很多，詳細(xì)討論每個(gè)函數(shù)已經(jīng)超出了本章的范圍，因此我鼓勵(lì)你去參考w2k_sym.exe的源代碼（位于光盤srcw2k_symx），來(lái)學(xué)習(xí)它們的典型用法。

表1-3

函數(shù)名稱

描 述

dbgBaseDriver

Return the base address and size of a driver, given its path

dbgBaseModule

Return the base address and size of a DLL module

dbgCrc32Block

Compute the CRC32 of a memory block

dbgCrc32Byte

Bytewise computation of a CRC32

dbgCrc32Start

CRC32 preconditioning

dbgCrc32Stop

CRC32 postconditioning

dbgDriverAdd

Add a driver entry to a list of drivers

dbgDriverAddresses

Return an array of driver addresses (EnumDeviceDrivers ( ) wrapper)

dbgDriverlndex

Create an indexed (and optionally sorted) driver list

dbgDriverList

Create a flat driver list

dbgFileClose

Close a disk file

dbgFileLoad

Load the contents of a disk file to a memory block

dbgFileNew

Create a new disk file

dbgFileOpen

Open an existing disk file

dbgFileRoot

Get the offset of the root token in a file path

dbgFileSave

Save a memory block to a disk file

dbgFileUnload

Free a memory block created by dbgFileLoad ( )

dbglndexCompare

Compare two entrIEs referenced by an index (used by dbgindexsort ( ) )

dbglndexCreate

Create a pointer index on an object list

dbglndexCreateEx

Create a sorted pointer index on an object list

dbglndexDestroy

Free the memory used by an index and its associated list

dbglndexDestroyEx

Free the memory used by a two-dimensional index and its associated lists

dbglndexList

Create a flat copy of a list from its index

dbglndexListEx

Create a flat copy of a two-dimensional list from its index

dbglndexReverse

Reverse the order of the list entries referenced by an index

dbglndexSave

Save the memory image of an indexed list to a disk file

dbglndexSaveEx

Save the memory image of a two-dimensional indexed list to a disk file

dbglndexSort

Sort the list entries referenced by an index by address, size, ID, or name

dbgListCreate

Create an empty list

dbgListCreateEx

Create an empty list with reserved space

dbgListDestroy

Free the memory used by a list

dbgListFinish

Terminate a sequentially built list and trim any unused memory

dbgListlndex

Create a pointer index on an object list

dbgListLoad

Create a list from a disk file image

dbgListNext

Update the list header after adding an entry

dbgListResize

Reserve memory for additional list entries

dbgListSave

Save the memory image of a list to a disk file

dbgMemory

Align Round up a byte count to the next 64-bit boundary

dbgMemoryAlignEx

Round up a string character count to the next 64-bit boundary

dbgMemoryBase

Query the internal base address of a heap memory block

dbgMemoryBaseEx

Query the internal base address of an individually tagged heap memory block

dbgMemoryCreate

Allocate a memory block from the heap

dbgMemoryCreateEx

Allocate an individually tagged memory block from the heap

dbgMemoryDestroy

Return a memory block to the heap

dbgMemoryDestroyEx

Return an individually tagged memory block to the heap

dbgMemoryReset

Reset the memory usage statistics

dbgMemoryResize

Change the allocated size of a heap memory block

dbgMemoryResizeEx

Change the allocated size of an individually tagged heap memory block

dbgMemoryStatus

Query the memory usage statistics

dbgMemory

Track Update the memory usage statistics

dbgModulelndex

Create an indexed (and optionally sorted) process module sub-list

dbgModuleList

Create a flat process module sub-list

dbgPathDriver

Build a default driver path specification

dbgPathFile

Get the offset of the file name token in a file path

dbgPrivilegeDebug

Request the debug privilege for the calling process

dbgPrivilegeSet

Request the specified privilege for the calling process

dbgProcessAdd

Add a process entry to a list of processes

dbgProcessGuess

Guess the default display name of an anonymous system process

dbgProcessIds

Return an array of process IDs (EnumProcesses ( ) wrapper)

dbgProcessIndex

Create an indexed (and optionally sorted) process list

dbgProcessIndexEx

Create a two-dimensional indexed (and optionally sorted) process/module list

dbgProcessList

Create a flat process list

dbgProcessModules

Return a list of process module handles (EnumProcessModules ( )wrapper)

dbgSizeDivide

Divide a byte count by a power of two, optionally rounding up or down

dbgSizeKB

Convert bytes to KB, optionally rounding up or down

dbgSizeMB

Convert bytes to MB, optionally rounding up or down

dbgStringAnsi

Convert a Unicode string to ANSI

dbgStringDay

Get the name of a day given a day-of-week number

dbgStringMatch

Apply a wildcard filter to a string

dbgSymbolCallback

Add a symbol entry to a list of symbols (called by SymEnumerateSymbols ( ) )

dbgSymbolIndex

Create an indexed (and optionally sorted) symbol list

dbgSymbolList

Create a flat symbol list

dbgSymbolLoad

Load a module's symbol table

dbgSymbolLookup

Look up a symbol name and optional offset given a memory address

dbgSymbolUnload

Unload a module's symbol table